De automatische parse()-methode
Op deze pagina
Bijgewerkt op 3 november 2026. Gebaseerd op de documentatie over Structured Outputs van xAI en de
openaiSDK 3.42.1: wanneer de OpenAI SDK naar xAI wijst, is de methodeclient.chat.completions.parse. Deze retourneert een voltooiing waarbij het getypte object wordt gelezen uitchoices[0].message.parsed;client.chat.parsebestaat niet (de xAI SDK biedt welchat.parse(Schema)aan op een conversatie, wat een paar van respons-object retourneert). Bron: Structured Outputs.
De snelle weg: parse()
De parse()-methode is de eenvoudigste manier om gestructureerde uitvoer te gebruiken met de Grok API. Deze methode accepteert een Pydantic-model als invoer en retourneert direct een getypt object: geen JSON om te parseren, geen handmatige validatie.
Definieer het Pydantic-model
U maakt een Python-klasse die de verwachte structuur beschrijft.
Roep client.chat.completions.parse() aan
U geeft het Pydantic-model door als response_format.
Ontvang de tuple (Response, ParsedModel)
Het getypte object is klaar voor gebruik in uw code.
Volledig voorbeeld
Hier ziet u hoe u een gestructureerde filmrecensie extrahert:
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 is een getypt MovieReview-object
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Wat parse() retourneert
De parse()-methode retourneert een tuple met twee elementen:
response: Het volledige API-responsobject (met metadata, gebruikte tokens, enz.)parsed: Uw Pydantic-model, geïnstantieerd met de geëxtraheerde gegevens
U hebt toegang tot beide wanneer nodig:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Toegang tot metadata
print(completion.usage.total_tokens)
print(completion.model)
# Toegang tot gestructureerde gegevens
print(parsed.title)
print(parsed.rating)
Geneste modellen
parse() verwerkt complexe structuren moeiteloos. U kunt Pydantic-modellen nesten:
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}")
Wanneer gebruikt u parse()?
parse() is de kortste weg tussen een modelrespons en een bruikbaar Python-object: als u met Pydantic werkt, is dit de standaardkeuze. De methode kapselt alles in: het verzenden van het schema, het valideren van de respons en het instantiëren van het object. Vervolgens ontvangt u direct een getypte instantie, zonder json.loads of handmatige controles. Het is de meest beknopte code die mogelijk is. Voor het overgrote deel van de use-cases gaat deze eenvoud niet ten koste van functionaliteit: u doet alleen afstand van fijnkorrelige parse-controle als u die daadwerkelijk nodig had, wat zelden het geval is. De volgende les behandelt precies die gevallen waarin handmatige controle gerechtvaardigd is.
Belangrijkste punten
parse()retourneert een tuple(Response, ParsedModel)– automatische parsing- Het geretourneerde object is een getypte en gevalideerde Pydantic-instantie
- Geneste modellen en lijsten van objecten werken native
- Dit is de aanbevolen methode voor de meeste use-cases in Python
- Geen behoefte aan
json.loads()of handmatige validatie