BroadRouter
Loslegen

JSON Mode vs. json_schema: strukturierte Ausgabe, die hält

Vom Team von BroadNet Inference · 4 Min. Lesezeit · Veröffentlicht

JSON Mode (response_format json_object) verspricht nur gültiges JSON. Strukturierte Ausgabe (response_format json_schema) verspricht zusätzlich Ihre Felder und Typen, sofern der Anbieter das durchsetzt. In beiden Fällen prüfen Sie finish_reason, parsen und validieren gegen ein Schema, etwa ein Pydantic-Modell. Schlägt die Validierung fehl, senden Sie den Fehler zurück und fragen erneut, mit einer festen Obergrenze für Versuche.

Ihr Code braucht Daten, und Modelle schreiben Text. Strukturierte Ausgabe schließt diese Lücke, aber „das Modell gibt JSON zurück“ bedeutet drei verschiedene Dinge, je nachdem, wie Sie fragen. Dieser Beitrag vergleicht die Optionen bei OpenAI-kompatiblen offenen Modellen, zeigt, wie Sie jede anfordern, und liefert eine Schleife zum Validieren und Reparieren, die Sie direkt in die Produktion übernehmen können.

Was ist der Unterschied zwischen JSON Mode und json_schema?

Methode Anfrage Was Ihnen versprochen wird
Nur Prompt „Antworte in JSON mit den Feldern …“ Nichts; meist JSON, manchmal mit zusätzlichem Text
JSON Mode response_format: {"type": "json_object"} Gültiges JSON, beliebige Struktur
Strukturierte Ausgabe response_format: {"type": "json_schema", ...} JSON passend zu Ihrem Schema, sofern durchgesetzt

Der Leitfaden zu Structured Outputs von OpenAI formuliert es direkt: „While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.“ (Übersetzung: „Beide stellen zwar sicher, dass gültiges JSON entsteht, aber nur Structured Outputs stellen die Einhaltung des Schemas sicher.“) Er empfiehlt, wann immer möglich, strukturierte Ausgabe statt JSON Mode.

Bei Anbietern offener Modelle hängt die Garantie davon ab, wie der Server sie umsetzt. Viele nutzen Constrained Decoding, das Tokens blockiert, die das Schema verletzen würden. Manche akzeptieren das Feld, setzen es aber nicht durch. Deshalb validiert der Code unten in jedem Fall.

Wie fordern Sie json_schema an?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic erzeugt das JSON Schema aus Ihrer Klasse, sodass Schema und Validator nie auseinanderlaufen. Wenn Sie kein Pydantic nutzen, baut der JSON-Schema-Generator aus einem Beispielobjekt ein Schema für den Strict Mode. Für den Strict Mode verlangt OpenAI additionalProperties: false und dass jede Eigenschaft als erforderlich gelistet ist.

Welchen Modus unterstützt Ihr Anbieter?

Führen Sie diesen Test einmal pro Modell durch, bevor Sie darauf aufbauen:

  1. Senden Sie json_schema mit einem Prompt, der zu einem zusätzlichen Feld einlädt („füge auch einen kurzen Kommentar hinzu“).
  2. Liefert die Anfrage einen Fehler, akzeptiert der Anbieter json_schema nicht. Versuchen Sie json_object.
  3. Enthält die Antwort das zusätzliche Feld, wird das Schema nicht durchgesetzt. Behandeln Sie es wie JSON Mode.
  4. Liefert auch json_object einen Fehler, nutzen Sie reine Prompt-Anweisungen mit Validierung.

Bei BroadNet Inference führt die Dokumentation strukturierte Ausgabe für GLM 5.3 und Qwen3.8 27B auf (direkt verglichen), nennt aber den Anfrageparameter nicht. Führen Sie den Test oben mit dem Modell durch, das Sie ausliefern.

Wie validieren und reparieren Sie fehlerhafte Ausgaben?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

Was diese Schleife funktionieren lässt:

  • Zuerst finish_reason prüfen. Eine Antwort, die an max_tokens gestoßen ist, ist abgeschnittenes JSON. Ein Retry mit demselben Limit scheitert auf dieselbe Weise. Beide Modelle oben führen vor der Antwort ein Reasoning durch, und Reasoning zählt zum Limit; lassen Sie also Spielraum.
  • Ablehnungen getrennt behandeln. Der Leitfaden von OpenAI weist darauf hin, dass eine Ablehnung „does not necessarily follow the schema you have supplied“ (Übersetzung: „nicht unbedingt dem von Ihnen angegebenen Schema folgt“).
  • Den exakten Fehler zurücksenden. Ein blinder Retry liefert oft denselben Fehler. „line_items: field required“ gibt dem Modell etwas, das es beheben kann.
  • Geschäftsregeln im Code prüfen. Ein Schema kann nicht ausdrücken, dass eine Summe ihren Positionen entsprechen muss. Die Prüfung oben kann es.
  • Versuche begrenzen. Jeder Versuch sendet den gesamten Prompt erneut als Input-Tokens.

Welche Schema-Features machen Probleme?

Halten Sie Schemas langweilig:

  1. Flach schlägt verschachtelt. Zwei Ebenen reichen für die meisten Extraktionen.
  2. Enums statt freier Strings für Kategorien.
  3. Keine offenen Objekte. Freiform-Felder vom Typ dict verfehlen den Zweck.
  4. Kurze Feldnamen mit Beschreibungen. Beschreibungen im Schema leiten das Modell.
  5. Optionale Felder als nullable. Im Strict Mode listen Sie jedes Feld als erforderlich und erlauben null.

Der Leitfaden von OpenAI weist darauf hin, dass manche Features von JSON Schema im Strict Mode nicht unterstützt werden. Server für offene Modelle haben ihre eigenen Grenzen. Wird ein Schema abgelehnt, vereinfachen Sie es, bevor Sie den Modus wechseln.

Wie überwachen Sie strukturierte Ausgabe in der Produktion?

Eine Schleife, die stillschweigend repariert, kann ein Problem verbergen, das Sie jeden Tag Tokens kostet. Loggen Sie pro Aufrufstelle drei Zahlen:

Metrik Was sie Ihnen sagt
Erfolgsquote beim ersten Versuch Wie gut Modell und Schema zusammenpassen; ein Rückgang folgt oft auf eine Änderung von Prompt oder Modell
Durchschnittliche Versuche pro Erfolg Die Token-Kosten der Reparaturen
Endgültige Fehlschläge Eingaben, die Ihre Pipeline nicht verarbeiten kann; prüfen Sie sie von Hand

Fällt die Erfolgsquote beim ersten Versuch unter das gewohnte Niveau, vereinfachen Sie das Schema oder probieren Sie ein anderes Modell, bevor Sie weitere Retries hinzufügen. Bewahren Sie eine Stichprobe fehlgeschlagener Rohantworten auf, damit Sie Korrekturen an echten Fällen testen können.

Wann sollten Sie stattdessen ein Tool nutzen?

Nutzen Sie strukturierte Ausgabe für die endgültige Antwort: eine Extraktion, eine Klassifizierung, einen Plan. Nutzen Sie Tool Calling, wenn das Modell Ihren Code etwas tun lassen und danach weitermachen muss. Viele Agenten nutzen beides: Tools während der Schleife, ein Schema für den letzten Schritt. Ein Beispiel von Bild zu JSON finden Sie unter arabische Rechnungen mit einem Vision-Modell auslesen.

Wo BroadNet Inference hineinpasst

BroadNet Inference listet strukturierte Ausgabe für GLM 5.3 und Qwen3.8 27B, hinter dem Standardformat für Chat Completions; der Code oben läuft also unverändert mit dem OpenAI Python SDK. Qwen3.8 27B nimmt außerdem Bilder an, was zur Extraktion aus Dokumenten passt. Für DeepSeek V4.1 Flash und Gemma 4 VL 26B nennt die Dokumentation von BroadNet keine strukturierte Ausgabe; nutzen Sie dort den Weg über reine Prompt-Anweisungen mit Validierung. Die Preise pro Token vergleichen Sie auf der Preisseite.

Häufige Fragen

Was ist der Unterschied zwischen JSON Mode und strukturierter Ausgabe?

JSON Mode, response_format vom Typ json_object, verspricht nur, dass sich die Antwort als JSON parsen lässt. Strukturierte Ausgabe, Typ json_schema, verspricht zusätzlich die von Ihnen definierten Felder und Typen, sofern der Anbieter das durchsetzt. OpenAI empfiehlt, wo möglich, strukturierte Ausgabe statt JSON Mode.

Unterstützen offene Modelle response_format mit json_schema?

Das hängt vom Anbieter ab. Manche akzeptieren json_schema, manche nur json_object, und manche ignorieren das Feld. Senden Sie eine Testanfrage mit einem Schema und einem Prompt, der das Modell dazu verleitet, ein zusätzliches Feld hinzuzufügen, und prüfen Sie die Antwort.

Muss ich strukturierte Ausgabe trotzdem validieren?

Ja. Antworten können von max_tokens abgeschnitten werden, Ablehnungen sein und Geschäftsregeln verletzen, die ein Schema nicht ausdrücken kann, etwa Summen, die aufgehen müssen.

Wie oft sollte ich bei ungültigem JSON neu anfragen?

Zwei oder drei Versuche mit dem Validierungsfehler im Prompt reichen meist. Danach loggen Sie die Eingabe und leiten sie an einen Fallback weiter, an ein stärkeres Modell oder an einen Menschen. Unbegrenzte Schleifen verschwenden Tokens.

Sollte ich strukturierte Ausgabe oder Tool Calling nutzen?

Nutzen Sie strukturierte Ausgabe, wenn Sie die endgültige Antwort in einer festen Form wollen. Nutzen Sie Tool Calling, wenn das Modell Ihren Code etwas ausführen lassen und danach weitermachen muss.

Als Markdown lesenChatGPT fragenClaude fragenPerplexity fragen