BroadRouter
Inizia

JSON mode (modalità JSON)

Aggiornato

La JSON mode è un’impostazione delle API LLM, response_format {"type": "json_object"} nelle API in stile OpenAI, che rende la risposta del modello JSON valido e analizzabile. A differenza degli structured output con un JSON Schema, non garantisce quali chiavi, tipi o valori contenga l’oggetto.

Detto anche: modalità JSON, output JSON, risposta in JSON, JSON mode, json_object, JSON output mode, JSON response mode

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_schema non è 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.

Domande frequenti

La JSON mode è la stessa cosa degli structured output?

No. La guida di OpenAI dice che entrambi producono JSON valido, ma solo gli Structured Outputs garantiscono il rispetto dello schema. La JSON mode può restituire qualsiasi oggetto valido.

Perché la JSON mode dà un errore sulla parola JSON?

OpenAI richiede che da qualche parte nei messaggi ci sia l’istruzione di produrre JSON e restituisce un errore se la stringa "JSON" non compare nel contesto.

La JSON mode può comunque restituire JSON rotto?

Sì, se la risposta viene troncata da max_tokens o dal limite di contesto. Controlla finish_reason prima del parsing.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity