JSON Toolkit

Mengurai JSON yang belum datang utuh: pratinjau streaming dan perbaikan bertahap

Intinya: LLM memancarkan JSON token demi token dan API mengirim respons besar potongan demi potongan, tetapi JSON.parse menolak mulai bekerja sampai dokumen lengkap tiba. Artikel ini memisahkan tiga gaya implementasi — perbaikan menyeluruh, tahapan sejati dan penguraian parsial — menjelaskan bagaimana mask Allow menjaga pratinjau tetap stabil, lengkap dengan hasil pengukuran pipeline dan kode siap produksi.

Menengah±5 menit bacaDiterbitkan 2026-11-16Diperbarui 2026-11-16
Diagram penguraian parsial dan perbaikan bertahap atas potongan JSON streaming

JSON.parse berjanji «saya mulai setelah dokumen lengkap tiba», sedangkan streaming berjanji «saya serahkan data sepotong demi sepotong». Konfliknya bukan pada kecepatan melainkan pada semantik kelengkapan: dokumen yang belum selesai ditulis belum memiliki «hasil penguraian yang benar» untuk dihitung.

Gejala: tiga skenario yang tak mampu menunggu teks penuh

Skenario pertama adalah aplikasi LLM. Model memancarkan JSON token demi token; keluaran terstruktur 8KB bisa butuh puluhan detik untuk tiba seluruhnya sementara pengguna menatap panel kosong — padahal field-field pertama sudah bisa ditampilkan sejak detik pertama. Skenario kedua adalah gateway dan proxy: upstream mendorong respons puluhan MB melalui HTTP chunk, dan proxy yang ingin menyaring field sebelum meneruskan justru melipatgandakan puncak memorinya bila menyangga semuanya dengan res.json(). Skenario ketiga adalah message queue dan pipeline log: rekaman NDJSON datang satu demi satu dan konsumen tidak mau mengumpulkan batch.

Benang merahnya jelas: data datang bertahap, sedangkan parser standar hanya menerima dokumen lengkap. JSON.parse melempar Unexpected end of JSON input pada potongan pertama, melempar error yang sama pada potongan ke-65 dan hanya mengembalikan hasil pada potongan terakhir. Menunggu bukan satu-satunya pilihan — tetapi lebih dulu Anda harus menetapkan apa artinya «mengurai» dokumen yang belum selesai.

Semantik penguraian berbasis prefiks: apakah setiap potongan valid?

Ambil satu array pesanan berukuran 7847 byte, potong menjadi potongan 120 karakter untuk mensimulasikan kedatangan streaming (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), lalu jalankan tiga parser atas setiap prefiks:

Pendekatan Keberhasilan pada 66 prefiks Waktu kumulatif Semantik
JSON.parse 1 (hanya potongan terakhir) 2,1 ms semua atau tidak sama sekali
partial-json (Allow.ALL) 66 (sejak potongan pertama) 14,3 ms selalu mengembalikan «yang diketahui sejauh ini»
jsonrepair dijalankan ulang menyeluruh pada setiap prefiks 66 23,8 ms dapat diurai setelah kurung dilengkapi, tetapi dihitung ulang dari awal setiap kali

Dua kesimpulan kunci. Pertama, kegagalan JSON.parse tidak membawa informasi apa pun: posisi kesalahan yang dilaporkan selalu di akhir, jadi Anda tidak tahu berapa yang masih kurang maupun apakah bagian yang diterima konsisten dengan dirinya sendiri. Kedua, perbaikan menyeluruh yang dijalankan ulang pada setiap prefiks bisa dilakukan tapi tidak sepadan: panjang teks rata-rata per panggilan tumbuh linear dan biaya kumulatif tumbuh kuadratik, O(n²). 23,8 ms tampak tak berbahaya; begitu teks mencapai skala megabyte, faktor yang sama berubah menjadi detik CPU terbuang.

Dan perlu diwaspadai: «dapat diurai per prefiks» tidak sama dengan «data lengkap». Angka terakhir prefiks yang kurungnya dilengkapi bisa dilanjutkan oleh potongan berikutnya, dan string terakhir bisa terpotong di tengah urutan escape — di situlah akar segala ketidakstabilan pratinjau streaming.

Tiga gaya implementasi dan pembagian tugasnya

Pustaka di sisi streaming terbagi dalam tiga sikap, dan salah memilih sikap lebih merugikan daripada salah memilih pustaka:

Pustaka Sikap Cocok untuk Tidak cocok untuk
jsonrepair (3.15.0) perbaikan menyeluruh + Transform stream Anda menerima «dokumen yang suatu saat akan lengkap» dan menginginkan hasil tanpa kehilangan sekadar pratinjau (keluarannya adalah seluruh teks yang dibetulkan, bukan objek data)
partial-json (0.1.7) penguraian parsial, membolehkan membuang ekor yang belum selesai pratinjau UI: setiap prefiks langsung punya objek yang bisa dipakai penyimpanan ke basis data (pratinjau bisa kekurangan field, angka tidak stabil)
jsonmend (0.1.3) tahapan sejati, korpus konsistensi publik pipeline bergaya «masuk sepotong, keluar satu versi» tanpa memindai ulang masa lalu dokumen yang sudah berakhir (penguraian menyeluruh lebih cepat)

Ketiganya bukan pesaing. jsonrepair mengekspor jsonrepairTransform melalui subpath ./stream, sebuah Transform stream standar: potongan dimasukkan dari kiri, di kanan keluar blok teks JSON yang telah dibetulkan, dan dijamin bila digabung akan sama dengan hasil penguraian seluruh teks sekaligus — kesetaraan decode(encode(x)) === x tetap ia jaga. partial-json menjaga garis lain: setiap prefiks langsung menghasilkan objek, dengan harga melepaskan janji «hasil akhirnya tidak berubah». jsonmend mengekang garis ketiga dengan korpus konsistensi publik: tahapan sejati, semantik bisa disandingkan, kedua implementasi memakai basis regresi yang sama.

Mask Allow: field mana yang berani ditampilkan dalam pratinjau

Inti partial-json bukanlah «mampu mengurai input rusak dengan cara apa pun», melainkan deklarasi pihak pemanggil sendiri tentang ketidaklengkapan yang bersedia ia terima. Mask dirangkai secara bit menurut tipe JSON (STR, NUM, ARR, OBJ…); lepaskan satu tipe, nilai yang belum selesai dari tipe itu tidak akan masuk pratinjau:

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        angka 12 adalah «terbaca sejauh ini»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    field yang sama telah berubah: pratinjau tidak stabil
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   tanpa bit NUM, angka yang belum selesai tidak ditampilkan

Inilah temuan paling bernilai secara rekayasa dari pengukuran: angka seperti harga dan penghitung yang bisa dilanjutkan oleh potongan berikutnya berubah di UI pada setiap frame; sedangkan Allow.ALL & ~Allow.NUM memerintahnya diam menunggu hingga selesai ditulis baru muncul. String pun demikian — string yang terpotong di tengah urutan escape Unicode dibuang dengan aman oleh partial-json 0.1.7, bukan ditebak. Kestabilan pratinjau bukan hadiah dari parser; pemanggil membelinya dengan mask.

Biaya implementasi perbaikan streaming: look-back buffer dan penyalinan kuadratik

Pipeline streaming bukan sekadar membungkus API menyeluruh dalam loop for. Pada sampel 66 potongan yang sama, pipeline dengan jsonrepairTransform memakan total 6,7ms, sedangkan perbaikan menyeluruh ulangan per prefiks berakumulasi 23,8ms — selisih 3,5 kali bersumber dari lapisan implementasi: implementasi streaming hanya menoleh ke belakang pada jendela yang perlu, keluaran ditulis bertahap dengan buffer tambahan, dan teks sebelumnya tidak disalin berulang kali.

Porting inti streaming jsonrepair ke HarmonyOS ArkTS (praktik adaptasi pustaka pihak ketiga openHarmony) mengungkap tiga biaya spesifik: jalur streaming di hulu perlu mengumpulkan «look-back buffer», sehingga untuk dokumen kecil hasilnya menunggu flush — penulisnya lalu menulis IncrementalRepairer terpisah untuk teks pendek; jalur regular di hulu menyalin keluaran seluruhnya berulang kali, sifatnya kuadratik, dan saat porting OutputBuilder menghapusnya; masih ada satu jebakan karakter batas — kondisi text[i] === undefined sebagai uji «sudah terbaca sampai akhir» ketika dipindahkan ke charAt bisa tertipu, karena ''.includes('') selalu true, sehingga pelampaian batas harus dahulu disekat dengan string kosong. Detail-detail ini menjelaskan mengapa «perbaikan streaming» berhak memiliki slot kategori sendiri: kompleksitas rekayasanya dan perbaikan sekali jalan tidak berada pada tingkat yang sama.

Patut dicatat juga batas yang sudah diketahui: issue #214 pada jsonrepair melaporkan perbaikan streaming menolak prefiks valid yang kekurangan koma sebelum nilai berlambak-slash — dalam mode streaming, pada tataran leksikal sulit membedakan «karakter berikutnya belum tiba» dengan «input tidak valid»; jendela look-back itulah harga yang dibayar untuk kekaburan ini.

Cara menggulirkannya: pratinjau dan penyimpanan berjalan di jalur terpisah

Rangkai semantik di atas menjadi satu pipeline; prinsipnya cukup dalam satu kalimat: pratinjau memakai penguraian parsial, penyimpanan memakai penguraian ketat.

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// Jalur 1: pipeline tanpa kehilangan. Masuk: potongan, keluar: teks JSON dibetulkan, diakhiri pemeriksaan ketat
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink selanjutnya melakukan JSON.parse + pemeriksaan bisnis
chunkStream.pipe(tr);

// Jalur 2: pipeline pratinjau. Setiap prefiks memberi satu frame UI; angka dan string yang belum selesai ditahan mask
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // hanya gambar field yang stabil; field yang cepat berubah biar menunggu
}

Kontrak kedua jalur berbeda dan tidak saling menggantikan: frame pratinjau boleh kekurangan field, frame penyimpanan tidak boleh; frame penyimpanan harus menunggu stream berakhir dan melewati JSON.parse penuh disertai pemeriksaan bisnis, sedangkan frame pratinjau tidak pernah tersimpan ke mana pun. Bila hulunya keluaran LLM, sebelum menyimpan perlu dinilai menurut stop_reason apakah terpotong — alur «lihat stop_reason dahulu, baru bicara perbaikan» sudah diuraikan dalam artikel perbaikan JSON terpotong dari LLM, tidak diulang di sini.

Kapan sebaiknya tidak streaming

Tiga syarat penolakan; cukup terpenuhi satu saja, gunakan penguraian menyeluruh dengan jujur: berkas kecil — JSON.parse biasa membaca hingga ~22MB sekali jalan biasanya di bawah satu detik, streaming hanya menambah kode; hanya statistik sekali jalan — agregasi lebih praktis dengan jq --stream atau NDJSON baris demi baris, lihat panduan praktis JSONL; penerima hilir tidak menerima data parsial — misalnya total uang, satu nilai antara yang tersalah kalikan dari pratinjau sudah berarti kerugian nyata; pada saat itu pratinjau streaming hanya bernilai sebagai «bilah kemajuan».

Yang diselesaikan penguraian streaming selalu adalah «tak mampu menunggu», bukan «lebih cepat». Dengan volume teks yang sama, CPU total penguraian menyeluruh selalu lebih kecil daripada segala opsi streaming; yang Anda tukar adalah waktu hingga byte pertama bisa dipakai dan tingkat memori yang tetap. Pahami pertukaran ini dengan jelas, pemilihan teknologi tidak akan goyah lagi.

Pertanyaan umum

Bisakah objek pratinjau langsung disimpan ke basis data?

Tidak bisa. Pratinjau adalah potret «yang diketahui sejauh ini»: angka bisa dilanjutkan oleh potongan berikutnya, string bisa terpotong, field bisa sementara tiada. Sebelum menyimpan harus menunggu stream berakhir, menjalankan JSON.parse ketat penuh atas keseluruhan teks, lalu melewati pemeriksaan bisnis. Pratinjau hanya milik lapisan UI.

partial-json atau jsonrepair?

Tergantung Anda menginginkan teks atau objek. Teks dibetulkan tanpa kehilangan (untuk diurai lanjut di hilir) — pakai jsonrepair, keluaran streamingnya dijamin cocok dengan penguraian keseluruhan; objek per prefiks untuk ditampilkan langsung di UI — pakai partial-json, dengan mask Allow disetel menurut ketidakstabilan yang sanggup Anda pikul.

Apakah penguraian streaming memangkas total waktu?

Tidak. CPU total penguraian menyeluruh selalu paling kecil, dan opsi streaming masih membayar biaya pemeliharaan status. Streaming menukar tiga hal: waktu hingga potongan pertama bisa dipakai, memori yang tidak tumbuh mengikuti panjang keseluruhan, dan kemampuan memproses saat masih menerima (meneruskan, menyaring, menampilkan).

Elemen array datang satu per satu dan saya ingin memprosesnya satu per satu, bagaimana?

Itu jalur lain: stream-json dengan streamArray melempar {key, value} tepat saat elemen tertutup, dan dengan for await membentuk backpressure secara alami — cocok untuk impor besar bergaya «urai lalu tulis», sedangkan artikel ini membahas pratinjau pada skala seluruh dokumen.

Referensi

Alat yang sesuai

Artikel terkait

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

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.

Menengah±6 menit bacaDiperbarui 2026-11-08

JSON dari LLM terpotong: lihat alasan berhentinya dulu, baru bicara perbaikan

Model mengembalikan JSON yang putus di tengah nilai dan parser hanya memberi nomor kolom. Menutup kurung membuatnya bisa di-parse lagi, tetapi setiap field yang hilang kini tersembunyi di dalam data. Artikel ini menetapkan batas antara apa yang bisa dipulihkan perbaikan pemotongan secara jujur dan apa yang harus diminta ulang.

Praktis±5 menit bacaDiperbarui 2026-11-14

JSONL dalam praktik: membuka, mengonversi, dan memperbaiki baris rusak

Memberikan seluruh file .jsonl ke JSON.parse lalu menerima error hampir tidak pernah berarti file rusak — artinya strategi membaca yang salah. Panduan ini mencakup cara standar memeriksa dan membaca JSONL baris demi baris, perintah konversi dua arah dengan array JSON, tabel enam jenis baris rusak, dan cara benar mengonsumsi NDJSON dari respons HTTP streaming.

Menengah±9 menit bacaDiperbarui 2026-11-06