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:
- Senden Sie
json_schemamit einem Prompt, der zu einem zusätzlichen Feld einlädt („füge auch einen kurzen Kommentar hinzu“). - Liefert die Anfrage einen Fehler, akzeptiert der Anbieter
json_schemanicht. Versuchen Siejson_object. - Enthält die Antwort das zusätzliche Feld, wird das Schema nicht durchgesetzt. Behandeln Sie es wie JSON Mode.
- Liefert auch
json_objecteinen 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_reasonprüfen. Eine Antwort, die anmax_tokensgestoß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:
- Flach schlägt verschachtelt. Zwei Ebenen reichen für die meisten Extraktionen.
- Enums statt freier Strings für Kategorien.
- Keine offenen Objekte. Freiform-Felder vom Typ
dictverfehlen den Zweck. - Kurze Feldnamen mit Beschreibungen. Beschreibungen im Schema leiten das Modell.
- 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.
