Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Strukturierte Modellausgaben

Stelle sicher, dass die Textantworten des Modells deinem JSON-Schema entsprechen.

JSON ist weltweit eines der gängigsten Formate für den Datenaustausch zwischen Anwendungen.

Wenn das Modell eine Anfrage vollständig beantwortet, ohne sie abzulehnen, entspricht die Antwort bei strukturierten Ausgaben deinem JSON-Schema. Deine Anwendung muss weiterhin Ablehnungen, unvollständige Antworten und API-Fehler behandeln. Außerdem muss sie prüfen, ob die Antwort alle Geschäftsregeln erfüllt, die das Schema nicht abbildet.

Strukturierte Ausgaben bieten unter anderem folgende Vorteile:

  1. Einhaltung des Schemas: Wenn du ein unterstütztes JSON-Schema vorgibst, enthält die Antwort alle darin vorgeschriebenen Felder und verwendet für Enum-Felder nur zulässige Werte.
  2. Explizite Ablehnungen: Du kannst jetzt im Code erkennen, wenn das Modell eine Anfrage aus Sicherheitsgründen ablehnt.
  3. Einfachere Prompts: Das Antwortformat bleibt auch ohne nachdrücklich formulierte Anweisungen konsistent.

Die REST-API unterstützt JSON Schema. Mit den OpenAI-Bibliotheken für Python und JavaScript kannst du Objektschemas auch direkt im Code definieren. In Python verwendest du dafür pydantic.BaseModel, in JavaScript z.object. Das folgende Beispiel zeigt, wie du Informationen aus unstrukturiertem Text extrahierst und ein Ergebnis erhältst, das dem im Code definierten Schema entspricht.

Das Ruby-SDK unterstützt Schemas, die du mit T::Struct von Sorbet definierst, und liefert nach dem Parsen typisierte Ergebnisse.

Eine strukturierte Antwort erhalten
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {"role": "system", "content": "Extract the event information."},
        {
            "role": "user",
            "content": "Alice and Bob are going to a science fair on Friday.",
        },
    ],
    text_format=CalendarEvent,
)

event = response.output_parsed

Unterstützte Modelle

Unsere neuesten großen Sprachmodelle unterstützen strukturierte Ausgaben ab GPT-4o. Verwende für neue Projekte zunächst gpt-6-astra. Bei älteren Modellen wie gpt-4-turbo und seinen Vorgängern kommt stattdessen der JSON-Modus infrage.

Strukturierte Ausgaben: Wann du Funktionsaufrufe verwendest und wann text.format

In der OpenAI API kannst du strukturierte Ausgaben auf zwei Arten nutzen:

  1. Mit Funktionsaufrufen
  2. Mit dem Antwortformat json_schema

Funktionsaufrufe eignen sich, wenn du dem Modell Funktionen deiner Anwendung zur Verfügung stellen möchtest.

Du kannst dem Modell zum Beispiel Zugriff auf Funktionen geben, die eine Datenbank abfragen. So lässt sich ein KI-Assistent entwickeln, der bei Fragen zu Bestellungen hilft. Du kannst auch Funktionen bereitstellen, die mit der Benutzeroberfläche interagieren.

Strukturierte Ausgaben über response_format eignen sich hingegen, wenn du ein Schema für die Antwort an die anfragende Person vorgeben möchtest. Für einen Toolaufruf verwendest du Funktionsaufrufe.

Wenn du zum Beispiel eine Anwendung für den Mathematikunterricht entwickelst, kannst du dem Assistenten für seine Antworten ein bestimmtes JSON-Schema vorgeben. So kannst du eine Benutzeroberfläche generieren, die einzelne Teile der Modellantwort unterschiedlich darstellt.

Für die Praxis gilt:

  • Verwende Funktionsaufrufe, wenn du das Modell mit Tools, Funktionen, Daten oder anderen Ressourcen deines Systems verbindest. Wenn du die Struktur der Antwort an die anfragende Person vorgeben möchtest, verwende ein strukturiertes text.format.

Der Rest dieses Leitfadens behandelt Anwendungsfälle ohne Funktionsaufrufe in der Responses API. Im Leitfaden zu

Funktionsaufrufen

erfährst du, wie du strukturierte Ausgaben mit Funktionsaufrufen verwendest.

Strukturierte Ausgaben und JSON-Modus im Vergleich

