Il codice ha bisogno di input prevedibili. L’output strutturato trasforma il testo libero di un modello in dati di cui il tuo programma può fidarsi.
Come funziona
Ci sono tre livelli di controllo:
| Metodo | Cosa ottieni |
|---|---|
| Chiederlo nel prompt | Di solito JSON, a volte con testo in più o campi mancanti |
| JSON mode | JSON valido, di qualsiasi forma |
| Output strutturato con uno schema | JSON conforme al tuo schema |
Nel formato OpenAI, la JSON mode è response_format: {"type": "json_object"}. L’output strutturato passa uno schema:
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice",
"strict": true,
"schema": {
"type": "object",
"properties": {
"vendor": { "type": "string" },
"total": { "type": "number" }
},
"required": ["vendor", "total"],
"additionalProperties": false
}
}
}
Il riferimento di OpenAI dice che il tipo json_schema “ensures the model will match your supplied JSON schema” (traduzione: garantisce che il modello rispetti il JSON Schema fornito). Molti provider ci riescono con il decoding vincolato: limitano i token che il modello può produrre a ogni passo, così un output che viola lo schema non può essere generato.
Perché è importante
- Meno errori di parsing. Pipeline di estrazione, classificatori e agenti possono leggere direttamente i campi.
- Prompt più semplici. Lo schema sostituisce lunghe istruzioni sul formato.
- Non è una garanzia totale. La guida di OpenAI dice che l’app deve comunque gestire rifiuti, risposte incomplete ed errori. Una risposta troncata da
max_tokensè JSON non valido, qualunque cosa dica lo schema.
Il supporto varia tra le API compatibili con OpenAI. Alcune accettano solo json_schema, altre solo json_object, e altre ignorano il campo. Verifica prima di farci affidamento.
Su BroadNet Inference
La documentazione di BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B. La documentazione non nomina il parametro della richiesta, quindi prova response_format sul tuo modello, e in ogni caso tieni un parser JSON con gestione degli errori. Il validatore di output JSON per LLM mostra dove si rompe una risposta e la verifica rispetto al tuo schema. Entrambi i modelli ragionano prima di rispondere, quindi lascia in max_tokens spazio per il ragionamento più il JSON.
L’output strutturato si abbina bene ai modelli vision. La guida alle fatture in arabo invia un’immagine e chiede i campi in JSON. Per le azioni invece che per le risposte, usa il tool calling.
Errori comuni
- Dimenticare
additionalProperties: false, o non elencare tutti i campi inrequired, quando usi la modalità strict. - Non controllare
finish_reasonprima del parsing.