Langfuse на Spaces

В этом руководстве показано, как развернуть Langfuse на Hugging Face Spaces и начать инструментацию вашего LLM-приложения для обеспечения наблюдаемости. Эта интеграция позволяет экспериментировать с LLM API на Hugging Face Hub, управлять промптами в одном месте и оценивать выходные данные моделей.

Что такое Langfuse?

Langfuse — это открытая платформа для разработки LLM-приложений, которая помогает командам совместно отлаживать, оценивать и совершенствовать свои LLM-приложения.

Ключевые возможности Langfuse включают трассировку LLM для фиксации полного контекста потока выполнения вашего приложения, управление промптами для централизованной и совместной итерации, метрики оценки для проверки качества вывода, создание датасетов для тестирования и бенчмаркинга, а также песочницу для экспериментов с промптами и конфигурациями моделей.

В этом видео за 10 минут рассказывается о возможностях Langfuse:

Зачем нужна наблюдаемость LLM?

• По мере того как языковые модели становятся всё более распространёнными, понимание их поведения и производительности приобретает важное значение.
• Наблюдаемость LLM предполагает мониторинг и понимание внутренних состояний LLM-приложения по его выводам.
• Это необходимо для решения таких задач, как:
  • Сложные потоки управления с повторяющимися или последовательными вызовами, что затрудняет отладку.
  • Нендетерминированный вывод, усложняющий последовательную оценку качества.
  • Разнообразие намерений пользователей, требующее глубокого понимания для улучшения пользовательского опыта.
• Создание приложений на базе LLM предполагает сложные рабочие процессы, а наблюдаемость помогает справляться с этой сложностью.

Шаг 1: Настройка Langfuse на Spaces

С помощью пространства Hugging Face для Langfuse вы можете запустить развернутую версию Langfuse всего в несколько кликов.

Чтобы начать, нажмите кнопку выше или выполните следующие шаги:

1. Создайте новый Hugging Face Space
2. Выберите Docker в качестве SDK для Space
3. Выберите Langfuse в качестве шаблона Space
4. Подключите Storage Bucket, чтобы данные Langfuse сохранялись после перезапусков
5. Убедитесь, что пространство имеет видимость public, чтобы API/SDK Langfuse могли получить доступ к приложению (см. примечание ниже для получения дополнительных сведений)
6. [Необязательно, но рекомендуется. Для безопасного развертывания замените значения по умолчанию переменных окружения :
   • NEXTAUTH_SECRET: Используется для проверки cookie сессии входа. Сгенерируйте секрет с энтропией не менее 256 с помощью openssl rand -base64 32.
   • SALT: Используется для добавления соли к хешированным API-ключам. Сгенерируйте секрет с энтропией не менее 256 с помощью openssl rand -base64 32.
   • ENCRYPTION_KEY: Используется для шифрования конфиденциальных данных. Должен быть 256 бит, 64 символа в шестнадцатеричном формате, генерируется командой: openssl rand -hex 32.
7. Нажмите Создать Space!

Доступ пользователя

Ваше пространство Langfuse предварительно настроено с использованием OAuth Hugging Face для безопасной аутентификации, поэтому при первом входе вам необходимо будет авторизовать доступ read к вашему аккаунту Hugging Face, следуя инструкциям в всплывающем окне.

После входа в приложение вы можете использовать встроенные функции Langfuse для управления организациями, проектами и пользователями.

Пространство Langfuse должно иметь видимость public, чтобы API/SDK Langfuse могли обращаться к приложению. Это означает, что по умолчанию любой пользователь Hugging Face, вошедший в систему, сможет получить доступ к пространству Langfuse.

Вы можете предотвратить регистрацию новых пользователей и доступ к пространству двумя различными способами:

1. (Рекомендуется) Нативные ограничения OAuth на уровне организации в Hugging Face

Если вы хотите ограничить доступ только членами указанной организации или организаций, просто задайте метаданные hf_oauth_authorized_org в файле README.md пространства, как показано здесь.

После настройки доступ к пространству получат только пользователи, являющиеся членами указанных организаций.

2. Ручной контроль доступа

Вы также можете ограничить доступ на уровне отдельных пользователей, установив переменную окружения AUTH_DISABLE_SIGNUP в значение true. Убедитесь, что вы сначала вошли в систему и прошли аутентификацию в пространстве, прежде чем устанавливать эту переменную, иначе ваш собственный профиль не сможет пройти аутентификацию.

Примечание: Если вы установили переменную окружения AUTH_DISABLE_SIGNUP в значение true, чтобы ограничить доступ, и хотите предоставить новому пользователю доступ к пространству, вам сначала нужно вернуть её значение в false (дождитесь завершения пересборки), добавить пользователя и попросить его пройти аутентификацию через OAuth, а затем снова установить значение true.

Шаг 2: Использование Langfuse

Теперь, когда у вас запущен Langfuse, вы можете начать инструментирование вашего LLM-приложения для захвата трассировок и управления промптами. Давайте посмотрим, как это сделать!

Мониторинг любого приложения

Langfuse не зависит от конкретной модели и может использоваться для отслеживания любых приложений. Ознакомьтесь с руководством по началу работы в документации Langfuse, чтобы узнать, как добавить инструментирование в ваш код.

Langfuse поддерживает нативные интеграции со многими популярными фреймворками LLM, включая Langchain, LlamaIndex и OpenAI, а также предоставляет SDK на Python и JS/TS для инструментирования вашего кода. Langfuse также предлагает различные API-эндпоинты для приёма данных и был интегрирован в другие проекты с открытым исходным кодом, такие как Langflow, Dify и Haystack.

Пример 1: Трассировка вызовов провайдеров инференса

В качестве простого примера ниже показано, как отслеживать вызовы LLM в Inference Providers с помощью Python SDK Langfuse.

Сначала убедитесь, что вы настроили переменные окружения LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY и LANGFUSE_SECRET_KEY, а также что вы авторизовались в своем аккаунте Hugging Face.

from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://huggingface.co/proxy/router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/v1",
    api_key=get_token(),
)

messages = [{"role": "user", "content": "What is observability for LLMs?"}]

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=messages,
    max_tokens=100,
)

Пример 2: Мониторинг приложения Gradio

Мы создали шаблон пространства Gradio, демонстрирующий, как создать простое чат-приложение с использованием модели Hugging Face и отслеживать вызовы модели и обратную связь пользователей в Langfuse — не покидая Hugging Face.

Для начала сделайте дубликат этого пространства шаблона Gradio и следуйте инструкциям в README.

Шаг 3: Просмотр трассировок в Langfuse

После того как вы добавите инструментацию в ваше приложение и импортируете трассировки или обратную связь пользователей в Langfuse, вы сможете просматривать свои трассировки в Langfuse.

Пример трассировки в интерфейсе Langfuse

Дополнительные ресурсы и поддержка

• Документация Langfuse
• Репозиторий Langfuse на GitHub
• Langfuse Discord
• Шаблон пространства Langfuse

Для получения дополнительной помощи создайте тему в обсуждениях на GitHub или откройте issue.