Handmatige response_format
Op deze pagina
Meer controle met response_format
De handmatige methode via response_format geeft u volledige controle over het parseren. In tegenstelling tot parse(), dat een getypeerd object retourneert, levert deze aanpak een JSON-tekenreeks op die u zelf parseert; het Pydantic-model biedt alleen het schema (model_json_schema()) en valideert afterward. Kies deze methode wanneer u flexibiliteit nodig hebt of wanneer u werkt in een omgeving zonder Pydantic.
Werkflow
Bij response_format verloopt het proces in twee stappen:
- De API retourneert de JSON als een tekenreeks in
response.choices[0].message.content - U parseert deze tekenreeks met uw methode naar keuze
Volledig voorbeeld
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
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Review the movie Inception"
}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "movie_review",
"schema": MovieReview.model_json_schema()
}
}
)
# De inhoud is een JSON-tekenreeks
json_string = response.choices[0].message.content
print(type(json_string)) # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}
# Handmatig parseren met Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title) # "Inception"
Verschillen met parse()
| Aspect | parse() | response_format |
|---|---|---|
| Retourwaarde | (Response, ParsedModel) | Alleen Response |
| Parseren | Automatisch | Handmatig |
| Gegevenstoegang | parsed.field | json.loads() of model_validate_json() |
| Flexibiliteit | Standaard | Maximaal |
| Foutafhandeling | Ingebouwd | Uw verantwoordelijkheid |
Parseren zonder Pydantic
U hoeft Pydantic niet te gebruiken om het resultaat te parseren. De standaard json-module werkt ook:
import json
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Analyze this text and extract entities"
}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "entities",
"schema": {
"type": "object",
"properties": {
"people": {
"type": "array",
"items": { "type": "string" }
},
"places": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
}
)
data = json.loads(response.choices[0].message.content)
print(data["people"]) # ["Marie Curie", "Pierre Curie"]
print(data["places"]) # ["Paris", "Warsaw"]
Wanneer kiest u voor response_format?
response_format blinkt uit wanneer u de JSON moet zien of inspecteren voordat deze een object wordt. Het meest voorkomende geval is logboekregistratie: in productieomgevingen is het bewaren van de ruwe JSON vóór transformatie vaak een vereiste voor auditing of debugging, en parse() biedt u dat interceptiepunt niet. Daarnaast speelt de schema-kwestie: als uw interfacecontract een ruw JSON-schema is—gedeeld met andere teams, gegenereerd door een tool, onafhankelijk van de Python-code geversioneerd—dan is het direct afdwingen daarvan getrouwer dan het reconstrueren ervan als een Pydantic-model. Tot slot opereert niet elk project binnen het Pydantic-ecosysteem: als uw validatie via een ander framework loopt, of via een tussenstap specifiek voor uw pipeline, dan levert response_format u de JSON zoals die is en laat het u de controle over wat er vervolgens gebeurt.
Foutafhandeling
Bij de handmatige methode moet u parseerfouten zelf afhandelen:
import json
try:
data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
print(f"Parsing error: {e}")
In de praktijk zou deze fout nooit mogen optreden, aangezien de API geldige JSON garandeert. Defensieve afhandeling blijft echter een best practice in productieomgevingen.
Belangrijkste punten
response_formatretourneert een JSON-tekenreeks inresponse.choices[0].message.content- Parseren is uw verantwoordelijkheid:
json.loads(),model_validate_json()of een andere methode - U kunt een ruw JSON-schema gebruiken in plaats van een Pydantic-model
- Meer flexibiliteit dan
parse(), maar meer code om te schrijven - De geretourneerde JSON is gegarandeerd geldig; parseerfouten zouden niet mogen optreden