Przejdź do głównej treści
Polski— Wybierz język
Menu

Automatyczna metoda parse()

Lekcja 4 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Szybka ścieżka: parse()
  2. Pełny przykład
  3. Co zwraca parse()?
  4. Zagnieżdżone modele
  5. Kiedy używać parse()?
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Na podstawie dokumentacji Structured Outputs od xAI oraz SDK openai w wersji 3.42.1: gdy SDK OpenAI jest skierowane na xAI, metodą jest client.chat.completions.parse, która zwraca uzupełnienie, gdzie typowany obiekt jest odczytywany z choices[0].message.parsed; client.chat.parse nie istnieje (SDK xAI oferuje jednak chat.parse(Schema) w kontekście konwersacji, co zwraca parę obiektów: odpowiedź i wynik). Źródło: Structured Outputs.

Szybka ścieżka: parse()

Metoda parse() to najprostszy sposób na wykorzystanie strukturyzowanych danych wyjściowych z API Grok. Przyjmuje ona model Pydantic jako dane wejściowe i zwraca bezpośrednio typowany obiekt – bez konieczności parsowania JSON-a czy ręcznej walidacji.

1

Zdefiniuj model Pydantic

Tworzysz klasę w Pythonie, która opisuje oczekiwaną strukturę danych.

2

Wywołaj client.chat.completions.parse()

Przekazujesz model Pydantic jako parametr `response_format`.

3

Otrzymaj krotkę (Odpowiedź, ParsedModel)

Typowany obiekt jest gotowy do użycia w Twoim kodzie.

Pełny przykład

Oto jak wyodrębnić strukturyzowaną recenzję filmu:

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 to typowany obiekt MovieReview
print(parsed.title)      # "Inception"
print(parsed.rating)     # 9.2
print(parsed.recommend)  # True
print(type(parsed))      # <class 'MovieReview'>

Co zwraca parse()?

Metoda parse() zwraca krotkę dwuelementową:

  1. response: Pełny obiekt odpowiedzi API (z metadanymi, użytymi tokenami itp.)
  2. parsed: Twój model Pydantic zinstancjonowany z wyodrębnionymi danymi

Możesz uzyskać dostęp do obu elementów w razie potrzeby:

completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed

# Dostęp do metadanych
print(completion.usage.total_tokens)
print(completion.model)

# Dostęp do strukturyzowanych danych
print(parsed.title)
print(parsed.rating)

Zagnieżdżone modele

parse() bez problemu obsługuje złożone struktury. Możesz zagnieżdżać 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}")

Kiedy używać parse()?

parse() to najkrótsza droga między odpowiedzią modelu a użytecznym obiektem w Pythonie: jeśli pracujesz z Pydantic, jest to wybór domyślny. Metoda ta inkapsuluje wszystko – wysyłanie schematu, walidację odpowiedzi, instancjonowanie obiektu – i przekazuje Ci bezpośrednio typowaną instancję, bez potrzeby stosowania json.loads czy ręcznych sprawdzeń. To najbardziej zwięzły kod, jaki możesz napisać, a w zdecydowanej większości przypadków ta prostota nie niesie ze sobą żadnych kosztów: rezygnujesz z drobnej kontroli nad procesem parsowania tylko wtedy, gdy naprawdę jej potrzebujesz, co zdarza się rzadko. Następna lekcja omawia dokładnie te przypadki, w których ręczna kontrola jest uzasadniona.

Kluczowe wnioski

  • parse() zwraca krotkę (Response, ParsedModel) – automatyczne parsowanie
  • Zwracany obiekt to typowana i zwalidowana instancja Pydantic
  • Zagnieżdżone modele i listy obiektów działają natywnie
  • Jest to zalecana metoda dla większości przypadków użycia w Pythonie
  • Nie ma potrzeby stosowania json.loads() ani ręcznej walidacji