Трейсинг¶

Eval AI Library включает модуль трейсинга для мониторинга вызовов LLM в продакшне. Доступен в виде легковесной установки с минимальным оверхедом, что позволяет использовать его даже в высоконагруженных системах.

Легковесная установка¶

Для трейсинга в продакшне без полного фреймворка оценки:

pip install "eval-ai-library[lite]"

Это установит только pydantic и aiohttp, без тяжёлых зависимостей для ML-моделей.

Основной трейсер¶

Синглтон tracer захватывает метаданные LLM-вызовов -- время выполнения, токены, стоимость, входные/выходные данные:

from eval_lib.tracing import tracer, SpanType

# Начать трейс
trace = tracer.start_trace("my-pipeline")

# Создать спан для LLM-вызова
span = tracer.start_span("generate-answer", SpanType.LLM_CALL, input_data={"prompt": "..."})
# ... ваш LLM-вызов ...
tracer.end_span(span, output="Ответ: 42")

# Или через контекст-менеджер
with tracer.trace("retrieval", SpanType.RETRIEVAL) as span:
    results = retrieve_documents(query)

tracer.end_trace()

Декораторы¶

Автоматическая инструментация функций через декораторы:

from eval_lib.tracing import trace_llm, trace_tool, trace_step

@trace_llm()
async def call_openai(prompt: str) -> str:
    # Автоматически трейсит вход, выход, длительность, стоимость
    ...

@trace_tool()
async def search_database(query: str) -> list:
    # Трейсит вызовы инструментов
    ...

@trace_step()
async def process_request(request):
    # Трейсит шаги рассуждений агента
    ...

Интеграция с LangChain¶

Автоматический трейсинг всех LLM-вызовов в цепочках LangChain:

from eval_lib.tracing import EvalLibCallbackHandler, callback_handler

from langchain_openai import ChatOpenAI

# Использовать глобальный callback handler
llm = ChatOpenAI(callbacks=[callback_handler])

# Или создать новый экземпляр
handler = EvalLibCallbackHandler()
llm = ChatOpenAI(callbacks=[handler])

Типы спанов¶

Доступные типы спанов для категоризации трейсов:

SpanType	Описание
`LLM_CALL`	Вызов LLM API
`TOOL_CALL`	Вызов инструмента/функции
`AGENT_STEP`	Шаг агента
`REASONING`	Цепочка рассуждений
`RETRIEVAL`	Поиск документов
`EVALUATION`	Шаг оценки
`CUSTOM`	Пользовательский тип

Конфигурация¶

Настройте эндпоинт и управляйте включением трейсинга:

from eval_lib.tracing import TracingConfig

config = TracingConfig(
    endpoint="https://your-tracing-server.com",
    api_key="your-api-key",
    enabled=True,
)

Переменные окружения:

Переменная	Описание
`EVAL_LIB_TRACING_ENABLED`	Включение/отключение трейсинга
`EVAL_LIB_TRACING_ENDPOINT`	Эндпоинт для сбора трейсов

Управление контекстом¶

Модуль использует контекстные переменные для управления вложенными спанами:

from eval_lib.tracing.context import get_trace_id, set_trace_id, get_parent_span_id

Типы данных¶

Данные трейсинга структурированы с помощью типизированных моделей:

from eval_lib.tracing import TraceSpan, SpanType

TraceSpan представляет одну единицу работы с таймингами, входными/выходными данными, статусом и метаданными.

Асинхронный отправитель¶

Асинхронный отправитель для передачи трейсов на эндпоинт сбора данных с батчингом:

from eval_lib.tracing.sender import TraceSender