Automaattinen parse()-metodi
Tällä sivulla
Päivitetty 3. marraskuuta 2026. Perustuu xAI:n Structured Outputs -dokumentaatioon ja
openaiSDK:n versioon 3.42.1: kun OpenAI SDK on suunnattu xAI:hin, käytettävä metodi onclient.chat.completions.parse, joka palauttaa täydennyksen, jossa tyypitetty objekti luetaan kohdastachoices[0].message.parsed; metodiaclient.chat.parseei ole olemassa (xAI SDK tarjoaa kuitenkin keskustelulle metodinchat.parse(Schema), joka palauttaa vastaus-objekti-parin). Lähde: Structured Outputs.
Pikarata: parse()
parse()-metodi on helpoin tapa hyödyntää jäsennettyjä tulosteita Grok API:n kanssa. Se ottaa syötteeksi Pydantic-mallin ja palauttaa suoraan tyypitetyn objektin – ei JSON:n jäsentämistä, ei manuaalista validointia.
Määritä Pydantic-malli
Luot Python-luokan, joka kuvaa odotetun rakenteen.
Kutsu client.chat.completions.parse()
Välität Pydantic-mallin parametrina response_format.
Vastaanota tuple (Response, ParsedModel)
Tyypitetty objekti on valmis käytettäväksi koodissasi.
Täydellinen esimerkki
Näin voit erottaa jäsennetyn elokuva-arvostelun:
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 on tyypitetty MovieReview-objekti
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Mitä parse() palauttaa
parse()-metodi palauttaa kaksiosaisen tuplen:
response: Täydellinen API-vastausobjekti (sisältää metadataa, käytetyt tokenit jne.)parsed: Pydantic-mallisi instanssi, joka on alustettu erotetuilla tiedoilla
Voit käyttää molempia tarpeen mukaan:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Käytä metadataa
print(completion.usage.total_tokens)
print(completion.model)
# Käytä jäsennettyä dataa
print(parsed.title)
print(parsed.rating)
Sisäkkäiset mallit
parse() käsittelee monimutkaisia rakenteita vaivattomasti. Voit sisällyttää Pydantic-malleja toisiinsa:
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}")
Milloin käyttää parse()-metodia
parse() on lyhin reitti mallivasteesta käyttökelpoiseen Python-objektiin: jos työskentelet Pydanticin kanssa, tämä on oletusvalinta. Metodi kapseloi kaiken – skeeman lähettämisen, vastauksen validoinnin ja objektin luonnin – ja antaa sinulle suoraan tyypitetyn instanssin ilman json.loads-kutsuja tai manuaalisia tarkistuksia. Se on mahdollisimman tiivis koodi, ja valtaosassa tapauksia tämä yksinkertaisuus ei maksa mitään: luovut hienojakoisesta jäsentämisohjauksesta vain, jos todella tarvitset sitä, mikä on harvinaista. Seuraava oppitunti käsittelee nimenomaan niitä tapauksia, joissa manuaalinen ohjaus on perusteltua.
Keskeiset asiat
parse()palauttaa tuplen(Response, ParsedModel)– automaattinen jäsennys- Palautettu objekti on tyypitetty ja validoitu Pydantic-instanssi
- Sisäkkäiset mallit ja objektlistat toimivat natiivisti
- Tämä on suositeltu metodi useimpiin Python-käyttötapauksiin
json.loads()-funktiota tai manuaalista validointia ei tarvita