Metoda automată parse()
Pe această pagină
Actualizat la 3 noiembrie 2026. Pe baza documentației Structured Outputs de la xAI și a SDK-ului
openaiversiunea 3.42.1: atunci când SDK-ul OpenAI este configurat pentru xAI, metoda utilizată esteclient.chat.completions.parse, care returnează o completare unde obiectul tipizat se citește dinchoices[0].message.parsed; metodaclient.chat.parsenu există (deși SDK-ul xAI oferăchat.parse(Schema)pe o conversație, care returnează o pereche obiect-răspuns). Sursă: Structured Outputs.
Calea rapidă: parse()
Metoda parse() reprezintă cea mai simplă modalitate de a utiliza ieșirile structurate cu API-ul Grok. Aceasta primește un model Pydantic ca intrare și returnează direct un obiect tipizat – fără necesitatea de a analiza JSON manual și fără validare manuală.
Definiți modelul Pydantic
Creați o clasă Python care descrie structura așteptată.
Apelați client.chat.completions.parse()
Transmiteți modelul Pydantic ca parametru response_format.
Primiți tuplul (Response, ParsedModel)
Obiectul tipizat este gata de utilizare în codul dumneavoastră.
Exemplu complet
Iată cum puteți extrage un recensământ structurat al unui film:
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 este un obiect MovieReview tipizat
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Ce returnează parse()
Metoda parse() returnează un tuplu cu două elemente:
response: Obiectul complet de răspuns API (conținând metadate, tokeni utilizați etc.)parsed: Modelul dumneavoastră Pydantic instanțiat cu datele extrase
Puteți accesa ambele elemente după nevoie:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Accesarea metadatelor
print(completion.usage.total_tokens)
print(completion.model)
# Accesarea datelor structurate
print(parsed.title)
print(parsed.rating)
Modele imbricate
Metoda parse() gestionează structuri complexe fără efort. Puteți imbrica modele 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}")
Când să utilizați parse()
Metoda parse() reprezintă calea cea mai scurtă între un răspuns al modelului și un obiect Python utilizabil: dacă lucrați cu Pydantic, aceasta este alegerea implicită. Metoda encapsulează totul – trimiterea schemei, validarea răspunsului, instanțierea obiectului – și vă livrează direct o instanță tipizată, fără a necesita json.loads sau verificări manuale. Este codul cel mai concis posibil, iar pentru marea majoritate a cazurilor, această simplitate nu implică niciun cost: renunțați la un control fin asupra analizei doar dacă aveți nevoie reală de acesta, situație care este rară. Lecția următoare acoperă exact acele cazuri în care controlul manual este justificat.
Puncte cheie
parse()returnează un tuplu(Response, ParsedModel)– analizare automată- Obiectul returnat este o instanță Pydantic tipizată și validată
- Modelele imbricate și listele de obiecte funcționează nativ
- Aceasta este metoda recomandată pentru majoritatea cazurilor de utilizare în Python
- Nu este nevoie de
json.loads()sau de validare manuală