OpenSmith: Локальный трейсер для LLM-пайплайнов с дашбордом и экспортом в OpenTelemetry

Запускаете агента на базе Llama, он делает пять последовательных вызовов к модели, а на выходе - нерелевантный ответ. Где потерялся контекст? Какой из шагов добавил лишнюю задержку? С OpenSmith вы видите полную картину: каждый промпт, каждый ответ, метаданные по токенам и времени выполнения - и всё это на локальной машине, без отправки данных в облако.

OpenSmith - open-source Python-инструмент для трассировки LLM-пайплайнов. Декоратор @trace на любой функции автоматически записывает входы, выходы и метаданные в SQLite. Никакого Docker, регистрации или облачных аккаунтов. Вы получаете встроенный дашборд, CLI-фильтры, экспорт в JSON/CSV и интеграцию с OpenTelemetry для отправки трейсов в Jaeger или Grafana Tempo. В этой статье разберём установку, настройку, продвинутые функции и сравним OpenSmith с коммерческими аналогами.

Зачем нужен локальный трейсер для LLM-пайплайнов

Типичный LLM-пайплайн редко состоит из одного запроса. Цепочки вызовов, RAG-системы, агенты с инструментами - каждый компонент добавляет задержку и может исказить результат. Разработчик сталкивается с тремя проблемами. Первая: сложность отладки. Без трассировки вы гадаете, на каком шаге агент выбрал неправильный инструмент или почему промпт мутировал в странный ответ. Вторая: стоимость и приватность. Коммерческие трейсеры вроде LangSmith или Weights & Biases Prompts требуют отправки данных на внешние серверы. Для проектов с чувствительными данными - медицинскими, финансовыми, внутренними корпоративными - это неприемлемо. Третья: инфраструктурные накладные расходы. Разворачивать Jaeger ради одного LLM-пайплайна избыточно, а настраивать его под специфику LLM-трейсов - отдельная задача.

OpenSmith решает эти проблемы прямым подходом. Все данные хранятся локально в SQLite. Установка - один pip install. Трассировка добавляется одним декоратором. Вы видите полную цепочку вызовов, замеряете расход токенов на каждом шаге, находите узкие места по задержке - и всё это без внешних зависимостей. Для тех, кто уже использует локальные модели через Ollama или llama.cpp, OpenSmith становится недостающим звеном в цепочке observability. Мы подробно разбирали архитектуру самописных AI-агентов и важность метрик в статье «Строим AI-агента с нуля: архитектура, метрики и код на Python» - OpenSmith закрывает именно потребность в прозрачности каждого шага.

Быстрый старт: установка и первый трейс с декоратором @trace

Установка OpenSmith выполняется одной командой:

pip install opensmith

После установки трейсы автоматически пишутся в SQLite-базу opensmith.db в текущей директории. Никаких конфигурационных файлов, переменных окружения или Docker-контейнеров. Минимальный рабочий пример выглядит так:

from opensmith import trace
import openai

@trace
def ask_llm(prompt: str) -> str:
    client = openai.OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = ask_llm("Объясни принцип работы трансформера за 100 слов")
print(result)

Декоратор @trace перехватывает аргументы функции, возвращаемое значение и автоматически фиксирует временные метки начала и завершения вызова. В базу попадают: название функции, входные параметры, выходной результат, длительность выполнения и статус (успех/ошибка). Если функция выбрасывает исключение, трейс помечается как failed с сохранением traceback.

Для цепочек вызовов трассировка работает рекурсивно. Вызовете одну функцию с @trace из другой функции с @trace - OpenSmith автоматически свяжет их в родительско-дочернюю иерархию. Это критически важно для отладки агентов, где один вызов модели порождает каскад последующих.

Трассировка локальных моделей: Ollama и llama.cpp

OpenSmith не привязан к конкретному провайдеру LLM. Декоратор работает с любой Python-функцией. Для локальных моделей через Ollama Python SDK код выглядит так:

from opensmith import trace
import ollama

@trace
def local_llm_call(prompt: str, model: str = "llama3.1:8b") -> str:
    response = ollama.chat(
        model=model,
        messages=[{"role": "user", "content": prompt}]
    )
    return response['message']['content']

OpenSmith записывает промпт, ответ и время выполнения. Метаданные о расходе токенов Ollama передаёт в объекте ответа - их можно извлечь и логировать отдельно. Для llama.cpp через Python-биндинги принцип тот же:

from opensmith import trace
from llama_cpp import Llama

llm = Llama(model_path="./models/qwen2.5-7b-instruct-q4_k_m.gguf")

@trace
def llama_cpp_inference(prompt: str) -> str:
    output = llm(
        prompt,
        max_tokens=512,
        echo=False
    )
    return output['choices'][0]['text']

В обоих случаях вы получаете полную историю вызовов с временными метками. Это позволяет замерить реальную скорость инференса на вашем железе и сравнить разные модели или параметры квантизации. Для тех, кто ищет оптимальный GUI для управления локальными моделями, рекомендуем обзор Python Toolkit - инструмент объединяет управление окружениями и AI-интерфейсами в одном окне.

Визуализация трейсов: запуск дашборда через opensmith ui

Команда opensmith ui запускает локальный веб-сервер на порту 8080. В браузере открывается дашборд с тремя основными областями: список трейсов слева, детализация выбранного трейса в центре, временная шкала справа.

Список трейсов показывает: название функции, статус (зелёный - успех, красный - ошибка), длительность и временную метку. Клик по трейсу раскрывает полную информацию: входные аргументы в форматированном JSON, выходное значение, стек ошибки при наличии. Временная шкала визуализирует длительность каждого шага в цепочке вызовов - родительские трейсы отображаются как полосы, дочерние - как вложенные сегменты.

Фильтры в интерфейсе дашборда позволяют отбирать трейсы по: названию функции, статусу (success/failed), временному диапазону и минимальной длительности. Это удобно для быстрого поиска проблемных вызовов - например, всех запросов к Ollama, которые выполнялись дольше 5 секунд.

Фильтрация и экспорт данных: CLI-инструменты

CLI-интерфейс OpenSmith предоставляет команду opensmith query для пакетной обработки трейсов. Фильтры задаются флагами:

# Все трейсы с ошибками за последние 24 часа
opensmith query --status failed --since 24h

# Трейсы функции local_llm_call дольше 3 секунд
opensmith query --name local_llm_call --min-duration 3s

# Экспорт в JSON
opensmith query --since 7d --output json > weekly_traces.json

# Экспорт в CSV для анализа в pandas
opensmith query --since 1d --output csv > daily_traces.csv

Экспорт в JSON сохраняет полную структуру трейса, включая вложенные дочерние вызовы. CSV-формат упрощает анализ в Jupyter или pandas: каждая строка - один трейс с колонками name, status, duration_ms, timestamp, input, output. Это позволяет строить агрегированные отчёты: среднее время ответа по функциям, распределение ошибок по времени суток, корреляцию между длиной промпта и задержкой.

Интеграция с экосистемой OpenTelemetry

OpenSmith поддерживает экспорт трейсов в формате OpenTelemetry. Это означает, что данные трассировки LLM-пайплайнов можно отправлять в любую OTLP-совместимую систему: Jaeger, Grafana Tempo, Honeycomb, Datadog. Настройка выполняется через переменные окружения или конфигурационный файл opensmith.yaml:

# opensmith.yaml
exporter:
  type: otlp
  endpoint: http://localhost:4317
  protocol: grpc
  service_name: my-llm-pipeline

После настройки каждый трейс автоматически экспортируется в указанный коллектор OpenTelemetry. Spans сохраняют родительско-дочерние связи, атрибуты функции записываются как span attributes. Это позволяет вписать трассировку LLM в общую картину мониторинга микросервисов: на одной временной шкале в Jaeger вы видите HTTP-запрос к API, вызов базы данных и цепочку LLM-вызовов с разбивкой по токенам.

Для команд, которые уже используют OpenTelemetry для мониторинга инфраструктуры, такая интеграция означает нулевые дополнительные затраты на внедрение. OpenSmith становится ещё одним источником спанов в существующем пайплайне observability. Аналогичный подход мы разбирали в статье про X-Ray библиотеку трассировки для AI на Python - сравните архитектурные решения и выберите подходящий инструмент под ваш стек.

Использование Postgres в качестве бэкенда

SQLite отлично работает для локальной разработки и одиночных пайплайнов. Для production-сценариев с конкурентным доступом нескольких процессов или сервисов OpenSmith поддерживает опциональный бэкенд на Postgres. Переключение выполняется изменением строки подключения в конфигурации:

# opensmith.yaml
backend:
  type: postgres
  dsn: postgresql://user:password@localhost:5432/opensmith

Postgres-бэкенд даёт три преимущества. Первое: конкурентная запись - несколько экземпляров пайплайна могут одновременно писать трейсы без блокировок. Второе: надёжность - WAL-журналирование и репликация защищают данные от потери. Третье: интеграция с существующей инфраструктурой - трейсы лежат в той же СУБД, что и остальные данные проекта, что упрощает резервное копирование и мониторинг. Миграция с SQLite на Postgres выполняется одной командой opensmith migrate, которая переносит все существующие трейсы.

Продвинутые возможности: live-обновления и токен-бюджетные алерты

Две функции выделяют OpenSmith среди open-source трейсеров: live-обновления через WebSocket и токен-бюджетные алерты.

Live-обновления работают через WebSocket-соединение между дашбордом и сервером OpenSmith. Когда пайплайн выполняет новый вызов с @trace, трейс появляется в дашборде мгновенно - не нужно обновлять страницу или перезапускать запрос. Это критически удобно при отладке длительных агентных цепочек: вы наблюдаете за прогрессом в реальном времени и можете прервать выполнение, если видите, что агент пошёл по неправильному пути. Никакой дополнительной настройки не требуется - WebSocket-соединение устанавливается автоматически при запуске opensmith ui.

Токен-бюджетные алерты решают проблему контроля затрат при использовании платных API. Вы задаёте лимит токенов на сессию или день, и OpenSmith предупреждает о приближении к порогу. Настройка в opensmith.yaml:

alerts:
  token_budget:
    daily_limit: 1000000
    warning_threshold: 0.8  # алерт при 80% лимита
    critical_threshold: 0.95  # критический алерт при 95%
    notification:
      type: stdout  # или webhook, slack

При достижении warning_threshold OpenSmith выводит предупреждение в консоль и помечает трейсы специальным тегом. При critical_threshold можно настроить webhook для отправки уведомления в Slack или другой мессенджер. Алерты считают реальный расход токенов из метаданных вызовов - OpenSmith парсит usage-поля ответов OpenAI, Anthropic и других провайдеров, а для локальных моделей через Ollama токенизатор оценивает количество токенов в промпте и ответе.

Сравнение с аналогами и сценарии применения

Выбор трейсера зависит от трёх факторов: требований к приватности, масштаба проекта и бюджета. OpenSmith занимает чёткую нишу - локальная трассировка без внешних зависимостей. Сравним с основными альтернативами.

OpenSmith оптимален в трёх сценариях. Первый: локальная разработка с Ollama/llama.cpp - вы получаете полную наблюдаемость без интернет-зависимости. Второй: проекты с чувствительными данными - финансовые, медицинские, юридические - где отправка промптов и ответов на внешние серверы исключена compliance-требованиями. Третий: быстрый старт - когда нужно трассировать пайплайн здесь и сейчас, без разворачивания инфраструктуры и создания аккаунтов.

LangSmith и W&B Prompts выигрывают в экосистеме и продвинутых фичах для командной работы: шаринг трейсов, аннотирование, A/B-тестирование промптов. Но за это приходится платить деньгами и передачей данных. Самописное решение на базе OpenTelemetry даёт максимальную гибкость, но требует недель разработки и поддержки - OpenSmith даёт готовый результат за минуты.

Для голосовых AI-агентов, где критичен мониторинг задержек STT и TTS, мы рассматривали интеграцию LangSmith в статье «Полная наблюдаемость голосовых AI-агентов через LangSmith». OpenSmith может использоваться как локальная альтернатива для тех же задач, если данные голосовых сессий нельзя отправлять в облако.

OpenSmith продолжает активно развиваться. В дорожной карте заявлены: интеграция с LangChain и LlamaIndex из коробки, распределённая трассировка между несколькими сервисами, расширенная аналитика по токенам с разбивкой по моделям. Текущая версия уже закрывает 80% потребностей разработчиков, работающих с LLM-пайплайнами на Python. Установите pip install opensmith, добавьте @trace на ключевые функции и запустите opensmith ui - через пять минут вы увидите полную картину работы вашего пайплайна.

Подписаться на канал