BroadRouter

Cara memperbaiki JSON tidak valid dari LLM: penyebab, perbaikan, retry

Oleh tim BroadNet Inference · 7 menit baca · Dipublikasikan · Diperbarui

Cek finish_reason dulu: balasan yang terpotong di max_tokens tidak bisa diperbaiki dengan aman, jadi naikkan batasnya dan kirim ulang. Jika tidak, buang code fence dan teks di sekitarnya, decode nilai JSON pertama, lalu perbaiki hanya kesalahan yang jelas maknanya seperti koma di akhir. Validasi dengan skema, dan jika gagal, kirim error persisnya kembali sekali atau dua kali. Output terstruktur mencegah sebagian besar masalah ini jika didukung.

Kode Anda memanggil json.loads() pada balasan model dan mendapat JSONDecodeError: Expecting value: line 1 column 1. Atau parsing berhasil, tetapi sebuah field berupa string padahal Anda mengharapkan angka. Artikel ini mengelompokkan penyebabnya berdasarkan apa yang aman dilakukan untuk masing-masing, memberikan fungsi Python teruji yang hanya memperbaiki kasus yang maknanya jelas, dan menunjukkan loop retry yang tahu kapan retry tidak akan membantu.

Memilih antara JSON mode dan json_schema dibahas di JSON mode vs json_schema. Artikel ini membahas apa yang harus dilakukan dengan balasan yang benar-benar Anda terima.

Kenapa LLM mengembalikan JSON yang tidak valid?

Model menulis teks satu token demi satu token. Kecuali server membatasi decoding, tidak ada yang mencegahnya menambahkan kalimat ramah atau kehabisan ruang. Kegagalan yang umum:

Yang Anda lihat Penyebab Aman diperbaiki di kode?
```json … ``` di sekitar objek Kebiasaan format chat Ya: buang fence-nya
“Here is the JSON:” sebelumnya, “Let me know…” sesudahnya Kebiasaan yang sama Ya: baca nilai pertama saja
<think>...</think> sebelum objek Teks penalaran masuk ke field content di beberapa server Ya: hapus bloknya
Berakhir di tengah string, kurung masih terbuka Mencapai max_tokens Tidak: kirim ulang dengan ruang lebih besar
Content kosong Penalaran memakai seluruh anggaran Tidak: kirim ulang dengan ruang lebih besar
{"a": 1,} Koma di akhir; JavaScript mengizinkannya, RFC 8259 tidak Ya: maknanya tunggal
{'a': True, 'b': None} Sintaks Python Ya: ast.literal_eval membacanya dengan aman
NaN, Infinity Bukan JSON; Python menerimanya secara default Tidak: tolak
JSON valid, tipe salah atau field hilang Skema tidak dipaksakan Tidak: minta ulang dengan error-nya

Garis pemisahnya adalah ambiguitas. Jika hanya ada tepat satu hal yang mungkin dimaksud model, perbaiki di kode dan catat di log bahwa Anda melakukannya. Jika Anda harus menebak, tolak balasannya.

Kenapa JSON yang terpotong tidak boleh diperbaiki?

Karena versi yang diperbaiki terlihat benar padahal tidak. Kami menjalankan json_repair 0.64.9, library populer berlisensi MIT, pada balasan yang terpotong di tengah kata:

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

Hasilnya JSON valid dengan kota “Jed”. README-nya terbuka soal ini: library itu “automatically completes missing values in JSON fields with reasonable defaults” (Terjemahan BroadRouter: secara otomatis melengkapi nilai yang hilang di field JSON dengan default yang masuk akal). Itu berguna untuk membaca log. Untuk data yang Anda simpan atau tindak lanjuti, ini mengubah kegagalan yang terlihat menjadi kegagalan yang tersembunyi.

Cek finish_reason sebelum parsing. "length" berarti balasan mencapai max_tokens. Mengirim ulang permintaan yang sama dengan batas yang sama akan gagal dengan cara yang sama, jadi gandakan batasnya atau minta lebih sedikit per panggilan. Model penalaran membuat ini lebih sering terjadi: referensi API BroadNet menyebut DeepSeek V4.1 Flash, GLM 5.3, dan Qwen3.8 27B bernalar sebelum menjawab, dan penalaran itu dihitung ke dalam max_tokens. Dengan batas kecil, jawabannya bisa kosong. Sisakan 1.000 token atau lebih, atau set reasoning_effort ke low; angka-angkanya ada di artikel anggaran penalaran.

Fungsi perbaikan yang hanya memperbaiki kasus aman

