BroadRouter

JSON non valido da un LLM: cause, riparazione e retry

A cura del team di BroadNet Inference · 7 min di lettura · Pubblicato · Aggiornato

Controlla prima finish_reason: una risposta tagliata a max_tokens non si può riparare in sicurezza, quindi alza il limite e reinvia. Altrimenti togli le code fence e il testo intorno, decodifica il primo valore JSON e correggi solo gli errori non ambigui, come le virgole finali. Valida rispetto a uno schema e, se fallisce, rimanda l’errore esatto una o due volte. Dove è supportato, l’output strutturato evita quasi tutto questo.

Il tuo codice chiama json.loads() sulla risposta di un modello e ottiene JSONDecodeError: Expecting value: line 1 column 1. Oppure il parsing riesce, ma un campo è una stringa dove volevi un numero. Questo articolo ordina le cause in base a cosa puoi fare in sicurezza per ciascuna, offre una funzione Python testata che ripara solo i casi non ambigui e mostra un ciclo di retry che sa quando un nuovo tentativo non può servire.

La scelta tra JSON mode e json_schema è trattata in JSON mode o json_schema. Qui parliamo di cosa fare con la risposta che hai davvero ricevuto.

Perché gli LLM restituiscono JSON non valido?

Un modello scrive il testo un token alla volta. Se il server non vincola la decodifica, niente gli impedisce di aggiungere una frase cordiale o di finire lo spazio. I fallimenti più comuni:

Cosa vedi Causa Si può riparare in sicurezza nel codice?
```json … ``` intorno all’oggetto Abitudine di formattazione da chat Sì: togli la fence
“Here is the JSON:” prima, “Let me know…” dopo Stessa abitudine Sì: leggi solo il primo valore
<think>...</think> prima dell’oggetto Testo di ragionamento nel campo content su alcuni server Sì: rimuovi il blocco
Finisce a metà stringa, parentesi aperte Raggiunto max_tokens No: reinvia con più spazio
Content vuoto Il ragionamento ha usato tutto il budget No: reinvia con più spazio
{"a": 1,} Virgola finale; JavaScript la ammette, RFC 8259 no Sì: un solo significato
{'a': True, 'b': None} Sintassi Python Sì: ast.literal_eval la legge in sicurezza
NaN, Infinity Non è JSON; Python li accetta per impostazione predefinita No: scarta
JSON valido, tipi sbagliati o campi mancanti Schema non imposto No: richiedi passando l’errore

Il confine è l’ambiguità. Se il modello poteva intendere una sola cosa, correggila nel codice e registra che l’hai fatto. Se dovresti tirare a indovinare, scarta la risposta.

Perché non riparare il JSON troncato?

Perché la versione riparata sembra corretta e non lo è. Abbiamo eseguito json_repair 0.64.9, una libreria diffusa con licenza MIT, su una risposta tagliata a metà parola:

'{"name": "Omar", "city": "Jed'  ->  {'name': 'Omar', 'city': 'Jed'}

Ha restituito JSON valido con la città “Jed”. Il suo README lo dice apertamente: «automatically completes missing values in JSON fields with reasonable defaults» (traduzione: completa automaticamente i valori mancanti nei campi JSON con valori predefiniti ragionevoli). È utile per leggere i log. Per i dati che salvi o su cui agisci, trasforma un errore visibile in un errore silenzioso.

Controlla finish_reason prima del parsing. "length" significa che la risposta ha raggiunto max_tokens. Reinviare la stessa richiesta con lo stesso limite fallisce allo stesso modo, quindi raddoppia il limite o chiedi meno per chiamata. I modelli di ragionamento rendono il caso più frequente: il riferimento API di BroadNet dice che DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max_tokens. Con un limite basso la risposta può tornare vuota. Lascia almeno 1.000 token, oppure imposta reasoning_effort a low; i numeri sono nell’articolo sul budget di ragionamento.

Una funzione di riparazione che corregge solo i casi sicuri

Usa solo la libreria standard. Restituisce il valore parsato e l’elenco delle riparazioni fatte, così puoi contarle.

import ast, json, re

class Truncated(Exception): pass
class NotJSON(Exception): pass

FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)

