# Langfuse на Spaces

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

## Что такое Langfuse?

[Langfuse](https://langfuse.com) — это открытая платформа для разработки LLM-приложений, которая помогает командам совместно отлаживать, оценивать и совершенствовать свои LLM-приложения.

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

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

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

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

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

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

    

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

1. Создайте [**новый Hugging Face Space**](https://huggingface.co/new-space)
2. Выберите **Docker** в качестве SDK для Space
3. Выберите **Langfuse** в качестве шаблона Space
4. Подключите **[Storage Bucket](https://huggingface.co/docs/hub/storage-buckets)**, чтобы данные Langfuse сохранялись после перезапусков
5. Убедитесь, что пространство имеет видимость **public**, чтобы API/SDK Langfuse могли получить доступ к приложению (см. примечание ниже для получения дополнительных сведений)
6. [Необязательно, но рекомендуется] Для безопасного развертывания замените значения по умолчанию переменных окружения **environment variables**:
   - `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**!

![Clone the Langfuse Space](https://langfuse.com/images/cookbook/huggingface/huggingface-space-setup.png)

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

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

После входа в приложение вы можете использовать [встроенные функции Langfuse](https://langfuse.com/docs/rbac) для управления организациями, проектами и пользователями.

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

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

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

Если вы хотите ограничить доступ только членами указанной организации или организаций, просто задайте метаданные `hf_oauth_authorized_org` в файле `README.md` пространства, как показано [здесь](https://huggingface.co/docs/hub/spaces-oauth#create-an-oauth-app).

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

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

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

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

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

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

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

Langfuse не зависит от конкретной модели и может использоваться для отслеживания любых приложений. Ознакомьтесь с [руководством по началу работы](https://langfuse.com/docs) в документации Langfuse, чтобы узнать, как добавить инструментирование в ваш код.

Langfuse поддерживает нативные интеграции со многими популярными фреймворками LLM, включая [Langchain](https://langfuse.com/docs/integrations/langchain/tracing), [LlamaIndex](https://langfuse.com/docs/integrations/llama-index/get-started) и [OpenAI](https://langfuse.com/docs/integrations/openai/python/get-started), а также предоставляет SDK на Python и JS/TS для инструментирования вашего кода. Langfuse также предлагает различные API-эндпоинты для приёма данных и был интегрирован в другие проекты с открытым исходным кодом, такие как [Langflow](https://langfuse.com/docs/integrations/langflow), [Dify](https://langfuse.com/docs/integrations/dify) и [Haystack](https://langfuse.com/docs/integrations/haystack/get-started).

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

В качестве простого примера ниже показано, как отслеживать вызовы LLM в [Inference Providers](https://huggingface.co/docs/inference-providers/en/index) с помощью Python SDK Langfuse.

Сначала убедитесь, что вы настроили переменные окружения `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY` и `LANGFUSE_SECRET_KEY`, а также что вы [авторизовались в своем аккаунте Hugging Face](https://huggingface.co/docs/huggingface_hub/en/quick-start#authentication).

```python
from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="https://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](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template?duplicate=true) и следуйте инструкциям в [README](https://huggingface.co/spaces/langfuse/langfuse-gradio-example-template/blob/main/README.md).

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

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

![Example trace with Gradio](https://langfuse.com/images/cookbook/huggingface/huggingface-gradio-example-trace.png)

_[Пример трассировки в интерфейсе Langfuse](https://langfuse-langfuse-template-space.hf.space/project/cm4r1ajtn000a4co550swodxv/traces/9cdc12fb-71bf-4074-ab0b-0b8d212d839f?timestamp=2024-12-20T12%3A12%3A50.089Z&view=preview)_

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

- [Документация Langfuse](https://langfuse.com/docs)
- [Репозиторий Langfuse на GitHub](https://github.com/langfuse/langfuse)
- [Langfuse Discord](https://langfuse.com/discord)
- [Шаблон пространства Langfuse](https://huggingface.co/spaces/langfuse/langfuse-template-space)

Для получения дополнительной помощи создайте тему в [обсуждениях на GitHub](https://langfuse.com/discussions) или [откройте issue](https://github.com/langfuse/langfuse/issues).