Fungsi ini hanya memakai standard library. Ia mengembalikan nilai hasil parse dan daftar perbaikan yang dilakukannya, sehingga Anda bisa menghitungnya.

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 kerja setiap langkah:

  1. Balasan terpotong dan kosong langsung memunculkan exception sebelum parsing apa pun, jadi tidak pernah menjadi data.
  2. Fence dan blok penalaran dibuang dengan dua regular expression.
  3. raw_decode adalah alat kuncinya. Dokumentasi Python menyebut fungsi ini men-decode dokumen “from a string that may have extraneous data at the end” (Terjemahan BroadRouter: dari string yang mungkin punya data berlebih di akhirnya), dan mengembalikan posisi berhentinya. Mulai dari { atau [ pertama, ia melewati teks sebelum objek dan mengabaikan teks sesudahnya. Jika kurung kurawal di dalam teks gagal di-decode, ia mencoba yang berikutnya.
  4. Pemindaian kurung menelusuri teks sambil melacak string dan escape. Kurung yang masih terbuka berarti balasan terpotong meskipun finish_reason tidak menyebutnya; ini memunculkan exception. Koma tepat sebelum } atau ] di luar string dibuang.
  5. ast.literal_eval membaca output gaya Python dengan kutip tunggal, True, dan None. Fungsi ini hanya mengevaluasi literal dan tidak pernah menjalankan kode. Hasilnya lalu harus bisa diserialisasi sebagai JSON yang ketat.
  6. NaN dan Infinity memunculkan exception lewat parse_constant. json Python menerimanya secara default; RFC 8259 menyatakan keduanya “are not permitted” (Terjemahan BroadRouter: tidak diizinkan), dan JSON.parse di JavaScript menolaknya.

Kami menjalankannya pada 17 string uji: JSON bersih, JSON ber-fence, key dan value berbahasa Arab di dalam fence, teks sebelum dan sesudah, placeholder {name} di teks sebelum objek, blok <think>, koma di akhir pada objek dan array, koma dan kurung di dalam string, kutip yang di-escape, path Windows yang berakhir dengan backslash, literal Python, NaN, balasan kosong, balasan terpotong dengan dan tanpa finish_reason: "length", serta dua objek berturut-turut. Semuanya berperilaku seperti yang tertulis di tabel atas. Satu uji menangkap bug nyata: versi awal membalik flag escape sebelum mengecek kutip penutup, sehingga "he said \"hi,]\"" kehilangan komanya. Uji kode perbaikan Anda sendiri dengan kutip yang di-escape.

Ada dua batasan yang perlu diketahui. Jika diberi dua objek berturut-turut, fungsi ini mengembalikan yang pertama; jika Anda menginginkan beberapa item, minta satu array JSON. Selain itu, output Python berkutip tunggal yang berisi kutip ganda di dalam string bisa salah dibaca oleh pemindaian kurung lalu ditolak. Menolak adalah kegagalan yang aman.

Bagaimana melakukan retry setelah perbaikan gagal?

Perbaikan mengurus format. Validasi mengurus isi: field yang benar, tipe yang benar, nilai yang masuk akal. Loop ini memvalidasi dengan paket jsonschema dan memilih jenis retry berdasarkan penyebabnya:

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

Aturan dalam loop tersebut:

  • Terpotong: kirim ulang pesan yang sama dengan batas dua kali lipat. Menambahkan pesan “tolong perbaiki” hanya membuat prompt lebih panjang tanpa membuat output lebih pendek.
  • Bukan JSON, atau bentuknya salah: kirim error persisnya kembali. “amount: ‘1200’ is not of type ‘number’” memberi model sesuatu yang spesifik untuk diperbaiki. Retry tanpa keterangan sering mengulang kesalahan yang sama.
  • Batasi percobaan sampai tiga kali. Setiap retry mengirim ulang seluruh percakapan sebagai token input. Setelah tiga kali, catat input-nya di log dan arahkan ke jalur lain.
  • Catat daftar perbaikan di log. Jumlah “removed code fence” yang naik setelah perubahan prompt menandakan prompt-nya memburuk, meskipun tidak ada yang gagal.

Kami menjalankan loop ini terhadap mock server lokal yang memutar balasan sesuai skrip. Balasan ber-fence dengan koma di akhir dan "amount": "1200" sebagai string berhasil diperbaiki, gagal validasi, lalu diperbaiki pada panggilan kedua setelah error-nya dikirim kembali. Balasan yang terpotong dengan finish_reason: "length" dikirim ulang dengan max_tokens dinaikkan dari 1.500 ke 3.000 dan berhasil. Mock server merekam permintaan setiap kali, mengonfirmasi jumlah pesan dan batas yang dikirim loop. Model sungguhan bisa gagal dengan cara lain, jadi jalankan loop ini pada 100 input Anda sendiri sebelum memercayai angkanya.

Apakah output terstruktur membuat semua ini tidak perlu?

Sebagian besar, ya. Server yang membatasi decoding sesuai skema Anda tidak bisa menghasilkan fence, koma di akhir, atau field yang hilang. vLLM, server model terbuka yang umum, melakukannya dengan backend xgrammar atau guidance. Meski begitu, dua kegagalan tetap ada: terpotong di max_tokens, dan penolakan. OpenAI mencatat bahwa output JSON mode valid “except for in some edge cases” (Terjemahan BroadRouter: kecuali dalam beberapa kasus tepi) dan bahwa aplikasi Anda “must detect and handle” (Terjemahan BroadRouter: harus mendeteksi dan menangani) output yang bukan objek lengkap. Jadi pertahankan pengecekan finish_reason dan validator, bahkan dengan json_schema.

Apa yang dicegah setiap pendekatan:

Pendekatan Fence dan teks tambahan Error sintaks Bentuk salah Terpotong
Prompt saja (“balas dengan JSON”) Berkurang Berkurang Berkurang Tidak
JSON mode (json_object) Ya Ya Tidak Tidak
Output terstruktur (json_schema, dipaksakan) Ya Ya Ya Tidak

Untuk JSON mode, OpenAI juga menyebut Anda “must always instruct the model to produce JSON” (Terjemahan BroadRouter: harus selalu menginstruksikan model untuk menghasilkan JSON) di salah satu pesan; jika tidak, model bisa menghasilkan whitespace sampai mencapai batas token. Server lain yang kompatibel dengan OpenAI bervariasi, jadi uji mode ini pada model yang Anda rilis. Pengujiannya ada di artikel output terstruktur.

Untuk mengecek balasan secara manual, tempelkan ke validator output JSON LLM, atau buat skema ketat dari contoh objek dengan generator JSON schema.

Posisi BroadNet Inference

BroadRouter adalah situs milik BroadNet. Referensi API BroadNet mencantumkan output terstruktur hanya untuk GLM 5.3 dan Qwen3.8 27B, dan tidak menyebut nama parameter permintaannya, jadi uji json_schema pada model tersebut sebelum mengandalkannya. Di DeepSeek V4.1 Flash dan Gemma 4 VL 26B, pakai JSON lewat prompt saja dengan fungsi perbaikan dan validator di atas. Tiga dari empat model bernalar sebelum menjawab, jadi anggarkan max_tokens untuk itu. Untuk ekstraksi massal, artikel batch runner menunjukkan cara mencatat finish_reason per item. Prompt dan balasan tidak disimpan setelah setiap permintaan.

Pertanyaan umum

Kenapa LLM saya mengembalikan JSON di dalam blok kode markdown?

Model chat biasanya memformat kode untuk dibaca manusia, dan code fence adalah cara antarmuka chat menampilkannya. Minta "hanya JSON, tanpa code fence", tetapi tetap buang fence di kode Anda: instruksi itu menurunkan frekuensinya, bukan menghilangkannya.

Bagaimana cara mengatasi JSONDecodeError pada output LLM?

Lihat finish_reason dulu. Jika nilainya "length", balasannya terpotong: naikkan max_tokens dan kirim ulang. Jika bukan, buang code fence dan decode nilai JSON pertama dengan raw_decode, yang mengabaikan teks sesudahnya. Perbaiki koma di akhir, lalu validasi. Jika masih gagal, minta ulang dengan menyertakan error-nya.

Perlukah saya memakai library perbaikan JSON?

Untuk log dan debugging, ya. Untuk data yang akan Anda tindak lanjuti, hati-hati. Library seperti json_repair melengkapi nilai yang hilang dengan default, sehingga kota "Jed" yang terpotong kembali sebagai "Jed" yang valid. Tolak output yang terpotong dan kirim ulang.

Kenapa output JSON LLM saya terpotong?

Balasannya mencapai max_tokens. Pada model penalaran seperti DeepSeek V4.1 Flash, GLM 5.3, dan Qwen3.8 27B, penalaran dihitung ke dalam batas itu, sehingga proses berpikir yang panjang bisa menyisakan terlalu sedikit ruang. Naikkan batasnya, set reasoning_effort ke low, atau minta output lebih sedikit per panggilan.

Apakah JSON mode menjamin JSON yang valid?

Hampir. OpenAI menyebut output JSON mode adalah JSON yang valid "except for in some edge cases" (Terjemahan BroadRouter: kecuali dalam beberapa kasus tepi), seperti saat mencapai batas token, dan JSON mode tidak memaksakan skema Anda. Output terstruktur dengan json_schema menambahkan kepatuhan skema jika penyedia memaksakannya. Tetap lakukan validasi.

Model BroadNet mana yang mendukung output terstruktur?

Referensi API BroadNet mencantumkan output terstruktur untuk GLM 5.3 dan Qwen3.8 27B, dicek pada 15 November 2026. Fitur ini tidak tercantum untuk DeepSeek V4.1 Flash atau Gemma 4 VL 26B, jadi di kedua model itu pakai JSON lewat prompt saja dengan perbaikan dan validasi.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity