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:
- Invia
json_schemacon un prompt che inviti ad aggiungere un campo in più («aggiungi anche un breve commento»). - Se la richiesta va in errore, il provider non accetta
json_schema. Provajson_object. - Se la risposta contiene il campo in più, lo schema non viene applicato. Trattalo come JSON mode.
- Se anche
json_objectva 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 raggiuntomax_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:
- Piatto è meglio di annidato. Per la maggior parte delle estrazioni bastano due livelli.
- Enum invece di stringhe libere per le categorie.
- Niente oggetti aperti. I campi
dicta forma libera vanificano lo scopo. - Nomi dei campi brevi, con descrizioni. Le descrizioni nello schema guidano il modello.
- 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.
