Metodo parse() automatico
In questa pagina
Aggiornato il 3 novembre 2026. Basato sulla documentazione Structured Outputs di xAI e sull’SDK
openai3.42.1: con l’SDK OpenAI puntato su xAI, il metodo èclient.chat.completions.parse, che restituisce un completamento da cui l’oggetto tipizzato si legge inchoices[0].message.parsed;client.chat.parsenon esiste (l’SDK xAI offre invecechat.parse(Schema)su una conversazione, che restituisce una coppia risposta-oggetto). Fonte: Structured Outputs.
La via rapida: parse()
Il metodo parse() è il modo più semplice per usare gli output strutturati con le API Grok. Accetta un modello Pydantic in input e restituisce direttamente un oggetto tipizzato: niente JSON da analizzare, nessuna validazione manuale.
Definisci il modello Pydantic
Crei una classe Python che descrive la struttura attesa.
Chiama client.chat.completions.parse()
Passi il modello Pydantic come response_format.
Ricevi la tupla (Response, ParsedModel)
L'oggetto tipizzato è pronto all'uso nel tuo codice.
Esempio completo
Ecco come estrarre una recensione di film strutturata:
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
class MovieReview(BaseModel):
title: str
rating: float
summary: str
recommend: bool
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Write a review of the movie Inception"
}],
response_format=MovieReview
)
parsed = completion.choices[0].message.parsed
# parsed è un oggetto MovieReview tipizzato
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Cosa restituisce parse()
Il metodo parse() restituisce una tupla di due elementi:
response: l’oggetto Response completo dell’API (con metadati, token usati, ecc.)parsed: il tuo modello Pydantic istanziato con i dati estratti
Puoi accedere a entrambi quando serve:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Accesso ai metadati
print(completion.usage.total_tokens)
print(completion.model)
# Accesso ai dati strutturati
print(parsed.title)
print(parsed.rating)
Modelli annidati
parse() gestisce senza sforzo strutture complesse. Puoi annidare modelli Pydantic:
class Actor(BaseModel):
name: str
role: str
class Review(BaseModel):
title: str
director: str
year: int
rating: float
main_actors: list[Actor]
genres: list[str]
strengths: list[str]
weaknesses: list[str]
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Complete analysis of the movie Interstellar"
}],
response_format=Review
)
parsed = completion.choices[0].message.parsed
for actor in parsed.main_actors:
print(f"{actor.name} plays {actor.role}")
Quando usare parse()
parse() è il percorso più breve tra una risposta del modello e un oggetto Python utilizzabile: se lavori con Pydantic, questa è la scelta predefinita. Il metodo incapsula tutto—invio dello schema, validazione della risposta, istanziazione dell’oggetto—e ti consegna direttamente un’istanza tipizzata, senza json.loads né controlli manuali. È il codice più conciso possibile e, nella stragrande maggioranza dei casi, questa semplicità non ha costi: rinunci al controllo fine sul parsing solo se ne avevi davvero bisogno, cosa rara. La prossima lezione tratta proprio quei casi in cui il controllo manuale è giustificato.
Punti chiave
parse()restituisce una tupla(Response, ParsedModel): parsing automatico- L’oggetto restituito è un’istanza Pydantic tipizzata e validata
- Modelli annidati e liste di oggetti funzionano nativamente
- Questo è il metodo consigliato per la maggior parte dei casi d’uso in Python
- Non serve
json.loads()né validazione manuale