Ihr Code ruft json.loads() auf einer Modellantwort auf und bekommt JSONDecodeError: Expecting value: line 1 column 1. Oder das Parsen klappt, aber ein Feld ist ein String, wo Sie eine Zahl erwartet haben. Dieser Beitrag sortiert die Ursachen danach, was Sie jeweils gefahrlos tun können, liefert eine getestete Python-Funktion, die nur die eindeutigen Fälle repariert, und zeigt eine Retry-Schleife, die weiß, wann ein neuer Versuch nichts bringt.
Die Wahl zwischen JSON Mode und json_schema behandelt JSON Mode vs. json_schema. Hier geht es darum, was Sie mit der Antwort anfangen, die Sie tatsächlich bekommen haben.
Warum liefern LLMs ungültiges JSON?
Ein Modell schreibt Text Token für Token. Solange der Server das Dekodieren nicht einschränkt, hindert es nichts daran, einen freundlichen Satz anzuhängen oder keinen Platz mehr zu haben. Die häufigsten Fehler:
| Was Sie sehen | Ursache | Im Code sicher reparierbar? |
|---|---|---|
```json … ``` um das Objekt |
Gewohnheit aus der Chat-Formatierung | Ja: Fence entfernen |
| „Here is the JSON:“ davor, „Let me know…“ danach | Dieselbe Gewohnheit | Ja: nur den ersten Wert lesen |
<think>...</think> vor dem Objekt |
Reasoning-Text im content-Feld bei manchen Servern | Ja: Block entfernen |
| Endet mitten im String, Klammern offen | max_tokens erreicht |
Nein: mit mehr Platz neu senden |
| Leerer Inhalt | Reasoning hat das ganze Budget verbraucht | Nein: mit mehr Platz neu senden |
{"a": 1,} |
Nachgestelltes Komma; JavaScript erlaubt es, RFC 8259 nicht | Ja: eine Bedeutung |
{'a': True, 'b': None} |
Python-Syntax | Ja: ast.literal_eval liest es sicher |
NaN, Infinity |
Kein JSON; Python akzeptiert es standardmäßig | Nein: ablehnen |
| Gültiges JSON, falsche Typen oder fehlende Felder | Schema nicht durchgesetzt | Nein: mit der Fehlermeldung neu anfragen |
Die Trennlinie ist Mehrdeutigkeit. Gibt es genau eine Sache, die das Modell gemeint haben kann, beheben Sie sie im Code und loggen, dass Sie es getan haben. Müssten Sie raten, lehnen Sie die Antwort ab.
Warum kein abgeschnittenes JSON reparieren?
Weil die reparierte Version richtig aussieht und es nicht ist. Wir haben json_repair 0.64.9, eine verbreitete Bibliothek unter MIT-Lizenz, auf eine Antwort angewendet, die mitten im Wort abbrach:
'{"name": "Omar", "city": "Jed' -> {'name': 'Omar', 'city': 'Jed'}
Zurück kam gültiges JSON mit der Stadt „Jed“. Das README sagt das offen: Die Bibliothek „automatically completes missing values in JSON fields with reasonable defaults“ (Übersetzung: „ergänzt fehlende Werte in JSON-Feldern automatisch mit sinnvollen Standardwerten“). Zum Lesen von Logs ist das nützlich. Bei Daten, die Sie speichern oder auf deren Grundlage Sie handeln, wird aus einem sichtbaren Fehler ein stiller.
Prüfen Sie finish_reason, bevor Sie parsen. "length" bedeutet, dass die Antwort max_tokens erreicht hat. Dieselbe Anfrage mit demselben Limit scheitert genauso, also verdoppeln Sie das Limit oder fordern pro Aufruf weniger an. Reasoning-Modelle machen das häufiger: Laut der API-Referenz von BroadNet denken DeepSeek V4.1 Flash, GLM 5.3 und Qwen3.8 27B nach, bevor sie antworten, und das Reasoning zählt zu max_tokens. Bei einem kleinen Limit kann die Antwort leer zurückkommen. Lassen Sie 1.000 Tokens oder mehr frei oder setzen Sie reasoning_effort auf low; die Zahlen stehen im Beitrag zum Reasoning-Budget.
Eine Reparaturfunktion, die nur die sicheren Fälle behebt
Sie nutzt nur die Standardbibliothek. Sie gibt den geparsten Wert und eine Liste der vorgenommenen Reparaturen zurück, sodass Sie diese zählen können.
import ast, json, re
class Truncated(Exception): pass
class NotJSON(Exception): pass
FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)
def _reject_constant(name): # NaN, Infinity: Python accepts them, JSON does not
raise NotJSON(f"non-standard constant {name}")
_decoder = json.JSONDecoder(parse_constant=_reject_constant)
def _first_value(s):
"""Decode the first JSON object or array in s, ignoring prose before and after it."""
for i, ch in enumerate(s):
if ch in "{[":
try:
return _decoder.raw_decode(s, i)[0]
except json.JSONDecodeError:
continue # a stray brace in prose; try the next one
raise NotJSON("no JSON object or array found")
def _scan(s):
"""Drop commas before } or ] outside strings; report brackets left open."""
out, stack, in_str, esc = [], [], False, False
for i, ch in enumerate(s):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch in "{[":
stack.append(ch)
elif ch in "}]" and stack:
stack.pop()
elif ch == ",":
rest = s[i + 1:].lstrip()
if rest[:1] in ("}", "]"):
continue # trailing comma: skip it
out.append(ch)
return "".join(out), len(stack) + (1 if in_str else 0)
def _python_literal(s):
"""Output in Python syntax: single quotes, True/False/None, trailing commas."""
start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
end = max(s.rfind("}"), s.rfind("]"))
if start < 0 or end <= start:
raise NotJSON("no braces")
value = ast.literal_eval(s[start:end + 1]) # literals only; never runs code
if not isinstance(value, (dict, list)):
raise NotJSON("not an object or array")
json.dumps(value, allow_nan=False) # must round-trip as strict JSON
return value
def parse_llm_json(content, finish_reason=None):
"""Return (value, repairs). Raises Truncated or NotJSON."""
if finish_reason == "length":
raise Truncated("hit max_tokens; raise the limit or shorten the output")
if not content or not content.strip():
raise NotJSON("empty content (reasoning may have used the whole budget)")
repairs = []
s = content.strip().lstrip("\ufeff")
if THINK.search(s):
s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
m = FENCE.search(s)
if m:
s = m.group(1).strip(); repairs.append("removed code fence")
try:
value = _decoder.decode(s)
return value, repairs
except json.JSONDecodeError:
pass
try:
value = _first_value(s); repairs.append("ignored text around JSON")
return value, repairs
except NotJSON:
pass
fixed, open_count = _scan(s)
if open_count:
raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
if fixed != s:
try:
value = _first_value(fixed); repairs.append("removed trailing commas")
return value, repairs
except NotJSON:
pass
try:
value = _python_literal(s); repairs.append("parsed Python-style literal")
return value, repairs
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
raise NotJSON(f"unrepairable: {e}") from None
So arbeitet jeder Schritt:
- Abgeschnittene und leere Antworten lösen vor jedem Parsen eine Ausnahme aus, sie werden also nie zu Daten.
- Fences und Reasoning-Blöcke werden mit zwei regulären Ausdrücken entfernt.
raw_decodeist das zentrale Werkzeug. Laut Python-Doku dekodiert es ein Dokument „from a string that may have extraneous data at the end“ (Übersetzung: „aus einem String, der am Ende überzählige Daten enthalten kann“) und gibt zurück, wo es aufgehört hat. Ab dem ersten{oder[überspringt es Text vor dem Objekt und ignoriert Text danach. Lässt sich eine Klammer im Fließtext nicht dekodieren, versucht es die nächste.- Der Klammer-Scan geht den Text durch und verfolgt dabei Strings und Escapes. Offene Klammern bedeuten, dass die Antwort abgeschnitten wurde, auch wenn
finish_reasondas nicht gemeldet hat; das löst eine Ausnahme aus. Kommas direkt vor}oder]außerhalb von Strings werden entfernt. ast.literal_evalliest Ausgaben in Python-Syntax mit einfachen Anführungszeichen,TrueundNone. Es wertet nur Literale aus und führt nie Code aus. Das Ergebnis muss sich danach als striktes JSON serialisieren lassen.NaNundInfinitylösen überparse_constanteine Ausnahme aus. Dasjson-Modul von Python akzeptiert sie standardmäßig; RFC 8259 sagt, sie „are not permitted“ (Übersetzung: „sind nicht erlaubt“), undJSON.parsein JavaScript lehnt sie ab.
Wir haben die Funktion mit 17 Test-Strings geprüft: sauberes JSON, JSON in einer Fence, arabische Schlüssel und Werte in einer Fence, Text davor und danach, ein Platzhalter {name} im Text vor dem Objekt, ein <think>-Block, nachgestellte Kommas in Objekten und Arrays, Kommas und Klammern innerhalb von Strings, escapte Anführungszeichen, ein Windows-Pfad mit Backslash am Ende, Python-Literale, NaN, eine leere Antwort, eine abgeschnittene Antwort mit und ohne finish_reason: "length" sowie zwei Objekte hintereinander. Alle verhielten sich wie in der Tabelle oben beschrieben. Ein Test fand einen echten Bug: Eine frühe Version kippte ihr Escape-Flag, bevor sie auf das schließende Anführungszeichen prüfte, sodass "he said \"hi,]\"" sein Komma verlor. Testen Sie Ihren eigenen Reparaturcode mit escapten Anführungszeichen.
Zwei Grenzen sollten Sie kennen. Bei zwei Objekten hintereinander gibt die Funktion das erste zurück; wenn Sie mehrere Einträge wollen, fordern Sie ein JSON-Array an. Und Python-Ausgaben in einfachen Anführungszeichen, die innerhalb eines Strings ein doppeltes Anführungszeichen enthalten, kann der Klammer-Scan falsch lesen und ablehnen. Ablehnen ist der sichere Fehlerfall.
Wie sollten Sie neu anfragen, wenn die Reparatur scheitert?
Die Reparatur kümmert sich ums Format. Die Validierung kümmert sich um den Inhalt: richtige Felder, richtige Typen, plausible Werte. Diese Schleife validiert mit dem Paket jsonschema und wählt den neuen Versuch nach Ursache:
import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON
client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
"required": ["name", "city", "amount"],
"properties": {"name": {"type": "string", "minLength": 1},
"city": {"type": ["string", "null"]},
"amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)
def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
"Schema: " + json.dumps(SCHEMA)},
{"role": "user", "content": text}]
for attempt in range(1, attempts + 1):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
reasoning_effort="low", temperature=0)
c = r.choices[0]
try:
value, repairs = parse_llm_json(c.message.content, c.finish_reason)
errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
if not errors:
log({"attempt": attempt, "repairs": repairs, "ok": True})
return value
problem = "The JSON does not match the schema: " + "; ".join(errors)
except Truncated:
log({"attempt": attempt, "ok": False, "why": "truncated"})
max_tokens *= 2 # same prompt, more room; a re-ask would be cut off too
continue
except NotJSON as e:
problem = f"That reply was not valid JSON ({e})."
log({"attempt": attempt, "ok": False, "why": problem})
messages += [{"role": "assistant", "content": c.message.content or ""},
{"role": "user", "content": problem + " Return the corrected JSON object only."}]
raise RuntimeError(f"no valid JSON after {attempts} attempts")
Die Regeln in dieser Schleife:
- Abgeschnitten: dieselben Nachrichten mit doppeltem Limit neu senden. Eine zusätzliche „bitte korrigieren“-Nachricht würde den Prompt länger machen, die Ausgabe aber nicht kürzer.
- Kein JSON oder falsche Form: die exakte Fehlermeldung zurücksenden. „amount: ‘1200’ is not of type ‘number’“ gibt dem Modell etwas Konkretes zu beheben. Ein bloßer Retry wiederholt den Fehler oft.
- Höchstens drei Versuche. Jeder Retry sendet die ganze Konversation erneut als Input-Tokens. Nach drei Versuchen loggen Sie die Eingabe und leiten sie anderswohin.
- Die Reparaturliste loggen. Steigt nach einer Prompt-Änderung die Zahl von „removed code fence“, ist der Prompt schlechter geworden, auch wenn nichts gescheitert ist.
Wir haben diese Schleife gegen einen lokalen Mock-Server laufen lassen, der vorbereitete Antworten abspielte. Eine Antwort in einer Fence mit nachgestelltem Komma und "amount": "1200" als String wurde repariert, fiel bei der Validierung durch und wurde beim zweiten Aufruf korrigiert, nachdem der Fehler zurückgesendet wurde. Eine mit finish_reason: "length" abgeschnittene Antwort wurde mit von 1.500 auf 3.000 erhöhtem max_tokens neu gesendet und war erfolgreich. Der Mock zeichnete jede Anfrage auf und bestätigte so die Zahl der Nachrichten und das Limit, die die Schleife sendete. Ein echtes Modell kann anders scheitern, also lassen Sie die Schleife über 100 Ihrer eigenen Eingaben laufen, bevor Sie den Zahlen trauen.
Macht strukturierte Ausgabe das überflüssig?
Sie beseitigt das meiste. Ein Server, der das Dekodieren auf Ihr Schema einschränkt, kann keine Fence, kein nachgestelltes Komma und kein fehlendes Feld ausgeben. vLLM, ein verbreiteter Server für offene Modelle, macht das mit den Backends xgrammar oder guidance. Zwei Fehler bleiben selbst dann: Abschneiden bei max_tokens und Ablehnungen. OpenAI weist darauf hin, dass die Ausgabe im JSON Mode gültig ist „except for in some edge cases“ (Übersetzung: „außer in einigen Grenzfällen“) und dass Ihre Anwendung Ausgaben, die kein vollständiges Objekt sind, „must detect and handle“ (Übersetzung: „erkennen und behandeln muss“). Behalten Sie also die Prüfung von finish_reason und den Validator bei, auch mit json_schema.
Was jeder Ansatz verhindert:
| Ansatz | Fences und Fließtext | Syntaxfehler | Falsche Form | Abschneiden |
|---|---|---|---|---|
| Nur Prompt („antworte mit JSON“) | Seltener | Seltener | Seltener | Nein |
JSON Mode (json_object) |
Ja | Ja | Nein | Nein |
Strukturierte Ausgabe (json_schema, durchgesetzt) |
Ja | Ja | Ja | Nein |
Für den JSON Mode sagt OpenAI außerdem, dass Sie das Modell in einer Nachricht „must always instruct the model to produce JSON“ (Übersetzung: „immer anweisen müssen, JSON zu erzeugen“); andernfalls gibt es womöglich Leerzeichen aus, bis das Token-Limit erreicht ist. Andere OpenAI-kompatible Server verhalten sich unterschiedlich, testen Sie den Modus also mit dem Modell, das Sie ausliefern. Der Test steht im Beitrag zur strukturierten Ausgabe.
Um eine Antwort von Hand zu prüfen, fügen Sie sie in den LLM-JSON-Validator ein, oder bauen Sie mit dem JSON-Schema-Generator aus einem Beispielobjekt ein striktes Schema.
Wo BroadNet Inference ins Bild passt
BroadRouter ist die Website von BroadNet. Die API-Referenz von BroadNet listet strukturierte Ausgabe nur für GLM 5.3 und Qwen3.8 27B und nennt den Anfrageparameter nicht. Testen Sie json_schema also mit dem Modell, bevor Sie sich darauf verlassen. Bei DeepSeek V4.1 Flash und Gemma 4 VL 26B nutzen Sie JSON per Prompt mit der Reparaturfunktion und dem Validator von oben. Drei der vier Modelle denken vor dem Antworten nach, planen Sie max_tokens also dafür ein. Für Extraktion in großen Mengen zeigt der Beitrag zum Batch-Runner, wie Sie finish_reason pro Eintrag loggen. Prompts und Antworten werden nach jeder Anfrage nicht gespeichert.
