Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Automaattinen parse()-metodi

Oppitunti 4 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Pikarata: parse()
  2. Täydellinen esimerkki
  3. Mitä parse() palauttaa
  4. Sisäkkäiset mallit
  5. Milloin käyttää parse()-metodia
  6. Keskeiset asiat

Päivitetty 3. marraskuuta 2026. Perustuu xAI:n Structured Outputs -dokumentaatioon ja openai SDK:n versioon 3.42.1: kun OpenAI SDK on suunnattu xAI:hin, käytettävä metodi on client.chat.completions.parse, joka palauttaa täydennyksen, jossa tyypitetty objekti luetaan kohdasta choices[0].message.parsed; metodia client.chat.parse ei ole olemassa (xAI SDK tarjoaa kuitenkin keskustelulle metodin chat.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.

1

Määritä Pydantic-malli

Luot Python-luokan, joka kuvaa odotetun rakenteen.

2

Kutsu client.chat.completions.parse()

Välität Pydantic-mallin parametrina response_format.

3

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:

  1. response: Täydellinen API-vastausobjekti (sisältää metadataa, käytetyt tokenit jne.)
  2. 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