Strukturierte Ausgaben

Strukturierte Ausgaben beschränken Claudes Antworten auf ein bestimmtes Schema und gewährleisten gültige, analysierbare Ausgaben für die nachgelagerte Verarbeitung. Strukturierte Ausgaben bieten zwei komplementäre Funktionen:

• JSON-Ausgaben (output_config.format): Claudes Antwort in einem bestimmten JSON-Format abrufen
• Strikte Tool-Nutzung (strict: true): Schemavalidierung für Tool-Namen und Eingaben garantieren

Sie können diese Funktionen unabhängig voneinander oder zusammen in derselben Anfrage verwenden.

Warum strukturierte Ausgaben verwenden

Ohne strukturierte Ausgaben kann Claude fehlerhafte JSON-Antworten oder ungültige Tool-Eingaben generieren, die Ihre Anwendungen unterbrechen. Selbst mit sorgfältiger Eingabeaufforderung können Sie auf folgende Probleme stoßen:

• Parsing-Fehler durch ungültige JSON-Syntax
• Fehlende erforderliche Felder
• Inkonsistente Datentypen
• Schemaverletzungen, die Fehlerbehandlung und Wiederholungen erfordern

Strukturierte Ausgaben garantieren schemakompatible Antworten durch eingeschränkte Dekodierung:

• Immer gültig: Keine JSON.parse()-Fehler mehr
• Typsicher: Garantierte Feldtypen und erforderliche Felder
• Zuverlässig: Keine Wiederholungen erforderlich für Schemaverletzungen

JSON-Ausgaben

JSON-Ausgaben steuern Claudes Antwortformat und stellen sicher, dass Claude gültiges JSON zurückgibt, das Ihrem Schema entspricht. Verwenden Sie JSON-Ausgaben, wenn Sie:

• Claudes Antwortformat steuern möchten
• Daten aus Bildern oder Text extrahieren möchten
• Strukturierte Berichte generieren möchten
• API-Antworten formatieren möchten

Schnellstart

Antwortformat: Gültiges JSON, das Ihrem Schema in response.content[0].text entspricht

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

Funktionsweise

Arbeiten mit JSON-Ausgaben in SDKs

Die SDKs bieten Hilfsfunktionen, die die Arbeit mit JSON-Ausgaben erleichtern, einschließlich Schemaumwandlung, automatischer Validierung und Integration mit beliebten Schemabibliotheken.

Verwendung von nativen Schemadefinitionen

Anstatt rohe JSON-Schemas zu schreiben, können Sie vertraute Schemadefinitionswerkzeuge in Ihrer Sprache verwenden:

• Python: Pydantic-Modelle mit client.messages.parse()
• TypeScript: Zod-Schemas mit zodOutputFormat() oder typisierte JSON-Schema-Literale mit jsonSchemaOutputFormat()
• Java: Einfache Java-Klassen mit automatischer Schemaableitung über outputConfig(Class<T>)
• Ruby: Anthropic::BaseModel-Klassen mit output_config: {format: Model}
• PHP: Klassen, die StructuredOutputModel implementieren, mit outputConfig: ['format' => MyClass::class]
• CLI, C#, : Rohe JSON-Schemas, die über übergeben werden

SDK-spezifische Methoden

Jedes SDK bietet Hilfsfunktionen, die die Arbeit mit strukturierten Ausgaben erleichtern. Weitere Details finden Sie auf den einzelnen SDK-Seiten.

Wie SDK-Transformation funktioniert

Die Python-, TypeScript-, Ruby- und PHP-SDKs transformieren Schemas automatisch mit nicht unterstützten Funktionen:

1. Entfernen nicht unterstützter Einschränkungen (z. B. minimum, maximum, minLength, maxLength)
2. Aktualisieren von Beschreibungen mit Einschränkungsinformationen (z. B. "Muss mindestens 100 sein"), wenn die Einschränkung nicht direkt mit strukturierten Ausgaben unterstützt wird
3. Hinzufügen von additionalProperties: false zu allen Objekten
4. Filtern von String-Formaten auf unterstützte Liste nur
5. Validieren von Antworten gegen Ihr ursprüngliches Schema (mit allen Einschränkungen)

Dies bedeutet, dass Claude ein vereinfachtes Schema erhält, aber Ihr Code erzwingt immer noch alle Einschränkungen durch Validierung.

Beispiel: Ein Pydantic-Feld mit minimum: 100 wird zu einem einfachen Integer im gesendeten Schema, aber das SDK aktualisiert die Beschreibung zu "Muss mindestens 100 sein" und validiert die Antwort gegen die ursprüngliche Einschränkung.

Häufige Anwendungsfälle

Strikte Werkzeugnutzung

Für die Erzwingung der JSON-Schema-Konformität bei Werkzeugeingaben mit grammatikbeschränkter Stichprobenentnahme siehe Strikte Werkzeugnutzung.

Beide Funktionen zusammen verwenden

JSON-Ausgaben und striktes Tool-Verwenden lösen unterschiedliche Probleme und funktionieren zusammen:

• JSON-Ausgaben steuern das Antwortformat von Claude (was Claude sagt)
• Striktes Tool-Verwenden validiert Tool-Parameter (wie Claude Ihre Funktionen aufruft)

In Kombination kann Claude Tools mit garantiert gültigen Parametern aufrufen UND strukturierte JSON-Antworten zurückgeben. Dies ist nützlich für agentenbasierte Workflows, bei denen Sie sowohl zuverlässige Tool-Aufrufe als auch strukturierte endgültige Ausgaben benötigen.

Wichtige Überlegungen

Grammatik-Kompilierung und Caching

Strukturierte Ausgaben verwenden eingeschränktes Sampling mit kompilierten Grammatik-Artefakten. Dies führt zu einigen Leistungsmerkmalen, die Sie beachten sollten:

• Latenz bei der ersten Anfrage: Wenn Sie ein bestimmtes Schema zum ersten Mal verwenden, gibt es zusätzliche Latenz während die Grammatik kompiliert wird
• Automatisches Caching: Kompilierte Grammatiken werden 24 Stunden lang ab der letzten Verwendung zwischengespeichert, was nachfolgende Anfragen viel schneller macht
• Cache-Invalidierung: Der Cache wird invalidiert, wenn Sie ändern:
  • Die JSON-Schema-Struktur
  • Die Menge der Tools in Ihrer Anfrage (bei Verwendung von strukturierten Ausgaben und Tool-Verwenden zusammen)
  • Das Ändern nur von name- oder description-Feldern invalidiert den Cache nicht

Prompt-Änderung und Token-Kosten

Bei Verwendung von strukturierten Ausgaben erhält Claude automatisch einen zusätzlichen System-Prompt, der das erwartete Ausgabeformat erklärt. Dies bedeutet:

• Ihre Eingabe-Token-Anzahl ist leicht höher
• Der eingefügte Prompt kostet Sie Token wie jeder andere System-Prompt
• Das Ändern des Parameters output_config.format invalidiert jeden Prompt-Cache für diesen Gesprächs-Thread

JSON-Schema-Einschränkungen

Strukturierte Ausgaben unterstützen Standard-JSON-Schema mit einigen Einschränkungen. Sowohl JSON-Ausgaben als auch striktes Tool-Verwenden teilen diese Einschränkungen.

Eigenschaftsreihenfolge

Bei Verwendung von strukturierten Ausgaben behalten Eigenschaften in Objekten ihre definierte Reihenfolge aus Ihrem Schema bei, mit einer wichtigen Ausnahme: erforderliche Eigenschaften erscheinen zuerst, gefolgt von optionalen Eigenschaften.

Zum Beispiel, gegeben dieses Schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Die Ausgabe wird Eigenschaften wie folgt ordnen:

1. name (erforderlich, in Schema-Reihenfolge)
2. email (erforderlich, in Schema-Reihenfolge)
3. notes (optional, in Schema-Reihenfolge)
4. age (optional, in Schema-Reihenfolge)

Dies bedeutet, dass die Ausgabe wie folgt aussehen könnte:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Wenn die Eigenschaftsreihenfolge in der Ausgabe für Ihre Anwendung wichtig ist, markieren Sie alle Eigenschaften als erforderlich, oder berücksichtigen Sie diese Neuordnung in Ihrer Parsing-Logik.

Ungültige Ausgaben

Während strukturierte Ausgaben in den meisten Fällen Schema-Konformität garantieren, gibt es Szenarien, in denen die Ausgabe möglicherweise nicht Ihrem Schema entspricht:

Ablehnungen (stop_reason: "refusal")

Claude behält seine Sicherheits- und Hilfreichkeitseigenschaften auch bei Verwendung von strukturierten Ausgaben bei. Wenn Claude eine Anfrage aus Sicherheitsgründen ablehnt:

• Die Antwort hat stop_reason: "refusal"
• Sie erhalten einen 200-Statuscode
• Ihnen werden die generierten Token in Rechnung gestellt
• Die Ausgabe entspricht möglicherweise nicht Ihrem Schema, da die Ablehnungsmeldung Vorrang vor Schema-Einschränkungen hat

Token-Limit erreicht (stop_reason: "max_tokens")

Wenn die Antwort aufgrund des Erreichens des max_tokens-Limits abgeschnitten wird:

• Die Antwort hat stop_reason: "max_tokens"
• Die Ausgabe kann unvollständig sein und nicht Ihrem Schema entsprechen
• Versuchen Sie es mit einem höheren max_tokens-Wert erneut, um die vollständige strukturierte Ausgabe zu erhalten

Schema-Komplexitätsgrenzen

Strukturierte Ausgaben funktionieren, indem Ihre JSON-Schemas in eine Grammatik kompiliert werden, die Claudes Ausgabe einschränkt. Komplexere Schemas erzeugen größere Grammatiken, deren Kompilierung länger dauert. Um vor übermäßigen Kompilierungszeiten zu schützen, erzwingt die API mehrere Komplexitätsgrenzen.

Explizite Grenzen

Die folgenden Grenzen gelten für alle Anfragen mit output_config.format oder strict: true:

Zusätzliche interne Grenzen

Über die oben genannten expliziten Grenzen hinaus gibt es zusätzliche interne Grenzen für die Größe der kompilierten Grammatik. Diese Grenzen existieren, weil Schema-Komplexität sich nicht auf eine einzelne Dimension reduziert: Funktionen wie optionale Parameter, Union-Typen, verschachtelte Objekte und die Anzahl der Tools interagieren auf Weise miteinander, die die kompilierte Grammatik überproportional groß machen können.

Wenn diese Grenzen überschritten werden, erhalten Sie einen 400-Fehler mit der Meldung "Schema is too complex for compilation." Diese Fehler bedeuten, dass die kombinierte Komplexität Ihrer Schemas übersteigt, was effizient kompiliert werden kann, selbst wenn jede einzelne oben genannte Grenze erfüllt ist. Als letzter Ausweg erzwingt die API auch ein Kompilierungs-Timeout von 180 Sekunden. Schemas, die alle expliziten Überprüfungen bestehen, aber sehr große kompilierte Grammatiken erzeugen, können dieses Timeout treffen.

Tipps zur Reduzierung der Schema-Komplexität

Wenn Sie Komplexitätsgrenzen erreichen, versuchen Sie diese Strategien in dieser Reihenfolge:

1. Markieren Sie nur kritische Tools als strikt. Wenn Sie viele Tools haben, reservieren Sie es für Tools, bei denen Schema-Verstöße echte Probleme verursachen, und verlassen Sie sich auf Claudes natürliche Einhaltung für einfachere Tools.

2. Reduzieren Sie optionale Parameter. Machen Sie Parameter required, wo möglich. Jeder optionale Parameter verdoppelt ungefähr einen Teil des Zustandsraums der Grammatik. Wenn ein Parameter immer einen angemessenen Standard hat, erwägen Sie, ihn erforderlich zu machen und Claude diesen Standard explizit bereitstellen zu lassen.

3. Vereinfachen Sie verschachtelte Strukturen. Tief verschachtelte Objekte mit optionalen Feldern verstärken die Komplexität. Vereinfachen Sie Strukturen, wo möglich.

4. Teilen Sie in mehrere Anfragen auf. Wenn Sie viele strikte Tools haben, erwägen Sie, diese auf separate Anfragen oder Sub-Agenten aufzuteilen.

Bei anhaltenden Problemen mit gültigen Schemas kontaktieren Sie den Support mit Ihrer Schema-Definition.

Datenspeicherung

Prompts und Antworten werden mit ZDR verarbeitet, wenn strukturierte Ausgaben verwendet werden. Das JSON-Schema selbst wird jedoch für bis zu 24 Stunden seit der letzten Verwendung zu Optimierungszwecken vorübergehend zwischengespeichert. Keine Prompt- oder Antwortdaten werden über die API-Antwort hinaus beibehalten.

Strukturierte Ausgaben sind HIPAA-berechtigt, aber PHI darf nicht in JSON-Schema-Definitionen enthalten sein. Die API kompiliert JSON-Schemas in Grammatiken, die separat vom Nachrichteninhalt zwischengespeichert werden, und diese zwischengespeicherten Schemas erhalten nicht den gleichen PHI-Schutz wie Prompts und Antworten. Fügen Sie PHI nicht in Schema-Eigenschaftsnamen, enum-Werte, const-Werte oder pattern-Regex-Ausdrücke ein. PHI sollte nur in Nachrichteninhalten (Prompts und Antworten) erscheinen, wo es unter HIPAA-Schutzmaßnahmen geschützt ist.

Für ZDR- und HIPAA-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

Funktionskompatibilität

Funktioniert mit:

• Batch-Verarbeitung: Verarbeiten Sie strukturierte Ausgaben im großen Maßstab mit 50% Rabatt
• Token-Zählung: Zählen Sie Token ohne Kompilierung
• Streaming: Streamen Sie strukturierte Ausgaben wie normale Antworten
• Kombinierte Verwendung: Verwenden Sie JSON-Ausgaben (output_config.format) und striktes Tool-Verwenden (strict: true) zusammen in der gleichen Anfrage

Nicht kompatibel mit:

• Zitationen: Zitationen erfordern das Verschachteln von Zitationsblöcken mit Text, was mit strikten JSON-Schema-Einschränkungen in Konflikt steht. Gibt 400-Fehler zurück, wenn Zitationen mit output_config.format aktiviert sind.
• Message Prefilling: Nicht kompatibel mit JSON-Ausgaben