LangSmith per debugging e monitoring LLM — Tracciare ogni chiamata AI senza perdere tempo

Hai un'applicazione LLM che a volte risponde con allucinazioni, si blocca su input identici o consuma token senza motivo. I log classici non bastano: vedi solo l'input e l'output, non il ragionamento intermedio, le chiamate a tool, i fallimenti di parsing. Il problema è che stai pagando per ogni token sprecato e non hai visibilità su dove si perde il valore. Noi, di Meteora Web, dopo anni di debugging di applicazioni complesse (ERP, e-commerce, piattaforme SaaS) abbiamo portato la stessa disciplina nelle AI pipeline. Ecco perché LangSmith non è un optional: è il cruscotto che trasforma il tuo LLM da scatola nera a sistema controllabile.

Perché usare LangSmith per il debugging di applicazioni LLM?

Un'applicazione LLM non è una funzione pura. Ogni run può coinvolgere una catena di passi: prompt template, retrieval da vector store, chiamata a API esterna, generazione della risposta, parsing dello structured output. Se un passo fallisce, l'errore si propaga silenziosamente. Con il logging tradizionale catturi solo il risultato finale; con LangSmith catturi ogni singolo trace — tempo, token spesi, input/output intermedi, eccezioni. Noi lo usiamo per rispondere velocemente a domande come: "perché il cliente ha ricevuto una risposta vuota?" — e invece di riprodurre il bug in locale, apriamo la trace e vediamo esattamente dove il retrieval ha restituito zero risultati.

Il costo nascosto del debugging manuale

Immagina un'applicazione che gestisce richieste di assistenza clienti. Un utente scrive "annulla ordine 12345" e l'AI risponde "non ho trovato l'ordine". Perché? Potrebbe essere: embedding sbagliato, chunking troppo aggressivo, tool mal configurato. Senza tracing, perdi ore a riprodurre e aggiungere log. Con LangSmith, la trace ti mostra il contesto recuperato dal vector store: magari il chunk finiva con "..." tagliando il numero. Lo abbiamo visto succedere. Risolto in dieci minuti invece di due giorni.

Come funziona il tracing in LangSmith?

LangSmith si integra con LangChain (ma supporta anche framework propri tramite SDK Python/JS). Ogni chiamata a un modello, un tool, un retriever genera un run. I run si annidano in trace che rappresentano un'intera sessione utente o una job. Il tutto viene inviato via API a LangSmith Cloud (o on-premise per enterprise). L'interfaccia web mostra una timeline interattiva con latenza, costo token, input/output, errori.

from langsmith import Client
from langchain_openai import ChatOpenAI
from langchain.smith import RunEvalConfig, run_on_dataset

client = Client()  # usa LANGCHAIN_API_KEY di default

# Imposta un run unico per una chiamata
with client.trace(
    project_name="my-app",
    run_type="chain",
    name="customer-support"
) as rt:
    llm = ChatOpenAI(model="gpt-4o-mini")
    result = llm.invoke("Qual è lo stato del mio ordine?")
    rt.end(outputs={"response": result.content})

Configurare l'ambiente in due minuti

Devi settare due variabili d'ambiente: LANGCHAIN_API_KEY (la trovi su smith.langchain.com) e LANGCHAIN_PROJECT (nome del tuo progetto). Poi importa langsmith e usa il context manager client.trace o, se usi LangChain, abilita automaticamente con langchain.llms che si integra da solo. Noi consigliamo di creare un progetto per ambiente (dev, staging, prod) e abilitare il tracing selettivamente con flag di configurazione.

Quali metriche monitorare in produzione con LangSmith?

LangSmith non è solo debugging a posteriori: offre monitoring in tempo reale con dashboard personalizzabili. Le metriche chiave:

• Latenza per step — identifica colli di bottiglia (es. retrieval lento vs generazione)
• Token consumati per run — confronta modelli e prompt per ottimizzare i costi
• Tasso di errore per tipo di run — tool call falliti, eccezioni di parsing
• Feedback utente — puoi inviare valutazioni (like/dislike) e correlarle ai trace
• Distribuzione dei costi per endpoint — se usi più provider, vedi dove spendi

Creare un monitoraggio dei costi con feedback loop