def _reject_constant(name):                 # NaN, Infinity: Python accepts them, JSON does not
    raise NotJSON(f"non-standard constant {name}")

_decoder = json.JSONDecoder(parse_constant=_reject_constant)

def _first_value(s):
    """Decode the first JSON object or array in s, ignoring prose before and after it."""
    for i, ch in enumerate(s):
        if ch in "{[":
            try:
                return _decoder.raw_decode(s, i)[0]
            except json.JSONDecodeError:
                continue                    # a stray brace in prose; try the next one
    raise NotJSON("no JSON object or array found")

def _scan(s):
    """Drop commas before } or ] outside strings; report brackets left open."""
    out, stack, in_str, esc = [], [], False, False
    for i, ch in enumerate(s):
        if in_str:
            if esc:
                esc = False
            elif ch == "\\":
                esc = True
            elif ch == '"':
                in_str = False
        elif ch == '"':
            in_str = True
        elif ch in "{[":
            stack.append(ch)
        elif ch in "}]" and stack:
            stack.pop()
        elif ch == ",":
            rest = s[i + 1:].lstrip()
            if rest[:1] in ("}", "]"):
                continue                    # trailing comma: skip it
        out.append(ch)
    return "".join(out), len(stack) + (1 if in_str else 0)

def _python_literal(s):
    """Output in Python syntax: single quotes, True/False/None, trailing commas."""
    start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
    end = max(s.rfind("}"), s.rfind("]"))
    if start < 0 or end <= start:
        raise NotJSON("no braces")
    value = ast.literal_eval(s[start:end + 1])       # literals only; never runs code
    if not isinstance(value, (dict, list)):
        raise NotJSON("not an object or array")
    json.dumps(value, allow_nan=False)               # must round-trip as strict JSON
    return value

def parse_llm_json(content, finish_reason=None):
    """Return (value, repairs). Raises Truncated or NotJSON."""
    if finish_reason == "length":
        raise Truncated("hit max_tokens; raise the limit or shorten the output")
    if not content or not content.strip():
        raise NotJSON("empty content (reasoning may have used the whole budget)")
    repairs = []
    s = content.strip().lstrip("\ufeff")
    if THINK.search(s):
        s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
    m = FENCE.search(s)
    if m:
        s = m.group(1).strip(); repairs.append("removed code fence")
    try:
        value = _decoder.decode(s)
        return value, repairs
    except json.JSONDecodeError:
        pass
    try:
        value = _first_value(s); repairs.append("ignored text around JSON")
        return value, repairs
    except NotJSON:
        pass
    fixed, open_count = _scan(s)
    if open_count:
        raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
    if fixed != s:
        try:
            value = _first_value(fixed); repairs.append("removed trailing commas")
            return value, repairs
        except NotJSON:
            pass
    try:
        value = _python_literal(s); repairs.append("parsed Python-style literal")
        return value, repairs
    except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
        raise NotJSON(f"unrepairable: {e}") from None

Come funziona ogni passaggio:

  1. Troncamenti e risposte vuote sollevano un’eccezione prima di qualsiasi parsing, quindi non diventano mai dati.
  2. Fence e blocchi di ragionamento vengono rimossi con due espressioni regolari.
  3. raw_decode è lo strumento chiave. La documentazione di Python dice che decodifica un documento «from a string that may have extraneous data at the end» (traduzione: da una stringa che può avere dati estranei alla fine) e restituisce il punto in cui si è fermato. Partendo dalla prima { o [, salta il testo prima dell’oggetto e ignora quello dopo. Se una parentesi graffa nel testo non si decodifica, prova la successiva.
  4. La scansione delle parentesi percorre il testo tenendo traccia di stringhe ed escape. Parentesi rimaste aperte significano che la risposta è stata tagliata anche se finish_reason non lo dice; in quel caso solleva un’eccezione. Le virgole subito prima di } o ] fuori dalle stringhe vengono eliminate.
  5. ast.literal_eval legge l’output in stile Python con apici singoli, True e None. Valuta solo letterali e non esegue mai codice. Il risultato deve poi serializzarsi come JSON rigoroso.
  6. NaN e Infinity sollevano un’eccezione, tramite parse_constant. Il modulo json di Python li accetta per impostazione predefinita; RFC 8259 dice che «are not permitted» (traduzione: non sono ammessi), e JSON.parse di JavaScript li rifiuta.

