JSON affidabile dagli LLM: schemi, validazione, retry
Ottenere JSON valido da un LLM richiede più che chiederlo con gentilezza: schemi, output strutturato, validazione e retry, e gli errori più comuni da evitare.
In questo articolo
- Perché i modelli rompono il JSON?
- Passo 1: descrivi l'output con precisione nel prompt
- Passo 2: usa la funzione di output strutturato dell'API
- Passo 3: valida tutto, anche con l'imposizione dello schema
- Passo 4: riprova con l'errore, non a caso
- Dove mettere il ragionamento in una risposta JSON?
- Errori comuni nel disegno degli schemi di output
- Il solo prompting basta mai?
Per ottenere JSON affidabile da un modello linguistico, definisci la struttura come JSON Schema, usa la funzione di output strutturato del fornitore dove è disponibile, valida ogni risposta nel codice e riprova con l'errore di validazione quando fallisce. La sola formulazione del prompt ti porta a buon punto; gli ultimi punti percentuali di affidabilità vengono dall'API e dalla tua validazione.
La distinzione conta perché "a buon punto" non basta per il codice. Un parser che fallisce sul 2% delle risposte significa una funzione rotta per qualcuno ogni pochi minuti, su larga scala.
Perché i modelli rompono il JSON?
Prima di risolvere, conviene sapere cosa va davvero storto. Più o meno nell'ordine in cui li incontrerai:
- Blocchi markdown. Il modello restituisce
```json ... ```perché i modelli di chat sono addestrati a presentare bene il codice. - Premesse chiacchierone. "Certo! Ecco il JSON che hai richiesto:" seguito dall'oggetto.
- Chiavi sbagliate o inventate.
customerNameinvece dicustomer_name, o un camponotesin più che non avevi chiesto. - Tipi sbagliati.
"price": "19.99"come stringa,"count": "three", un singolo oggetto dove volevi un array. - Troncamento. La risposta raggiunge il limite massimo di token e si ferma a metà oggetto.
- Nonsenso sintatticamente valido. JSON perfetto, contenuto sbagliato: una data nel formato sbagliato, un numero di telefono allucinato,
nulldove il valore era lì nell'input.
Le funzioni di output strutturato eliminano i primi cinque, per lo più. Nulla elimina il sesto tranne buoni prompt, grounding e controlli.
Passo 1: descrivi l'output con precisione nel prompt
Anche con lo schema imposto, il prompt è il posto dove spieghi cosa significa ogni campo. Uno schema dice che due_date è una stringa; solo il prompt può dire che dev'essere in ISO 8601 e che le date relative vanno risolte rispetto alla data di invio dell'email.
Un prompt debole:
Estrai i dettagli della fattura da questa email come JSON.
Uno più solido:
Estrai i dettagli della fattura dall'email qui sotto.
Restituisci un singolo oggetto JSON con esattamente queste chiavi:
- "vendor": stringa, l'azienda che ha emesso la fattura
- "invoice_number": stringa, come scritta (mantieni gli zeri iniziali)
- "total": numero, nella valuta della fattura, senza simbolo di valuta
- "currency": stringa, codice ISO 4217 come "USD" o "EUR"
- "due_date": stringa nel formato YYYY-MM-DD, oppure null se non indicata
Se un valore non è nell'email, usa null. Non tirare a indovinare.
Restituisci solo l'oggetto JSON, senza markdown e senza spiegazioni.
<email>
{{email_text}}
</email>
Due dettagli pesano molto. "Mantieni gli zeri iniziali" impedisce al modello di trasformare "per comodità" 00417 in 417. E "usa null, non tirare a indovinare" dà al modello una via d'uscita legittima. Senza un'opzione null esplicita, un modello con un campo obbligatorio inventerà un valore plausibile invece di lasciarlo vuoto.
Passo 2: usa la funzione di output strutturato dell'API
La maggior parte dei grandi fornitori offre ormai un modo per vincolare l'output a uno schema. Nomi e dettagli differiscono e cambiano nel tempo, quindi controlla la documentazione aggiornata, ma le opzioni principali sono queste:
- OpenAI ha un JSON mode di base che garantisce JSON sintatticamente valido, e gli Structured Outputs, dove passi un JSON Schema con strict mode e l'output è vincolato a rispettarlo.
- Google Gemini permette di impostare il MIME type della risposta su JSON e di fornire uno schema di risposta.
- Anthropic permette di definire uno strumento con uno schema di input e far sì che Claude lo chiami, ottenendo argomenti conformi allo schema; la documentazione descrive anche un supporto nativo all'output strutturato.
La distinzione importante è JSON mode contro schema enforcement. Il JSON mode promette solo che il testo si possa interpretare. Le tue chiavi possono comunque essere sbagliate. L'imposizione dello schema (spesso con constrained decoding, che limita quali token il modello può generare di volta in volta) promette la forma.
Uno schema per l'esempio della fattura:
{
"type": "object",
"properties": {
"vendor": { "type": ["string", "null"] },
"invoice_number": { "type": ["string", "null"] },
"total": { "type": ["number", "null"] },
"currency": { "type": ["string", "null"], "enum": ["USD", "EUR", "GBP", null] },
"due_date": { "type": ["string", "null"], "description": "YYYY-MM-DD" }
},
"required": ["vendor", "invoice_number", "total", "currency", "due_date"],
"additionalProperties": false
}
Nota i tipi nullable. Nelle modalità strict di solito ogni campo è obbligatorio, quindi "facoltativo" va espresso come "obbligatorio ma può essere null". Nota anche additionalProperties: false, che blocca i campi a sorpresa. Le modalità strict di solito supportano solo un sottoinsieme di JSON Schema, quindi controlla quali parole chiave sono ammesse prima di costruire qualcosa di elaborato.
Se usi Python o TypeScript, definisci lo schema come modello Pydantic o schema Zod e genera il JSON Schema da quello. Così la stessa definizione valida la risposta e le due cose non possono divergere.
Passo 3: valida tutto, anche con l'imposizione dello schema
L'imposizione dello schema garantisce la struttura. Non garantisce:
- che
due_datesia una data reale (il 30 febbraio è una stringa valida), - che
totalcorrisponda alla somma delle righe, - che
vendorcompaia da qualche parte nell'email di partenza, - che il modello non abbia saltato la terza riga di cinque.
Scrivi i controlli che contano per il tuo dominio. Interpreta le date. Verifica che i totali non siano negativi. Nei compiti di estrazione, controlla che le stringhe estratte compaiano davvero nell'input; questo solo test intercetta una quantità sorprendente di allucinazioni.
Passo 4: riprova con l'errore, non a caso
Quando la validazione fallisce, non rimandare semplicemente la stessa richiesta sperando bene. Rimanda l'errore:
La tua risposta precedente non ha superato la validazione:
- "due_date": "3 marzo" non corrisponde al formato YYYY-MM-DD
- "currency": "dollari" non è uno tra USD, EUR, GBP
Restituisci solo l'oggetto JSON corretto.
I modelli correggono bene gli errori specifici e nominati. Limita i retry a uno o due, registra ogni fallimento e guarda i log ogni settimana. Fallimenti ripetuti sullo stesso campo di solito significano che il prompt o lo schema non sono chiari, non che il modello sia instabile. Librerie come Instructor (Python) racchiudono per te questo ciclo di validazione e retry, ma il meccanismo è abbastanza semplice da scriverlo da soli.
Per i guasti solo sintattici sui fornitori senza imposizione, un parser indulgente che rimuove i blocchi e il testo finale prima di JSON.parse copre i casi più comuni. Consideralo un ripiego, non una strategia.
Dove mettere il ragionamento in una risposta JSON?
Se il compito richiede giudizio (una classificazione con motivazione, un punteggio di rischio), metti un campo di ragionamento prima del campo della decisione:
{
"evidence": "Il cliente segnala un addebito duplicato sulla fattura di marzo.",
"category": "fatturazione",
"confidence": "alta"
}
I modelli generano i campi in ordine. Una decisione scritta per prima viene giustificata dopo, invece di essere informata dal ragionamento. Ne parliamo più a fondo in chain-of-thought prompting spiegato.
Il rovescio della medaglia: i campi di ragionamento costano token a ogni chiamata. Per l'estrazione semplice, lasciali fuori.
Errori comuni nel disegno degli schemi di output
Annidamento profondo senza motivo. Tre livelli di oggetti dove bastava un elenco piatto. Ogni livello è un altro posto dove il modello può sbagliare il valore.
Campi di testo libero che dovrebbero essere enum. Se il codice a valle si comporta in base a status, rendilo un enum. Altrimenti otterrai "In attesa", "in attesa", "In corso" e "da verificare" per la stessa cosa.
Nomi di campo ambigui. date su una fattura potrebbe essere la data di emissione, di scadenza o di pagamento. Chiamalo due_date e descrivilo.
Chiedere troppo in una sola chiamata. Uno schema con quaranta campi estratti da un contratto di venti pagine invita alle omissioni. Dividilo: una chiamata per sezione, oppure una chiamata per individuare i passaggi rilevanti e un'altra per estrarre da quelli.
Dimenticare il caso vuoto. Cosa deve restituire l'output se l'email non è affatto una fattura? Aggiungi un booleano is_invoice o ammetti un risultato vuoto, altrimenti il modello estrarrà una fattura da un invito a pranzo.
Il solo prompting basta mai?
Per i prototipi, gli script che lanci a mano o i modelli senza supporto all'output strutturato, sì. Una descrizione precisa del formato, un esempio dell'output esatto e un parser difensivo ti portano a un'alta affidabilità. Per qualsiasi cosa rivolta agli utenti, usa l'imposizione dello schema dove disponibile e la validazione sempre.
La competenza di fondo è la stessa in ogni caso: descrivi l'output in modo così preciso che ci sia un solo modo ragionevole di compilarlo. L'argomento output strutturato allena proprio queste decisioni, e se il JSON che produci è una chiamata a uno strumento e non una risposta finale, tool calling e agenti AI riparte da qui. Per l'estrazione basata su documenti di origine, vedi cos'è la RAG.
Domande frequenti
Come costringo un LLM a restituire JSON valido?
Usa la funzione di output strutturato del fornitore con un JSON Schema quando esiste, perché vincola la generazione allo schema. Poi valida comunque il risultato nel codice, e riprova o ripara quando la validazione fallisce.
Qual è la differenza tra JSON mode e structured outputs?
Il JSON mode fa produrre al modello JSON sintatticamente valido ma non garantisce le tue chiavi o i tuoi tipi. Gli structured outputs con schema rigoroso vincolano l'output a corrispondere allo schema che fornisci.
Perché il mio LLM avvolge il JSON in blocchi di codice markdown?
I modelli ottimizzati per la chat sono addestrati a formattare bene il codice per le persone. Di' al modello di restituire solo l'oggetto JSON grezzo, oppure usa una modalità di output strutturato, e rimuovi i blocchi nel parser per sicurezza.
Devo validare il JSON di un LLM anche con uno schema?
Sì. Uno schema garantisce la forma, non la verità. Il JSON può essere perfettamente valido e contenere comunque una data sbagliata, un valore inventato o un campo vuoto dove i dati c'erano.
- #output strutturato
- #JSON
- #JSON schema
- #validazione