response_format-manuaalinen käyttö
Tällä sivulla
Tarkempi hallinta response_format-menetelmällä
Manuaalinen menetelmä response_format-parametrin avulla antaa sinulle täyden hallinnan jäsennykseen. Toisin kuin parse(), joka palauttaa tyypitetyn objektin, tämä lähestymistapa palauttaa JSON-merkkijonon, jonka jäsennät itse – Pydantic-malli tarjoaa vain skeeman (model_json_schema()) ja suorittaa validoinnin jälkikäteen. Valitse tämä menetelmä, kun tarvitset joustavuutta tai työskentelet ympäristössä, jossa Pydanticia ei ole käytettävissä.
Työnkulku
Käytettäessä response_format-parametria prosessi etenee kahdessa vaiheessa:
- API palauttaa JSONin merkkijonona kentässä
response.choices[0].message.content - Jäsennät tämän merkkijonon valitsemallasi menetelmällä
Täydellinen esimerkki
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()
}
}
)
# Sisältö on JSON-merkkijono
json_string = response.choices[0].message.content
print(type(json_string)) # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}
# Manuaalinen jäsennys Pydanticilla
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title) # "Inception"
Erot parse()-metodiin verrattuna
| Näkökulma | parse() | response_format |
|---|---|---|
| Palautusarvo | (Response, ParsedModel) | Vain Response |
| Jäsennys | Automaattinen | Manuaalinen |
| Tietojen käyttö | parsed.kenttä | json.loads() tai model_validate_json() |
| Joustavuus | Vakio | Maksimaalinen |
| Virheenkäsittely | Sisäänrakennettu | Sinun vastuullasi |
Jäsennys ilman Pydanticia
Sinun ei tarvitse käyttää Pydanticia tuloksen jäsentämiseen. Myös vakio json-moduuli toimii:
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"]
Milloin valita response_format
response_format loistaa aina, kun haluat tarkastella tai tutkia JSONia ennen sen muuntamista objektiksi. Yleisin tapaus on lokitus: tuotantoympäristössä raakana JSONina säilyttäminen ennen muunnosta on usein auditointi- tai vianetsintävaatimus, eikä parse() tarjoa tätä sieppauspistettä. Seuraavaksi tulee skeema-kysymys: jos rajapintasopimuksesi on raaka JSON-skeema – jaettu muiden tiimien kanssa, työkalun generoima tai versioidtu erillään Python-koodista – sen suora pakottaminen on uskollisempaa kuin sen uudelleenrakentaminen Pydantic-mallina. Lopuksi, kaikki projektit eivät toimi Pydantic-ekosysteemissä: jos validointisi kulkee toisen kehyksen läpi tai läpi putkistosi spesifin välivaiheen käsittelyn, response_format antaa sinulle JSONin sellaisenaan ja jättää sinut hallitsemaan seuraavia vaiheita.
Virheenkäsittely
Manuaalisessa menetelmässä sinun on käsiteltävä jäsennysvirheet itse:
import json
try:
data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
print(f"Jäsennysvirhe: {e}")
Käytännössä tämän virheen ei pitäisi koskaan esiintyä, sillä API takaa kelvollisen JSONin. Puolustava käsittely on kuitenkin edelleen paras käytäntö tuotantoympäristöissä.
Keskeiset asiat
response_formatpalauttaa JSON-merkkijonon kohteessaresponse.choices[0].message.content- Jäsennys on sinun vastuullasi:
json.loads(),model_validate_json()tai jokin muu menetelmä - Voit käyttää raakaa JSON-skeemaa Pydantic-mallin sijaan
- Joustavampi kuin
parse(), mutta vaatii enemmän koodin kirjoittamista - Palautettu JSON on taatusti kelvollinen – jäsennysvirheitä ei pitäisi esiintyä