OpenAI Strukturierte Ausgaben: Anleitung zur Nutzung

Am Ende dieses Leitfadens werden Sie in der Lage sein, strukturierte OpenAI-Ausgaben aus Ihrem eigenen Code aufzurufen: Sie übergeben dem Modell ein JSON-Schema, setzen strict: true und erhalten eine Antwort zurück, die garantiert der von Ihnen angeforderten Form entspricht. Sie senden eine erste Anfrage, lesen die Antwort, behandeln die Grenzfälle und generieren API-Testsammlungen in Apidog, die bestätigen, dass die Nutzlast tatsächlich konform ist.

Schaltfläche

Was Sie vor dem Start benötigen

Strukturierte Ausgaben schränken die Generierung des Modells ein, sodass die Ausgabe einem von Ihnen bereitgestellten JSON-Schema entspricht. Wenn Sie ein Schema mit strict: true übergeben, kann das Modell kein Feld ausgeben, das dagegen verstößt. Jeder erforderliche Schlüssel ist vorhanden, jeder Typ stimmt überein und jeder Enum-Wert ist einer der von Ihnen aufgelisteten. Sie hören auf, defensiven Parsing-Code zu schreiben, und beginnen, der Nutzlast zu vertrauen.

Das ist ein echtes Upgrade gegenüber der Alternative. Freitext-Prompts wie „Antworten Sie nur mit JSON“ funktionieren, bis sie es nicht mehr tun. Eine gedankliche Abweichung und Sie erhalten Prosa um Ihr Objekt gewickelt oder ein Datum, wo Sie eine Ganzzahl erwartet haben. Strukturierte Ausgaben verschieben den Vertrag von einer hoffnungsvollen Anweisung zu einer erzwungenen Einschränkung zur Dekodierungszeit.

Um mitzumachen, benötigen Sie:

Einen OpenAI API-Schlüssel, der als OPENAI_API_KEY gesetzt ist.
Ein Modell, das die strikte Schema-Durchsetzung unterstützt (mehr zu den Modellen weiter unten).
Ein JSON-Schema, das die gewünschte Ausgabeform beschreibt.

Wählen Sie das richtige Modell

Strukturierte Ausgaben sind bei den neueren Modellen von OpenAI verfügbar, beginnend mit der GPT-4o-Familie und fortgesetzt in der GPT-5-Serie. Die OpenAI-Dokumentation empfiehlt derzeit, neue Projekte mit ihrem neuesten Flaggschiff (gpt-5.5 zum Zeitpunkt der Erstellung) zu starten. Ältere Modelle und Modelle der gpt-3.5-Ära unterstützen den JSON-Modus, aber keine strikte Schema-Durchsetzung. Wenn Sie auf strict: true angewiesen sind, vergewissern Sie sich vor der Veröffentlichung, dass die spezifische Modell-ID dies unterstützt, da die Unterstützung an Modellversionen gebunden ist und OpenAI diese kontinuierlich weiterentwickelt.

Es hilft zu wissen, welche Funktion Sie tatsächlich anstreben, da OpenAI zwei verwandte Funktionen anbietet, die leicht zu verwechseln sind.

JSON-Modus (response_format: { "type": "json_object" }) garantiert, dass die Ausgabe *syntaktisch gültiges JSON* ist. Das ist alles. Er kennt Ihre Felder, Ihre Typen oder Ihre erforderlichen Schlüssel nicht. Sie müssen die Form immer noch selbst validieren.

Strukturierte Ausgaben (response_format mit type: "json_schema" und strict: true) garantieren, dass die Ausgabe gültiges JSON ist *und* Ihrem Schema entspricht. OpenAI beschreibt strukturierte Ausgaben als die Evolution des JSON-Modus: Beide erzeugen gültiges JSON, aber nur strukturierte Ausgaben erzwingen die Schema-Konformität. Für neue Arbeiten sind strukturierte Ausgaben die richtige Wahl.

	JSON-Modus	Strukturierte Ausgaben (strikt)
Parameter	`response_format: {"type":"json_object"}`	`response_format` mit `type: "json_schema"`, `strict: true`
Gültiges JSON	Ja	Ja
Entspricht Ihrem Schema	Nein	Ja
Erforderliche Felder erzwungen	Nein	Ja
Typen und Enums erzwungen	Nein	Ja
Sie validieren immer noch nachgelagert	Immer	Empfohlen (siehe unten)

Ein Hinweis zu APIs: Der Chat Completions Endpunkt verwendet response_format wie oben gezeigt. Die neuere Responses API drückt dasselbe unter text.format mit type: "json_schema" aus. Die Schema-Regeln sind identisch; nur der Wrapper unterscheidet sich. Überprüfen Sie die aktuelle Dokumentation für den genauen Feldpfad am von Ihnen aufgerufenen Endpunkt.

Ihre erste Anfrage stellen

