Премини към основното съдържание
Български— Изберете език
Меню

Автоматичен метод parse()

Урок 4 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Бързият път: parse()
  2. Пълен пример
  3. Какво връща parse()
  4. Вложени модели
  5. Кога да използвате parse()
  6. Ключови изводи

Обновено на 3 ноември 2026 г. Въз основа на документацията за Structured Outputs от xAI и openai SDK 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 или ръчна валидация.

1

Дефиниране на Pydantic модела

Създавате Python клас, който описва очакваната структура.

2

Извикване на client.chat.completions.parse()

Предавате Pydantic модела като response_format.

3

Получаване на кортежа (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() връща кортеж от два елемента:

  1. response: Пълният обект за отговор от API (с метаданни, използвани токени и др.)
  2. 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() или ръчна валидация