JSON Toolkit

Panduan Pemulihan JSON: menyelamatkan output LLM yang rusak tanpa kehilangan kepercayaan

Inti pati: Output LLM yang dibalut pagar markdown, dengan koma penghujung dan literal Python, ditolak habis oleh parser ketat — begitu juga konfigurasi yang disunting tangan tanpa tanda petik. Panduan ini menarik garis sempadan sebenar antara sembilan kelas kesalahan yang alat pembaiki mampu betulkan dan empat kelas yang tidak akan pernah, menjelaskan mengapa mesin keadaan mengalahkan regex, serta membekalkan rantaian parse sedia produksi dengan jsonrepair dan json-repair.

Pertengahan~6 min bacaanDiterbitkan 2026-11-08Dikemas kini 2026-11-08
Rajah saluran pemulihan JSON: penyingkiran pagar, penormalan tanda petik, pengimbangan kurungan, pengesahan akhir

Parser ketat tidak memberikan sebarang kelonggaran kepada input rosak: satu mesej ralat, satu nombor baris — dan tidak satu bait pun data anda. Alat pembaiki wujud untuk menukar "kegagalan total" kepada "cukup baik untuk berjalan" — tetapi apa yang ia tambal sentiasa hanya tekaan terbaik tentang niat, bukan jaminan kebetulan.

Satu: dari mana JSON rosak datang

