Обзор Langfuse: трассы, оценки и версии промптов охватывает платформу для отладки и развития приложений на языковых моделях. Langfuse — открытая платформа для трассировки, управления промптами и оценки приложений. Ниже разберём её функции на ручном наборе обращений в поддержку.
Функции платформы и её место рядом с моделью
Документация langfuse.com/docs объединяет трассы, версии промптов и оценки в одной платформе. Трассы помогают исследовать вызовы, промпты сохраняют инструкции, оценки проверяют ответы.
В нашем упражнении модель должна выбрать billing, delivery или account. Ручная таблица показывает, как мы проверили бы её ответ. Платформа нужна для хранения связи между входом, инструкцией, выходом и оценкой; сама таблица ниже создана без подключения Langfuse.
Руководство по наблюдаемости описывает трассу как журнал запроса: промпт, ответ, токены, задержка и промежуточные операции. Подключение телеметрии надо настроить в приложении; наличие аккаунта само по себе не создаёт историю вызовов.
AI Gateway предоставляет общую точку обращений к поставщикам моделей и учёт вызовов. В ручном упражнении шлюз не используется.
Как связаны трасса, версия промпта, dataset и experiment
В интерфейсе Langfuse значок промпта у генерации открывает связанную версию. Для нашего упражнения нужная связь выглядит так: CASE-3 → V1 → billing → эталон account → несовпадение.
Dataset хранит примеры; experiment проверяет выбранный вариант на наборе. Документация допускает запуск через интерфейс. В упражнении эти сущности вручную обозначены как D1, E1 и E2.
Руководство по оценке разделяет проверку живых трасс и эксперименты на заранее заданных наборах. У нашего D1 нет живого трафика: это полностью заданные учебные строки, которые нельзя выдавать за наблюдения из production.
Полезная деталь из документации проекта: эксперименты можно запускать в CI. Для этого в workflow по pull_request добавляется действие langfuse/experiment-action, а скрипт эксперимента поднимает RegressionError, когда оценка нарушает порог, и задание падает. Это работает и с Langfuse Cloud, и с самостоятельно размещённым Langfuse.
Учебный набор и ручной расчёт
Возьмём учебную карту промпта ticket-category. Три полных входа и эталона: CASE-1 «Списали оплату дважды» относится к billing, CASE-2 «Трек посылки не меняется» — к delivery, CASE-3 «Забыл пароль» — к account. Допустимы только три значения: billing, delivery, account.
Версия V1 содержит инструкцию «Определи категорию обращения». Заданные учебные выходы: billing, delivery, billing. Версия V2 содержит «Верни одну категорию billing/delivery/account; доступ и пароль относятся к account». Заданные выходы: billing, delivery, account.
Ручной exact-match считается по эталонам:
| CASE | Эталон | Выход V1 | Совпадение V1 | Выход V2 | Совпадение V2 |
|---|---|---|---|---|---|
| CASE-1 | billing | billing | да | billing | да |
| CASE-2 | delivery | delivery | да | delivery | да |
| CASE-3 | account | billing | нет | account | да |
| Итог | — | — | 2/3 | — | 3/3 |
Это заданные значения учебного примера, посчитанные вручную. Они не являются результатами модели или самой платформы. Dataset D1 содержит три CASE. Experiment E1 — это V1 плюс D1, experiment E2 — V2 плюс D1. Каждая строка отчёта несёт идентификатор примера, версию, выход, эталон и оценку.
Промпт для воспроизведения разметки:
Ты классификатор обращений в поддержку. Верни ровно одну категорию из списка: billing, delivery, account. Никаких пояснений, только слово категории.
Правила:
- списания, двойные платежи, возвраты — billing;
- доставка, трекинг, сроки посылки — delivery;
- вход в аккаунт, пароль, доступ, регистрация — account.
Обращение: [текст обращения]
Категория:
Меняйте под себя список допустимых категорий, правила отнесения и текст обращения. Держите формат ответа одним словом, иначе exact-match перестанет считаться автоматически.
Номер версии и метки production и staging
Версия фиксирует содержимое промпта, метка указывает на версию. По документации Langfuse метки используются для развёртывания, а latest отмечает новую версию.
Метка production может перемещаться на новую версию и возвращаться на прежнюю.
В учебной карте условная метка production указывает на V1, staging — на V2. Отсюда практическое правило: в отчёте фиксируется номер версии. Одной подвижной метки latest для воспроизведения недостаточно: сохраняйте также точный номер версии и дату прогона. Метка отвечает на вопрос «что сейчас обслуживает окружение», номер версии — на вопрос «какой именно текст инструкции дал этот результат».
Вкладка метрик позволяет сравнивать версии по задержке, расходу и оценкам. В ручном наборе этих измерений нет.
Независимая приёмка после правки по набору
Журнал правки в учебной карте короткий. Изменено правило пароля. CASE-3 исправлен на учебных выходах. Независимых данных пока нет. При подтверждённой регрессии предусмотрен возврат метки на V1.
Здесь кроется главная ошибка. Набор D1 использован для правки, поэтому он перестал быть независимой приёмкой. Рост с 2/3 до 3/3 на нём показывает лишь то, что правило пароля попало в промпт. Для перевода production на V2 нужен отдельный набор D2, собранный заново. В примере D2 не задан, поэтому готовность к выпуску не подтверждена.
Порядок действий для честной приёмки:
- Зафиксировать текущую версию и метку production до правки.
- Внести правку и получить новую версию с номером.
- Прогнать новую версию по набору, который использовался для правки, и убедиться, что целевой случай исправлен.
- Собрать отдельный набор D2 из примеров, не участвовавших в правке.
- Прогнать обе версии по D2 и сравнить оценки.
- Перевести метку production только при отсутствии регрессии на D2.
- Сохранить номер версии и идентификатор набора в отчёте о выпуске.
До появления независимых данных в журнале остаётся запись: готовность к переводу production не подтверждена. Ручные совпадения D1 сами по себе это решение не меняют.
Cloud, self-hosted и путь телеметрии
Доступны Langfuse Cloud и самостоятельное размещение. В документации Haystack облачный адрес передаётся через LANGFUSE_HOST.
Путь телеметрии: приложение → настроенный SDK → выбранный экземпляр Langfuse. Перед отправкой проверьте, на какой адрес настроен клиент и какие данные включены в события. Наши учебные обращения ни в облако, ни на собственный сервер не отправлялись.
Для самостоятельного размещения нужны собственные ресурсы под сервис и хранилище, а также настройка доступа. Облачный вариант снимает эту работу с команды. Выбор зависит от требований к хранению данных и от того, кто обслуживает инфраструктуру.
Проверка совместимости SDK по документации
Перед интеграцией составьте карточку совместимости своего окружения: версия Python или JavaScript, установленный SDK, выбранная интеграция и адрес экземпляра Langfuse. В нашем упражнении этих значений нет; карточку нужно заполнить перед реальным запуском.
В документации Haystack для интеграции указан пакет langfuse-haystack. Ключи берутся из окружения, передаваемое содержимое трасс включается отдельной настройкой. Документация Haystack предупреждает: переменные окружения выставляются до импорта компонентов Haystack, потому что внутренние компоненты трассировки инициализируются при импорте. Надёжнее задать их в оболочке перед запуском скрипта.
Проверку подключения зафиксируйте отдельно: какой пакет установлен, какой клиент создал трассу, где виден её идентификатор и выполнен ли сброс ожидающих событий перед завершением. Это план проверки, готовый SDK-скрипт здесь не приводится.
Ключи читаются из окружения и не печатаются в терминал и логи. Пример учебный: перед запуском сверьте имена пакетов, импортов и функций с текущей документацией проекта и с версией SDK в вашем окружении. Документация Haystack также описывает альтернативу — компонент LangfuseConnector, который включает ту же трассировку, отдаёт trace_url как выход и поддерживает собственный SpanHandler.
Частые вопросы
Что такое Langfuse простыми словами?
Это платформа для трассировки, управления промптами и проверки ответов. В нашем примере она связывала бы обращение, версию инструкции, ответ и оценку.
Чем Langfuse Cloud отличается от self-hosted?
Облачный вариант доступен по адресу cloud.langfuse.com и не требует своей инфраструктуры. Самостоятельное размещение даёт контроль над сервером и хранилищем. Путь телеметрии в обоих случаях одинаков: SDK отправляет события трассировки, платформа их сохраняет и показывает.
Как связать трассу с конкретной версией промпта?
Значок промпта у генерации открывает связанную версию. Для нашего CASE-3 сохраняйте V1 или V2: подвижная метка не заменяет эту запись.
Зачем нужен отдельный набор для приёмки?
Набор, использованный для правки, перестаёт быть независимой проверкой: он уже подогнан под новое правило. Отдельный набор собирается заново и показывает, не сломалась ли работа на примерах, которых правка не касалась. Без него готовность к выпуску остаётся неподтверждённой.
Как проверить совместимость SDK?
Сверьте имена пакетов, импортов и функций с текущей документацией проекта и с версией SDK в вашем окружении. Переменные окружения выставляйте до импорта компонентов, потому что трассировка инициализируется при импорте. Ключи держите в окружении и не выводите их в терминал и логи.