JSON Toolkit

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.

Pratico~5 min di letturaPubblicato il 2026-11-14Aggiornato il 2026-11-14
Schema di chiusura a pila del JSON troncato: scansione consapevole delle stringhe e completamento tramite stack di parentesi

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.

Riferimenti

Strumenti correlati

Articoli correlati

Guida alla riparazione JSON: recuperare gli output LLM rotti senza perdere fiducia

Gli output LLM avvolti in recinti markdown, con virgole finali e letterali Python, non sopravvivono a un parser rigoroso — nemmeno le config modificate a mano senza virgolette. Questa guida traccia il confine reale tra nove classi di errori che un riparatore corregge e quattro che non correggerà mai, spiega perché le macchine a stati battono le regex e fornisce una catena di parsing pronta per la produzione con jsonrepair e json-repair.

Intermedio~6 min di letturaAggiornato il 2026-11-08

Guida al formato TOON: alleggerire il JSON prima di darlo a un LLM

Quando passi un array uniforme a un modello linguistico in formato JSON, i nomi delle chiavi ripetuti e le parentesi consumano token. TOON dichiara la struttura una sola volta con oggetti indentati e array tabellari, e scarica i dati riga per riga. I benchmark ufficiali mostrano circa il 40% di token in meno con maggiore accuratezza di parsing. Questa guida copre la sintassi, quando il risparmio si applica, quando non conviene convertire e come collegare encode e decode.

Intermedio~6 min di letturaAggiornato il 2026-11-10

Test contrattuali JSON Schema: salda le regole di validazione nella CI

Uno schema non finisce quando è scritto — lì inizia il degrado. Un refuso rilassa la validazione in silenzio, un refactoring rompe tutte le fixture. Questa guida illustra un'impostazione di test contrattuali attuabile: fixture positivi, negativi e snapshot, lint dello schema stesso, compilazione una tantum riutilizzata e quattro porte CI che trasformano la rottura del contratto in una build rossa.

Intermedio~8 min di letturaAggiornato il 2026-11-05