Panduan Perbaikan JSON: menyelamatkan output LLM yang rusak tanpa kehilangan kepercayaan
Intinya: Output LLM yang dibungkus pagar markdown, dengan koma di akhir dan literal Python, ditolak habis oleh parser ketat — begitu pula konfigurasi yang diedit tangan tanpa tanda kutip. Panduan ini menarik garis batas nyata antara sembilan kelas kesalahan yang alat perbaiki mampu memperbaiki dan empat kelas yang tidak akan pernah, menjelaskan mengapa mesin status mengalahkan regex, serta menyediakan rantai parse siap produksi dengan jsonrepair dan json-repair.

Parser ketat tidak memberi kelonggaran sedikit pun pada input rusak: satu pesan kesalahan, satu nomor baris — dan tidak satu byte pun data Anda kembali. Alat perbaiki ada untuk mengubah "kegagalan total" menjadi "cukup baik untuk dijalankan" — tetapi yang ia tambal selalu hanya tebakan terbaik tentang maksud, bukan jaminan kebenaran.
Satu: dari mana JSON rusak berasal
Perbaikan bukan sulap — mulailah dari mengamati input. Dalam proyek nyata, JSON non-standar berasal dari tiga sumber terkonsentrasi:
- Output LLM. Model bahasa menghasilkan teks token demi token; mereka tidak menjalankan serializer JSON. Bahkan saat diminta "hanya JSON", model membungkus jawaban dalam pagar
```json, menyisipkan "Ini datamu" di depan, meninggalkan koma di akhir, atau menghantam batas token dan berhenti di tengah objek. - Salinan dari bahasa lain. Objek JavaScript yang dicetak lewat
console.logmembawa kutip tunggal dan kunci tanpa kutip; dictionary Python mencetak sebagaiTrue/False/None. String yang "mirip JSON" ini meledak saat pertama bertemuJSON.parse. - Konfigurasi JSON5/JSONC. File seperti tsconfig secara sah mengizinkan komentar dan koma di akhir. Tempel salah satu ke parser ketat — ia menolak seluruh file.
Tiga sumber memerlukan perlakuan berbeda, tetapi alat perbaiki menampung semuanya — selama kesalahan ada dalam daftar kasus yang bisa diperbaiki yang mereka deklarasikan.
Dua: sembilan kelas kesalahan yang alat perbaiki benar-benar perbaiki
Menggabungkan dokumentasi pustaka jsonrepair dengan daftar kemampuan yang dipublikasikan penyedia alat, kesalahan yang bisa diperbaiki otomatis terbagi menjadi sembilan kelas:
| Kelas | Input rusak | Hasil setelah perbaikan |
|---|---|---|
| Koma di akhir | [1, 2, 3,] |
[1, 2, 3] |
| Kutip tunggal / kutip melengkung | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| Kunci tanpa kutip | {name: 'Ada'} |
{"name": "Ada"} |
| Komentar | {"a": 1 /* catatan */} |
{"a": 1} |
| Literal Python | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| Pagar markdown | ```json {...} ``` |
{...} |
| Koma hilang | [1 2] |
[1, 2] |
| Kurung / kutip tak tertutup | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP / penyambungan string | cb({...})、"x" + "y" |
{...}、"xy" |
Persamaan sembilan kelas ini: data semuanya ada; yang rusak hanya sintaks. Alat perbaiki merapikan tanda baca dan pembungkus tanpa menyentuh satu nilai pun. Beberapa detail layak diingat tersendiri:
- Angka dengan nol di depan menjadi string.
007diperbaiki menjadi"007", bukan7, agar digit tidak hilang. Kalau memang kodenya teks, itu benar; kalau angka sungguhan, keputusan di tangan Anda. - Kata telanjang menjadi string.
NaNtidak bisa diperbaiki menjadi angka — sebagian implementasi memberi"NaN", sebagiannull. Perilaku berbeda antarpustaka; uji milik Anda sebelum dipasang ke pipeline. - Input valid lewat tanpa diubah. Setiap alat perbaiki serius menjalankan jalur cepat parse ketat lebih dahulu. JSON valid tidak pernah masuk logika perbaikan, sehingga "memperbaiki dokumen baik menjadi buruk" mustahil.
Tiga: empat hal yang alat perbaiki tidak perbaiki
Batas di seberang sama tegasnya. Jangan berharap perbaikan untuk:
- Halaman kesalahan HTML atau prosa murni. Tak ada struktur JSON dalam input, dan tak ada alat yang bisa menciptakan data dari ketiadaan.
- Data yang sah secara sintaks tapi salah isinya. Kunci salah eja, nilai di tempat keliru, angka disimpan sebagai string — ini masalah semantik yang setiap parser, alat perbaiki termasuk, biarkan lewat tanpa protes.
- Data yang hilang karena terpotong. Pelengkap bisa mengubah
{"items": [{"id": 1}, {"namenjadi JSON valid, tetapi nilai bidangnametak akan kembali selamanya. Anda mendapat objek "valid tapi tak lengkap". Di produksi, cekstopReason === "max_tokens"sebelum memutuskan: melengkapi atau mencoba ulang. - Kunci duplikat dan struktur ambigu. Dari dua kunci serupa, mana yang menang bergantung pada implementasi parser. Alat perbaiki yang bertanggung jawab menyediakan mode strict yang melempar kesalahan alih-alih diam-diam memilih satu.
Batas kepercayaan dalam satu kalimat: perbaikan adalah tebakan terbaik, bukan jaminan kebenaran. Membiarkan hasil perbaikan yang belum diverifikasi mengalir ke hilir berarti menukar kesalahan sintaks yang berisik dengan kesalahan data yang senyap.
Empat: dua aliran implementasi — satu URL menyelesaikan perdebatan
Alat perbaiki di pasaran hadir dalam dua ragam, dan jaraknya tampak jelas pada jenis input yang sangat spesifik.
Aliran penggantian regex menerapkan cari-dan-ganti global pada pola rusak. Perhatikan input ini:
{"url": "http://example.com", 'note': 'fine'}
Regex yang mengubah kutip tunggal jadi ganda ikut mengunyah isi URL; regex pembersih komentar yang menghapus setiap // akan memotong http:// menjadi dua. Di dalam string dan di luar struktur, karakter tampak serupa — regex tak mampu membedakannya.
Aliran mesin status per karakter melacak status parse: di dalam string kutip ganda, kutip tunggal, di dalam komentar baris, komentar blok, atau sedang menunggu nilai. Saat melihat ', ia bertanya dahulu "apakah saya di dalam string?" lalu memutuskan mengubah kutip atau melewatkannya. http://example.com berada di dalam string kutip ganda, sehingga mesin status tahu // di sana adalah data, bukan komentar, dan mengekalkannya. jsonrepair dan json-healer termasuk aliran ini, dan mantra komunitas "alat perbaiki bukan cari-dan-ganti" merujuk tepat pada hal ini.
Urutan lengkap pipeline perbaikan (seperti dibuka implementasi devkits) juga patut dilihat: melepas pagar → menormalkan kutip melengkung → mengekstrak blok seimbang pertama → menghapus komentar → membungkus kunci telanjang dengan kutip → menghapus koma akhir → mengonversi literal → akhirnya mem-serial ulang lewat JSON.stringify. Serialis ulang akhir itulah langkah kunci: apa pun yang dilakukan tahap sebelumnya, output dihasilkan kembali dari hasil parse, sehingga parser ketat mana pun di hilir mampu menelannya.
Lima: menyambung di kode — rantai parse berurutan
Saat memasang perbaikan di kode, urutan lebih penting daripada pilihan pustaka. Mengikuti pola yang dipublikasikan json2toon dan aijsonmedic, urutannya harus: pemeriksaan pemotongan → ekstraksi rentang JSON → parse ketat → perbaikan sebagai cadangan → validasi skema.
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// Memperbaiki output terpotong tetap kekurangan data — coba ulang saja
throw new Error("Truncated output: retry with a higher max_tokens");
}
// Ekstrak rentang JSON: LLM bisa saja bercakap-cakap di depan dan belakang
const start = text.search(/[[{]/);
const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
try {
return JSON.parse(candidate); // jalur cepat untuk input valid
} catch {
return JSON.parse(jsonrepair(candidate)); // perbaikan sebagai cadangan
}
}
Di sisi Python, paket json-repair (lebih dari 4.700 bintang) menyediakan loads() yang langsung mengembalikan objek:
from json_repair import repair_json
import json
broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}
Dua detail rekayasa lagi:
- Selaraskan stack. Kalau frontend dan backend sama-sama memperbaiki, pilih implementasi dengan semantik bersama — Python json-repair dan port TypeScript-nya
@yarmu/json-repair, atau jsonmend yang versi Python dan JS-nya lulus korpus kesesuaian 485 kasus yang sama. Tanpa itu, output yang sama diperbaiki menjadi A di klien dan B di server, dan debugging menjadi mimpi buruk. - Nyalakan log perbaikan.
@yarmu/json-repairdenganlogging: truemengembalikan larik setiap operasi perbaikan. Lonjakan mendadak pada tingkat perbaikan biasanya berarti prompt atau versi model berubah — sinyal yang lebih awal daripada laporan kesalahan mana pun.
Satu langkah setelah perbaikan tak bisa ditawar: validasi skema. Sah secara sintaks belum berarti bisa dipakai. Bidang hilang, tipe keliru, kunci tak terduga — semuanya ditangkap skema. Pendekatan pengujian kontrak dipakai langsung di sini; lihat panduan pengujian kontrak JSON Schema kami.
Enam: checklist pencegahan — perbaikan termurah adalah yang tidak diperlukan
Perbaikan itu cadangan. Kemenangan sejati adalah menghasilkan lebih sedikit JSON rusak di sumbernya, berurutan menurut prioritas:
- Structured Outputs (mode json_schema). Dekodasi dibatasi skema, sehingga koma di akhir sederhananya tak bisa dihasilkan. Mode strict OpenAI gagal sekitar 0,1% — dengan harga tuntutan keras seperti
additionalProperties: false. - Mode JSON (json_object). Menjamin kesahihan sintaks saja — bukan bentuk — dan pemotongan karena batas token tetap terjadi.
- Instruksi eksplisit. Pada endpoint tanpa mode JSON, formulasi "tanpa pagar, tanpa komentar, tanpa koma akhir, keluarkan hanya objek" menurunkan tingkat kesalahan 70–80%.
- Turunkan temperature, naikkan batas token. Yang pertama mengurangi melenceng ke prosa; yang kedua mengurangi pemotongan.
- Coba ulang dengan kesalahan dilampirkan. Saat validasi gagal, sisipkan output rusak plus "jalur JSON + pesan kesalahan" ke percakapan dan minta lagi. Dengan kesalahan yang presisi, model biasanya memperbaiki diri sendiri.
Dalam praktik, penumpukan tiga lapis "structured outputs + perbaikan cadangan + validasi skema" menampung hampir semua skenario.
Tujuh: pembagian kerja — konversi dialek bukanlah perbaikan
Di kotak alat situs ini ada dua tujuan yang menampung segmen berbeda dari pipeline ini:
- Masalah dialek (komentar, kutip tunggal, koma akhir) langsung ke konverter JSON5. Konversi JSON5 ↔ JSON standar menampung tepat tiga kelas ini, dengan semantik eksplisit, tanpa tebak-tebakan. Kalau seluruh input adalah file JSONC/JSON5, konversi lebih dapat diprediksi daripada perbaikan. Tentang pertimbangan dialek itu sendiri, lihat panduan JSON5 dan JSONC.
- Setelah perbaikan, kirimkan hasil lewat alat parse JSON untuk validasi dan format — kesalahan dilokalisasi ke baris dan kolom, mengonfirmasi parser ketat benar-benar menerima output.
- Masalah kelas pustaka (literal Python, pelengkap pemotongan, pembungkus JSONP, pagar markdown) masih memerlukan jsonrepair / json-repair di sisi kode — perbaikan satu klik yang setara di peramban belum ada, karena perbaikan ini melibatkan penyimpulan maksud, dan pustaka lokal lebih aman jadi rumahnya daripada konverter serbaguna.
Kalau yang di tangan Anda pesan kesalahan, bukan data rusak, mulailah dari panduan perbaikan kesalahan parse JSON untuk menerjemahkan pesan menjadi koordinat, baru putuskan: menyunting tangan atau memperbaiki.
FAQ
Apakah perbaikan JSON merusak data saya?
Untuk sembilan kelas yang bisa diperbaiki, hanya tanda baca dan pembungkus yang berubah — nilai tetap utuh, dan //, koma, serta kurung kurawal di dalam string dikenali dan dikekalkan mesin status. Tetapi pelengkap pemotongan menghasilkan objek tak lengkap, angka berawalan nol menjadi string, dan perlakuan NaN berbeda antarpustaka. Memeriksa bidang kunci setelah perbaikan wajib dilakukan.
Bagaimana hubungan perbaikan dan validasi?
Validasi memberitahu di mana input melanggar hukum; perbaikan menyerahkan dokumen yang sah. Alur kerja yang dapat dipercaya melakukan keduanya: memperbaiki dahulu, lalu memvalidasi — skema menangkap tipe dan bidang wajib, pemeriksaan sintaks mengonfirmasi parser ketat menerima hasil. Memperbaiki tanpa memvalidasi berarti menukar kesalahan sintaks yang berisik dengan kesalahan data yang senyap.
Output LLM selalu dibungkus pagar ```json — bagaimana?
Jangka pendek: ekstrak. Ambil teks dari { atau [ pertama sampai } atau ] terakhir dan parse; alat perbaiki dengan pelepasan pagar juga menelan seluruh pesan. Jangka panjang: gunakan structured outputs atau instruksi eksplisit "tanpa pagar markdown" agar pagar tidak dihasilkan sama sekali.
jsonrepair atau json-repair — pilih yang mana?
Untuk JavaScript paket npm jsonrepair (mendukung transform streaming); untuk Python json-repair dari PyPI. Kalau kedua ujung memperbaiki, pilih pasangan bersemantik selaras — misalnya json-repair plus port TS-nya — agar input yang sama diperbaiki serupa di kedua sisi.
Alat perbaiki sanggup menangani Bahasa Indonesia dan kutip melengkung?
Sanggup. Kutip tipografis dari papan ketik Indonesia (" "), spasi lebar penuh dan BOM di awal file semuanya ada dalam daftar perbaikan standar; kutip melengkung dinormalkan menjadi kutip lurus. Kirim hasil lewat validator sekali dan selesai.