Capitolo 3 — Output strutturati: quando la risposta la legge un programma
Cambio di prospettiva fondamentale: finora le risposte del modello le leggevi tu. Da questo capitolo in poi, le leggerà un altro programma. E i programmi non tollerano la prosa: hanno bisogno di struttura — campi con un nome, valori di un tipo previsto. Il formato standard è il JSON: {"categoria": "reclamo", "urgenza": 4, "riassunto": "..."}.
Il problema è che il modello è una macchina probabilistica, e la probabilità ama chiacchierare. Chiedi JSON e ricevi "Certo! Ecco il JSON richiesto:" seguito dal JSON — e quel preambolo manda in errore il tuo parser. Oppure ricevi un JSON con una virgola fuori posto, o con un campo inventato che non avevi chiesto.
La disciplina per domarlo cresce in quattro gradini. Uno: chiedi JSON con lo schema esplicito nel prompt — elenca i campi, i tipi, i valori ammessi, e mostra un esempio (il few-shot del Livello 1 al lavoro). Due: usa il prefilling — inizi tu la risposta con {, e il preambolo chiacchierone muore prima di nascere. Tre: dove disponibile, usa lo structured output nativo dell'API, che vincola il modello allo schema. Quattro, il gradino che non si salta mai: valida comunque. Il tuo codice fa il parsing dentro una rete di sicurezza, controlla lo schema (in Python, Pydantic è lo strumento classico), e se qualcosa non torna riprova — rimandando al modello l'errore ricevuto. Curiosità professionale: il retry con il messaggio d'errore incluso funziona sorprendentemente bene; il modello legge l'errore e si corregge.
La regola da tatuarsi: mai fidarsi del parsing. Non perché il modello sia scarso, ma perché il tuo programma deve funzionare anche l'uno per cento delle volte in cui l'output è storto. L'affidabilità non è mai del modello: è del sistema che ci costruisci intorno. Questa frase è il riassunto dell'intero livello.
L'esperimento del giorno. Scrivi lo script che prende un testo libero — una richiesta di un cliente, una email — e restituisce JSON validato: categoria, urgenza, riassunto, azione suggerita. Sparagli addosso dieci input veri, anche cattivi (testo vuoto, mezza riga, un papiro). Conta quante volte il parsing fallirebbe senza la rete di sicurezza.
Fonti
- Structured outputs — Anthropic (Claude API) — come vincolare la risposta a uno schema dal lato API, invece di sperare che il prompt basti.
- Structured model outputs — OpenAI — schema JSON, campi obbligatori e limiti: cosa lo structured output garantisce davvero e cosa resta da validare nel tuo codice.
Correlati. JSON affidabile da un LLM · Tool use