---
title: "JSON mode o JSON Schema: output strutturato, con codice"
description: "JSON mode dà JSON valido; json_schema dà la tua struttura. Come richiederli sui modelli compatibili con OpenAI, validare con Pydantic e correggere in un loop."
url: https://broadrouter.com/it/blog/structured-output-json-schema/
lang: it
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/blog/structured-output-json-schema/) (aggiornato il 2026-11-14).

# JSON mode o json\_schema: output strutturato che regge in produzione

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato 2026-11-14

JSON mode (response\_format json\_object) garantisce solo JSON valido. L’output strutturato (response\_format json\_schema) garantisce anche i tuoi campi e tipi, dove il provider lo applica. In entrambi i casi controlla finish\_reason, fai il parsing e valida con uno schema, per esempio un modello Pydantic. Se la validazione fallisce, rimanda l’errore e richiedi la risposta, con un limite rigido di tentativi.

## Punti chiave

-   La guida di OpenAI: entrambe le modalità producono JSON valido, ma "only Structured Outputs ensure schema adherence" (traduzione: solo gli Structured Outputs garantiscono il rispetto dello schema).
-   Il supporto varia tra i provider compatibili con OpenAI. Prova prima json\_schema, poi ripiega su json\_object, infine sul solo prompt.
-   Valida ogni risposta. Una risposta troncata da max\_tokens è JSON rotto, qualunque cosa dica lo schema.
-   I loop di correzione funzionano se rimandi l’errore di validazione esatto. Limitali a due o tre tentativi.
-   Su BroadNet Inference, GLM 5.3 e Qwen3.8 27B indicano il supporto all’output strutturato.

**In questa pagina**

1.  Che differenza c’è tra JSON mode e json\_schema?
2.  Come si richiede json\_schema?
3.  Quale modalità supporta il tuo provider?
4.  Come si valida e si corregge un output errato?
5.  Quali funzionalità dello schema creano problemi?
6.  Come si monitora l’output strutturato in produzione?
7.  Quando conviene usare uno strumento?
8.  Dove si colloca BroadNet Inference

Il tuo codice ha bisogno di dati, e i modelli scrivono testo. L’[output strutturato](https://broadrouter.com/it/glossary/structured-output/) colma questa distanza, ma «il modello restituisce JSON» può voler dire tre cose diverse a seconda di come lo chiedi. Questo articolo confronta le opzioni sui modelli open compatibili con OpenAI, mostra come richiederle e propone un loop di validazione e correzione da inserire in produzione.

## Che differenza c’è tra JSON mode e json\_schema?

| Metodo | Richiesta | Che cosa ti viene garantito |
| --- | --- | --- |
| Solo prompt | «Rispondi in JSON con i campi…» | Niente; di solito JSON, a volte con testo in più |
| JSON mode | `response_format: {"type": "json_object"}` | JSON valido, con qualsiasi struttura |
| Output strutturato | `response_format: {"type": "json_schema", ...}` | JSON conforme al tuo schema, dove applicato |

La guida di OpenAI agli Structured Outputs è esplicita: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (traduzione: anche se entrambi garantiscono la produzione di JSON valido, solo gli Structured Outputs garantiscono il rispetto dello schema). Consiglia l’output strutturato rispetto a JSON mode ogni volta che è possibile.

Con i provider di modelli open, la garanzia dipende da come il server la implementa. Molti usano il constrained decoding, che blocca i token che violerebbero lo schema. Alcuni accettano il campo ma non lo applicano. Per questo il codice qui sotto valida comunque.

## Come si richiede json\_schema?

```python
import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}
```

Pydantic genera il JSON Schema dalla tua classe, così schema e validatore non si disallineano mai. Se non usi Pydantic, il [generatore di JSON Schema](https://broadrouter.com/tools/json-schema-generator/) crea uno schema in strict mode a partire da un oggetto di esempio. Per lo strict mode, OpenAI richiede `additionalProperties: false` e tutte le proprietà elencate come obbligatorie.

## Quale modalità supporta il tuo provider?

Esegui questo test una volta per modello, prima di costruirci sopra:

1.  Invia `json_schema` con un prompt che inviti ad aggiungere un campo in più («aggiungi anche un breve commento»).
2.  Se la richiesta va in errore, il provider non accetta `json_schema`. Prova `json_object`.
3.  Se la risposta contiene il campo in più, lo schema non viene applicato. Trattalo come JSON mode.
4.  Se anche `json_object` va in errore, usa il solo prompt con validazione.

Su BroadNet Inference, la documentazione indica l’output strutturato per [GLM 5.3](https://broadrouter.com/it/models/glm-5.3/) e [Qwen3.8 27B](https://broadrouter.com/it/models/qwen3.8-27b/) ([messi a confronto](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)), ma non specifica il parametro della richiesta. Esegui il test qui sopra sul modello che metti in produzione.

## Come si valida e si corregge un output errato?

```python
import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")
```

Che cosa fa funzionare questo loop:

-   **Controlla prima `finish_reason`.** Una risposta che ha raggiunto [`max_tokens`](https://broadrouter.com/it/glossary/max-tokens/) è JSON troncato. Ritentare con lo stesso limite fallisce allo stesso modo. Entrambi i modelli citati ragionano prima di rispondere, e [il ragionamento conta ai fini del limite](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/), quindi lascia margine.
-   **Gestisci i rifiuti a parte.** La guida di OpenAI precisa che un rifiuto “does not necessarily follow the schema you have supplied” (traduzione: non segue necessariamente lo schema che hai fornito).
-   **Rimanda l’errore esatto.** Un retry alla cieca restituisce spesso lo stesso errore. «line\_items: field required» dà al modello qualcosa da correggere.
-   **Controlla le regole di business nel codice.** Uno schema non può dire che un totale deve essere uguale alla somma delle righe. Il controllo qui sopra sì.
-   **Limita i tentativi.** Ogni tentativo reinvia l’intero prompt come [token di input](https://broadrouter.com/it/glossary/input-and-output-tokens/).

## Quali funzionalità dello schema creano problemi?

Tieni gli schemi semplici:

1.  **Piatto è meglio di annidato.** Per la maggior parte delle estrazioni bastano due livelli.
2.  **Enum invece di stringhe libere** per le categorie.
3.  **Niente oggetti aperti.** I campi `dict` a forma libera vanificano lo scopo.
4.  **Nomi dei campi brevi, con descrizioni.** Le descrizioni nello schema guidano il modello.
5.  **Campi opzionali come nullable.** In strict mode, elenca ogni campo come obbligatorio e consenti `null`.

La guida di OpenAI precisa che alcune funzionalità di JSON Schema non sono supportate in strict mode. I server dei modelli open hanno i loro limiti. Se uno schema viene rifiutato, semplificalo prima di cambiare modalità.

## Come si monitora l’output strutturato in produzione?

Un loop che corregge in silenzio può nascondere un problema che ti costa token ogni giorno. Registra tre numeri per ogni punto di chiamata:

| Metrica | Che cosa ti dice |
| --- | --- |
| Tasso di successo al primo tentativo | Quanto modello e schema si adattano; un calo segue spesso un cambio di prompt o di modello |
| Tentativi medi per successo | Il costo in token delle correzioni |
| Fallimenti finali | Input che la tua pipeline non sa gestire; rivedili a mano |

Se il successo al primo tentativo scende sotto i valori abituali, semplifica lo schema o prova un altro modello prima di aggiungere altri retry. Conserva un campione delle risposte grezze fallite, così puoi provare le correzioni su casi reali.

## Quando conviene usare uno strumento?

Usa l’output strutturato per la **risposta finale**: un’estrazione, una classificazione, un piano. Usa il [tool calling](https://broadrouter.com/it/blog/tool-calling-open-models/) quando il modello ha bisogno che il tuo codice **faccia** qualcosa per poi proseguire. Molti agenti usano entrambi: strumenti durante il loop, uno schema per l’ultimo passaggio. Per un esempio da immagine a JSON, vedi [leggere fatture in arabo con un modello di visione](https://broadrouter.com/it/guides/read-arabic-invoices-with-vision/).

## Dove si colloca BroadNet Inference

BroadNet Inference indica l’output strutturato per GLM 5.3 e Qwen3.8 27B, dietro il formato standard delle chat completions, quindi il codice qui sopra funziona senza modifiche con l’[SDK Python di OpenAI](https://broadrouter.com/it/guides/openai-python-sdk/). Qwen3.8 27B accetta anche immagini, il che lo rende adatto all’estrazione da documenti. La documentazione di BroadNet non indica l’output strutturato per DeepSeek V4.1 Flash né per Gemma 4 VL 26B, quindi lì usa il percorso con il solo prompt e la validazione. Confronta i prezzi per token nella [pagina dei prezzi](https://broadrouter.com/it/pricing/).

Strumenti gratuiti sul tema (in inglese)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Strumenti gratuiti (in inglese)](https://broadrouter.com/tools/)

## Termini in questo articolo

[Output strutturato (structured output)](https://broadrouter.com/it/glossary/structured-output/)

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.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[JSON Schema](https://broadrouter.com/it/glossary/json-schema/)

JSON Schema è un vocabolario, scritto in JSON, per descrivere e validare la struttura dei dati JSON: tipi, campi obbligatori, valori ammessi e annidamento. La versione attuale è la 2020-12. Le API LLM lo usano per definire i parametri dei tool e la forma esatta che un output strutturato deve seguire.

[JSON mode (modalità JSON)](https://broadrouter.com/it/glossary/json-mode/)

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.

[Tool calling (chiamata di strumenti)](https://broadrouter.com/it/glossary/tool-calling/)

Il tool calling, detto anche function calling, è una funzionalità delle API LLM in cui il modello restituisce una richiesta strutturata di eseguire una funzione definita dallo sviluppatore, con argomenti JSON. L’applicazione esegue la funzione e rimanda il risultato; il modello non esegue mai codice da solo.

[AI multimodale (multimodal AI)](https://broadrouter.com/it/glossary/multimodal/)

L’AI multimodale è un modello o un sistema che lavora con più di un tipo di dato, come testo, immagini, video e audio. Un modello multimodale può leggere insieme una foto e una domanda, oppure ricevere parlato e rispondere in testo. Il tipo più comune è il modello vision-language.

[Chat Completions API](https://broadrouter.com/it/glossary/chat-completions-api/)

La Chat Completions API è l’endpoint HTTP di OpenAI, POST /v1/chat/completions, che riceve il nome di un modello e una lista di messaggi con un ruolo e restituisce il messaggio successivo del modello. La forma della sua richiesta e risposta è diventata il formato comune che riusano provider e SDK compatibili con OpenAI.

[Modello vision-language (VLM)](https://broadrouter.com/it/glossary/vision-language-model/)

Un modello vision-language (VLM) è un modello che riceve in input immagini e testo insieme e produce testo, quindi può descrivere foto, rispondere a domande su di esse e leggere documenti, grafici o screenshot. I VLM sono chiamati anche modelli image-text-to-text o multimodali.

## Domande frequenti

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

JSON mode, response\_format di tipo json\_object, garantisce solo che la risposta sia JSON valido. L’output strutturato, di tipo json\_schema, garantisce anche i campi e i tipi che hai definito, dove il provider lo applica. OpenAI consiglia l’output strutturato rispetto a JSON mode quando possibile.

### I modelli open supportano response\_format json\_schema?

Dipende dal provider. Alcuni accettano json\_schema, altri solo json\_object, altri ancora ignorano il campo. Invia una richiesta di prova con uno schema e un prompt che spinga il modello ad aggiungere un campo in più, poi controlla la risposta.

### Devo validare comunque l’output strutturato?

Sì. Le risposte possono essere troncate da max\_tokens, possono essere rifiuti e possono violare regole di business che uno schema non sa esprimere, come totali che devono tornare.

### Quante volte devo ritentare se il JSON non è valido?

Di solito bastano due o tre tentativi con l’errore di validazione incluso. Dopo, registra l’input e indirizzalo a un fallback, a un modello più potente o a una persona. I loop senza limite sprecano token.

### 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 ha bisogno che il tuo codice faccia qualcosa per poi proseguire.

## Continua a leggere

-   [Classificare testo arabo con un LLM: sentiment, intenzione, triage](https://broadrouter.com/it/blog/arabic-text-classification-llm/)
-   [Tool calling con modelli aperti: schemi, chiamate parallele, retry](https://broadrouter.com/it/blog/tool-calling-open-models/)
-   [Passare a un’API compatibile con OpenAI: la checklist di migrazione](https://broadrouter.com/it/blog/openai-compatible-api-migration-checklist/)
-   [AI Agent n8n con un LLM economico: setup, modello e costo a esecuzione](https://broadrouter.com/it/blog/n8n-ai-agent-cheap-llm/)
-   [JSON non valido da un LLM: cause, riparazione e retry](https://broadrouter.com/it/blog/fix-invalid-json-from-llm/)
-   [Estrarre entità nominate dall’arabo con un LLM: JSON, date e controlli](https://broadrouter.com/it/blog/arabic-named-entity-extraction-llm/)
-   [Hardware GPU e serving di BroadNet, come li descrive BroadNet](https://broadrouter.com/it/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache delle risposte delle API LLM: una cache esatta in Python](https://broadrouter.com/it/blog/cache-llm-responses-cut-cost/)
-   [Guida: Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)
-   [Guida: Leggere fatture e scontrini in arabo con un modello vision](https://broadrouter.com/it/guides/read-arabic-invoices-with-vision/)
-   [Guida: Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-structured-output-json-schema&utm_content=page-cta) ·

**Fonti**

-   [OpenAI, guida agli Structured Outputs (verificata il 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [Riferimento API di OpenAI, creazione di una chat completion (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Documentazione di Pydantic, JSON Schema e validazione](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [Riferimento API di BroadNet Inference, modelli (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-blog-structured-output-json-schema&utm_content=sources#models)
