Что такое `LangSmith` и как он помогает в отладке и трейсинге LangChain-приложений?

Question

Accepted Answer

Что такое LangSmith

LangSmith — hosted-платформа от Langchain Inc. для observability, отладки и оценки LLM-приложений. Она решает проблему «чёрного ящика»: когда агент или RAG-цепочка даёт неверный ответ, без трейсинга невозможно понять, где именно произошла ошибка — в промпте, retrieval-шаге, tool call или парсинге ответа.

Как включить трейсинг

Достаточно выставить три переменные окружения — LangChain автоматически отправляет все трейсы:

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="ls__..."
export LANGCHAIN_PROJECT="my-rag-app"  # имя проекта в LangSmith UI

Или через код перед первым вызовом:

import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "ls__..."
os.environ["LANGCHAIN_PROJECT"] = "my-rag-app"

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o-mini")
prompt = ChatPromptTemplate.from_messages([
    ("system", "Ты помощник."),
    ("human", "{input}"),
])
chain = prompt | llm

# Этот вызов автоматически создаст трейс в LangSmith
response = chain.invoke({"input": "Объясни разницу между RAG и fine-tuning"})

Что фиксирует LangSmith в трейсе

Run tree: иерархия вызовов — chain → prompt → llm → output_parser, каждый шаг отдельно
Inputs / Outputs: точные входные и выходные данные каждого шага
Latency: время на каждый компонент — сразу видно, что тормозит (retrieval vs LLM)
Token usage: prompt_tokens, completion_tokens, total_tokens по каждому LLM-вызову
Tool calls: какие инструменты вызывал агент, с какими аргументами, что вернули
Errors: исключения с полным стектрейсом, привязанным к конкретному шагу

Ручная аннотация через декоратор @traceable

from langsmith import traceable

@traceable(name="retrieve_docs", run_type="retriever")
def retrieve(query: str) -> list[str]:
    # Обычная функция — LangSmith обернёт её в отдельный span
    return vectorstore.similarity_search(query, k=4)

@traceable(name="full_pipeline")
def answer(question: str) -> str:
    docs = retrieve(question)  # станет дочерним span-ом
    context = "
".join(d.page_content for d in docs)
    return llm.invoke(f"Контекст: {context}

Вопрос: {question}").content

Datasets и оценка качества

LangSmith позволяет создавать датасеты из реальных трейсов и запускать автоматические оценки:

from langsmith import Client
from langsmith.evaluation import evaluate, LangChainStringEvaluator

client = Client()

# Создаём датасет из реальных примеров
dataset = client.create_dataset("rag-qa-v1")
client.create_examples(
    inputs=[{"question": "Что такое pgvector?"}],
    outputs=[{"answer": "Расширение PostgreSQL для векторного поиска"}],
    dataset_id=dataset.id,
)

# Запускаем оценку с LLM-as-judge
results = evaluate(
    lambda x: chain.invoke(x["question"]),
    data="rag-qa-v1",
    evaluators=[LangChainStringEvaluator("qa")],
    experiment_prefix="gpt-4o-mini-rag",
)

Подводные камни

Трейсинг асинхронен по умолчанию — в pytest нужно явно дожидаться flush через langsmith.utils.get_tracer_project() или использовать wait_for_all_tracers()
Переменная LANGCHAIN_TRACING_V2=true активирует отправку данных на серверы Langchain Inc. — в enterprise-сценариях используйте self-hosted LangSmith или отключайте трейсинг в тестах
Чувствительные данные (PII, API-ключи в промптах) попадают в трейсы без фильтрации — нужно настраивать hide_inputs / hide_outputs на уровне клиента
LangSmith не входит в бесплатный tier без ограничений — на высоком RPS стоимость хранения трейсов значительна
Трейсы агентов с циклами (ReAct, LangGraph) могут быть очень глубокими — UI медленно рендерит деревья с 50+ узлами
При использовании @traceable на async-функциях нужно импортировать из langsmith, а не из langchain — разные пакеты
Datasets версионируются, но diff между версиями нет в UI — надо отслеживать вручную через client.list_examples()
Метрика «faithfulness» LLM-as-judge стохастична — для воспроизводимых бенчмарков задавайте temperature=0 в evaluator-модели

Что такое `LangSmith` и как он помогает в отладке и трейсинге LangChain-приложений?