L’abbiamo provata su 17 stringhe di test: JSON pulito, JSON in una fence, chiavi e valori in arabo dentro una fence, testo prima e dopo, un segnaposto {name} nel testo prima dell’oggetto, un blocco <think>, virgole finali in oggetti e array, virgole e parentesi dentro le stringhe, virgolette con escape, un percorso Windows che finisce con una barra rovesciata, letterali Python, NaN, una risposta vuota, una risposta tagliata con e senza finish_reason: "length" e due oggetti di seguito. Tutte si sono comportate come dice la tabella sopra. Un test ha trovato un bug vero: una prima versione invertiva il flag di escape prima di controllare la virgoletta di chiusura, quindi "he said \"hi,]\"" perdeva la virgola. Prova il tuo codice di riparazione sulle virgolette con escape.

Due limiti da conoscere. Con due oggetti di seguito restituisce il primo; se vuoi più elementi, chiedi un unico array JSON. E un output Python con apici singoli che contiene una virgoletta doppia dentro una stringa può essere letto male dalla scansione delle parentesi e scartato. Scartare è il fallimento sicuro.

Come fare retry quando la riparazione fallisce?

La riparazione si occupa del formato. La validazione si occupa del contenuto: campi giusti, tipi giusti, valori sensati. Questo ciclo valida con il pacchetto jsonschema e sceglie il retry in base alla causa:

import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON

client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
                api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
          "required": ["name", "city", "amount"],
          "properties": {"name": {"type": "string", "minLength": 1},
                         "city": {"type": ["string", "null"]},
                         "amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)

def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
    messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
                                              "Schema: " + json.dumps(SCHEMA)},
                {"role": "user", "content": text}]
    for attempt in range(1, attempts + 1):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
                                           reasoning_effort="low", temperature=0)
        c = r.choices[0]
        try:
            value, repairs = parse_llm_json(c.message.content, c.finish_reason)
            errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
            if not errors:
                log({"attempt": attempt, "repairs": repairs, "ok": True})
                return value
            problem = "The JSON does not match the schema: " + "; ".join(errors)
        except Truncated:
            log({"attempt": attempt, "ok": False, "why": "truncated"})
            max_tokens *= 2                 # same prompt, more room; a re-ask would be cut off too
            continue
        except NotJSON as e:
            problem = f"That reply was not valid JSON ({e})."
        log({"attempt": attempt, "ok": False, "why": problem})
        messages += [{"role": "assistant", "content": c.message.content or ""},
                     {"role": "user", "content": problem + " Return the corrected JSON object only."}]
    raise RuntimeError(f"no valid JSON after {attempts} attempts")

Le regole di quel ciclo:

  • Troncato: reinvia gli stessi messaggi con il limite raddoppiato. Aggiungere un messaggio “per favore correggi” allungherebbe il prompt senza accorciare l’output.
  • Non è JSON, o ha la forma sbagliata: rimanda l’errore esatto. “amount: ‘1200’ is not of type ‘number’” dà al modello qualcosa di preciso da correggere. Un retry senza spiegazioni spesso ripete l’errore.
  • Massimo tre tentativi. Ogni retry reinvia l’intera conversazione come token di input. Dopo tre, registra l’input e instradalo altrove.
  • Registra l’elenco delle riparazioni. Se dopo una modifica al prompt crescono i “removed code fence”, il prompt è peggiorato, anche se nulla è fallito.

Abbiamo eseguito questo ciclo contro un server mock locale che riproduceva risposte preparate. Una risposta in fence con una virgola finale e "amount": "1200" come stringa è stata riparata, ha fallito la validazione ed è stata corretta alla seconda chiamata rimandando l’errore. Una risposta tagliata con finish_reason: "length" è stata reinviata con max_tokens alzato da 1.500 a 3.000 ed è riuscita. Il mock ha registrato ogni richiesta, confermando il numero di messaggi e il limite inviati dal ciclo. Un modello reale può fallire in modi diversi, quindi provalo su 100 dei tuoi input prima di fidarti dei numeri.

L’output strutturato rende tutto questo inutile?

