Ręczne response_format
Na tej stronie
Większa kontrola dzięki response_format
Ręczna metoda poprzez response_format daje Ci pełną kontrolę nad parsowaniem. W przeciwieństwie do parse(), które zwraca typizowany obiekt, to podejście zwraca ciąg JSON, który parsujesz samodzielnie – model Pydantic dostarcza jedynie schemat (model_json_schema()) i przeprowadza walidację afterward. Wybierz tę metodę, gdy potrzebujesz elastyczności lub pracujesz w środowisku bez Pydantic.
Przebieg pracy
Przy użyciu response_format proces odbywa się w dwóch krokach:
- API zwraca JSON jako ciąg znaków w
response.choices[0].message.content - Parsujesz ten ciąg wybraną przez siebie metodą
Kompletny przykład
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()
}
}
)
# Zawartość to ciąg JSON
json_string = response.choices[0].message.content
print(type(json_string)) # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}
# Ręczne parsowanie z Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title) # "Inception"
Różnice względem parse()
| Aspekt | parse() | response_format |
|---|---|---|
| Zwracana wartość | (Response, ParsedModel) | Tylko Response |
| Parsowanie | Automatyczne | Ręczne |
| Dostęp do danych | parsed.field | json.loads() lub model_validate_json() |
| Elastyczność | Standardowa | Maksymalna |
| Obsługa błędów | Wbudowana | Twoja odpowiedzialność |
Parsowanie bez Pydantic
Nie musisz używać Pydantic do parsowania wyniku. Standardowy moduł json również działa:
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"]
Kiedy wybrać response_format
response_format sprawdza się zawsze, gdy musisz zobaczyć lub zbadać JSON, zanim stanie się on obiektem. Najczęstszym przypadkiem jest logowanie: w środowisku produkcyjnym zachowanie surowego JSON przed transformacją jest często wymogiem audytowym lub debugerskim, a parse() nie daje Ci takiego punktu перехwycenia. Kolejną kwestią jest schemat: jeśli kontraktem Twojego interfejsu jest surowy schemat JSON – udostępniany innym zespołom, generowany przez narzędzie, wersjonowany niezależnie od kodu Python – wymuszanie go bezpośrednio jest wierniejsze niż rekonstruowanie go jako modelu Pydantic. Wreszcie, nie każdy projekt działa w ekosystemie Pydantic: jeśli Twoja walidacja przechodzi przez inny framework lub przez pośredni krok przetwarzania specyficzny dla Twojego potoku, response_format przekazuje Ci JSON „tak jak jest“ i pozostawia Ci kontrolę nad tym, co nastąpi dalej.
Obsługa błędów
Przy metodzie ręcznej musisz samodzielnie obsługiwać błędy parsowania:
import json
try:
data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
print(f"Błąd parsowania: {e}")
W praktyce ten błąd nigdy nie powinien wystąpić, ponieważ API gwarantuje poprawny JSON. Jednak defensywne obsługiwanie błędów pozostaje dobrą praktyką w środowisku produkcyjnym.
Kluczowe wnioski
response_formatzwraca ciąg JSON wresponse.choices[0].message.content- Parsowanie leży po Twojej stronie:
json.loads(),model_validate_json()lub inna metoda - Możesz użyć surowego schematu JSON zamiast modelu Pydantic
- Większa elastyczność niż
parse(), ale więcej kodu do napisania - Zwrócony JSON jest gwarantowanie poprawny – błędy parsowania nie powinny wystąpić