La JSON mode risponde a una domanda: json.loads() andrà a buon fine? Non risponde alla seconda: è l’oggetto che il mio codice si aspetta?
Come funziona
Nella Chat Completions API la attivi con un solo campo:
{"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Return JSON with keys name and email."},
{"role": "user", "content": "Reach me at Sara, sara@example.com"}]}
Il riferimento API di OpenAI la chiama “the older JSON mode, which ensures the message the model generates is valid JSON” (traduzione: la vecchia JSON mode, che garantisce che il messaggio generato dal modello sia JSON valido). Porta con sé due regole. Devi chiedere JSON in un messaggio: la guida di OpenAI dice che l’API “will throw an error if the string ‘JSON’ does not appear somewhere in the context” (traduzione: restituirà un errore se la stringa ‘JSON’ non compare da qualche parte nel contesto). E la forma la decide il modello. La guida afferma che la JSON mode “will not guarantee the output matches any specific schema” (traduzione: non garantisce che l’output corrisponda a uno schema specifico).
L’output strutturato è l’opzione più rigorosa. Passa un JSON Schema con {"type": "json_schema", ...} e il modello è vincolato a rispettarlo.
JSON mode (json_object) |
Structured output (json_schema) |
|
|---|---|---|
| JSON valido | sì | sì |
| Chiavi e tipi obbligatori | no | sì |
| Fornisci tu uno schema | no | sì |
| Devi citare “JSON” nel prompt | sì (OpenAI) | no |
OpenAI consiglia di “always using Structured Outputs instead of JSON mode when possible” (traduzione: usare sempre gli Structured Outputs al posto della JSON mode quando possibile).
Perché è importante
- La validazione resta a te. Con la JSON mode, una chiave mancante o un numero inviato come stringa superano il parsing e falliscono più avanti. Valida contro uno schema nel codice.
- Troncamento. Se la risposta arriva a
max_tokens, il JSON è incompleto. I modelli di ragionamento sono più esposti, perché il ragionamento consuma lo stesso budget. - Ripiego. La guida di OpenAI indica la JSON mode per i modelli più vecchi in cui
json_schemanon è disponibile. Il supporto varia per provider e modello, quindi JSON mode più la tua validazione è il ripiego quando uno schema non viene accettato.
Su BroadNet Inference
Il riferimento API di BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B. Non dice se il response_format supportato sia json_object o json_schema, né se DeepSeek V4.1 Flash e BroadNet Gemma 4 VL 26B accettino l’uno o l’altro. Provali entrambi sul tuo modello. Per scrivere lo schema usa il generatore di JSON Schema. L’articolo JSON mode o json_schema tratta riparazione e monitoraggio, e la guida alle fatture mostra l’estrazione di JSON da immagini.