BroadRouter
Inizia

Output strutturato (structured output)

Aggiornato

L’output strutturato è una funzionalità delle API LLM che vincola la risposta di un modello a un formato indicato dallo sviluppatore, di solito un JSON Schema, così il codice può interpretarla in modo affidabile. È più rigoroso della JSON mode, che garantisce un JSON valido ma non una struttura precisa.

Detto anche: output strutturato, output JSON, output con JSON Schema, structured output, structured outputs, JSON schema output, response_format

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 in required, quando usi la modalità strict.
  • Non controllare finish_reason prima del parsing.

Domande frequenti

Che differenza c’è tra JSON mode e output strutturato?

La JSON mode promette solo che la risposta sia un JSON interpretabile. L’output strutturato con uno schema promette anche i campi, i tipi e le chiavi obbligatorie che hai definito. La guida di OpenAI dice che solo gli Structured Outputs garantiscono l’aderenza allo schema.

Devo comunque validare l’output?

Sì. Una risposta può comunque essere un rifiuto o essere troncata da max_tokens, e uno schema non può esprimere ogni regola di business, come un totale che deve essere uguale alla somma delle righe.

Meglio l’output strutturato o il tool calling?

Usa l’output strutturato quando vuoi la risposta finale in una forma fissa. Usa il tool calling quando il modello deve chiedere al tuo codice di fare qualcosa e poi proseguire.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity