Lotook
Structured outputs sind eine Funktion von LLM APIs, die eine Modellantwort an ein von Ihnen vorgegebenes JSON Schema bindet. Mithilfe von constrained decoding kompiliert die API Ihr Schema in eine Grammatik oder einen Zustandsautomaten, der die Token-Erzeugung einschränkt und so Syntaxfehler und fehlende Felder in APIs von OpenAI, Anthropic und Google verhindert.
Was sind Structured Outputs in einer LLM API?
Structured outputs in einer LLM API schränken die vom Modell erzeugten Tokens so ein, dass die fertige Antwort einem von Entwicklern vorgegebenen JSON Schema entspricht. Anthropic und Google bezeichnen den zugrunde liegenden Mechanismus als constrained decoding: Vor Beginn des Samplings kompiliert die API Ihr Schema in eine Grammatik oder einen endlichen Zustandsautomaten, der jedes nächste Token ausschließt, das gegen Struktur, Schlüsselnamen oder Werttypen des Schemas verstoßen würde.
Ohne structured outputs funktioniert die Aufforderung an ein Sprachmodell, in JSON zu antworten, im Produktivbetrieb nicht zuverlässig. Die Dokumentation von Anthropic nennt vier häufige Fehlerarten bei ausschließlicher Verwendung von Prompt-Anweisungen: Parsing-Fehler durch ungültige JSON-Syntax, fehlende Pflichtfelder, inkonsistente Datentypen und Schema-Verstöße, die Fehlerbehandlung und erneute Versuche erfordern. In der Praxis sehen diese Fehler beispielsweise so aus:
- Parsing-Fehler durch ungültige JSON-Syntax: Nicht geschlossene Klammern, abschließende Kommas oder Markdown-Text um die Nutzdaten können etwa einen JSON-Parser aus dem Takt bringen.
- Fehlende Pflichtfelder: Ein Modell kann etwa einen Schlüssel auslassen, den nachgelagerter Anwendungscode erwartet.
- Inkonsistente Datentypen: Ein numerisches Feld kann etwa als Zeichenfolge oder ein einzelner Wert anstelle eines Arrays eintreffen.
- Schema-Verstöße mit Fehlerbehandlung und erneuten Versuchen: Nicht angeforderte Schlüssel oder Werte außerhalb des zulässigen Bereichs erzwingen etwa Wiederholungsschleifen und defensive Validierung.
Constrained decoding macht nachdrückliche Formatierungsanweisungen im Prompt überflüssig. Damit die Anwendungstypen dem an die API übergebenen Schema entsprechen, bieten OpenAI und Google native SDK-Hilfsfunktionen für Pydantic-BaseModel-Klassen in Python und Zod-Objekte in JavaScript. Das Python SDK von Anthropic akzeptiert ein Pydantic-Modell über client.messages.parse() und parst die Antwort in diesen Typ.
Wie unterscheiden sich Structured Outputs von JSON mode und JSON nur per Prompt?
Structured outputs garantieren die Einhaltung Ihres exakten JSON Schema, während JSON mode und reine Prompt-Anweisungen weder bestimmte Eigenschaftsnamen noch verschachtelte Strukturen oder Pflichtfelder erzwingen können.
JSON mode war der Zwischenschritt vor vollständigen Schema-Einschränkungen. Bei OpenAI stellt die Aktivierung von JSON mode über { "type": "json_object" } sicher, dass das Modell syntaktisch gültiges JSON erzeugt, sofern kein Sonderfall eintritt, etwa wenn die Ausgabe-Tokens mitten in einem Objekt ausgehen. Die Dokumentation von OpenAI nennt jedoch ausdrückliche Einschränkungen: Sie müssen irgendwo im Gesprächskontext eine Anweisung zur JSON-Ausgabe aufnehmen. Fehlt das Wort JSON, gibt die API einen Fehler aus; andernfalls kann das Modell einen endlosen Strom von Leerzeichen erzeugen, bis das Token-Limit erreicht ist.
OpenAI bezeichnet structured outputs als Weiterentwicklung von JSON mode und empfiehlt sie überall dort, wo sie unterstützt werden. JSON mode ist für ältere Modelle wie gpt-4-turbo und frühere Modelle vorgesehen.
| Funktion | JSON nur per Prompt | JSON mode | Structured Outputs |
|---|---|---|---|
| Gültige JSON-Syntax garantiert | Nein | Ja, sofern nicht abgeschnitten | Ja, sofern nicht abgelehnt oder abgeschnitten |
| Erzwingt exaktes Schema und Typen | Nein | Nein | Ja |
| Benötigt JSON-Anweisung im Prompt | Ja | Ja, von OpenAI vorgeschrieben | Nein |
| Vermeidet formatbedingte Wiederholungen | Nein | Teilweise | Ja, für die Schema-Struktur |
| Natives Parsing mit Pydantic und Zod | Manuell | Manuell | Von Anbieter-SDKs unterstützt |
Structured Outputs und Function Calling: Wann nutzen Sie was?
Structured outputs formatieren die endgültige Antwort des Modells an Ihre Anwendung oder Endnutzer, während function calling das Modell während der Ausführung mit externen Tools, APIs und Datenquellen verbindet.
Entwickler verwechseln die beiden Funktionen oft, weil beide auf JSON Schema-Definitionen beruhen. OpenAI und Google ziehen dieselbe architektonische Grenze:
- Nutzen Sie structured outputs, wenn die endgültige Assistant-Nachricht sauber für Ihre Benutzeroberfläche, Datenbank oder nachgelagerte Pipeline formatiert sein soll, etwa zur Datenextraktion oder strukturierten Klassifikation.
- Nutzen Sie function calling (tool use), wenn das Modell eine Aktion anfordern, aktuelle Datensätze abrufen oder eine Backend-Routine aufrufen muss, bevor es antworten kann. Mehr zur Einbindung von Tool-Definitionen in moderne Protokolle erfahren Sie in unserem Leitfaden zu tool calling und MCP.
OpenAI bietet strikte Schemas in zwei Formen: function calling mit strikten Schemas zur Verbindung des Modells mit Tools oder Daten und das Antwortformat json_schema zur Strukturierung der Antwort an Nutzer. Anthropic trennt seine Funktionen in output_config.format für Claudes endgültige Antwort und strict: true für einzelne Tools, um gültige Tool-Namen und Eingabeargumente zu garantieren; beide lassen sich ausdrücklich in einer Anfrage verwenden. Diese Kombination ist besonders praktisch in AI agent workflows, in denen sowohl zwischenzeitliche Tool-Aufrufe als auch die abschließende Zusammenfassung strikte Vorgaben erfüllen müssen.
Wie OpenAI, Anthropic und Google Structured Outputs umsetzen
OpenAI, Anthropic und Google implementieren structured outputs jeweils durch Schema-Kompilierung, Stand November 2026. Anfrageparameter, unterstützte JSON Schema-Schlüsselwörter und Komplexitätsgrenzen unterscheiden sich jedoch.
| Anbieter | Aktivierung | SDK-Schemahilfen | Wichtige Schema-Regeln | Wichtige Grenzen |
|---|---|---|---|---|
| OpenAI | Responses API text.format oder Chat Completions response_format mit type: "json_schema" und strict: true |
Pydantic BaseModel (Python), Zod (JS) |
Wurzel muss ein Objekt sein, kein anyOf; alle Felder in required; additionalProperties: false erforderlich; Schlüssel in Schema-Reihenfolge ausgegeben |
Bis zu 5.000 Eigenschaften, 10 Verschachtelungsebenen, 120.000 Zeichen für Namen/Enums, 1.000 Enum-Werte |
| Anthropic Claude | output_config.format mit type: "json_schema", dazu strict: true für Tools |
client.messages.parse() mit Pydantic (Python) |
Unterstützt $ref/$defs, anyOf und allOf (mit Grenzen); additionalProperties: false erforderlich; keine Grenzen für Zahlen oder Zeichenfolgenlängen |
Maximal 20 strikte Tools, 24 optionale Parameter, 16 Union-Parameter, 180s Kompilierungs-Timeout; Grammatik-Cache für 24 Stunden |
| Google Gemini API | Antwortkonfiguration mit Texttyp, mime_type: "application/json" und Schema |
Pydantic (Python), Zod (JS) | Unterstützt minimum/maximum, minItems/maxItems, prefixItems; entfernt nicht unterstützte Grenzen stillschweigend |
Große oder tief verschachtelte Schemas schlagen mit 400 INVALID_ARGUMENT fehl |
OpenAI
OpenAI unterstützt structured outputs ab GPT-4o und empfiehlt gpt-6-astra für neue Projekte. Ein API-Aufruf mit strict: true und einem nicht unterstützten Schlüsselwort wie allOf, not, if/then/else, dependentRequired oder dependentSchemas gibt einen Fehler zurück, statt stillschweigend fehlzuschlagen. OpenAI unterstützt Zeichenfolgenformate wie date-time, time, date, duration, email, hostname, ipv4, ipv6 und uuid sowie numerische Grenzen (minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf) und Array-Grenzen (minItems, maxItems).
Anthropic Claude
Anthropic unterstützt structured outputs für alle Modelle der Messages API, jedoch nicht innerhalb von Managed Agents. Wenn Sie client.messages.parse() im Python SDK verwenden, werden nicht unterstützte Einschränkungen wie minimum, maximum, minLength und maxLength automatisch in Feldbeschreibungen verschoben, damit Claude die Absicht erkennt. Das SDK validiert die zurückgegebenen Nutzdaten lokal gegen Ihr ursprüngliches Pydantic-Modell.
Claude speichert kompilierte Grammatiken ab der letzten Nutzung 24 Stunden im Cache. Änderungen an der Schema-Struktur oder am Tool-Satz invalidieren diesen Cache, Änderungen an Feldnamen oder Beschreibungen dagegen nicht. Da Claude zudem einen automatischen System-Prompt erhält, der das JSON-Format erklärt, steigt die Zahl der Eingabe-Tokens leicht; eine Änderung von output_config.format invalidiert den Prompt-Cache der Unterhaltung. Pflichtfelder werden zuerst ausgegeben, gefolgt von optionalen Feldern. Structured outputs funktionieren mit Streaming, Token-Zählung und Batch processing (mit 50 Prozent Rabatt von Anthropic). Die Kombination von JSON-Ausgaben mit Citations gibt jedoch einen 400-Fehler zurück; structured outputs sind außerdem mit dem Vorbefüllen von Nachrichten inkompatibel.
Google Gemini API
Google nennt Datenextraktion, strukturierte Klassifikation und agentische Arbeitsabläufe als wichtigste Anwendungsfälle für structured outputs in Gemini. Anders als OpenAI und Anthropic entfernt und ignoriert Gemini mehrere Schlüsselwörter stillschweigend, ohne einen Fehler auszugeben, darunter minLength, maxLength, minProperties, maxProperties, uniqueItems, contains, minContains und maxContains. Sie sollten bei Gemini-Antworten stets Pydantic model_validate_json() oder Zod .parse() ausführen, um diese Einschränkungen im Anwendungscode durchzusetzen. Gibt Gemini bei einem zu komplexen Schema 400 INVALID_ARGUMENT zurück, empfiehlt Google, Verschachtelungen abzuflachen, optionale Felder oder Enums zu reduzieren, Eigenschaftsnamen zu kürzen und nicht strukturelle Regeln in Feldbeschreibungen zu verschieben.
Wie Sie ein zuverlässiges JSON Schema für LLMs entwerfen
Ein zuverlässiges JSON Schema für structured outputs von LLMs bleibt flach, markiert Felder als erforderlich und verwendet nullable Typen statt optionaler Schlüssel. Schemas nach gemeinsamen anbieterübergreifenden Regeln zu entwerfen, hilft, Kompilierungsfehler und unerwartete Ablehnungen zur Laufzeit zu vermeiden.
Nutzen Sie diese Checkliste, bevor Sie ein Schema für OpenAI, Claude oder Gemini bereitstellen:
- Halten Sie Verschachtelungen flach: Flachen Sie tief verschachtelte Objekte nach Möglichkeit ab, um deutlich unter der Grenze von 10 Ebenen bei OpenAI zu bleiben und Kompilierungsablehnungen durch Gemini oder Claude zu vermeiden.
- Machen Sie jedes Feld erforderlich: Führen Sie jeden Objektschlüssel in
requiredauf, da OpenAI diese Regel strikt durchsetzt und Claude die Gesamtzahl optionaler Parameter pro Anfrage auf 24 begrenzt. - Nutzen Sie nullable Unions für fehlende Daten: Stellen Sie optionale Werte mit
"type": ["string", "null"]dar, statt Schlüssel ausrequiredwegzulassen. - Schränken Sie Objekte ein: Setzen Sie
"additionalProperties": falsefür jede Objektdefinition, wie von OpenAI und Anthropic vorgeschrieben. - Begrenzen Sie feste Auswahlmöglichkeiten mit Enums: Ersetzen Sie offene Zeichenfolgenkategorien durch explizite
enum-Arrays, wenn nur bekannte Bezeichnungen gültig sind. - Schreiben Sie klare Beschreibungen: Platzieren Sie Fachregeln und ignorierte Einschränkungen wie Zielwerte für Zeichenlängen oder Fallback-Anweisungen in der
descriptionjeder Eigenschaft.
Das folgende Beispielschema klassifiziert ein Kundensupport-Ticket. Es folgt den oben genannten anbieterübergreifenden Regeln: ein Wurzelobjekt, alle Felder erforderlich, ein nullable Feld für optionale Metadaten, additionalProperties: false und ein enum für die Weiterleitung.
{
"type": "object",
"additionalProperties": false,
"required": ["category", "urgency", "summary", "order_id"],
"properties": {
"category": {
"type": "string",
"enum": ["billing", "bug_report", "account_access", "other"],
"description": "Primary topic of the support message."
},
"urgency": {
"type": "string",
"enum": ["low", "normal", "high"],
"description": "Escalation priority based on user impact."
},
"summary": {
"type": "string",
"description": "One-sentence summary of the issue in 25 words or fewer."
},
"order_id": {
"type": ["string", "null"],
"description": "Order identifier if present in the message, otherwise null."
}
}
}Was kann bei Structured Outputs weiterhin schiefgehen?
Structured outputs garantieren gültige Syntax gemäß Ihrem Schema. Dennoch treten in produktiven Anwendungen Ablehnungen, abgeschnittene Tokens, halluzinierte Werte, abweichende Groß- und Kleinschreibung bei Enums, Latenz bei der ersten Anfrage und nicht vertrauenswürdige Nutzereingaben auf. Wenn Sie Schema-Konformität als Prüfung der Syntax statt als Prüfung auf Wahrheit oder Sicherheit behandeln, vermeiden Sie stille Fehler im Produktivbetrieb.
Sicherheitsbedingte Ablehnungen und Abschneiden am Token-Limit
Modelle können unsichere Nutzeranfragen weiterhin ablehnen oder die Erzeugung beim Erreichen Ihrer Ausgabe-Token-Grenze mittendrin stoppen. Bei OpenAI füllt eine sicherheitsbedingte Ablehnung ein separates Feld refusal, das Ihrem JSON Schema nicht entspricht. Bei Anthropic Claude gibt eine Ablehnung HTTP 200 mit stop_reason auf "refusal" zurück (was weiterhin berechnet wird) und setzt Ihr Schema außer Kraft. Ebenso gibt das Erreichen der Ausgabegrenze stop_reason "max_tokens" mit unvollständigem JSON zurück. Prüfen Sie immer Ablehnungsindikatoren und Stoppgründe, bevor Sie JSON.parse() oder einen Validator aufrufen.
Schema-gültige, aber sachlich falsche Werte
Constrained decoding zwingt das Modell, Ihr Schema auszufüllen, selbst wenn der Quelltext keine Antwort enthält oder den Annahmen des Schemas widerspricht. Eine Antwort kann alle Typ- und enum-Prüfungen bestehen und dennoch erfundene Daten, falsche Kategorien oder plausibel klingende Vermutungen enthalten. OpenAI empfiehlt, das Modell im Prompt anzuweisen, was es bei mit dem Schema unvereinbaren Eingaben zurückgeben soll, etwa null oder leere Felder. Google rät Entwicklern, Werte im Code anhand von Geschäftsregeln zu validieren. Mehr darüber, warum überzeugend klingende Ausgaben falsch sein können, lesen Sie in unserem Leitfaden zu AI-Halluzinationsraten.
Enum-Großschreibung bei Claude und Kompilierungslatenz
Zwei Besonderheiten im Betrieb überraschen Teams bei der Einführung:
- Enum-Großschreibung bei Claude: Anthropic weist darauf hin, dass die Groß- und Kleinschreibung von Enums beim constrained decoding nicht garantiert ist. Vergleichen Sie zurückgegebene Enum-Zeichenfolgen daher in Ihrer Anwendungslogik ohne Beachtung der Groß- und Kleinschreibung.
- Kompilierungsverzögerung bei der ersten Anfrage: Claude benötigt zusätzliche Zeit, wenn ein neues Schema erstmals in eine Grammatik kompiliert und anschließend 24 Stunden zwischengespeichert wird. OpenAI nennt eine ähnliche Verzögerung bei der ersten Schema-Verarbeitung für feinabgestimmte Modelle.
Prompt Injection in Feldwerten
Die Einschränkung der Ausgabestruktur neutralisiert keine bösartigen Anweisungen, die in nicht vertrauenswürdigem Text versteckt sind, der zusammengefasst oder in ein JSON-Zeichenfolgenfeld extrahiert wird. Ein Modell kann regelkonform gültiges JSON zurückgeben, dessen Feld summary oder notes eingeschleuste Anweisungen oder irreführende Inhalte für nachgelagerte Tools oder menschliche Prüfer enthält. Behandeln Sie jeden geparsten Feldwert als nicht vertrauenswürdige Eingabe und lesen Sie unsere Einführung dazu, was Prompt Injection ist, bevor Sie extrahierte Felder für automatisierte Aktionen verwenden.
Häufig gestellte Fragen
Verlangsamen structured outputs LLM-Antworten?
Structured outputs können bei der ersten Anfrage mit einem neuen Schema zusätzliche Latenz verursachen; spätere Anfragen aus dem Cache laufen ohne Kompilierungsaufwand. Anthropic speichert kompilierte Claude-Grammatiken ab der letzten Nutzung 24 Stunden, sofern Sie die Schema-Struktur oder Tool-Definitionen nicht ändern. OpenAI nennt zusätzliche Latenz bei der ersten Schema-Verarbeitung nur für feinabgestimmte Modelle.
Kann ein LLM bei structured outputs weiterhin halluzinieren?
Ja, ein LLM kann Werte halluzinieren und gleichzeitig zu 100 Prozent schema-gültiges JSON zurückgeben. Constrained decoding beschränkt Token-Syntax und Feldtypen, nicht die sachliche Richtigkeit. Fehlen in der Eingabe erforderliche Informationen, kann das Modell Werte für Pflichtschlüssel erfinden, sofern Sie keine nullable Felder zulassen und es nicht anweisen, wann es null zurückgeben soll.
Sollte ich Pydantic oder Zod mit structured output APIs verwenden?
Native SDK-Schemahilfen helfen, Anwendungstypen und API-Schemas aufeinander abzustimmen. OpenAI und Google unterstützen sowohl Pydantic in Python als auch Zod in JavaScript, während das Python SDK von Anthropic Pydantic über client.messages.parse() unterstützt. Diese Hilfen wandeln Ihre Modelle in JSON Schema um, parsen Antworten in typisierte Objekte und validieren Einschränkungen wie Zeichenfolgenlängen, die Gemini entfernt oder Anthropic in Feldbeschreibungen verschiebt.
Was passiert, wenn ein Modell eine Anfrage mit aktivierten structured outputs ablehnt?
Lehnt ein Modell eine Anfrage aus Sicherheitsgründen ab, setzt die Ablehnung Ihr JSON Schema außer Kraft. OpenAI platziert die Erklärung in einem eigenen Feld refusal, statt dem Schema zu folgen; Anthropic gibt HTTP 200 mit stop_reason auf "refusal" zurück. Ihre Anwendung muss diese Felder prüfen, bevor sie versucht, JSON zu parsen.
Warum lehnt Claude oder Gemini mein JSON Schema mit einem 400-Fehler ab?
Claude und Gemini lehnen Schemas mit einem 400-Fehler ab, wenn sie interne Komplexitätsgrenzen für Grammatik oder Zustandsautomaten überschreiten. Claude gibt auch einen 400-Fehler zurück, wenn Sie nicht unterstützte Schema-Funktionen wie rekursive Schemas oder numerische Grenzen einfügen oder JSON-Ausgaben mit Citations kombinieren. Verschachtelte Objekte abzuflachen, Namen zu kürzen und optionale oder Union-Parameter zu reduzieren, behebt solche Kompilierungsablehnungen meist.
