Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Metodo parse() automatico

Lezione 4 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. La via rapida: parse()
  2. Esempio completo
  3. Cosa restituisce parse()
  4. Modelli annidati
  5. Quando usare parse()
  6. Punti chiave

Aggiornato il 3 novembre 2026. Basato sulla documentazione Structured Outputs di xAI e sull’SDK openai 3.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 in choices[0].message.parsed; client.chat.parse non esiste (l’SDK xAI offre invece chat.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.

1

Definisci il modello Pydantic

Crei una classe Python che descrive la struttura attesa.

2

Chiama client.chat.completions.parse()

Passi il modello Pydantic come response_format.

3

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:

  1. response: l’oggetto Response completo dell’API (con metadati, token usati, ecc.)
  2. 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