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:
- Troncamenti e risposte vuote sollevano un’eccezione prima di qualsiasi parsing, quindi non diventano mai dati.
- Fence e blocchi di ragionamento vengono rimossi con due espressioni regolari.
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.- 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_reasonnon lo dice; in quel caso solleva un’eccezione. Le virgole subito prima di}o]fuori dalle stringhe vengono eliminate. ast.literal_evallegge l’output in stile Python con apici singoli,TrueeNone. Valuta solo letterali e non esegue mai codice. Il risultato deve poi serializzarsi come JSON rigoroso.NaNeInfinitysollevano un’eccezione, tramiteparse_constant. Il modulojsondi Python li accetta per impostazione predefinita; RFC 8259 dice che «are not permitted» (traduzione: non sono ammessi), eJSON.parsedi 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.
