Manuelle Antwortformatierung

Mehr Kontrolle durch response_format

Die manuelle Methode über response_format bietet Ihnen volle Kontrolle über das Parsing. Im Gegensatz zu parse(), das ein typisiertes Objekt zurückgibt, liefert dieser Ansatz eine JSON-Zeichenfolge, die Sie selbst parsen – das Pydantic-Modell stellt lediglich das Schema bereit (model_json_schema()) und validiert im Nachhinein. Wählen Sie diese Methode, wenn Sie Flexibilität benötigen oder in einer Umgebung ohne Pydantic arbeiten.

Arbeitsablauf

Mit response_format erfolgt der Prozess in zwei Schritten:

1. Die API gibt das JSON als Zeichenfolge in response.choices[0].message.content zurück.
2. Sie parsen diese Zeichenfolge mit Ihrer bevorzugten Methode.

Vollständiges Beispiel

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()
        }
    }
)

# Der Inhalt ist eine JSON-Zeichenfolge
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Manuelles Parsen mit Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Unterschiede zu parse()

Parsing ohne Pydantic

Sie müssen Pydantic nicht verwenden, um das Ergebnis zu parsen. Das Standardmodul json funktioniert ebenfalls:

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"]

Wann response_format wählen

response_format kommt zum Tragen, wenn Sie das JSON vor seiner Umwandlung in ein Objekt einsehen oder inspizieren müssen. Der häufigste Anwendungsfall ist das Protokollieren: In der Produktion ist die Aufbewahrung des rohen JSON vor der Transformation oft eine Anforderung für Audits oder das Debugging, und parse() bietet diesen Abfangpunkt nicht. Als nächstes kommt die Frage des Schemas: Wenn Ihr Schnittstellenvertrag ein rohes JSON-Schema ist – das mit anderen Teams geteilt wird, von einem Tool generiert wird oder unabhängig vom Python-Code versioniert wird – ist die direkte Durchsetzung treuer als die Rekonstruktion als Pydantic-Modell. Schließlich operiert nicht jedes Projekt innerhalb des Pydantic-Ökosystems: Wenn Ihre Validierung über ein anderes Framework läuft oder über einen Zwischenschritt erfolgt, der spezifisch für Ihre Pipeline ist, übergibt response_format Ihnen das JSON unverändert und lässt Sie die Kontrolle über den weiteren Verlauf behalten.

Fehlerbehandlung

Bei der manuellen Methode müssen Sie Parsing-Fehler selbst behandeln:

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Parsing error: {e}")

In der Praxis sollte dieser Fehler niemals auftreten, da die API gültiges JSON garantiert. Eine defensive Behandlung bleibt jedoch in der Produktion eine bewährte Praxis.

Kernaussagen

• response_format gibt eine JSON-Zeichenfolge in response.choices[0].message.content zurück.
• Das Parsing ist Ihre Verantwortung: json.loads(), model_validate_json() oder eine andere Methode.
• Sie können ein rohes JSON-Schema anstelle eines Pydantic-Modells verwenden.
• Mehr Flexibilität als parse(), aber mehr Code zum Schreiben.
• Das zurückgegebene JSON ist garantiert gültig – Parsing-Fehler sollten nicht auftreten.