Strukturierte Ausgabe: Garantiertes JSON
Auf dieser Seite
Strukturierte Ausgabe: Garantiertes JSON
Die strukturierte Ausgabe ist eine der leistungsfähigsten Funktionen der Responses API. Anstatt darauf zu hoffen, dass das Modell gültiges JSON zurückgibt, garantieren Sie dies, indem Sie ein Schema bereitstellen. Das Modell ist dann strukturell daran gehindert, davon abzuweichen. Dies verwandelt ein Sprachmodell von einem kreativen Textgenerator in einen zuverlässigen Bestandteil einer automatisierten Verarbeitungsleitung.
Das Problem, das dies löst
Das Anfordern von JSON im Prompt funktioniert die meiste Zeit, was genau den Grund für die Gefährlichkeit dieses Ansatzes ausmacht. An einem von hundert Tagen fügt das Modell einen einleitenden Satz vor seine Antwort, umwickelt alles in einen Markdown-Codeblock oder benennt ein Feld um – und Ihr json.loads() wirft in der Produktion eine Ausnahme für eine Anfrage, die Sie nicht reproduzieren können.
from openai import OpenAI
client = OpenAI()
# Ohne Struktur — das Modell kann jedes Format zurückgeben
response = client.responses.create(
model="gpt-5.6-terra",
input="Gib mir Informationen über Paris in JSON."
)
print(response.output_text)
# Unvorhersehbares Ergebnis:
# Manchmal gültiges JSON, manchmal Text, der JSON enthält,
# manchmal ein unerwartetes Format...
Der Parameter text ändert die Natur der Garantie. Sie deklarieren ein json_schema-Format zusammen mit dem erwarteten Schema, und die Ausgabe entspricht diesem: Die Deserialisierung wird zu einer sicheren Operation.
response = client.responses.create(
model="gpt-5.6-terra",
input="Gib mir Informationen über Paris.",
text={
"format": {
"type": "json_schema",
"name": "city_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"},
"population": {"type": "integer"},
"official_language": {"type": "string"},
"landmarks": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "country", "population", "official_language", "landmarks"],
"additionalProperties": False
}
}
}
)
import json
data = json.loads(response.output_text)
print(f"Stadt: {data['name']}")
print(f"Einwohnerzahl: {data['population']:,}")
print(f"Sehenswürdigkeiten: {', '.join(data['landmarks'])}")
# Ergebnis GARANTIERT gültiges JSON:
# Stadt: Paris
# Einwohnerzahl: 2.161.000
# Sehenswürdigkeiten: Eiffelturm, Louvre, Notre-Dame, Triumphbogen, Sacré-Cœur
Pydantic statt handgeschriebener JSON-Schema
Das Schreiben von Schemas von Hand wird schnell mühsam und anfällig für Tippfehler. Mit Pydantic können Sie diese als Python-Klassen beschreiben, das JSON-Schema mit model_json_schema() generieren und dann die Antwort mit model_validate_json() validieren und typisieren. Am Ende der Kette erhalten Sie ein vollständiges Python-Objekt mit Editor-Autovervollständigung, anstatt ein anonymes Wörterbuch.
from pydantic import BaseModel
from typing import Optional
import json
class Produkt(BaseModel):
name: str
price: float
category: str
in_stock: bool
description: Optional[str] = None
response = client.responses.create(
model="gpt-5.6-terra",
input="Beschreibe einen High-End-Gaming-Laptop.",
text={
"format": {
"type": "json_schema",
"name": "product",
"strict": True,
"schema": Produkt.model_json_schema()
}
}
)
# Parsen und Validieren mit Pydantic
produkt = Produkt.model_validate_json(response.output_text)
print(f"Produkt: {produkt.name}")
print(f"Preis: {produkt.price} EUR")
print(f"Auf Lager: {'Ja' if produkt.in_stock else 'Nein'}")
# Ergebnis:
# Produkt: ASUS ROG Strix G18
# Preis: 2499,99 EUR
# Auf Lager: Ja
Nichts schränkt Sie auf flache Strukturen ein. Durch das Komponieren von Klassen beschreiben Sie verschachtelte Objekte und Listen von Objekten, die Sie benötigen, sobald Sie ein realistisches Kundenprofil erstellen: Eine Firma enthält Kontakte, und jeder Kontakt hat eine Adresse.
from pydantic import BaseModel
class Adresse(BaseModel):
street: str
city: str
postal_code: str
country: str
class Kontakt(BaseModel):
last_name: str
first_name: str
email: str
phone: str
address: Adresse
class Firma(BaseModel):
name: str
sector: str
employees: int
contacts: list[Kontakt]
response = client.responses.create(
model="gpt-5.6-terra",
input="Generiere ein fiktives Firmenprofil im Technologie-Sektor "
"mit 2 Kontakten.",
text={
"format": {
"type": "json_schema",
"name": "company",
"strict": True,
"schema": Firma.model_json_schema()
}
}
)
firma = Firma.model_validate_json(response.output_text)
print(f"Firma: {firma.name} ({firma.sector})")
for c in firma.contacts:
print(f" - {c.first_name} {c.last_name}: {c.email}")
Zwei häufige Anwendungsfälle
Der erste ist die Extraktion: das Umwandeln von geschriebenen Text in ein verwertbares Datensatz. Eine Konferenzankündigung, die in natürlicher Sprache verfasst ist, wird zu einer Datenbankzeile mit Titel, Datum, Ort und Teilnehmerzahl – ohne reguläre Ausdrücke und ohne zu brechen, sobald sich die Formulierung ändert.
class Event(BaseModel):
title: str
date: str
location: str
attendees: int
text = """
Die PyCon France 2026-Konferenz findet am 15. und 16. November
im Palais des Congrès in Lyon statt. Mehr als 800 Python-Entwickler
sind für diese Ausgabe erwartet.
"""
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Extrahieren Sie die Informationen aus diesem Event:\n{text}",
text={
"format": {
"type": "json_schema",
"name": "event",
"strict": True,
"schema": Event.model_json_schema()
}
}
)
evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} in {evt.location} ({evt.attendees} Teilnehmer)")
# Ergebnis: PyCon France 2026 - 15.-16. November 2026 in Lyon (800 Teilnehmer)
Der zweite ist die Klassifizierung. Indem Sie eine Aufzählung deklarieren, beschränken Sie das Modell auf ein geschlossenes Vokabular: Es kann nicht antworten mit “eher positiv” oder “positiv”, wenn Ihr Code positive erwartet. Dies ist der Unterschied zwischen einem Wert, den Sie direkt verwenden können, und einem Wert, den Sie nachträglich normalisieren müssen.
from enum import Enum
class Sentiment(str, Enum):
positive = "positive"
negative = "negative"
neutral = "neutral"
class Analyse(BaseModel):
sentiment: Sentiment
confidence: float
keywords: list[str]
response = client.responses.create(
model="gpt-5.6-terra",
input="Analysieren Sie diesen Kommentar: 'Großartiger Service, schnelle Lieferung!'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"strict": True,
"schema": Analyse.model_json_schema()
}
}
)
analyse = Analyse.model_validate_json(response.output_text)
print(f"Stimmung: {analyse.sentiment.value} ({analyse.confidence:.0%})")
# Ergebnis: Stimmung: positive (95%)
Was strenger Modus erfordert
Die Garantie hat einen Preis: Wenn strict: True aktiviert ist, muss das Schema einem bestimmten Teilbereich von JSON Schema entsprechen. Diese Einschränkungen sind die Hauptursache für 400-Fehler bei Anfängern, daher ist es am besten, sie zu kennen, bevor Sie auf sie stoßen:
- Alle Eigenschaften müssen in
requiredaufgeführt sein additionalPropertiesmussFalsesein- Unterstützte Typen:
string,number,integer,boolean,array,object,null - Kein
oneOfoderanyOfmit gemischten Typen - Verwenden Sie
Optional[str], was{"anyOf": [{"type": "string"}, {"type": "null"}]}übersetzt
Die Regel zu required überrascht Menschen oft: Ein optionales Feld wird nicht ausgedrückt, indem es aus der Liste entfernt wird, sondern indem der null-Wert erlaubt wird, genau das, was Optional[str] auf der Pydantic-Seite erzeugt.
Wichtige Erkenntnisse
- Strukturierte Ausgabe garantiert, dass die Antwort Ihrem JSON-Schema entspricht
- Verwenden Sie
text={"format": {"type": "json_schema", ...}}in der Responses API - Pydantic ist das ideale Werkzeug zur Definition und Validierung von Schemas
- Aktivieren Sie
strict: Truefür garantierte Schema-Konformität - Ideal für Datenextraktion, Klassifizierung und strukturierte Generierung