Strukturierte Ausgaben sind eine Weiterentwicklung des JSON-Modus. Beide stellen sicher, dass das Modell gültiges JSON erzeugt. Nur strukturierte Ausgaben gewährleisten auch, dass die Antwort dem vorgegebenen Schema entspricht. Die Responses API, die Chat Completions API, die Assistants API, die Fine-tuning API und die Batch API unterstützen beide Varianten.

Wir empfehlen, nach Möglichkeit immer strukturierte Ausgaben anstelle des JSON-Modus zu verwenden.

Strukturierte Ausgaben mit response_format: {type: "json_schema", ...} unterstützen allerdings nur die Modellversionen gpt-4o-mini, gpt-4o-mini-2024-07-18 und gpt-4o-2024-08-06 sowie neuere Versionen.

Strukturierte Ausgaben JSON-Modus
Gibt gültiges JSON aus Ja Ja
Hält das Schema ein Ja (siehe unterstützte Schemas) Nein
Kompatible Modelle gpt-4o-mini, gpt-4o-2024-08-06 und neuere Modelle gpt-3.5-turbo, gpt-4-*, gpt-4o-* und kompatible GPT-5-Modelle
Aktivierung text: { format: { type: "json_schema", "strict": true, "schema": ... } } text: { format: { type: "json_object" } }

Beispiele

Gedankenkette

Du kannst das Modell bitten, seine Antwort in einzelne Schritte zu gliedern. So können Lernende den Lösungsweg Schritt für Schritt nachvollziehen.

Strukturierte Ausgaben für die Mathe-Nachhilfe mit Gedankenketten
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()


class Step(BaseModel):
    explanation: str
    output: str


class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {
            "role": "system",
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
        },
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
)

math_reasoning = response.output_parsed

Beispielantwort

{
  "steps": [
    {
      "explanation": "Start with the equation 8x + 7 = -23.",
      "output": "8x + 7 = -23"
    },
    {
      "explanation": "Subtract 7 from both sides to isolate the term with the variable.",
      "output": "8x = -23 - 7"
    },
    {
      "explanation": "Simplify the right side of the equation.",
      "output": "8x = -30"
    },
    {
      "explanation": "Divide both sides by 8 to solve for x.",
      "output": "x = -30 / 8"
    },
    {
      "explanation": "Simplify the fraction.",
      "output": "x = -15 / 4"
    }
  ],
  "final_answer": "x = -15 / 4"
}

So verwendest du strukturierte Ausgaben mit text.format

Das Antwortformat während der Unterhaltung ändern

Um zwischen zwei Antworten zu einem neuen Schema zu wechseln, hänge ein Element vom Typ configuration_update an input an, bevor du die nächste Nutzernachricht hinzufügst. Gib bei jeder Anfrage auf der obersten Ebene weiterhin das ursprüngliche text.format an, damit das bisherige Prompt-Präfix für das Prompt-Caching infrage kommt.

Bei unterstützten Modellen ab GPT-6 kannst du das Antwortformat im Standardmodus mit einem einzelnen Agenten ändern.

Angenommen, im vorherigen Gesprächsschritt wurde eine Lieferung mit 17 roten und 26 blauen Kisten in Klartext beschrieben. Setze die Unterhaltung mit previous_response_id fort und übergib das folgende Array als input.

Von Klartext zur strukturierten Ausgabe der Kistenanzahl wechseln
from openai import OpenAI
from pydantic import BaseModel, ConfigDict


class CrateCount(BaseModel):
    model_config = ConfigDict(extra="forbid")
    total_crates: int


client = OpenAI()
model = "gpt-6-astra"

first = client.responses.create(
    model=model,
    input="Summarize this shipment in one sentence: 17 red crates and 26 blue crates.",
    store=True,
)

second = client.responses.parse(
    model=model,
    previous_response_id=first.id,
    input=[
        {
            "type": "configuration_update",
            "text": {
                "format": {
                    "type": "json_schema",
                    "name": "crate_count",
                    "schema": CrateCount.model_json_schema(),
                    "strict": True,
                }
            },
        },
        {"role": "user", "content": "How many crates are in the shipment?"},
    ],
    parse_as=CrateCount,
)

if second.status == "completed" and second.output_parsed is not None:
    print(second.output_parsed.total_crates)

Die erwartete Antwort lautet {"total_crates":43}. Im Antwortobjekt gibt text.format weiterhin das ursprünglich auf Anfrageebene festgelegte Format an. Prüfe zuerst, ob das Modell die Anfrage abgelehnt hat oder die Antwort unvollständig ist. Liegt eine vollständige Antwort ohne Ablehnung vor, parse sie mit dem Schema aus der letzten Formatänderung.

Jede Formatänderung ersetzt das gesamte Format. Das neue Format gilt auch in späteren Gesprächsschritten, selbst wenn du nur reasoning.effort änderst. Um wieder zu Klartext zu wechseln, hänge {"type":"configuration_update","text":{"format":{"type":"text"}}} an. Für Formatänderungen sind nur json_schema und text zulässig.

Wenn du den Gesprächsverlauf manuell erneut übergibst, belasse jede Aktualisierung an ihrer ursprünglichen Position. Gib nach einer expliziten Kontextverdichtung jede Einstellung erneut an, die du geändert hast. Weitere Informationen findest du im Abschnitt zur Kompatibilität von Konfigurationsänderungen.

Ablehnungen bei strukturierten Ausgaben

Wenn du strukturierte Ausgaben für Nutzereingaben verwendest, können OpenAI-Modelle eine Anfrage gelegentlich aus Sicherheitsgründen ablehnen. Eine Ablehnung folgt nicht unbedingt dem Schema, das du in response_format angegeben hast. Deshalb enthält die API-Antwort in diesem Fall ein neues Feld namens refusal. Es zeigt an, dass das Modell die Anfrage abgelehnt hat.

Wenn das Ausgabeobjekt die Eigenschaft refusal enthält, kannst du die Ablehnung in der Benutzeroberfläche anzeigen. Du kannst diesen Fall auch im Code abfangen, der die Antwort verarbeitet.

class Step(BaseModel):
    explanation: str
    output: str


class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {
            "role": "system",
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
        },
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
)

for output in response.output:
    if output.type != "message":
        continue

    for item in output.content:
        if item.type == "refusal":
            # If the model refuses to respond, you will get a refusal message
            print(item.refusal)
            continue

        if not item.parsed:
            raise Exception("Could not parse response")

        print(item.parsed)

Bei einer Ablehnung sieht die API-Antwort etwa so aus:

{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1721596428,
  "status": "completed",
  "completed_at": 1721596429,
  "error": null,
  "incomplete_details": null,
  "input": [],
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4o-2024-08-06",
  "output": [{
    "id": "msg_1234567890",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "refusal",
        "refusal": "I'm sorry, I cannot assist with that request."
      }
    ]
  }],
  "usage": {
    "input_tokens": 81,
    "output_tokens": 11,
    "total_tokens": 92,
    "output_tokens_details": {
      "reasoning_tokens": 0,
    }
  },
}

Tipps und bewährte Vorgehensweisen

Nutzereingaben verarbeiten

Wenn deine Anwendung Nutzereingaben verarbeitet, gib im Prompt an, wie das Modell vorgehen soll, wenn sich aus einer Eingabe keine gültige Antwort ableiten lässt.

Das Modell versucht immer, das vorgegebene Schema einzuhalten. Wenn die Eingabe inhaltlich nichts mit dem Schema zu tun hat, kann das Modell deshalb Informationen erfinden.

Du kannst im Prompt zum Beispiel festlegen, dass das Modell leere Parameter oder einen bestimmten Satz zurückgeben soll, wenn es erkennt, dass die Eingabe nicht zur Aufgabe passt.

Mit Fehlern umgehen

Auch strukturierte Ausgaben können Fehler enthalten. Wenn dir Fehler auffallen, passe deine Anweisungen an, ergänze die Systemanweisungen um Beispiele oder zerlege die Aufgabe in einfachere Teilaufgaben. Weitere Hinweise zum Anpassen deiner Eingaben findest du im Leitfaden zum Prompt Engineering.

JSON-Schema und Typdefinitionen synchron halten

Damit dein JSON-Schema und die entsprechenden Typen in deiner Programmiersprache übereinstimmen, empfehlen wir ausdrücklich, die integrierten Hilfsfunktionen des SDK für Schemas zu verwenden, sofern sie verfügbar sind.

Wenn du das JSON-Schema lieber direkt angibst, kannst du CI-Regeln hinzufügen, die Änderungen am JSON-Schema oder an den zugrunde liegenden Datenobjekten melden. Eine weitere Möglichkeit ist ein CI-Schritt, der das JSON-Schema automatisch aus den Typdefinitionen generiert oder umgekehrt.

Streaming

Mit Streaming kannst du Modellantworten oder Argumente von Funktionsaufrufen bereits während der Generierung verarbeiten und als strukturierte Daten einlesen.

So kannst du mit der Verarbeitung beginnen, bevor die vollständige Antwort vorliegt. Das ist besonders hilfreich, wenn du JSON-Felder nacheinander anzeigen oder die Argumente eines Funktionsaufrufs verarbeiten möchtest, sobald sie verfügbar sind.

Wir empfehlen, für das Streaming strukturierter Ausgaben die SDKs zu verwenden.

from openai import OpenAI
from pydantic import BaseModel


class EntitiesModel(BaseModel):
    attributes: list[str]
    colors: list[str]
    animals: list[str]


client = OpenAI()

with client.responses.stream(
    model="gpt-6-astra",
    input=[
        {"role": "system", "content": "Extract entities from the input text"},
        {
            "role": "user",
            "content": "The quick brown fox jumps over the lazy dog with piercing blue eyes",
        },
    ],
    text_format=EntitiesModel,
) as stream:
    for event in stream:
        if event.type == "response.refusal.delta":
            print(event.delta, end="")
        elif event.type == "response.output_text.delta":
            print(event.delta, end="")
        elif event.type == "error":
            raise RuntimeError(event.message)
        elif event.type in ("response.failed", "response.incomplete"):
            response = event.response
            message = f"Response {response.status}"
            if response.error and response.error.message:
                message += f": {response.error.message}"
            elif response.incomplete_details and response.incomplete_details.reason:
                message += f": {response.incomplete_details.reason}"
            raise RuntimeError(message)
        elif event.type == "response.completed":
            print("Completed")  # print(event.response.output)

    final_response = stream.get_final_response()
    print(final_response)

Unterstützte Schemas

Für strukturierte Ausgaben kannst du eine Teilmenge der Sprache JSON Schema verwenden.

Unterstützte Typen

Strukturierte Ausgaben unterstützen die folgenden Typen:

  • Zeichenkette
  • Zahl
  • Boolescher Wert
  • Ganzzahl
  • Objekt
  • Array
  • Aufzählung
  • anyOf

Unterstützte Eigenschaften

Neben dem Typ einer Eigenschaft kannst du zusätzliche Bedingungen festlegen.

Unterstützte Eigenschaften für string:

  • pattern gibt einen regulären Ausdruck an, dem die Zeichenkette entsprechen muss.
  • format legt das Format der Zeichenkette fest. Derzeit werden folgende vordefinierte Formate unterstützt:
    • date-time
    • time
    • date
    • duration
    • email
    • hostname
    • ipv4
    • ipv6
    • uuid

Unterstützte Eigenschaften für number:

  • multipleOf gibt den Wert an, dessen Vielfaches die Zahl sein muss.
  • maximum legt die Obergrenze fest. Die Zahl darf höchstens so groß sein wie dieser Wert.
  • exclusiveMaximum legt die Obergrenze fest. Die Zahl muss kleiner sein als dieser Wert.
  • minimum legt die Untergrenze fest. Die Zahl muss mindestens so groß sein wie dieser Wert.
  • exclusiveMinimum legt die Untergrenze fest. Die Zahl muss größer sein als dieser Wert.

Unterstützte Eigenschaften für array:

  • minItems gibt an, wie viele Elemente das Array mindestens enthalten muss.
  • maxItems gibt an, wie viele Elemente das Array höchstens enthalten darf.

Die folgenden Beispiele zeigen, wie du diese typspezifischen Bedingungen verwendest.

{
    "name": "user_data",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The name of the user"
            },
            "username": {
                "type": "string",
                "description": "The username of the user. Must start with @",
                "pattern": "^@[a-zA-Z0-9_]+$"
            },
            "email": {
                "type": "string",
                "description": "The email of the user",
                "format": "email"
            }
        },
        "additionalProperties": false,
        "required": [
            "name", "username", "email"
        ]
    }
}

Auf der obersten Ebene ist ein Objekt erforderlich und anyOf unzulässig

Auf der obersten Ebene muss das Schema ein Objekt beschreiben. Dort darf es anyOf nicht verwenden. In Zod ist es beispielsweise üblich, einen Union-Typ mit Diskriminator zu verwenden. Dadurch entsteht auf der obersten Ebene ein anyOf. Code wie im folgenden Beispiel funktioniert daher nicht.

import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";

const BaseResponseSchema = z.object({
  status: z.literal("success"),
  data: z.string(),
});
const UnsuccessfulResponseSchema = z.object({
  status: z.literal("error"),
  error: z.string(),
});

const finalSchema = z.discriminatedUnion("status", [
  BaseResponseSchema,
  UnsuccessfulResponseSchema,
]);

// Invalid JSON Schema for Structured Outputs
const json = zodResponseFormat(finalSchema, "final_schema");

Alle Felder müssen als required gekennzeichnet sein

Für strukturierte Ausgaben musst du alle Felder bzw. Funktionsparameter als required angeben.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": "string",
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": ["location", "unit"]
    }
}

Alle Felder sind Pflichtfelder, und das Modell gibt für jeden Parameter einen Wert zurück. Einen optionalen Parameter kannst du dennoch nachbilden, indem du einen Union-Typ verwendest, der null zulässt.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": ["string", "null"],
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": [
            "location", "unit"
        ]
    }
}

Grenzen für Verschachtelungstiefe und Größe von Objekten

Ein Schema darf insgesamt bis zu 5.000 Objekteigenschaften enthalten und bis zu 10 Ebenen tief verschachtelt sein.

Maximale Gesamtlänge von Zeichenketten

Alle Eigenschaftsnamen, Definitionsnamen, enum-Werte und const-Werte in einem Schema dürfen zusammen höchstens 120.000 Zeichen lang sein.

Größenbeschränkungen für Aufzählungen

Ein Schema darf über alle enum-Eigenschaften hinweg insgesamt bis zu 1.000 enum-Werte enthalten.

Wenn eine einzelne enum-Eigenschaft mehr als 250 Zeichenketten als Werte enthält, dürfen diese zusammen höchstens 15.000 Zeichen lang sein.

Für Objekte musst du immer additionalProperties: false setzen

additionalProperties legt fest, ob ein Objekt zusätzliche Schlüssel-Wert-Paare enthalten darf, die im JSON-Schema nicht definiert sind.

Bei strukturierten Ausgaben erzeugt das Modell nur die im Schema vorgesehenen Schlüssel und Werte. Um strukturierte Ausgaben zu verwenden, musst du daher additionalProperties: false setzen.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": "string",
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": [
            "location", "unit"
        ]
    }
}

Reihenfolge der Schlüssel

In strukturierten Ausgaben erscheinen die Schlüssel in derselben Reihenfolge wie im Schema.

Einige typspezifische Schlüsselwörter werden noch nicht unterstützt

  • Für die Kombination von Schemata: allOf, not, dependentRequired, dependentSchemas, if, then, else

Feinabgestimmte Modelle unterstützen außerdem die folgenden Schlüsselwörter nicht:

  • Für Zeichenketten: minLength, maxLength, pattern, format
  • Für Zahlen: minimum, maximum, multipleOf
  • Für Objekte: patternProperties
  • Für Arrays: minItems, maxItems

Wenn du strukturierte Ausgaben mit strict: true aktivierst und die API mit einem nicht unterstützten JSON-Schema aufrufst, erhältst du eine Fehlermeldung.

Bei anyOf muss jedes eingebettete Schema ein gültiges JSON-Schema sein und zur unterstützten Teilmenge gehören

Das folgende Beispiel zeigt ein unterstütztes Schema mit anyOf.

{
    "type": "object",
    "properties": {
        "item": {
            "anyOf": [
                {
                    "type": "object",
                    "description": "The user object to insert into the database",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The name of the user"
                        },
                        "age": {
                            "type": "number",
                            "description": "The age of the user"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name",
                        "age"
                    ]
                },
                {
                    "type": "object",
                    "description": "The address object to insert into the database",
                    "properties": {
                        "number": {
                            "type": "string",
                            "description": "The number of the address. Eg. for 123 main st, this would be 123"
                        },
                        "street": {
                            "type": "string",
                            "description": "The street name. Eg. for 123 main st, this would be main st"
                        },
                        "city": {
                            "type": "string",
                            "description": "The city of the address"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "number",
                        "street",
                        "city"
                    ]
                }
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "item"
    ]
}

Definitionen werden unterstützt

Mit Definitionen kannst du Teilschemata festlegen, auf die du an beliebigen Stellen in deinem Schema verweisen kannst. Das folgende Beispiel zeigt, wie das geht.

{
    "type": "object",
    "properties": {
        "steps": {
            "type": "array",
            "items": {
                "$ref": "#/$defs/step"
            }
        },
        "final_answer": {
            "type": "string"
        }
    },
    "$defs": {
        "step": {
            "type": "object",
            "properties": {
                "explanation": {
                    "type": "string"
                },
                "output": {
                    "type": "string"
                }
            },
            "required": [
                "explanation",
                "output"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "steps",
        "final_answer"
    ],
    "additionalProperties": false
}

Rekursive Schemata werden unterstützt

In diesem rekursiven Schema verweist # auf die Wurzel des Schemas.

{
    "name": "ui",
    "description": "Dynamically generated UI",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "type": {
                "type": "string",
                "description": "The type of the UI component",
                "enum": ["div", "button", "header", "section", "field", "form"]
            },
            "label": {
                "type": "string",
                "description": "The label of the UI component, used for buttons or form fields"
            },
            "children": {
                "type": "array",
                "description": "Nested UI components",
                "items": {
                    "$ref": "#"
                }
            },
            "attributes": {
                "type": "array",
                "description": "Arbitrary attributes for the UI component, suitable for any element",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The name of the attribute, for example onClick or className"
                        },
                        "value": {
                            "type": "string",
                            "description": "The value of the attribute"
                        }
                    },
                    "additionalProperties": false,
                    "required": ["name", "value"]
                }
            }
        },
        "required": ["type", "label", "children", "attributes"],
        "additionalProperties": false
    }
}

Das folgende Schema verwendet explizite Rekursion.

{
    "type": "object",
    "properties": {
        "linked_list": {
            "$ref": "#/$defs/linked_list_node"
        }
    },
    "$defs": {
        "linked_list_node": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "number"
                },
                "next": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/linked_list_node"
                        },
                        {
                            "type": "null"
                        }
                    ]
                }
            },
            "additionalProperties": false,
            "required": [
                "next",
                "value"
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "linked_list"
    ]
}

JSON-Modus

Der JSON-Modus ist eine einfachere Variante der strukturierten Ausgaben. Er stellt sicher, dass das Modell gültiges JSON ausgibt. Bei strukturierten Ausgaben entspricht das Ergebnis außerdem zuverlässig dem Schema, das du vorgibst. Wir empfehlen strukturierte Ausgaben, wenn sie für deinen Anwendungsfall unterstützt werden.

Bei aktiviertem JSON-Modus gibt das Modell gültiges JSON aus. Es gibt einige Ausnahmefälle, die deine Anwendung erkennen und entsprechend behandeln sollte.

Um den JSON-Modus in der Responses API zu aktivieren, kannst du text.format auf { "type": "json_object" } setzen. Bei Funktionsaufrufen ist der JSON-Modus immer aktiviert.

Wichtige Hinweise:

  • Im JSON-Modus musst du das Modell in mindestens einer Nachricht der Unterhaltung ausdrücklich anweisen, JSON zu erzeugen, etwa in der Systemnachricht. Ohne diese Anweisung kann das Modell fortlaufend Leerraumzeichen ausgeben. Die Anfrage läuft dann unter Umständen weiter, bis das Tokenlimit erreicht ist. Damit du die Anweisung nicht vergisst, meldet die API einen Fehler, wenn die Zeichenfolge „JSON“ im Kontext fehlt.
  • Der JSON-Modus gewährleistet, dass die Ausgabe gültiges JSON ist und sich fehlerfrei parsen lässt. Ob sie einem bestimmten Schema entspricht, garantiert er nicht. Verwende strukturierte Ausgaben, um sicherzustellen, dass die Ausgabe deinem Schema entspricht. Falls das nicht möglich ist, prüfe die Ausgabe mit einer Validierungsbibliothek und wiederhole die Anfrage bei Bedarf.
  • Deine Anwendung muss Ausnahmefälle erkennen und behandeln, in denen das Modell möglicherweise kein vollständiges JSON-Objekt ausgibt (siehe unten).

Weiterführende Ressourcen

Wenn du mehr über strukturierte Ausgaben erfahren möchtest, empfehlen wir dir diese Ressourcen: