BroadRouter

Cara membaiki JSON tidak sah daripada LLM: punca, baiki, cuba semula

Oleh pasukan BroadNet Inference · 7 minit bacaan · Diterbitkan · Dikemas kini

Semak finish_reason dahulu: jawapan yang terpotong pada max_tokens tidak boleh dibaiki dengan selamat, jadi naikkan had dan hantar semula. Jika tidak, buang pagar kod dan prosa di sekelilingnya, nyahkod nilai JSON pertama, kemudian baiki hanya kesilapan yang jelas seperti koma di hujung. Sahkan terhadap skema, dan jika gagal, hantar semula ralat yang tepat sekali atau dua kali. Output berstruktur mencegah kebanyakan masalah ini jika disokong.

Kod anda memanggil json.loads() pada jawapan model dan mendapat JSONDecodeError: Expecting value: line 1 column 1. Atau ia berjaya dihurai, tetapi satu medan ialah rentetan sedangkan anda mahukan nombor. Artikel ini menyusun punca-puncanya mengikut apa yang boleh anda lakukan dengan selamat bagi setiap satu, memberi fungsi Python teruji yang hanya membaiki kes yang jelas, dan menunjukkan gelung cuba semula yang tahu bila cuba semula tidak akan membantu.

Pilihan antara mod JSON dan json_schema dibincangkan dalam mod JSON vs json_schema. Artikel ini tentang apa yang perlu dilakukan dengan jawapan yang sebenarnya anda terima.

Mengapakah LLM memulangkan JSON yang tidak sah?

Model menulis teks satu token pada satu masa. Melainkan pelayan mengekang penyahkodan, tiada apa yang menghalangnya daripada menambah ayat mesra atau kehabisan ruang. Kegagalan biasa:

Apa yang anda lihat Punca Selamat dibaiki dalam kod?
```json … ``` di sekeliling objek Tabiat pemformatan chat Ya: buang pagar
“Here is the JSON:” sebelum, “Let me know…” selepas Tabiat yang sama Ya: baca nilai pertama sahaja
<think>...</think> sebelum objek Teks penaakulan dalam medan content pada sesetengah pelayan Ya: buang blok itu
Berakhir di tengah rentetan, kurungan masih terbuka Mencapai max_tokens Tidak: hantar semula dengan lebih banyak ruang
Content kosong Penaakulan menggunakan seluruh bajet Tidak: hantar semula dengan lebih banyak ruang
{"a": 1,} Koma di hujung; JavaScript membenarkannya, RFC 8259 tidak Ya: satu makna
{'a': True, 'b': None} Sintaks Python Ya: ast.literal_eval membacanya dengan selamat
NaN, Infinity Bukan JSON; Python menerimanya secara lalai Tidak: tolak
JSON sah, jenis salah atau medan hilang Skema tidak dikuatkuasakan Tidak: minta semula bersama ralat

Garis pemisahnya ialah kekaburan. Jika hanya ada satu perkara yang mungkin dimaksudkan oleh model, baikinya dalam kod dan log bahawa anda berbuat demikian. Jika anda terpaksa meneka, tolak jawapan itu.

Mengapakah JSON yang terpotong tidak patut dibaiki?

Kerana versi yang dibaiki kelihatan betul tetapi sebenarnya tidak. Kami menjalankan json_repair 0.64.9, pustaka popular berlesen MIT, pada jawapan yang terpotong di tengah perkataan:

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

Ia memulangkan JSON yang sah dengan bandar “Jed”. README-nya berterus terang tentang perkara ini: ia “automatically completes missing values in JSON fields with reasonable defaults” (Terjemahan: melengkapkan nilai yang hilang dalam medan JSON secara automatik dengan nilai lalai yang munasabah). Itu berguna untuk membaca log. Untuk data yang anda simpan atau gunakan untuk bertindak, ia menukar kegagalan yang kelihatan kepada kegagalan senyap.

Semak finish_reason sebelum menghurai. "length" bermaksud jawapan mencapai max_tokens. Menghantar semula permintaan yang sama dengan had yang sama akan gagal dengan cara yang sama, jadi gandakan had atau minta lebih sedikit bagi setiap panggilan. Model penaakulan menjadikan ini lebih kerap: rujukan API BroadNet menyatakan DeepSeek V4.1 Flash, GLM 5.3 dan Qwen3.8 27B membuat penaakulan sebelum menjawab, dan penaakulan dikira dalam max_tokens. Dengan had yang kecil, jawapan boleh kembali kosong. Tinggalkan 1,000 token atau lebih, atau tetapkan reasoning_effort kepada low; artikel bajet penaakulan mempunyai angkanya.

Fungsi pembaikan yang hanya membaiki kes selamat

Ini hanya menggunakan pustaka standard. Ia memulangkan nilai yang dihurai dan senarai pembaikan yang dibuatnya, supaya anda boleh mengiranya.

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

Cara setiap langkah berfungsi:

  1. Jawapan terpotong dan kosong menimbulkan ralat sebelum sebarang penghuraian, jadi ia tidak pernah menjadi data.
  2. Pagar dan blok penaakulan dibuang dengan dua ungkapan nalar (regular expression).
  3. raw_decode ialah alat utama. Dokumentasi Python menyatakan ia menyahkod dokumen “from a string that may have extraneous data at the end” (Terjemahan: daripada rentetan yang mungkin mempunyai data berlebihan di hujungnya), dan memulangkan kedudukan ia berhenti. Bermula pada { atau [ pertama, ia melangkau prosa sebelum objek dan mengabaikan prosa selepasnya. Jika pendakap dalam prosa gagal dinyahkod, ia mencuba yang seterusnya.
  4. Imbasan kurungan menyusuri teks sambil menjejak rentetan dan escape. Kurungan yang masih terbuka bermaksud jawapan terpotong walaupun finish_reason tidak menyatakannya; itu menimbulkan ralat. Koma tepat sebelum } atau ] di luar rentetan dibuang.
  5. ast.literal_eval membaca output gaya Python dengan petikan tunggal, True dan None. Ia menilai literal sahaja dan tidak pernah menjalankan kod. Hasilnya kemudian mesti boleh disiri sebagai JSON yang ketat.
  6. NaN dan Infinity menimbulkan ralat, melalui parse_constant. json Python menerimanya secara lalai; RFC 8259 menyatakan ia “are not permitted” (Terjemahan: tidak dibenarkan), dan JSON.parse JavaScript menolaknya.

Kami menjalankannya pada 17 rentetan ujian: JSON bersih, JSON berpagar, kunci dan nilai Arab dalam pagar, prosa sebelum dan selepas, pemegang tempat {name} dalam prosa sebelum objek, blok <think>, koma di hujung dalam objek dan tatasusunan, koma dan kurungan di dalam rentetan, petikan ber-escape, laluan Windows yang berakhir dengan garis condong terbalik, literal Python, NaN, jawapan kosong, jawapan terpotong dengan dan tanpa finish_reason: "length", dan dua objek berturut-turut. Semuanya berkelakuan seperti yang dinyatakan dalam jadual di atas. Satu ujian menangkap pepijat sebenar: versi awal menterbalikkan bendera escape sebelum menyemak petikan penutup, jadi "he said \"hi,]\"" kehilangan komanya. Uji kod pembaikan anda sendiri pada petikan ber-escape.

Dua had yang perlu diketahui. Jika diberi dua objek berturut-turut, ia memulangkan yang pertama; jika anda mahukan beberapa item, minta satu tatasusunan JSON. Dan output Python berpetikan tunggal yang mengandungi petikan ganda di dalam rentetan boleh disalah baca oleh imbasan kurungan dan ditolak. Penolakan ialah kegagalan yang selamat.

Bagaimanakah cara mencuba semula selepas pembaikan gagal?

Pembaikan mengendalikan format. Pengesahan mengendalikan kandungan: medan yang betul, jenis yang betul, nilai yang munasabah. Gelung ini mengesahkan dengan pakej jsonschema dan memilih cara cuba semula mengikut punca:

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

Peraturan dalam gelung itu:

  • Terpotong: hantar semula mesej yang sama dengan had berganda. Menambah mesej “sila betulkan” akan memanjangkan prompt tanpa memendekkan output.
  • Bukan JSON, atau bentuk salah: hantar semula ralat yang tepat. “amount: ‘1200’ is not of type ‘number’” memberi model sesuatu yang khusus untuk dibaiki. Cuba semula kosong selalunya mengulang kesilapan yang sama.
  • Hadkan percubaan kepada tiga. Setiap cuba semula menghantar semula seluruh perbualan sebagai token input. Selepas tiga, log input itu dan halakannya ke tempat lain.
  • Log senarai pembaikan. Kiraan “removed code fence” yang meningkat selepas perubahan prompt memberitahu anda prompt itu menjadi lebih teruk, walaupun tiada apa yang gagal.

Kami menjalankan gelung ini terhadap pelayan olok-olok setempat yang memainkan semula jawapan berskrip. Jawapan berpagar dengan koma di hujung dan "amount": "1200" sebagai rentetan telah dibaiki, gagal pengesahan, dan dibetulkan pada panggilan kedua selepas ralat dihantar semula. Jawapan yang terpotong dengan finish_reason: "length" dihantar semula dengan max_tokens dinaikkan daripada 1,500 kepada 3,000 dan berjaya. Pelayan olok-olok merekod permintaan setiap kali, mengesahkan bilangan mesej dan had yang dihantar oleh gelung. Model sebenar boleh gagal dengan cara berbeza, jadi jalankannya pada 100 input anda sendiri sebelum mempercayai angka-angka itu.

Adakah output berstruktur menjadikan semua ini tidak perlu?

Ia menghapuskan sebahagian besarnya. Pelayan yang mengekang penyahkodan mengikut skema anda tidak boleh mengeluarkan pagar, koma di hujung atau medan yang hilang. vLLM, pelayan model terbuka yang biasa, melakukan ini dengan backend xgrammar atau guidance. Dua kegagalan masih kekal: pemotongan pada max_tokens, dan penolakan. OpenAI menyatakan output mod JSON sah “except for in some edge cases” (Terjemahan: kecuali dalam beberapa kes pinggir) dan aplikasi anda “must detect and handle” (Terjemahan: mesti mengesan dan mengendalikan) output yang bukan objek lengkap. Jadi kekalkan semakan finish_reason dan pengesah, walaupun dengan json_schema.

Apa yang dicegah oleh setiap pendekatan:

Pendekatan Pagar dan prosa Ralat sintaks Bentuk salah Pemotongan
Prompt sahaja (“reply with JSON”) Berkurang Berkurang Berkurang Tidak
Mod JSON (json_object) Ya Ya Tidak Tidak
Output berstruktur (json_schema, dikuatkuasakan) Ya Ya Ya Tidak

Dengan mod JSON, OpenAI juga menyatakan anda “must always instruct the model to produce JSON” (Terjemahan: mesti sentiasa mengarahkan model menghasilkan JSON) dalam satu mesej; jika tidak, ia mungkin mengeluarkan ruang kosong sehingga mencapai had token. Pelayan lain yang serasi OpenAI berbeza-beza, jadi uji mod itu pada model yang anda gunakan dalam produksi. Ujiannya ada dalam artikel output berstruktur.

Untuk menyemak jawapan secara manual, tampalkannya ke dalam pengesah output JSON LLM, atau bina skema ketat daripada objek sampel dengan penjana skema JSON.

Di manakah BroadNet Inference sesuai

BroadRouter ialah laman web BroadNet. Rujukan API BroadNet menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B sahaja, dan tidak menamakan parameter permintaannya, jadi uji json_schema pada model itu sebelum bergantung padanya. Pada DeepSeek V4.1 Flash dan Gemma 4 VL 26B, gunakan JSON melalui prompt sahaja bersama fungsi pembaikan dan pengesah di atas. Tiga daripada empat model membuat penaakulan sebelum menjawab, jadi bajetkan max_tokens untuknya. Untuk pengekstrakan pukal, artikel pelari batch menunjukkan cara melog finish_reason bagi setiap item. Prompt dan jawapan tidak disimpan selepas setiap permintaan.

Soalan lazim

Mengapakah LLM saya memulangkan JSON di dalam blok kod markdown?

Model chat biasanya memformat kod untuk manusia, dan pagar kod ialah cara antara muka chat memaparkannya. Minta "JSON sahaja, tanpa pagar kod", tetapi tetap buang pagar dalam kod: arahan itu mengurangkan kekerapan, ia tidak menghapuskannya.

Bagaimanakah saya membaiki JSONDecodeError pada output LLM?

Lihat finish_reason dahulu. Jika "length", jawapan terpotong: naikkan max_tokens dan hantar semula. Jika tidak, buang pagar kod dan nyahkod nilai JSON pertama dengan raw_decode, yang mengabaikan teks selepasnya. Baiki koma di hujung, kemudian sahkan. Minta semula bersama ralat jika masih gagal.

Patutkah saya menggunakan pustaka pembaikan JSON?

Untuk log dan nyahpepijat, ya. Untuk data yang anda gunakan untuk bertindak, berhati-hati. Pustaka seperti json_repair melengkapkan nilai yang hilang dengan nilai lalai, jadi bandar "Jed" yang terpotong kembali sebagai "Jed" yang sah. Tolak output yang terpotong dan hantar semula.

Mengapakah output JSON LLM saya terpotong?

Jawapan mencapai max_tokens. Pada model penaakulan seperti DeepSeek V4.1 Flash, GLM 5.3 dan Qwen3.8 27B, penaakulan dikira dalam had itu, jadi proses berfikir yang panjang boleh meninggalkan ruang yang terlalu sedikit. Naikkan had, tetapkan reasoning_effort kepada low, atau minta output yang lebih sedikit bagi setiap panggilan.

Adakah mod JSON menjamin JSON yang sah?

Hampir. OpenAI menyatakan output mod JSON ialah JSON yang sah "except for in some edge cases" (Terjemahan: kecuali dalam beberapa kes pinggir), seperti mencapai had token, dan ia tidak menguatkuasakan skema anda. Output berstruktur dengan json_schema menambah pematuhan skema jika penyedia menguatkuasakannya. Sahkan juga dalam kedua-dua keadaan.

Model BroadNet manakah yang menyokong output berstruktur?

Rujukan API BroadNet menyenaraikan output berstruktur untuk GLM 5.3 dan Qwen3.8 27B, disemak pada 15 November 2026. Ia tidak menyenaraikannya untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi gunakan JSON melalui prompt sahaja bersama pembaikan dan pengesahan pada model itu.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity