JSON-Modus und Schema-Enforcement
Auf dieser Seite
Lektion aktualisiert am 3. November 2026 basierend auf der OpenAI-Dokumentation:
temperatureundtop_pwerden nur mit einem Reasoning-Effort vonnoneakzeptiert, während GPT-5.6-Modelle standardmäßig mitmediumreasonieren. Aufrufe, die diese Parameter setzen, müssen daherreasoning={"effort": "none"}(Responses API) oderreasoning_effort="none"(Chat Completions) angeben. Quellen: Using GPT-6 · GPT-5.6 Terra.
JSON-Modus und Schema-Enforcement
Der Structured Output von OpenAI garantiert, dass die Antwort des Modells gültiges JSON ist, das einem von Ihnen definierten Schema entspricht. Keine mehr zerbrechliche Parsing-Logik mit regulären Ausdrücken oder Formatierungsfehlern – die Einschränkung wird direkt auf der Generierungsebene angewendet.
Diese Nuance ist entscheidend und ändert alles für einen Entwickler. Die Aufforderung „Antworten Sie in JSON” im Prompt ist ein Flehen: Das Modell gehorcht meistens, aber an einem Tag fügt es dem Response den Präfix „Hier ist das angeforderte JSON:” hinzu, verwendet Markdown-Hintergrundticks oder vergisst ein Komma, und Ihr json.loads wirft eine Ausnahme in der Produktion um 3 Uhr morgens am größten Batch der Woche. Mit Structured Output wird die Einschränkung während der Dekodierung angewendet: Tokens, die ungültiges oder nicht konformes JSON erzeugen würden, können einfach nicht ausgewählt werden. Sie hören auf zu flehen und beginnen, durchzusetzen.
JSON-Modus vs. Structured Output
OpenAI bietet zwei Ebenen der Einschränkung, und der Unterschied beruht auf einem einzigen Wort. Der JSON-Modus garantiert gültiges JSON ohne strukturelle Einschränkungen; Structured Output garantiert JSON, das einem von Ihnen geschriebenen JSON-Schema entspricht.
Der JSON-Modus löst das Problem zur Hälfte. Sie sind sicher, dass Sie den Response parsen können, aber nicht sicher, was er enthält: Das Modell könnte ein Feld in einer Anfrage annee und in der nächsten year nennen oder seine Liste in einem resultats-Objekt einwickeln, das es den Tag zuvor nicht verwendet hat. Für einen Prototypen oder eine Rohanzeige, die für einen Menschen gedacht ist, reicht dies aus; sobald die Ausgabe Code füttert, der Felder nach Namen zugreift, benötigen Sie die zweite Ebene.
from openai import OpenAI
client = OpenAI()
# Einfacher JSON-Modus (gültiges JSON, freie Struktur)
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Antworten Sie immer in JSON.",
input="Listen Sie 3 Programmiersprachen mit ihrem Gründungsjahr.",
text={"format": {"type": "json_object"}}
)
import json
data = json.loads(response.output_text)
print(data)
Structured Output mit JSON-Schema
Dies ist die leistungsfähigste Funktion. Sie definieren ein JSON-Schema, und die API garantiert, dass die Ausgabe diesem entspricht. Das folgende Beispiel analysiert die Stimmung einer Kundenbewertung und illustriert drei komplementäre Anwendungen des Schemas.
Das enum bei sentiment verhindert, dass das Modell eine Zwischenkategorie wie „ziemlich positiv” erfindet: Es muss sich zwischen den vier bereitgestellten Werten entscheiden, wodurch die Ausgabe direkt in einem Filter oder Dashboard nutzbar wird. Die description des score-Felds wirkt als lokaler Mini-Prompt, der den erwarteten Maßstab angibt, ohne dass Sie ihn in den allgemeinen Anweisungen erklären müssen, und bleibt dem Feld auch dann angehängt, wenn sich der Prompt entwickelt. Schließlich ermöglicht das aspects-Array, eine widersprüchliche Bewertung zu zerlegen – hier ein Produkt, das geliebt wurde, aber die Lieferung gescheitert ist –, anstatt diese Nuance in eine einzige Punktzahl zu pressen, die niemandem hilft.
response = client.responses.create(
model="gpt-5.6-terra",
input="Analysieren Sie die Stimmung von: 'Das Produkt ist hervorragend, "
"aber die Lieferung war katastrophal.'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"schema": {
"type": "object",
"properties": {
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "mixed", "neutral"]
},
"score": {
"type": "number",
"description": "Punktzahl von -1.0 (sehr negativ) bis 1.0 (sehr positiv)"
},
"aspects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"aspect": {"type": "string"},
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "neutral"]
}
},
"required": ["aspect", "sentiment"],
"additionalProperties": False
}
},
"summary": {"type": "string"}
},
"required": ["sentiment", "score", "aspects", "summary"],
"additionalProperties": False
},
"strict": True
}
}
)
result = json.loads(response.output_text)
# Garantiert: result hat genau die definierten Felder
print(f"Stimmung: {result['sentiment']}")
print(f"Punktzahl: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Regeln für striktes Structured Output
Der Modus strict: true verhängt eigene Einschränkungen über das Schema. Alle Felder müssen in required erscheinen, und additionalProperties muss bei jedem Objekt auf false stehen. Zulässige Typen sind string, number, integer, boolean, array, object und null, plus enum, um Werte einzuschränken. Weder pattern noch minLength/maxLength werden jedoch akzeptiert: die feingranulare Validierung findet auf der Client-Seite statt.
Diese Regeln können beim ersten Versuch überraschend wirken, da sie das optionale Feld so verbieten, wie es in einem JSON-Schema üblicherweise geschrieben wird. Der Kompromiss ist komfortabel: Ihr Code muss nie testen, ob ein Schlüssel existiert; er ist immer da. Für ein Feld, das rechtmäßig leer sein kann – eine fehlende Telefonnummer in einem Dokument, ein Enddatum für einen laufenden Vertrag – lautet die Antwort nicht, es aus required zu entfernen, sondern es zuzulassen, dass es null ist. Was die Abwesenheit von pattern und Längenbeschränkungen betrifft, signalisiert dies die nächste Lektion: Das Schema garantiert die Form, aber die geschäftliche Validierung bleibt Ihre Aufgabe, sobald die Antwort empfangen wurde.
Helfer zum Erstellen von Schemas
Das manuelle Schreiben des text.format-Blocks für jeden Aufruf wird schnell mühsam und fehleranfällig – ein fehlender name-Schlüssel, ein falsch platziertes strict, und der Fehler kommt von der API zurück, ohne anzuzeigen, wo man suchen soll. Ein paar Zeilen Wrapper-Code zentralisieren die Struktur, wenden standardmäßig eine niedrige Temperatur an (da Variabilität der Extraktion nichts hinzufügt) und machen den Aufrufsort lesbar.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Wrapper für Structured Output-Anfragen."""
response = client.responses.create(
model=model,
reasoning={"effort": "none"}, # temperature erfordert effort none
instructions=system or "Antworten Sie in JSON gemäß dem bereitgestellten Schema.",
input=prompt,
text={
"format": {
"type": "json_schema",
"name": schema_name,
"schema": schema,
"strict": True
}
},
temperature=0.1
)
return json.loads(response.output_text)
Beispiel: Strukturierte Datenerfassung
Hier ist der Anwendungsfall, der allein die Erlernung dieser Technik rechtfertigt: die Umwandlung einer als reiner Text empfangenen Rechnung in ein Objekt, das von Ihrem Buchhaltungssystem genutzt werden kann. Das Schema beschreibt drei Ebenen – den Rechnungskopf, ein verschachteltes vendor-Objekt und ein lines-Array, bei dem jedes Element die gleiche Form hat. Das Modell muss daher Informationen finden, die im gesamten Dokument verstreut sind, und sie an den richtigen Ort setzen, einschließlich für eine Zeile, die in Stunden statt in Einheiten ausgedrückt ist, wobei der Einheitspreis als Stundensatz verstanden wird.
Beachten Sie, dass Totale im Schema als zu extrahierende Felder erscheinen, nicht zur Neuberechnung. Wir bitten das Modell, zu lesen; die Kontrolle der Arithmetik erfolgt danach in Ihrem Code, wo ein einfacher Vergleich zwischen der Summe der Zeilen und dem extrahierten total_ht Dokumente für eine menschliche Überprüfung markiert.
invoice_schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"date": {"type": "string"},
"vendor": {
"type": "object",
"properties": {
"name": {"type": "string"},
"siret": {"type": "string"},
"address": {"type": "string"}
},
"required": ["name", "siret", "address"],
"additionalProperties": False
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"quantity": {"type": "integer"},
"unit_price_excl_tax": {"type": "number"},
"vat_percent": {"type": "number"}
},
"required": ["description", "quantity",
"unit_price_excl_tax", "vat_percent"],
"additionalProperties": False
}
},
"total_excl_tax": {"type": "number"},
"total_incl_tax": {"type": "number"}
},
"required": ["invoice_number", "date", "vendor",
"lines", "total_excl_tax", "total_incl_tax"],
"additionalProperties": False
}
invoice_text = """
Rechnung Nr. 2026-0042
Datum: 15/03/2026
Lieferant: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris
- REST API Entwicklung x1: 3500,00 EUR zzgl. MwSt. (MwSt. 20%)
- Cloud-Hosting (3 Monate) x1: 450,00 EUR zzgl. MwSt. (MwSt. 20%)
- Technischer Support x10h: 150,00 EUR zzgl. MwSt./h (MwSt. 20%)
Gesamt zzgl. MwSt.: 5450,00 EUR
Gesamt inkl. MwSt.: 6540,00 EUR
"""
result = structured_query(
invoice_text,
invoice_schema,
schema_name="invoice",
system="Extrahieren Sie die Daten aus dieser Rechnung."
)
Messung des Nutzens der Einschränkung
Wenden Sie dieses Prinzip auf ein Dokument an, das Sie gut kennen: Definieren Sie ein JSON-Schema, um Schlüsselinformationen aus einem Lebenslauf zu extrahieren – Name, Erfahrung, Fähigkeiten, Ausbildung – und testen Sie es auf drei Lebensläufen als reiner Text, die bewusst für ihre heterogenen Layouts ausgewählt wurden. Verifizieren Sie, dass die Ausgabe dem Schema entspricht, auch wenn eine Sektion vollständig fehlt.
Wiederholen Sie dann dieselbe Extraktion ohne Structured Output, indem Sie einfach im Prompt nach JSON bitten, und halten Sie die sechs Ausgaben nebeneinander. Der Vergleich der beiden Reihen zeigt, was die Einschränkung bringt: Der Unterschied liegt selten im extrahierten Inhalt, fast immer in der Stabilität der Feldnamen und der Anwesenheit erwarteter Schlüssel.
Wichtige Erkenntnisse
- Structured Output garantiert JSON, das dem Schema auf der Generierungsebene entspricht
- Verwenden Sie
strict: truefür maximale Konformität - Alle Felder müssen
requiredsein mitadditionalProperties: false - Ideal für Datenerfassung, Klassifizierung und Verarbeitungs-Pipelines
- Feingranulare Validierung (Länge, Muster) findet auf der Client-Seite nach Erhalt statt