BroadRouter
Inizia

JSON mode o json_schema: output strutturato che regge in produzione

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato

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.

Il tuo codice ha bisogno di dati, e i modelli scrivono testo. L’output strutturato 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?

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 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 e Qwen3.8 27B (messi a confronto), 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?

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 è 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, 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.

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 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.

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. 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.

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.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity