Il JSON dell'LLM è troncato: prima guarda il motivo di arresto, poi parla di riparazione
In sintesi: Il JSON restituito dal modello manca della chiusura e il parser offre solo un numero di colonna: aggiungere le parentesi fa girare il codice, ma il buco finisce nascosto nei dati. Questo articolo traccia il confine tra ciò che si può riparare e ciò che richiede un retry negli scenari di troncamento: diagnosi dal motivo di arresto, dimensionamento dell'output su p99, ordinamento dei campi dello schema e divulgazione onesta del recupero parziale.

Il troncamento non è un errore di sintassi, è un dato incompleto. La sintassi rotta si ripara; il troncamento si recupera solo in parte — nel momento in cui il riparatore chiude il varco, il resto del varco passa da "errore di parsing" a "nessuno lo sa".
Che aspetto ha il troncamento: un numero di colonna non ti salva
Il modello restituisce il JSON secondo il tuo schema, a metà generazione urta il limite di output e il testo si interrompe di colpo. Collaudando con il modulo json di Python 3.11 un input di questo tipo:
{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"
json.loads segnala Expecting ':' delimiter, col 94 — la colonna punta alla posizione in cui manca il valore dopo "qty", ma la vera malattia è che l'intero documento non ha fine. Sullo stesso input, aggiungere con una regex avida una chiusura "} fa fallire subito il parsing; con la chiusura a pila consapevole delle stringhe (sesta sezione) il parsing riesce, ma items si riduce a 2 elementi e il terzo record incompleto viene scartato. Il numero di colonna ti dice "dove si è spezzato", non ti dice "quanto si è perso".
Questa è la prima differenza tra troncamento e un normale errore JSON: non ha un punto d'arrivo chiaro della riparazione. Una virgola finale, una volta corretta, rende il documento completo; un troncamento, una volta "corretto", lascia comunque un esemplare mutilato.
Troncamento e sintassi rotta non sono la stessa cosa: il punto cieco dei riparatori
L'obiettivo di un riparatore (come jsonrepair) è trasformare JSON sintatticamente rotto in JSON legale: togliere i recinti markdown, eliminare le virgole finali, convertire le virgolette singole in doppie. In questi scenari l'"intento" è completo e la riparazione è solo pulizia. L'input troncato agli occhi del riparatore è comunque "JSON rotto", quindi chiude allo stesso modo la stringa incompiuta, gli array e gli oggetti, restituendo un risultato che passa il parsing — degli 83 report Claude troncati, il riparatore ne ha "riparati" 79, con soli 4 fallimenti duri. Il tasso di errore visto dal monitoraggio era sottostimato di 20 volte.
Che aspetto ha il risultato riparato? La stringa di feedback della domanda 6 si ferma a metà frase, le domande da 7 a 9 sono sparite del tutto, l'array next_steps non esiste. La validazione Pydantic passa lo stesso, perché il campo ha un valore predefinito [] e la lista non ha vincoli di lunghezza. Ogni livello funziona correttamente e il prodotto finale è un report sbagliato ma sicuro di sé. La logica di riparazione sintattica, portata nello scenario del troncamento, passa da "pulizia" a "falsificazione".
Quindi il confine va tracciato subito: il riparatore deve occuparsi solo delle macchie di formato su risposte complete; l'output interrotto non deve entrare nel riparatore. Come si correggono le macchie di formato simili, lo trovi nella Guida alla riparazione JSON di questo sito.
Il primo passo è sempre guardare il motivo di arresto
Tutte le API principali ti dicono nei metadati della risposta perché si è fermato il generatore: il campo esiste ed è gratuito, ed è però la riga di codice più ignorata. In Anthropic è stop_reason, nelle versioni precedenti di OpenAI è finish_reason; il valore max_tokens significa troncamento, mentre end_turn/stop indicano la fine naturale:
resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
raise TruncatedOutput(
f"stop_reason={resp.stop_reason}, "
f"output_tokens={resp.usage.output_tokens}"
)
data = json.loads(resp.content[0].text)
Trasformato il troncamento in un'eccezione esplicita, il percorso di retry ha finalmente una condizione di innesco e il monitoraggio una fonte di allarme. Gli 83 report citati prima sono stati recuperati proprio dal campo stop_reason nei log — i metadati erano sempre stati salvati, solo che nessuno li aveva mai letti. Analogamente, valori come length e incomplete hanno lo stesso significato nelle risposte di Google e OpenAI: quando colleghi un nuovo fornitore, verifica prima questa tabella di corrispondenza invece di tirare a indovinare.
max_tokens non è un budget: dimensiona il tetto sul caso peggiore
La causa diretta del troncamento è di solito un tetto di output fissato per un prodotto in fase iniziale: un cap di 1500 token, dopo il lancio delle sessioni lunghe, ha lasciato il 39% dei report lunghi a metà strada. Alzare il tetto è gratuito — la fatturazione conta solo i token effettivamente generati; un limite di 4096 su un report che ne usa realmente 1100 costa esattamente quanto un limite di 1500. Il limite serve a impedire output fuori controllo, non è una valvola di risparmio.
Metodo di dimensionamento: dopo il lancio, osserva per una settimana la distribuzione reale degli output e prendi il p99 con un margine. Nel post-mortem citato la scelta è stata 4096, perché il p99 misurato era 2350. L'altra direzione è comprimere l'output stesso: nei array omogenei la ripetizione dei nomi delle chiavi pesa la maggior parte dei token; prima di dare il testo al modello, convertilo in una codifica tabellare (vedi la Guida al formato TOON di questo sito): a parità di informazione risparmi quota considerevole e riduci alla fonte la probabilità di toccare il tetto.
L'ordine dei campi dello schema è l'ordine del troncamento
Il modello scrive il JSON dall'alto in basso: quando l'output si esaurisce, a essere tagliati sono sempre i campi in fondo allo schema. In uno schema di report didattico che mette scores dopo per_question_feedback, il troncamento elimina per primo proprio il punteggio che gli utenti si scattano per confrontarlo. La modifica è solo un riordino delle proprietà: i campi brevi e critici all'inizio, i dettagli lunghi e rigenerabili dopo, i testi liberi tipo notes in coda.
Le differenze di comportamento tra fornitori decidono anche lo stesso troncamento con conseguenze diverse:
| Fornitore | Modalità di output strutturato | Comportamento al troncamento |
|---|---|---|
| OpenAI | response_format + strict: true |
Garanzia a livello di campionamento, ma dialetto più ristretto; di solito rifiuta direttamente la generazione |
| Anthropic | input_schema del tool use |
Nessuna garanzia in fase di decodifica, può consegnare parentesi non chiuse |
| Gemini | responseSchema + MIME JSON |
In decodifica garantisce solo enum e tipi; il troncamento resta possibile |
Quindi "con lo structured output non serve validare" è un'illusione: più il vincolo del fornitore è lasco, più devi aggiungere dalla tua parte un ciclo di validazione dello schema con retry. Come costruire i test di contratto lo vedi nei Test di contratto JSON Schema.
Se serve davvero il recupero parziale: chiusura a pila consapevole delle stringhe
In certi scenari bisogna strizzare l'esemplare mutilato — visualizzazione in streaming, risposta degradata, revisione umana. In quel caso l'ultimo gradino della scala di riparazione è la chiusura, e deve soddisfare due condizioni. Primo: la scansione delle parentesi deve essere consapevole delle stringhe, carattere per carattere con stato di virgolette ed escape; altrimenti un { dentro un valore scombina la pila. Secondo: le coppie chiave-valore incompiute vanno eliminate prima di chiudere; quando dopo "qty" non c'è un valore, chiudere direttamente produrrebbe una struttura illegale come {"qty"} — la scelta giusta è buttare via la coppia intera.
def close_truncated(s: str) -> str:
# 1) scansione consapevole delle stringhe: se il taglio cade in mezzo a una stringa, prima si chiude la virgoletta
out, in_str, esc = [], False, False
for ch in s:
out.append(ch)
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str
text = ''.join(out) + ('"' if in_str else '')
# 2) rimozione delle coppie incomplete e dei due punti/virgole pendenti
text = re.sub(r',\s*"[^"]*"\s*$', '', text)
text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
text = re.sub(r'[:,\s*$', '', text)
# 3) nuova scansione della pila, chiusure in ordine last-in-first-out
stack, in_str, esc = [], False, False
for ch in text:
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str; continue
if not in_str:
if ch in '{[': stack.append(ch)
elif ch in '}]' and stack: stack.pop()
return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))
In locale, eseguendo questo codice (Python 3.11, solo libreria standard) sull'input mostrato all'inizio della sezione, l'output è {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} — parseabile, con il terzo record incompleto scartato. Sul versante dei modelli locali la pratica equivalente usa librerie dedicate come partial-json-parser, con la stessa idea: completare per pila, tagliare per completezza.
La parte decisiva è la divulgazione: la funzione di chiusura deve restituire un rapporto su "da quale gradino sono arrivata la riparazione", e il prodotto del livello truncation può essere etichettato solo come risultato parziale — chiedere l'intervallo mancante, ritentare con un tetto più alto, o dichiarare esplicitamente all'utente che i dati sono incompleti. Fingere in silenzio che nulla sia accaduto significa fabbricare allucinazioni con codice deterministico.
Cosa riparare e cosa ritentare: una tabella di confine
| Forma dell'input | Azione corretta | Motivo |
|---|---|---|
| Recinti, virgola finale, virgolette singole | Riparatore | Intento completo, solo sintassi sporca |
| Troncamento in mezzo a una stringa | Retry o recupero parziale + divulgazione | Il valore stesso è amputato, non si ricuce |
| Troncamento in mezzo a una struttura | Recupero parziale + divulgazione | Si salvano i campi completati, le coppie incomplete vanno eliminate |
| Parsing ok ma semantica sospetta | Validazione di business | Non c'entra col troncamento, ma spesso coesiste |
Il caso lato cinese delle fatture finanziarie quantifica il costo: dopo il troncamento di fatture lunghe, l'aggiunta delle parentesi produceva JSON legale, il campo total mancante assumeva il valore predefinito 0, e un sistema con un tasso di conformità di formato del 98,2% sbagliava circa 200 fatture al mese; passando al degrado immediato al troncamento e aggiungendo un controllo di identità sul totale, il tasso di errore sugli importi è sceso dallo 0,8% allo 0,02%. Ottimizzare per tre mesi il "tasso di conformità di formato" era una direzione sbagliata dall'inizio: ciò che passa al parser non è ciò che passa al business.
Quattro punti per la messa in produzione: controlla il motivo di arresto prima del parsing; dimensiona il tetto sul p99, non risparmiare sul budget; metti i campi critici dello schema all'inizio; lascia al riparatore solo le macchie di formato delle risposte complete. Con tutte e quattro le regole applicate, il troncamento torna da corrosione silenziosa dei dati a un fallimento rumoroso e ritentabile.
Un JSON troncato con le parentesi chiuse si può usare direttamente?
No, non direttamente. La chiusura garantisce solo la legalità sintattica, i dati restano un esemplare mutilato: la stringa interrotta si ferma a metà frase, l'ultimo record viene scartato, i campi che dipendono dai valori predefiniti non contengono valori reali. La strada giusta è etichettare il prodotto della chiusura come risultato parziale, innescare retry o degrado, e registrare il tasso di recupero.
Come capire se un JSON è troncato e non scritto male
Guarda il campo del motivo di arresto nei metadati della risposta: max_tokens/length/incomplete indicano troncamento; se invece end_turn/stop e il parsing fallisce, è un problema di sintassi. Senza metadati si può guardare la forma della fine del testo: interrotto in mezzo a virgolette o parentesi, ultimo livello di struttura non chiuso — è quasi sempre troncamento.
Perché il riparatore "ripara" i dati troncati in modo ancora più pericoloso
La funzione obiettivo del riparatore è "far passare il parsing", e il documento troncato una volta chiuso proprio ci riesce: così il monitoraggio degli errori resta a zero allarmi e la validazione a valle passa grazie ai valori predefiniti. Il meccanismo dei 83 report troncati con soli 4 errori segnalati è esattamente questo. Il riparatore non ha un concetto di intento e non sa quanto dato manca: per questo il troncamento va intercettato a monte.
Alzare max_tokens costa di più?
No. La fatturazione si basa sui token effettivamente generati; il limite è solo una valvola di sicurezza. Un tetto di 4096 su un output reale di 1100 token produce una bolletta identica a un tetto di 1500. Ciò che va davvero controllato è l'output fuori controllo: dimensiona il tetto sul p99 con un margine, e basta.