Ne elimina la maggior parte. Un server che vincola la decodifica al tuo schema non può emettere una fence, una virgola finale o un campo mancante. vLLM, un server diffuso per modelli aperti, lo fa con i backend xgrammar o guidance. Anche così restano due fallimenti: il troncamento a max_tokens e i rifiuti. OpenAI nota che l’output in JSON mode è valido «except for in some edge cases» (traduzione: salvo alcuni casi limite) e che la tua applicazione «must detect and handle» (traduzione: deve rilevare e gestire) un output che non sia un oggetto completo. Quindi tieni il controllo su finish_reason e il validatore, anche con json_schema.

Cosa evita ciascun approccio:

Approccio Fence e testo Errori di sintassi Forma sbagliata Troncamento
Solo prompt (“rispondi in JSON”) Ridotti Ridotti Ridotta No
JSON mode (json_object) Sì Sì No No
Output strutturato (json_schema, imposto) Sì Sì Sì No

Con il JSON mode, OpenAI dice anche che «must always instruct the model to produce JSON» (traduzione: devi sempre istruire il modello a produrre JSON) in un messaggio; altrimenti può emettere spazi bianchi fino al limite di token. Gli altri server compatibili con OpenAI variano, quindi prova la modalità sul modello che metti in produzione. Il test è nell’articolo sull’output strutturato.

Per controllare una risposta a mano, incollala nel validatore di output JSON per LLM, oppure crea uno schema rigoroso da un oggetto di esempio con il generatore di JSON schema.

Dove si inserisce BroadNet Inference

BroadRouter è il sito di BroadNet. Il riferimento API di BroadNet indica l’output strutturato solo per GLM 5.3 e Qwen3.8 27B e non nomina il parametro della richiesta, quindi prova json_schema sul modello prima di farci affidamento. Su DeepSeek V4.1 Flash e Gemma 4 VL 26B usa JSON chiesto nel prompt con la funzione di riparazione e il validatore visti sopra. Tre dei quattro modelli ragionano prima di rispondere, quindi prevedi spazio in max_tokens. Per l’estrazione in blocco, l’articolo sul batch runner mostra come registrare finish_reason per ogni elemento. Prompt e risposte non vengono conservati dopo ogni richiesta.

Domande frequenti

Perché il mio LLM restituisce il JSON dentro un blocco di codice markdown?

I modelli di chat di solito formattano il codice per le persone, e la code fence è il modo in cui le interfacce di chat lo mostrano. Chiedi “solo JSON, senza code fence”, ma togli comunque le fence nel codice: l’istruzione riduce la frequenza, non la azzera.

Come risolvo JSONDecodeError sull’output di un LLM?

Guarda prima finish_reason. Se è "length", la risposta è stata tagliata: alza max_tokens e reinvia. Altrimenti togli le code fence e decodifica il primo valore JSON con raw_decode, che ignora il testo successivo. Correggi le virgole finali, poi valida. Se fallisce ancora, richiedi passando l’errore.

Conviene usare una libreria di riparazione JSON?

Per log e debug, sì. Per i dati su cui agisci, attenzione. Librerie come json_repair completano i valori mancanti con valori predefiniti, quindi una città troncata “Jed” torna come “Jed” valido. Scarta l’output troncato e reinvia.

Perché l’output JSON del mio LLM è tagliato?

La risposta ha raggiunto max_tokens. Sui modelli di ragionamento come DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B il ragionamento conta in quel limite, quindi un ragionamento lungo può lasciare troppo poco spazio. Alza il limite, imposta reasoning_effort low o chiedi meno output per chiamata.

Il JSON mode garantisce un JSON valido?

Quasi. OpenAI dice che l’output in JSON mode è JSON valido “except for in some edge cases” (traduzione: salvo alcuni casi limite), come il raggiungimento del limite di token, e non impone il tuo schema. L’output strutturato con json_schema aggiunge l’aderenza allo schema dove il provider la impone. Valida in ogni caso.

Quali modelli BroadNet supportano l’output strutturato?

Il riferimento API di BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B, verificato il 15 novembre 2026. Non lo indica per DeepSeek V4.1 Flash né per Gemma 4 VL 26B, quindi su questi usa JSON chiesto nel prompt con riparazione e validazione.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity