Автоматичен метод parse()
На тази страница
Обновено на 3 ноември 2026 г. Въз основа на документацията за Structured Outputs от xAI и
openaiSDK 3.42.1: когато OpenAI SDK е насочен към xAI, методът еclient.chat.completions.parse, който връща завършване, където типизираният обект се чете отchoices[0].message.parsed;client.chat.parseне съществува (SDK на xAI предлагаchat.parse(Schema)върху разговор, който връща двойка обект-отговор). Източник: Structured Outputs.
Бързият път: parse()
Методът parse() е най-простият начин за използване на структурирани изходи с Grok API. Той приема Pydantic модел като вход и връща директно типизиран обект – без нужда от парсване на JSON или ръчна валидация.
Дефиниране на Pydantic модела
Създавате Python клас, който описва очакваната структура.
Извикване на client.chat.completions.parse()
Предавате Pydantic модела като response_format.
Получаване на кортежа (Response, ParsedModel)
Типизираният обект е готов за употреба във Вашия код.
Пълен пример
Ето как да извлечете структуриран филмов отзив:
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 е типизиран обект MovieReview
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Какво връща parse()
Методът parse() връща кортеж от два елемента:
response: Пълният обект за отговор от API (с метаданни, използвани токени и др.)parsed: Вашият Pydantic модел, инстанциран с извлечените данни
Можете да достъпвате и двете според нуждите:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Достъп до метаданни
print(completion.usage.total_tokens)
print(completion.model)
# Достъп до структурирани данни
print(parsed.title)
print(parsed.rating)
Вложени модели
parse() обработва сложни структури без усилие. Можете да влагате 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}")
Кога да използвате parse()
parse() е най-краткият път между отговор от модел и използваем Python обект: ако работите с Pydantic, това е изборът по подразбиране. Методът обхваща всичко – изпращане на схемата, валидиране на отговора, инстанциране на обекта – и Ви предоставя директно типизирана инстанция, без json.loads или ръчни проверки. Това е възможно най-краткият код и за огромното мнозинство случаи тази простота няма цена: губите фина контрол над парсването само ако действително сте имали нужда от него, което е рядкост. Следващият урок разглежда точно онези случаи, когато ръчният контрол е оправдан.
Ключови изводи
parse()връща кортеж(Response, ParsedModel)– автоматично парсване- Върнатият обект е типизирана и валидирана Pydantic инстанция
- Вложените модели и списъци от обекти работят нативно
- Това е препоръчителният метод за повечето случаи на употреба в Python
- Няма нужда от
json.loads()или ръчна валидация