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:
- Balasan terpotong dan kosong langsung memunculkan exception sebelum parsing apa pun, jadi tidak pernah menjadi data.
- Fence dan blok penalaran dibuang dengan dua regular expression.
raw_decodeadalah 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.- Pemindaian kurung menelusuri teks sambil melacak string dan escape. Kurung yang masih terbuka berarti balasan terpotong meskipun
finish_reasontidak menyebutnya; ini memunculkan exception. Koma tepat sebelum}atau]di luar string dibuang. ast.literal_evalmembaca output gaya Python dengan kutip tunggal,True, danNone. Fungsi ini hanya mengevaluasi literal dan tidak pernah menjalankan kode. Hasilnya lalu harus bisa diserialisasi sebagai JSON yang ketat.NaNdanInfinitymemunculkan exception lewatparse_constant.jsonPython menerimanya secara default; RFC 8259 menyatakan keduanya “are not permitted” (Terjemahan BroadRouter: tidak diizinkan), danJSON.parsedi 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.
