Обзор Langfuse 2026: open-source платформа для трассировки и оценки LLM-агентов

Архитектура Langfuse

Зачем нужна наблюдаемость LLM-приложений

Разработка на базе больших языковых моделей фундаментально отличается от классического программирования. В традиционном коде вызов функции детерминирован: одинаковые входные данные всегда дают одинаковый результат. LLM-приложения, напротив, недетерминированы по своей природе — один и тот же промпт может возвращать разные ответы, агент может выбирать разные цепочки инструментов, а стоимость каждого вызова измеряется токенами и деньгами. Без инструментов наблюдаемости разработчик буквально летит вслепую: невозможно понять, почему агент повёл себя некорректно, сколько стоил конкретный пользовательский запрос, и как изменение промпта повлияло на качество ответов.

Langfuse решает именно эту проблему. Он даёт полную картину происходящего внутри LLM-приложения: от входящего запроса пользователя до финального ответа модели, включая все промежуточные вызовы инструментов, обращения к векторным базам данных, цепочки размышлений агента и метаданные о потраченных токенах. Это не просто логирование — это структурированная трассировка с визуализацией деревьев вызовов, временными шкалами, метриками стоимости и встроенной системой оценки качества. И всё это доступно как в облаке, так и на собственной инфраструктуре.

Ключевые возможности Langfuse

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

Компоненты и интеграции

Langfuse состоит из нескольких логических компонентов, каждый из которых закрывает определённый аспект работы с LLM. Серверная часть написана на Next.js и работает с PostgreSQL для хранения метаданных и ClickHouse для аналитических запросов. Такая архитектура обеспечивает высокую производительность даже при миллионах наблюдений в день.

Установка и запуск

Langfuse можно развернуть двумя способами. Первый — self-hosted через Docker Compose, что рекомендуется для production-сред и случаев, когда критична приватность данных. Второй — облачная версия на cloud.langfuse.com, удобная для быстрого старта и небольших проектов. Self-hosted вариант поднимает пять контейнеров: сервер Langfuse на Next.js, PostgreSQL для метаданных, ClickHouse для аналитики, Redis для очередей и кэширования, а также MinIO для хранения артефактов. Весь стек управляется одним файлом docker-compose — от клонирования репозитория до работающего дашборда проходит буквально пять минут.

# 1. Клонируем репозиторий и запускаем Docker Compose
git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up -d

# 2. Устанавливаем Python SDK
pip install langfuse

# 3. Устанавливаем переменные окружения
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_HOST="http://localhost:3000"

Пример трассировки на Python

Ниже — полноценный пример, демонстрирующий ключевые концепции Langfuse: создание trace как корневого контекста, открытие span для группировки вызовов, автоматическое логирование вызова OpenAI как generation (дочернего элемента span), а также добавление оценки качества через score. Модуль langfuse.openai является прозрачной обёрткой над стандартным OpenAI-клиентом — весь код, использующий обычный openai.chat.completions.create, продолжает работать, но теперь каждый вызов автоматически трассируется.

# langfuse_tracing_demo.py
import os
from langfuse import Langfuse
from langfuse.openai import openai

# Инициализация клиента
langfuse = Langfuse(
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    host=os.environ["LANGFUSE_HOST"],
)

# Создаём trace — корневой объект трассировки
trace = langfuse.trace(
    name="support-chatbot",
    user_id="user-42",
    metadata={"channel": "web"},
)

# Открываем span для группировки вызовов
span = trace.span(
    name="generate-response",
    input={"question": "Как работает Langfuse?"},
)

# Вызов OpenAI — автоматически логируется как generation
completion = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Объясни Langfuse кратко"},
    ],
    langfuse_observation=span,  # ← связываем с trace
)

answer = completion.choices[0].message.content

# Завершаем span с output-данными
span.update(output={"answer": answer})
span.end()

# Score — оценка качества (LLM-as-judge или ручная)
trace.score(
    name="relevance",
    value=0.92,
    comment="Ответ релевантный и точный",
)

# Отправляем данные в Langfuse
langfuse.flush()
print("✅ Трассировка завершена — проверьте дашборд Langfuse")

Декоратор @observe: минималистичная трассировка

Самый быстрый способ обернуть любую функцию в трассировку — декоратор @observe(). Входные аргументы и возвращаемое значение автоматически попадают в trace, а вложенные вызовы декорированных функций образуют иерархию spans. Это особенно удобно для быстрого прототипирования и случаев, когда не хочется вручную управлять trace и span объектами. Декоратор работает и для асинхронных функций, поддерживает кастомные имена и передачу метаданных.

from langfuse.decorators import observe
from openai import OpenAI

client = OpenAI()

@observe()
@observe
def answer_question(question: str) -> str:
    """Любой вызов этой функции → trace в Langfuse"""
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": question}],
    )
    return response.choices[0].message.content

# Вызов — автоматически трассируется
result = answer_question("Что такое observability в LLM?")
print(result)

Сравнение Langfuse с аналогами

Рынок observability-инструментов для LLM активно развивается, и у Langfuse есть несколько заметных конкурентов. Главные из них — LangSmith от создателей LangChain, Helicone (лёгкий API-прокси с мониторингом) и Arize Phoenix (open-source наблюдаемость для ML-моделей). Каждый инструмент имеет свою специализацию, и выбор зависит от конкретных потребностей команды. Ниже — детальное сравнение по ключевым критериям.

Когда выбирать Langfuse

Langfuse оптимален для команд, которые строят production LLM-приложения и нуждаются в комплексном решении, а не в точечном инструменте для одной задачи. Если вам нужна одновременно трассировка, управление промптами, оценка качества и эксперименты с датасетами — и всё это на собственной инфраструктуре с полным контролем над данными — Langfuse практически не имеет альтернатив. LangSmith может быть предпочтительнее для команд, глубоко интегрированных в экосистему LangChain и готовых платить за облачный сервис. Helicone хорош как лёгкий прокси для мониторинга API-вызовов, если не нужны evals и промпт-менеджмент. Arize Phoenix интересен командам с фоновым ML-мониторингом, выходящим за рамки чисто LLM-задач.

Langfuse в цифрах

Плюсы и минусы