LangSmith: tracing, evaluare și depanare în LangChain & LangGraph

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<cheia-ta>"
# workspace bazat pe proiecte (și LangSmith self-hosted):
export LANGSMITH_PROJECT="aplicatie-productie"
# workspace bazat pe agenți (LangSmith Cloud), în locul lui LANGSMITH_PROJECT:
# export LANGSMITH_AGENT_ID="<agent-id>"
# export LANGSMITH_AGENT_ENVIRONMENT="production"

LangSmith este platforma LangChain pentru tracing, evaluare, prompturi și deployment; funcționează cu LangChain, LangGraph și cu cod scris fără ele. Pentru LangChain și LangGraph nu trebuie cod suplimentar: setezi LANGSMITH_TRACING=true și LANGSMITH_API_KEY, iar fiecare rulare se trimite ca trace. Trace-ul arată arborele de pași (prompt, model, unelte, retriever), intrările și ieșirile, latența, tokenii și, pentru furnizorii principali, costul calculat automat.

Destinația trace-urilor depinde de tipul workspace-ului. În workspace-urile bazate pe proiecte (inclusiv LangSmith self-hosted) setezi LANGSMITH_PROJECT. În workspace-urile bazate pe agenți din LangSmith Cloud creezi o dată un agent și setezi LANGSMITH_AGENT_ID și LANGSMITH_AGENT_ENVIRONMENT (local, development, staging sau production); documentația cere să nu combini cele două variante. Conturile din altă regiune decât US setează și LANGSMITH_ENDPOINT, de exemplu https://eu.api.smith.langchain.com.

Funcțiile proprii, care nu folosesc LangChain, se urmăresc cu decoratorul @traceable din pachetul langsmith. Trace-urile se trimit dintr-un fir de fundal, ca să nu încetinească aplicația; un proces scurt se poate termina înainte să plece toate, iar pentru SDK-ul folosit direct există flush(). Planul gratuit Developer include, conform paginii de prețuri, un loc și până la 5.000 de trace-uri de bază pe lună, păstrate 14 zile. Mai multe despre monitorizare găsești la LangSmith în secțiunea LLMOps.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
LANGSMITH_TRACING=true	Activează trimiterea trace-urilor.
LANGSMITH_API_KEY	Cheia API LangSmith.
LANGSMITH_PROJECT	Proiectul de tracing, în workspace-urile bazate pe proiecte și în LangSmith self-hosted.
LANGSMITH_AGENT_ID / LANGSMITH_AGENT_ENVIRONMENT	Adresarea pe agent în workspace-urile bazate pe agenți din LangSmith Cloud.
LANGSMITH_ENDPOINT	URL-ul API pentru regiunile din afara US.
@traceable	Decorator din langsmith pentru funcțiile proprii, care apar ca pași în trace.
config={"tags": [...], "metadata": {...}}	Etichete și metadate pe un apel; se moștenesc de pașii copii și se pot filtra în interfață.

Exemple practice și scenarii reale

Exemplul 1: Etichete și metadate pe un apel

chain.invoke(
    {"input": "Care este politica de retur?"},
    {"tags": ["productie", "v2"], "metadata": {"user_id": "99"}},
)

Exemplul 2: Funcție proprie urmărită cu @traceable

from langsmith import traceable

@traceable
def formateaza_context(documente: list[str]) -> str:
    return "\n\n".join(documente)

Greșeli frecvente și capcane

• Să scrii cheia API în cod și să o urci în repository. Ține-o în variabile de mediu sau într-un manager de secrete.
• Să setezi LANGSMITH_PROJECT împreună cu variabilele de agent. Documentația cere o singură variantă, cea potrivită workspace-ului.
• Trace-uri lipsă în scripturi scurte sau funcții serverless. Trimiterea se face în fundal; procesul trebuie să aștepte sau să apeleze flush() înainte de ieșire.

Noțiuni și module înrudite

• lcel-pipe-runnable
• langgraph-stategraph
• create-agent
• langchain-streaming-tools