Nehmen wir an, Sie extrahieren ein Support-Ticket in einen typisierten Datensatz. Hier ist eine Chat Completions Anfrage mit einem strikten Schema.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "system", "content": "Extract the ticket into the schema." },
      { "role": "user", "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary":  { "type": "string" },
            "category": { "type": "string", "enum": ["billing", "bug", "account", "other"] },
            "severity": { "type": "integer" },
            "account_id": {
              "anyOf": [ { "type": "string" }, { "type": "null" } ]
            }
          },
          "required": ["summary", "category", "severity", "account_id"],
          "additionalProperties": false
        }
      }
    }
  }'

Die Antwort lesen

Das Modell gibt eine Nachricht zurück, deren content ein JSON-String ist, der dem Schema entspricht, zum Beispiel:

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}

Beachten Sie, dass account_id anyOf mit null verwendet. So modelliert man ein optionales Feld, was direkt zu den Regeln führt, die Sie beim Schreiben Ihrer eigenen Schemas befolgen müssen.

Bleiben Sie innerhalb der Schema-Untermenge

Strukturierte Ausgaben akzeptieren eine Untermenge von JSON Schema. Die Untermenge existiert, damit OpenAI die Einschränkungen zuverlässig durchsetzen und das kompilierte Schema zwischenspeichern kann. Die Regeln, die man sich merken sollte:

Die Wurzel muss ein Objekt sein. Sie können die oberste Ebene nicht zu einem Array oder einem einfachen String machen. Umschließen Sie eine Liste in einer Objekteigenschaft.
Jede Eigenschaft muss in required aufgeführt sein. Es gibt kein „optional“ im üblichen Sinne. Um ein Feld nullable zu machen, geben Sie ihm anyOf mit dem Typ null, wie im obigen Beispiel.
additionalProperties muss bei jedem Objekt false sein. Dies verhindert, dass das Modell zusätzliche Schlüssel erfindet.
Es gelten Größenbeschränkungen. Ein Schema kann grob bis zu 100 Objekteigenschaften mit bis zu 5 Verschachtelungsebenen enthalten. Tief verschachtelte oder ausufernde Schemas werden abgelehnt, also glätten Sie, wo immer Sie können.
Einige Schlüsselwörter werden nicht durchgesetzt. Nur zur Validierung dienende Schlüsselwörter wie pattern, format, minLength und minimum werden vom Modell nicht garantiert. Wenn Sie möchten, dass ein Regex oder ein numerischer Bereich eingehalten wird, müssen Sie dies nach Erhalt der Antwort selbst überprüfen.
Latenz beim ersten Aufruf. Die erste Anfrage mit einem neuen Schema benötigt Zeit zum Kompilieren (normalerweise Sekunden, manchmal bis zu einer Minute bei komplexen Schemas). Danach wird es zwischengespeichert und ist schnell.

Da Validierungsschlüsselwörter nicht erzwungen werden, bedeutet „garantiertes JSON“ nicht „garantiert geschäftsvalid“. Die Struktur ist gesperrt. Die Werte darin verdienen immer noch einen Test. Wenn Sie jemals optionale oder Union-Felder mit oneOf/anyOf/allOf modelliert haben, ist das mentale Modell vertraut: Ein Schema schränkt die Form ein, aber Sie bestätigen echte Werte separat.

Ablehnungen und Kürzungen behandeln

Es gibt einen Fall, in dem die Ausgabe absichtlich nicht Ihrem Schema entspricht. Wenn das Modell eine unsichere Anfrage ablehnt, gibt es stattdessen ein refusal-Feld in der Nachricht zurück, anstatt schemakonformen Inhalt. Ihr Code sollte dies vor dem Parsen abfangen:

msg = response.choices[0].message
if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)

Ablehnungen sind jetzt programmatisch erkennbar, was sauberer ist, als den Text nach einer Entschuldigung zu durchsuchen. Zwei weitere Gründe, warum eine Antwort dem Schema nicht entsprechen könnte: Erreichen von max_tokens mitten im Objekt (das JSON wird abgeschnitten) oder die Verwendung paralleler Tool-Aufrufe, die von strukturierten Ausgaben nicht unterstützt werden. Setzen Sie parallel_tool_calls auf false, wenn Sie die beiden kombinieren.

So testen Sie es in Apidog

Der strikte Modus erzwingt das Schema zur Generierungszeit. Er entbindet Sie nicht vom Testen. Modelle werden ausgetauscht, Schemas weichen ab, ein Teamkollege bearbeitet das required-Array, oder ein Ablehnungspfad ändert sich. Sie wollen einen Test, der lautstark fehlschlägt, wenn die Antwort nicht mehr dem Vertrag entspricht. Hier passt Apidog.

Um die Arbeitsteilung präzise zu beschreiben: Der strikte Modus von OpenAI erzeugt schemakonformes JSON. Apidog erzwingt das Schema nicht auf Modellebene. Was Apidog tut, ist, die *zurückerhaltene Antwort* gegen das erwartete Schema zu validieren, sodass Sie Abweichungen in CI statt in der Produktion erkennen.

Hier ist der Workflow:

Senden Sie die Anfrage. Erstellen Sie den Chat Completions Aufruf in Apidog mit Ihrem response_format-Block. Speichern Sie ihn in einer Sammlung, damit er wiederholbar ist.
Bestätigen Sie die Form. Fügen Sie Antwort-Assertions in Apidog hinzu. Überprüfen Sie, ob category einer Ihrer Enum-Werte ist, dass severity eine Ganzzahl ist, dass account_id ein String oder Null ist. Apidog kann die Antwort gegen ein JSON-Schema validieren, sodass Sie das genaue Schema anhängen und den Lauf fehlschlagen lassen, wenn die Nutzlast abweicht.
Führen Sie es in CI aus. Platzieren Sie die Sammlung in Ihrer Pipeline, damit jede Modell- oder Prompt-Änderung die Konformität erneut überprüft. Ein stiller Schema-Bruch führt zu einem roten Build.
Mocken Sie den Vertrag. Bevor der eigentliche Aufruf existiert, oder um nachgelagerte Konsumenten zu testen, ohne Tokens auszugeben, erstellen Sie eine Mock-API, die schemakonforme Beispielantworten zurückgibt. Ihr Frontend und Ihre Tests laufen gegen eine stabile Form, während sich die Integration festigt.

Dieser letzte Punkt wird unterschätzt. Sie können alles, was die strukturierte Ausgabe *konsumiert*, gegen einen Mock entwickeln und testen, der dasselbe Schema einhält, und dann den Live-OpenAI-Aufruf einfügen, wenn Sie bereit sind. Laden Sie Apidog herunter und Sie können die Anfrage, die Assertions und den Mock an einem Ort erstellen.

Häufig gestellte Fragen

Ist der JSON-Modus veraltet, jetzt, da es strukturierte Ausgaben gibt? Der JSON-Modus funktioniert weiterhin und garantiert gültiges JSON. Er erzwingt nur kein Schema. Für neuen Code sind strukturierte Ausgaben mit strict: true die stärkere Wahl. Verwenden Sie den reinen JSON-Modus nur bei Modellen, die keine strikten Schemas unterstützen, oder wenn Sie tatsächlich keine feste Form haben.

Kann die Wurzel meines Schemas ein Array sein? Nein. Die oberste Ebene muss ein Objekt sein. Umschließen Sie Ihre Liste in einer Eigenschaft, wie { "items": [...] }, und setzen Sie items in required. Das verwirrt viele Leute am ersten Tag.

Wie mache ich ein Feld optional? Strukturierte Ausgaben erfordern, dass jede Eigenschaft in required enthalten ist, daher gibt es kein klassisches optionales Feld. Modellieren Sie „fehlend“ als nullable: Verwenden Sie anyOf mit einem string (oder welchem Typ auch immer) und einem null. Der Schlüssel ist immer vorhanden; sein Wert kann null sein.

Bedeutet der strikte Modus, dass ich die Validierung komplett überspringen kann? Die Struktur ist garantiert, sodass Sie Formprüfungen überspringen können. Aber Schlüsselwörter wie pattern, format und numerische Bereiche werden vom Modell nicht erzwungen, und Ablehnungen oder Kürzungen können immer noch nicht spezifikationskonforme Antworten erzeugen. Ein Konformitätstest hat immer noch seinen Wert. Wenn Sie neu in diesem Format sind, deckt dieser JSON Schema Primer die Bausteine ab, und Sie können die Prüfung bei jeder Bereitstellung durchführen.

Welche Modelle soll ich verwenden? Strukturierte Ausgaben funktionieren mit GPT-4o und neueren Modellen, einschließlich der GPT-5-Serie. Die OpenAI-Dokumentation empfiehlt neue Projekte mit ihrem aktuellen Flaggschiff zu starten. Bestätigen Sie, dass die genaue Modell-ID den strikten Modus unterstützt, bevor Sie sich darauf verlassen, da die Unterstützung den Modellversionen folgt.

Zusammenfassung

Sie haben nun den vollständigen Ablauf: Wählen Sie ein Modell, das den strikten Modus unterstützt, senden Sie eine Chat Completions Anfrage mit json_schema und strict: true, halten Sie Ihr Schema innerhalb der unterstützten Untermenge, verzweigen Sie bei refusal, und denken Sie daran, dass Regeln auf Werteebene immer noch überprüft werden müssen. Dann beweisen Sie es mit einem Test: Erstellen Sie die Anfrage in Apidog, bestätigen Sie die Antwort gegen Ihr Schema und mocken Sie sie, damit der Rest Ihres Stacks weiterarbeiten kann, während sich die Integration festigt. Das Modell verspricht die Form. Ihre Tests beweisen, dass es so geblieben ist.

Schaltfläche