BroadRouter

Paano ayusin ang invalid JSON mula sa LLM: sanhi, repair, retry

Ng BroadNet Inference team · 7 minutong basa · Nailathala · Na-update

Tingnan muna ang finish_reason: hindi ligtas na maaayos ang sagot na naputol sa max_tokens, kaya taasan ang limit at ipadala ulit. Kung hindi, alisin ang code fence at nakapalibot na prose, i-decode ang unang JSON value, at ayusin lang ang malinaw na mali gaya ng trailing comma. I-validate laban sa schema, at kung pumalya, ibalik nang isa o dalawang beses ang eksaktong error. Kung suportado, napipigilan ng structured output ang karamihan nito.

Tinatawag ng code mo ang json.loads() sa sagot ng model at nakakakuha ng JSONDecodeError: Expecting value: line 1 column 1. O kaya napa-parse ito, pero string ang isang field na dapat sana ay number. Inaayos ng post na ito ang mga sanhi ayon sa kung ano ang ligtas mong magagawa sa bawat isa, nagbibigay ng tested na Python function na nag-aayos lang ng malinaw na kaso, at nagpapakita ng retry loop na alam kung kailan walang maitutulong ang retry.

Nasa JSON mode vs json_schema ang pagpili sa pagitan ng JSON mode at json_schema. Tungkol ang post na ito sa kung ano ang gagawin sa sagot na talagang natanggap mo.

Bakit invalid JSON ang ibinabalik ng mga LLM?

Isa-isang token ang pagsulat ng model sa text. Maliban kung kinokontrol ng server ang decoding, walang pumipigil dito na magdagdag ng magiliw na pangungusap o maubusan ng puwang. Ang mga karaniwang palya:

Ang nakikita mo Sanhi Ligtas bang ayusin sa code?
```json … ``` sa paligid ng object Nakasanayang chat formatting Oo: alisin ang fence
“Here is the JSON:” bago, “Let me know…” pagkatapos Parehong nakasanayan Oo: basahin lang ang unang value
<think>...</think> bago ang object Reasoning text sa content field sa ilang server Oo: alisin ang block
Natatapos sa gitna ng string, bukas pa ang mga bracket Tumama sa max_tokens Hindi: ipadala ulit nang may mas malaking puwang
Walang laman na content Naubos ng reasoning ang buong budget Hindi: ipadala ulit nang may mas malaking puwang
{"a": 1,} Trailing comma; pinapayagan ito ng JavaScript, hindi ng RFC 8259 Oo: iisa ang kahulugan
{'a': True, 'b': None} Syntax ng Python Oo: ligtas itong nababasa ng ast.literal_eval
NaN, Infinity Hindi JSON; tinatanggap ng Python bilang default Hindi: tanggihan
Valid na JSON, maling type o kulang na field Hindi ipinapatupad ang schema Hindi: magtanong ulit kasama ang error

Ang hangganan ay ang pagkalabo. Kung iisa lang talaga ang posibleng ibig sabihin ng model, ayusin ito sa code at i-log na ginawa mo. Kung kailangan mong manghula, tanggihan ang sagot.

Bakit hindi dapat i-repair ang naputol na JSON?

Dahil mukhang tama ang naayos na bersyon pero hindi. Pinatakbo namin ang json_repair 0.64.9, isang sikat na library na may MIT license, sa sagot na naputol sa gitna ng salita:

'{"name": "Omar", "city": "Jed'  ->  {'name': 'Omar', 'city': 'Jed'}

Nagbalik ito ng valid na JSON na ang city ay “Jed”. Tapat dito ang README nito: “automatically completes missing values in JSON fields with reasonable defaults” (salin: awtomatikong pinupunan ang nawawalang value sa mga JSON field ng makatwirang default). Kapaki-pakinabang iyan sa pagbasa ng log. Pero para sa data na iniimbak mo o pinagbabatayan ng aksyon, ginagawa nitong tahimik na palya ang palyang dapat ay nakikita.

Tingnan ang finish_reason bago ka mag-parse. Ang "length" ay nangangahulugang tumama ang sagot sa max_tokens. Papalya rin sa parehong paraan ang pagpapadala ulit ng parehong request na may parehong limit, kaya doblehin ang limit o humingi ng mas kaunti kada call. Mas madalas ito sa mga reasoning model: sabi ng API reference ng BroadNet, nagre-reason muna bago sumagot ang DeepSeek V4.1 Flash, GLM 5.3 at Qwen3.8 27B, at kasama ang reasoning sa max_tokens. Kapag maliit ang limit, puwedeng bumalik na walang laman ang sagot. Mag-iwan ng 1,000 token o higit pa, o itakda ang reasoning_effort sa low; nasa post tungkol sa reasoning budget ang mga numero.

Isang repair function na ligtas na kaso lang ang inaayos

Standard library lang ang gamit nito. Ibinabalik nito ang na-parse na value at listahan ng mga repair na ginawa nito, para mabilang mo ang mga ito.

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

Paano gumagana ang bawat hakbang:

  1. Ang naputol at walang lamang sagot ay nagra-raise bago pa ang anumang parsing, kaya hindi sila nagiging data.
  2. Ang mga fence at reasoning block ay inaalis gamit ang dalawang regular expression.
  3. Ang raw_decode ang pangunahing tool. Sabi ng docs ng Python, nagde-decode ito ng document “from a string that may have extraneous data at the end” (salin: mula sa string na maaaring may sobrang data sa dulo), at ibinabalik kung saan ito huminto. Nagsisimula sa unang { o [, nilalaktawan nito ang prose bago ang object at hindi pinapansin ang prose pagkatapos. Kung pumalya ang pag-decode sa isang brace sa prose, susubukan nito ang susunod.
  4. Ang bracket scan ay dumadaan sa text habang sinusubaybayan ang mga string at escape. Kapag may bukas pang bracket, naputol ang sagot kahit hindi iyon sinabi ng finish_reason; nagra-raise iyon. Inaalis ang mga comma na direktang bago ang } o ] sa labas ng string.
  5. Binabasa ng ast.literal_eval ang output na istilong Python na may single quote, True at None. Mga literal lang ang ine-evaluate nito at hindi ito kailanman nagpapatakbo ng code. Kailangan pagkatapos na ma-serialise ang resulta bilang mahigpit na JSON.
  6. Ang NaN at Infinity ay nagra-raise, sa pamamagitan ng parse_constant. Tinatanggap ang mga ito ng json ng Python bilang default; sabi ng RFC 8259, “are not permitted” (salin: hindi pinapayagan) ang mga ito, at tinatanggihan ang mga ito ng JSON.parse ng JavaScript.

Pinatakbo namin ito sa 17 test string: malinis na JSON, JSON na may fence, Arabic na key at value sa loob ng fence, prose bago at pagkatapos, {name} na placeholder sa prose bago ang object, <think> block, trailing comma sa object at array, comma at bracket sa loob ng string, escaped quote, Windows path na nagtatapos sa backslash, Python literal, NaN, walang lamang sagot, sagot na naputol nang may at walang finish_reason: "length", at dalawang magkasunod na object. Lahat ay kumilos ayon sa sinasabi ng table sa itaas. May isang test na nakahuli ng totoong bug: sa isang naunang bersyon, binabaligtad ang escape flag bago i-check ang closing quote, kaya nawala ang comma ng "he said \"hi,]\"". I-test ang sarili mong repair code sa mga escaped quote.

Dalawang limit na dapat mong malaman. Kapag dalawang magkasunod na object, ang una ang ibinabalik nito; kung gusto mo ng maraming item, humingi ng iisang JSON array. At ang single-quoted na output ng Python na may double quote sa loob ng string ay puwedeng mabasa nang mali ng bracket scan at matanggihan. Ang pagtanggi ang ligtas na uri ng palya.

Paano dapat mag-retry kapag pumalya ang repair?

Format ang hinahawakan ng repair. Content naman ang sa validation: tamang field, tamang type, makatwirang value. Nagva-validate ang loop na ito gamit ang jsonschema package at pinipili ang retry ayon sa sanhi:

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")

Ang mga patakaran sa loop na iyan:

  • Naputol: ipadala ulit ang parehong mga message na doble ang limit. Kapag nagdagdag ng “please fix” na message, hahaba ang prompt at hindi iikli ang output.
  • Hindi JSON, o maling hugis: ibalik ang eksaktong error. Ang “amount: ‘1200’ is not of type ‘number’” ay nagbibigay sa model ng tiyak na aayusin. Madalas inuulit ng basta-bastang retry ang parehong mali.
  • Hanggang tatlong attempt lang. Ipinapadala ulit ng bawat retry ang buong usapan bilang input token. Pagkatapos ng tatlo, i-log ang input at ipasa ito sa ibang paraan.
  • I-log ang listahan ng repair. Kapag dumarami ang “removed code fence” pagkatapos magpalit ng prompt, ibig sabihin lumala ang prompt, kahit walang pumalya.

Pinatakbo namin ang loop na ito laban sa isang lokal na mock server na nagpe-play back ng mga scripted na sagot. Ang sagot na may fence, trailing comma at "amount": "1200" bilang string ay na-repair, pumalya sa validation, at naayos sa ikalawang call matapos ibalik ang error. Ang sagot na naputol na may finish_reason: "length" ay ipinadala ulit na tinaasan ang max_tokens mula 1,500 papuntang 3,000 at nagtagumpay. Ini-record ng mock ang request sa bawat pagkakataon, na nagkumpirma ng bilang ng message at limit na ipinadala ng loop. Puwedeng iba ang paraan ng pagpalya ng totoong model, kaya patakbuhin ito sa 100 sarili mong input bago pagkatiwalaan ang mga numero.

Hindi na ba ito kailangan kung may structured output?

Inaalis nito ang karamihan. Ang server na kinokontrol ang decoding ayon sa schema mo ay hindi makakapaglabas ng fence, trailing comma o kulang na field. Ginagawa ito ng vLLM, isang karaniwang server para sa open model, gamit ang xgrammar o guidance backend. Dalawang palya pa rin ang natitira: truncation sa max_tokens, at refusal. Sabi ng OpenAI, valid ang output ng JSON mode “except for in some edge cases” (salin: maliban sa ilang edge case) at “must detect and handle” (salin: kailangang tuklasin at hawakan) ng application mo ang output na hindi kumpletong object. Kaya panatilihin ang check sa finish_reason at ang validator, kahit may json_schema.

Ang napipigilan ng bawat paraan:

Paraan Fence at prose Syntax error Maling hugis Truncation
Prompt lang (“reply with JSON”) Nababawasan Nababawasan Nababawasan Hindi
JSON mode (json_object) Oo Oo Hindi Hindi
Structured output (json_schema, ipinapatupad) Oo Oo Oo Hindi

Sa JSON mode, sinasabi rin ng OpenAI na “must always instruct the model to produce JSON” (salin: kailangang laging utusan ang model na gumawa ng JSON) ka sa isang message; kung hindi, puwede itong maglabas ng whitespace hanggang tumama sa token limit. Iba-iba ang ibang OpenAI-compatible na server, kaya i-test ang mode sa model na ilalabas mo. Nasa post tungkol sa structured output ang test.

Para i-check nang mano-mano ang isang sagot, i-paste ito sa LLM JSON output validator, o gumawa ng mahigpit na schema mula sa isang sample object gamit ang JSON schema generator.

Saan bagay ang BroadNet Inference

Ang BroadRouter ay website ng BroadNet. Sa API reference ng BroadNet, nakalista ang structured output para sa GLM 5.3 at Qwen3.8 27B lang, at hindi nito pinangangalanan ang request parameter, kaya i-test ang json_schema sa model bago umasa rito. Sa DeepSeek V4.1 Flash at Gemma 4 VL 26B, gumamit ng JSON na nasa prompt lang kasama ang repair function at validator sa itaas. Nagre-reason muna bago sumagot ang tatlo sa apat na model, kaya mag-budget ng max_tokens para dito. Para sa maramihang extraction, ipinapakita ng post tungkol sa batch runner kung paano i-log ang finish_reason kada item. Hindi itinatago ang mga prompt at sagot pagkatapos ng bawat request.

Mga tanong

Bakit nasa loob ng markdown code block ang JSON na ibinabalik ng LLM ko?

Karaniwang pino-format ng mga chat model ang code para sa tao, at code fence ang paraan ng mga chat interface sa pagpapakita nito. Humingi ng "JSON lang, walang code fence", pero alisin pa rin ang mga fence sa code: binababa ng utos ang dalas, hindi nito inaalis.

Paano ko aayusin ang JSONDecodeError sa output ng LLM?

Tingnan muna ang finish_reason. Kung "length", naputol ang sagot: taasan ang max_tokens at ipadala ulit. Kung hindi, alisin ang code fence at i-decode ang unang JSON value gamit ang raw_decode, na hindi pinapansin ang text pagkatapos nito. Ayusin ang trailing comma, saka i-validate. Kung pumapalya pa rin, magtanong ulit kasama ang error.

Dapat ba akong gumamit ng JSON repair library?

Para sa log at debugging, oo. Para sa data na pagbabatayan mo ng aksyon, mag-ingat. Pinupunan ng default ng mga library gaya ng json_repair ang nawawalang value, kaya bumabalik ang naputol na city na "Jed" bilang valid na "Jed". Tanggihan ang naputol na output at ipadala ulit.

Bakit naputol ang JSON output ng LLM ko?

Tumama ang sagot sa max_tokens. Sa mga reasoning model gaya ng DeepSeek V4.1 Flash, GLM 5.3 at Qwen3.8 27B, kasama ang reasoning sa limit na iyon, kaya puwedeng masyadong kaunti ang matirang puwang pagkatapos ng mahabang pag-iisip. Taasan ang limit, itakda ang reasoning_effort sa low, o humingi ng mas kaunting output kada call.

Garantisado ba ng JSON mode ang valid na JSON?

Halos. Sabi ng OpenAI, valid na JSON ang output ng JSON mode "except for in some edge cases" (salin: maliban sa ilang edge case), gaya ng pag-abot sa token limit, at hindi nito ipinapatupad ang schema mo. Nagdadagdag ng schema adherence ang structured output na may json_schema kung ipinapatupad ito ng provider. I-validate pa rin alinman dito.

Aling mga model ng BroadNet ang sumusuporta sa structured output?

Nakalista sa API reference ng BroadNet ang structured output para sa GLM 5.3 at Qwen3.8 27B, sinuri noong Nobyembre 15, 2026. Hindi ito nakalista para sa DeepSeek V4.1 Flash o Gemma 4 VL 26B, kaya JSON na nasa prompt lang kasama ang repair at validation ang gamitin sa mga iyon.

Basahin bilang MarkdownTanungin ang ChatGPTTanungin ang ClaudeTanungin ang Perplexity