Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Strukturierte Ausgabe: Garantiertes JSON

Lektion 9 von 22 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Strukturierte Ausgabe: Garantiertes JSON
  2. Das Problem, das dies löst
  3. Pydantic statt handgeschriebener JSON-Schema
  4. Zwei häufige Anwendungsfälle
  5. Was strenger Modus erfordert
  6. Wichtige Erkenntnisse

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 required aufgeführt sein
  • additionalProperties muss False sein
  • Unterstützte Typen: string, number, integer, boolean, array, object, null
  • Kein oneOf oder anyOf mit 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: True für garantierte Schema-Konformität
  • Ideal für Datenextraktion, Klassifizierung und strukturierte Generierung