Noi abbiamo costruito un sistema che, per ogni risposta generata, invia un feedback a LangSmith con il costo calcolato. Poi filtriamo per project e otteniamo un report giornaliero: "Il modello gpt-4o-mini ha generato il 90% delle risposte con costo accettabile, ma il 10% ha sforato a causa di prompt lunghi". Abbiamo ridotto i costi del 30% semplicemente tagliando i prompt inutili.

# Esempio di invio feedback con costo
client.create_feedback(
    run_id=run.id,
    key="cost_usd",
    score=0.0025  # dollari spesi per quella run
)

Come integrare LangSmith nel tuo progetto LangChain?

Se usi LangChain (Python o TypeScript), l'integrazione è trasparente. Basta impostare le variabili d'ambiente e LangChain invierà automaticamente i trace. Per progetti personalizzati (senza LangChain), usa il client SDK direttamente. Vediamo i due scenari.

Integrazione automatica con LangChain

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = "support-chat"

llm = ChatOpenAI(model="gpt-4o-mini")
prompt = ChatPromptTemplate.from_messages([
    ("system", "Sei un assistente. Rispondi in modo conciso."),
    ("human", "{input}")
])
chain = prompt | llm
result = chain.invoke({"input": "Dove è il mio pacco?"})
print(result.content)

Ogni invocazione di chain.invoke produce un trace completo. Puoi vedere la durata, i token, e persino il contenuto del prompt inviato all'API.

Integrazione manuale senza LangChain (SDK nativo)

from langsmith import Client
import openai

client = Client()
openai.api_key = "sk-..."

with client.trace(
    project_name="custom-app",
    run_type="llm",
    name="gpt-call"
) as rt:
    response = openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Ciao"}]
    )
    rt.end(outputs={"response": response.choices[0].message.content},
            inputs={"messages": [{"role": "user", "content": "Ciao"}]})

Esempi pratici di debugging con LangSmith: trace session e feedback

Un caso reale: un chatbot per un'azienda di moda. L'AI doveva rispondere su taglie e disponibilità. A volte rispondeva correttamente, altre volte diceva "prodotto non trovato". Abbiamo abilitato il tracing e scoperto che il retriever usava un campo description vuoto per alcuni prodotti. Il trace mostrava il contesto recuperato: zero documenti. Risolto popolando le descrizioni mancanti.

Usare le sessioni per debuggare flussi multi-turn

LangSmith supporta le sessioni: puoi raggruppare più run sotto un unico identificatore (es. conversazione utente). Così vedi l'intera conversazione: ogni messaggio è un run con padre la sessione. Noi lo usiamo per analizzare dove l'AI perde il filo dopo tre turni.

with client.trace(
    project_name="conversation-demo",
    run_type="session",
    name="user-1234-session"
) as session:
    for turn in ["Ciao", "Voglio un maglione rosso", "Taglia M"]:
        with session.run(
            run_type="llm",
            name=f"turn-{turn[:5]}"
        ) as run:
            response = llm.invoke(turn)
            run.end(outputs={"response": response.content})

Cosa fare adesso

1. Attiva LangSmith oggi — Vai su smith.langchain.com, crea un account gratuito (fino a 1.000 run/giorno) e ottieni la tua API key. Imposta LANGCHAIN_API_KEY e LANGCHAIN_PROJECT nel tuo ambiente di sviluppo.
2. Identifica un flusso critico — Scegli una pipeline che usi in produzione o in test. Aggiungi il tracing con il context manager o abilita LANGCHAIN_TRACING_V2 = true. Esegui una chiamata e guarda il trace in tempo reale.
3. Configura un alert su errori — LangSmith permette webhook. Collega Slack o email per ricevere notifiche quando il tasso di errore supera una soglia. Noi lo usiamo per intervenire prima che il cliente se ne accorga.
4. Invia feedback di costo — Dopo ogni run, calcola il costo (token * prezzo per token) e invialo come feedback. In pochi giorni avrai un cruscotto economico.
5. Approfondisci con la Pillar Guide — Se vuoi padroneggiare LangChain dalla A alla Z, leggi la nostra Pillar Guide su LangChain e LLM per sviluppatori.

LangSmith ti dà la visibilità che manca quando gestisci un sistema AI in produzione. Noi non lo consideriamo più un extra: è il cruscotto che ci permette di dormire sonni tranquilli, sapendo che ogni token speso è tracciato e ogni anomalia è sotto controllo.