JSON garantito dallo schema
In questa pagina
Perché gli output strutturati cambiano tutto
Quando utilizzi un modello linguistico in produzione, hai bisogno di risposte che il tuo codice possa utilizzare direttamente. Non testo libero, non JSON approssimativo: ti serve un JSON garantito conforme a uno schema da te definito. È esattamente ciò che gli output strutturati dell’API Grok ti offrono.
Il principio è semplice: fornisci uno schema JSON al modello e l’API garantisce che la risposta seguirà questa struttura esattamente. Niente parsing approssimativo, niente espressioni regolari fragili, nessun blocco try/catch per gestire i casi in cui il modello inventa un formato.
Come funziona
Gli output strutturati si basano su un meccanismo di vincolo applicato durante la generazione del testo. A ogni token prodotto, il modello è costretto a generare solo token compatibili con lo schema fornito. Il risultato: un JSON sempre valido, sempre conforme.
Vediamo un esempio concreto. Vuoi estrarre le informazioni di contatto da un’email:
from pydantic import BaseModel
class Contact(BaseModel):
nom: str
email: str
entreprise: str
telephone: str | None
# La risposta sarà SEMPRE un oggetto Contact valido
Senza output strutturati, il modello potrebbe restituire il numero di telefono come "tel", "phone" o "numéro". Con uno schema, il campo si chiamerà sempre telephone e il suo valore sarà sempre una stringa o null.
Disponibilità
Gli output strutturati sono supportati su tutti i modelli linguistici xAI: Grok 4.5, Grok 4.3, le varianti grok-4.20 e le versioni successive. Qualunque modello tu utilizzi, la funzionalità è disponibile senza costi aggiuntivi né configurazioni supplementari.
Senza contro Con gli Output Strutturati
Ecco cosa ottieni senza e con questa funzionalità:
Senza output strutturati:
- Il modello può restituire testo libero, JSON parziale o un formato inaspettato
- Devi effettuare il parsing manualmente e gestire gli errori
- I nomi dei campi possono variare da una richiesta all’altra
- La tua pipeline si interrompe non appena il modello cambia formato
Con gli output strutturati:
- Il JSON è sempre sintatticamente valido
- La struttura corrisponde esattamente allo schema fornito
- I tipi di dati sono rispettati (stringa, numero, booleano, ecc.)
- Il tuo codice può consumare direttamente la risposta
Due approcci disponibili
L’API Grok offre due metodi per utilizzare gli output strutturati:
parse(): Metodo automatico che restituisce direttamente un oggetto tipizzato. Ideale per la maggior parte dei casi d’uso.response_format: Metodo manuale che restituisce una stringa JSON. Offre maggiore controllo, ma il parsing spetta a te.
Scoprirai questi due metodi nel dettaglio nelle prossime lezioni.
Punti chiave
- Gli output strutturati garantiscono un JSON conforme al tuo schema a ogni chiamata
- Il vincolo viene applicato durante la generazione, non dopo
- Tutti i modelli linguistici xAI supportano questa funzionalità
- Sono disponibili due metodi:
parse()(automatico) eresponse_format(manuale) - Questa è la base di qualsiasi pipeline di produzione affidabile con l’API Grok