Просмотр работы ИИ в Langfuse

Name: Mockarty
Author: Mockarty

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

Можно использовать Langfuse Cloud (https://cloud.langfuse.com) или собственный сервер Langfuse.

Что записывается

Mockarty объединяет записанные события в трейсы. Трейс — это одна задача агента или одно сообщение с ответом в чате. Внутри него могут быть:

Шаги с инструментами (spans): вызовы инструментов, их входные данные, результаты и ошибки. Шаги другого агента показываются внутри вызова, который передал ему работу.
Вызовы модели (generations): отправленные сообщения, ответ, название модели, расход токенов, длительность и ошибки.
Сессия: объединяет сообщения одного разговора.

Для задачи агента ID трейса совпадает с ID задачи. Отправка идёт в фоне, поэтому новый трейс может появиться не сразу. Если буфер заполнится, часть событий будет потеряна; подробности — в разделе Надёжность.

Включение интеграции

Langfuse настраивает только администратор. Трейсы всех пространств имён отправляются в один проект; по имени пространства их можно отфильтровать.

Как администратору включить Langfuse

Откройте Админ → ИИ и LLM → Настройки агентов → Обсервабилити LLM (Langfuse):

Включите Обсервабилити Langfuse.
Укажите адрес, публичный и секретный ключи (pk-lf-... / sk-lf-...) из раздела Settings → API Keys вашего проекта Langfuse. Оставьте адрес пустым для Langfuse Cloud.
Выберите Только метаданные, если тексты запросов и ответов нельзя отправлять в открытом виде.
Нажмите Сохранить, затем Проверить подключение. Проверка использует сохранённые ключи и включает ссылки на трейсы из карточек задач.

Пока переключатель выключен, Mockarty не создаёт новые трейсы Langfuse. Настроек Langfuse для отдельных пространств имён нет.

Режим Только метаданные заменяет записываемые входные данные и результаты отметкой об их размере. Структура трейса, названия моделей, длительность и расход токенов остаются видны. Перед отправкой трейсов во внешний сервис проверьте также имена инструментов и метаданные.

Секретный ключ после сохранения больше не показывается. Если вашей организации нужно шифрование этого ключа при хранении, настройте дополнительное шифрование персональных данных Mockarty до его ввода.

Работа с трейсами

Из карточки задачи: после успешной проверки подключения откройте записанную задачу агента в панели задач и нажмите Открыть трейс в Langfuse. Ответ GET /api/v1/agent/tasks/{id} содержит ту же ссылку в поле langfuseTraceUrl, когда она доступна.
Из чата: просто спросите ассистента. У него три инструмента:
- langfuse_trace_get — все шаги с инструментами и вызовы модели в одном трейсе;
- langfuse_traces_search — поиск недавних трейсов по сессии, пользователю, названию или времени;
- langfuse_costs_summary — расход токенов и стоимость по дням и моделям.
Например: «Покажи, что происходило в задаче 3f2a…, и объясни, зачем агент вызвал этот инструмент» или «Сколько токенов использовали модели за последние три дня?».
REST: те же данные доступны по GET /api/v1/langfuse/traces, GET /api/v1/langfuse/traces/{traceId} и GET /api/v1/langfuse/costs.

curl -H "Authorization: Bearer $MOCKARTY_TOKEN" \
  "http://localhost:5770/api/v1/langfuse/traces?hours=24&limit=10"

Надёжность

Отправка идёт в фоне. Если входящий буфер заполнится, новые события отбрасываются и учитываются в счётчике. При длительном сбое ограниченный буфер повторной доставки теряет самые старые события.
Если Langfuse недоступен, Mockarty делает паузу и повторяет отправку с растущим интервалом: от 30 секунд до 15 минут.
В кластере каждый узел отправляет записанные им события. Выключение интеграции прекращает создание новых трейсов; уже поставленные в очередь события ещё могут быть отправлены.