Automatyczna metoda parse()
Na tej stronie
Zaktualizowano 3 listopada 2026 r. Na podstawie dokumentacji Structured Outputs od xAI oraz SDK
openaiw wersji 3.42.1: gdy SDK OpenAI jest skierowane na xAI, metodą jestclient.chat.completions.parse, która zwraca uzupełnienie, gdzie typowany obiekt jest odczytywany zchoices[0].message.parsed;client.chat.parsenie istnieje (SDK xAI oferuje jednakchat.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.
Zdefiniuj model Pydantic
Tworzysz klasę w Pythonie, która opisuje oczekiwaną strukturę danych.
Wywołaj client.chat.completions.parse()
Przekazujesz model Pydantic jako parametr `response_format`.
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ą:
response: Pełny obiekt odpowiedzi API (z metadanymi, użytymi tokenami itp.)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