Salt la conținutul principal
Română— Alege o limbă
Meniu

Metoda automată parse()

Lecția 4 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Calea rapidă: parse()
  2. Exemplu complet
  3. Ce returnează parse()
  4. Modele imbricate
  5. Când să utilizați parse()
  6. Puncte cheie

Actualizat la 3 noiembrie 2026. Pe baza documentației Structured Outputs de la xAI și a SDK-ului openai versiunea 3.42.1: atunci când SDK-ul OpenAI este configurat pentru xAI, metoda utilizată este client.chat.completions.parse, care returnează o completare unde obiectul tipizat se citește din choices[0].message.parsed; metoda client.chat.parse nu 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ă.

1

Definiți modelul Pydantic

Creați o clasă Python care descrie structura așteptată.

2

Apelați client.chat.completions.parse()

Transmiteți modelul Pydantic ca parametru response_format.

3

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:

  1. response: Obiectul complet de răspuns API (conținând metadate, tokeni utilizați etc.)
  2. 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ă