Pembaikan bukan sihir — mulakan dengan memeriksa input. Dalam projek sebenar, JSON bukan standard datang dari tiga sumber tertumpu:

  1. Output LLM. Model bahasa menjana teks token demi token; mereka tidak menjalankan serializer JSON. Walaupun diminta "JSON sahaja", model membungkus jawapan dalam pagar ```json, menambah "Ini data anda" di depan, meninggalkan koma penghujung, atau menghentam had token dan berhenti di tengah objek.
  2. Salin dari bahasa lain. Objek JavaScript dicetak melalui console.log membawa petikan tunggal dan kunci tanpa petikan; kamus Python dicetak sebagai True/False/None. Rentetan "mirip JSON" ini meletup pada sentuhan pertama dengan JSON.parse.
  3. Konfigurasi JSON5/JSONC. Fail seperti tsconfig sah membenarkan komen dan koma penghujung. Tampal satu ke dalam parser ketat — ia menolak keseluruhan fail.

Tiga sumber memerlukan layanan berbeza, tetapi alat pembaiki menampung semua — dengan syarat kesalahan itu ada dalam senarai kes boleh baiki yang diisytiharkan.

Dua: sembilan kelas kesalahan yang alat pembaiki benar-benar baiki

Dengan menggabungkan dokumentasi pustaka jsonrepair dan senarai keupayaan yang diterbitkan pembekal alat, kesalahan yang boleh dibaiki secara automatik terbahagi kepada sembilan kelas:

Kelas Input rosak Hasil dibaiki
Koma penghujung [1, 2, 3,] [1, 2, 3]
Petikan tunggal / petik melengkung {'a': 'b'}、{"a": "b"} {"a": "b"}
Kunci tanpa petikan {name: 'Ada'} {"name": "Ada"}
Komen {"a": 1 /* nota */} {"a": 1}
Literal Python {"ok": True, "v": None} {"ok": true, "v": null}
Pagar markdown ```json {...} ``` {...}
Koma hilang [1 2] [1, 2]
Kurungan / petikan tak tertutup {"a": [1, 2 {"a": [1, 2]}
JSONP / gabungan rentetan cb({...})、"x" + "y" {...}、"xy"

Persamaan sembilan kelas ini: data semuanya ada; rosak hanya sintaks. Alat pembaiki menyelaraskan tanda baca dan pembalut tanpa menyentuh satu nilai pun. Beberapa butiran layak diingat berasingan:

  • Nombor dengan sifar pendulu menjadi rentetan. 007 dibaiki menjadi "007", bukan 7, supaya digit tidak hilang. Jika medan memang kod teks, itu betul; kalau ia nombor sebenar, keputusan di tangan anda.
  • Perkataan bogel menjadi rentetan. NaN tidak boleh dibaiki menjadi nombor — sesetengah pelaksanaan mengeluarkan "NaN", yang lain null. Kelakuan berbeza antara pustaka; uji milik anda sebelum menyambungnya ke pipeline.
  • Input sah dilalui tanpa diubah. Setiap alat pembaiki serius mula-mula menjalankan laluan pantas parse ketat. JSON sah tidak pernah masuk logik pembaikan, jadi "membaiki dokumen baik menjadi buruk" adalah mustahil.

Tiga: empat perkara yang alat pembaiki tidak baiki

Sempadan di seberang sama jelasnya. Jangan harap pembaikan untuk:

  1. Halaman ralat HTML atau prosa tulen. Tiada struktur JSON dalam input, dan tiada alat boleh mencipta data dari tiada.
  2. Data sah dari segi sintaks tetapi salah. Kunci tersalah eja, nilai di tempat salah, nombor disimpan sebagai rentetan — ini masalah semantik yang setiap parser, alat pembaiki termasuk, membiarkan lalu tanpa bantahan.
  3. Data hilang kerana terpotong. Pelengkap boleh menukar {"items": [{"id": 1}, {"na menjadi JSON sah, tetapi nilai medan name tidak akan kembali selamanya. Anda menerima objek "sah tetapi tidak lengkap". Dalam produksi, periksa stopReason === "max_tokens" sebelum memutuskan: melengkapkan atau mencuba semula.
  4. Kunci pendua dan struktur kabur. Antara dua kunci serupa, yang mana menang bergantung pada pelaksanaan parser. Alat pembaiki yang bertanggungjawab menawarkan mod strict yang membaling ralat, bukan memilih satu secara senyap.

Sempadan kepercayaan dalam satu ayat: pembaikan ialah tekaan terbaik, bukan jaminan kebetulan. Membiarkan hasil pembaikan yang belum disahkan terus ke hilir bermakna menukar ralat sintaks yang bising dengan ralat data yang senyap.

Empat: dua aliran pelaksanaan — satu URL menamatkan perdebatan

Alat pembaiki di pasaran datang dalam dua ragam, dan jurang muncul pada jenis input yang sangat khusus.

Aliran penggantian regex mengguna cari-dan-ganti global pada corak rosak. Pertimbangkan input ini:

{"url": "http://example.com", 'note': 'fine'}

Regex yang menukar petikan tunggal kepada berganda akan mentekak kandungan URL juga; regex pembersih komen yang memadam setiap // akan memotong http:// separuh. Di dalam rentetan dan di luar struktur, aksara kelihatan serupa — regex tidak mampu membezakannya.

Aliran mesin keadaan aksara demi aksara menjejak keadaan parse: di dalam rentetan petik berganda, petik tunggal, di dalam komen baris, komen blok, atau menunggu nilai. Apabila melihat ', ia bertanya dahulu "adakah saya dalam rentetan?" sebelum memutuskan sama ada menukar petikan atau melangkau. http://example.com berada dalam rentetan petik berganda, maka mesin keadaan tahu // di situ adalah data, bukan komen, dan mengekalkannya. jsonrepair dan json-healer termasuk aliran ini, dan mantra komuniti "alat pembaiki bukan cari-dan-ganti" merujuk tepat kepada perkara ini.

Susunan lengkap saluran pembaikan (seperti didedahkan pelaksanaan devkits) juga berbaloi dilihat: menanggalkan pagar → menormal petik melengkung → mengekstrak blok berimbang pertama → menyingkir komen → membalut kunci bogel dengan petikan → menyingkir koma penghujung → menukar literal → akhirnya menyerialis semula melalui JSON.stringify. Serialis semula akhir itulah langkah kunci: apa pun yang dilakukan peringkat awal, output dijana semula daripada hasil parse, jadi parser ketat mana-mana di hilir mampu menelannya.

Lima: menyambung dalam kod — rantaian parse berurutan

Apabila menyambung pembaikan dalam kod, susunan lebih penting daripada pilihan pustaka. Mengikut corak yang diterbitkan json2toon dan aijsonmedic, urutannya patut: semakan terpotong → pengekstrakan julat JSON → parse ketat → pembaikan sebagai sandaran → pengesahan skema.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Membaiki output terpotong tetap kekurangan data — cuba semula
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Ekstrak julat JSON: LLM mungkin berbual di hadapan 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);   // laluan pantas untuk input sah
  } catch {
    return JSON.parse(jsonrepair(candidate));  // pembaikan sebagai sandaran
  }
}

Di sisi Python, pakej json-repair (melebihi 4,700 bintang) menyediakan loads() yang memulangkan objek terus:

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 butiran kejuruteraan lagi:

  • Selaraskan stack. Jika frontend dan backend kedua-duanya membaiki, pilih pelaksanaan 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 kes yang sama. Kalau tidak, output yang sama dibaiki menjadi A di klien dan B di pelayan, dan penyahpepijatan menjadi mimpi ngeri.
  • Hidupkan log pembaikan. @yarmu/json-repair dengan logging: true memulangkan tatasusunan setiap operasi pembaikan. Lompatan mendadak kadar pembaikan biasanya bermakna prompt atau versi model telah berubah — isyarat lebih awal daripada sebarang laporan ralat.

Satu langkah selepas pembaikan tidak boleh dirunding: pengesahan skema. Sah dari segi sintaks tidak bermakna boleh guna. Medan hilang, jenis salah, kunci tak dijangka — semuanya ditangkap skema. Pendekatan pengujian kontrak digunakan terus di sini; lihat panduan pengujian kontrak JSON Schema kami.

Enam: senarai semak pencegahan — pembaikan termurah ialah yang tidak diperlukan

Pembaikan ialah jaring keselamatan. Kemenangan sebenar ialah kurang JSON rosak di punca, mengikut urutan keutamaan:

  1. Structured Outputs (mod json_schema). Penyahkodan dikekang skema, jadi koma penghujung langsung tidak boleh dijana. Mod strict OpenAI gagal sekitar 0.1% — harga tuntutan keras seperti additionalProperties: false.
  2. Mod JSON (json_object). Menjamin kesahan sintaks sahaja — bukan bentuk — dan terpotong kerana had token masih berlaku.
  3. Arahan eksplisit. Pada endpoint tanpa mod JSON, formulasi "tiada pagar, tiada komen, tiada koma penghujung, keluarkan objek sahaja" menurunkan kadar ralat 70–80%.
  4. Turunkan temperature, naikkan had token. Yang pertama mengurangkan hanyut ke prosa; yang kedua mengurangkan terpotong.
  5. Cuba semula dengan ralat dilampirkan. Apabila pengesahan gagal, tambahkan output rosak plus "laluan JSON + mesej ralat" ke perbualan dan minta semula. Dengan ralat yang tepat, model biasanya memperbetulkan diri.

Dalam amalan, penyusunan bertingkat "structured outputs + pembaikan sandaran + pengesahan skema" menampung hampir setiap senario.

Tujuh: pembahagian kerja — penukaran dialek bukanlah pembaikan

Dalam kotak alat laman ini ada dua destinasi yang menampung segmen berbeza saluran ini:

  • Masalah dialek (komen, petikan tunggal, koma penghujung) terus ke penukar JSON5. Penukaran JSON5 ↔ JSON standard menampung tepat tiga kelas ini, dengan semantik jelas, tanpa meneka. Jika keseluruhan input ialah fail JSONC/JSON5, penukaran lebih mudah diramal daripada pembaikan. Tentang trade-off dialek itu sendiri, lihat panduan JSON5 dan JSONC.
  • Selepas pembaikan, hantar hasil melalui alat parse JSON untuk disahkan dan diformat — ralat dikesan ke baris dan lajur, mengesahkan parser ketat benar-benar menerima output.
  • Masalah kelas pustaka (literal Python, pelengkap terpotong, balutan JSONP, pagar markdown) masih memerlukan jsonrepair / json-repair di sisi kod — pembaikan satu klik yang setara dalam pelayar belum ada, kerana pembaikan ini melibatkan kesimpulan niat, dan pustaka tempatan lebih rumah selamat untuknya daripada penukar sejagat.

Jika yang di tangan anda mesej ralat, bukan data rosak, mulakan dengan panduan pembetulan ralat parse JSON untuk menterjemah mesej ke koordinat, baru putuskan: sunting tangan atau membaiki.

Soalan Lazim

Adakah pemulihan JSON merosakkan data saya?

Untuk sembilan kelas boleh baiki, hanya tanda baca dan pembalut berubah — nilai kekal tak tersentuh, dan //, koma serta kurungan di dalam rentetan dikekalkan mesin keadaan. Tetapi pelengkap terpotong menghasilkan objek tidak lengkap, nombor sifar pendulu menjadi rentetan, dan layanan NaN berbeza antara pustaka. Pemeriksaan medan utama selepas pembaikan adalah wajib.

Apakah hubungan pembaikan dan pengesahan?

Pengesahan memberitahu di mana input tidak sah; pembaikan menghulurkan dokumen yang sah. Aliran kerja boleh dipercayai membuat keduanya: membaiki dahulu, kemudian mengesahkan — skema menangkap jenis dan medan wajib, semakan sintaks mengesahkan parser ketat menerima hasil. Membaiki tanpa mengesahkan bermakna menukar ralat sintaks yang bising dengan ralat data yang senyap.

Output LLM sentiasa dibalut pagar ```json — apa nak buat?

Jangka pendek: ekstrak. Ambil teks daripada { atau [ pertama hingga } atau ] terakhir dan parse; alat pembaiki dengan penyingkiran pagar juga menelan keseluruhan mesej. Jangka panjang: guna structured outputs atau arahan eksplisit "tiada pagar markdown" supaya pagar tidak dijana langsung.

jsonrepair atau json-repair — pilih yang mana?

Untuk JavaScript guna pakej npm jsonrepair (menyokong transform strim); untuk Python json-repair dari PyPI. Jika kedua-dua hujung membaiki, pilih pasangan bersemantik selari — contohnya json-repair plus port TS-nya — supaya input sama dibaiki serupa di kedua-dua belah.

Bolehkah alat pembaiki urus Bahasa Melayu dan petik melengkung?

Boleh. Petikan tipografi dari papan kekunci Melayu (" "), ruang lebar penuh dan BOM di awal fail semuanya dalam senarai pembaikan standard; petik melengkung dinormalkan kepada petik lurus. Hantar hasil melalui pengesah sekali dan selesai.