تجزیه JSONی که هنوز کامل نرسیده: پیشنمایش استریمی و ترمیم افزایشی
جمعبندی: مدلهای LLM خروجی JSON را توکنبهتوکن میفرستند و APIها پاسخهای بزرگ را قطعهقطعه میدهند، اما JSON.parse تا وقتی کل سند نرسیده حاضر به کار نیست. این مقاله سه سبک پیادهسازی را جدا میکند — ترمیم کامل، افزایشی واقعی و تجزیه جزئی — و نشان میدهد ماسک Allow چگونه پیشنمایش را پایدار نگه میدارد، همراه با دادههای اندازهگیری پایپلاین و کد آمادهٔ production.

عهدِ
JSON.parseاین است که «تا سند کامل نرسیده شروع نمیکنم»، و عهدِ استریم این است که «داده را قطعهبهقطعه تحویل میدهم» — تعارض این دو در سرعت نیست، در معناشناسی کامل بودن است: سندی که هنوز نوشته نشده اصلاً «نتیجهٔ تجزیهٔ درست» ندارد.
نشانه: سه سناریو که منتظر تمام متن نمیمانند
سناریوی نخست کاربردهای LLM است. مدل خروجی JSON را توکنبهتوکن میفرستد؛ یک خروجی ساختیافتهٔ ۸ کیلوبایتی ممکن است دهها ثانیه طول بکشد تا برسد، در حالی که کاربر به پنل خالی خیره است — در حالی که فیلدهای نخست از همان ثانیهٔ اول قابل نمایش بودند. سناریوی دوم دروازهها و پروکسیها هستند: upstream پاسخی چند ده مگابایتی را بهصورت chunkهای HTTP میفشارند و پروکسیای که میخواهد قبل از ارسال مجدد فیلدها را فیلتر کند، اگر همهچیز را با res.json() بافر کند اوج مصرف حافظهاش چند برابر میشود. سناریوی سوم صفهای پیام و پایپلاین لاگ هستند: رکوردهای NDJSON پشتسرهم میرسند و مصرفکننده نمیخواهد دسته جمع کند.
وجه مشترک روشن است: دادهها تدریجی میرسند، اما تجزیهگر استاندارد فقط سند کامل را میپذیرد. JSON.parse از قطعهٔ اول Unexpected end of JSON input میپراند، در قطعهٔ ۶۵ هم همان خطا را میپراند و فقط در قطعهٔ آخر نتیجه میدهد. منتظر ماندن تنها گزینه نیست — اما نخست باید تعیین کنید «تجزیهٔ» یک سند ناتمام یعنی چه.
معناشناسی پایهای تجزیه بر اساس پیشوند: هر قطعه معتبر است یا نه؟
یک آرایهٔ سفارش ۷۸۴۷ بایتی را بردارید، آن را به قطعههای ۱۲۰ نویسهای برش بزنید تا رسیدن استریمی شبیهسازی شود (Node v22.13.1، jsonrepair 3.15.0، partial-json 0.1.7)، و هر پیشوند را از سه تجزیهگر عبور دهید:
| رویکرد | موفقیت روی ۶۶ پیشوند | زمان انباشته | معنا |
|---|---|---|---|
JSON.parse |
۱ (فقط قطعهٔ آخر) | 2.1 ms | همه یا هیچ |
partial-json (Allow.ALL) |
66 (از قطعهٔ اول) | 14.3 ms | همیشه «تا اینجا شناختهشده» را میدهد |
jsonrepair با اجرای مجدد کامل روی هر پیشوند |
66 | 23.8 ms | پس از تکمیل پرانتز قابل تجزیه، اما هر بار از صفر محاسبه |
دو نتیجهگیری کلیدی. نخست، شکست JSON.parse هیچ اطلاعاتی حمل نمیکند: موقعیت گزارششدهٔ خطا همیشه انتهاست، نه میدانید چقدر کم مانده و نه میدانید بخش دریافتی با خودش سازگار است یا نه. دوم، اجرای مجدد ترمیم کامل روی هر پیشوند ممکن است اما نمیارزد: طول متوسط متن در هر فراخوانی خطی رشد میکند و هزینهٔ انباشته بهصورت O(n²) بالا میرود. ۲۳٫۸ میلیثانیه بیآزار به نظر میرسد؛ وقتی متن به مقیاس مگابایت برسد همان ضریب به ثانیههای هدررفتهٔ CPU تبدیل میشود.
و یک هشدار دیگر: «قابل تجزیه بودن بر اساس پیشوند» به معنای «دادهٔ کامل» نیست. آخرین عدد پیشوند تکمیلشده ممکن است توسط قطعهٔ بعدی ادامه یابد، و آخرین رشته ممکن است وسط یک دنبالهٔ escape بریده شود — ریشهٔ همهٔ ناپایداریهای پیشنمایش استریمی همینجاست.
سه سبک پیادهسازی و تقسیم کارشان
کتابخانههای سمت استریم در سه نگرش تقسیم میشوند، و انتخاب اشتباهِ نگرش از انتخاب اشتباه کتابخانه آسیبزا تر است:
| کتابخانه | نگرش | مناسب | نامناسب |
|---|---|---|---|
jsonrepair (3.15.0) |
ترمیم کامل + Transform stream | میگیرید «سندی که سرانجام کامل خواهد شد» و نتیجهٔ بدونافت میخواهید | فقط پیشنمایش (خروجی، متن کاملِ ترمیمشده است نه شیء داده) |
partial-json (0.1.7) |
تجزیه جزئی، اجازهٔ دور انداختن دمِ ناتمام | پیشنمایش UI: هر پیشوند بلافاصله یک شیء قابل استفاده دارد | ذخیره در پایگاه داده (پیشنمایش ممکن است فیلد کم داشته باشد، اعداد ناپایدارند) |
jsonmend (0.1.3) |
افزایشی واقعی، پیکرهٔ سازگاری عمومی | پایپلاین به سبک «یک تکه وارد، یک نسخه بیرون» بدون اسکن مجدد گذشته | سندی که تمام شده (تجزیهٔ کامل سریعتر است) |
این سه رقیب هم نیستند. jsonrepair از زیرمسیر ./stream تابع jsonrepairTransform را صادر میکند، یک Transform stream استاندارد: قطعهها از چپ وارد میشوند، از راست بلوکهای متن JSON ترمیمشده بیرون میآیند، و تضمین میشود که چسباندنشان دقیقاً برابر با تجزیهٔ کل متن در یک نوبت است — تساوی decode(encode(x)) === x را حفظ میکند. partial-json خط دیگری را نگه میدارد: هر پیشوند فوراً شیء میدهد، به بهای کنار گذاشتن وعدهٔ «نتیجهٔ نهایی دیگر تغییر نخواهد کرد». jsonmend خط سوم را با پیکرهٔ سازگاری عمومی مهار میکند: افزایشی واقعی، معنای قابل مقایسه، هر دو پیادهسازی یک پایگاه رگرسیون مشترک دارند.
ماسک Allow: کدام فیلدها جرئت نمایش در پیشنمایش را دارند
هستهٔ partial-json «میتوانم هر ورودی خرابی را تجزیه کنم» نیست، بلکه اعلام خودِ فراخواننده است که چه اندازهای از ناتمامی را حاضر است تحمل کند. ماسک بهصورت بیتی بر اساس انواع JSON ترکیب میشود (STR، NUM، ARR، OBJ…)؛ یک نوع را حذف کنید، مقادیر ناتمام آن نوع وارد پیشنمایش نمیشوند:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } عدد 12 یعنی «تا اینجا خوانده شده»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } همان فیلد تغییر کرد: پیشنمایش ناپایدار است
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} بدون بیت NUM، عدد ناتمام نمایش داده نمیشود
این کاربردترین یافتهٔ مهندسی اندازهگیری است: اعدادی مثل قیمت و شمارنده که ممکن است قطعهٔ بعدی ادامهشان دهد، در UI با هر فریم تغییر میکنند؛ اما Allow.ALL & ~Allow.NUM فرمان میدهد تا وقتی کامل نشدهاند بیصدا صبر کنند. رشتهها هم همینطور — رشتهای که وسط دنبالهٔ escape یونیکد بریده، partial-json 0.1.7 آن را ایمن دور میاندازد، بهجای حدس زدن. پایداری پیشنمایش هدیهٔ تجزیهگر نیست؛ فراخواننده با ماسک آن را میخرد.
هزینهٔ پیادهسازی ترمیم استریمی: بافر نگاه به عقب و کپی درجهٔ دو
پایپلاین استریمی یعنی پیچیدن API کامل در یک حلقه for نیست. روی همان نمونهٔ ۶۶ قطعهای، پایپلاین با jsonrepairTransform در مجموع 6.7ms برد، در حالی که اجرای مجدد ترمیم کامل روی هر پیشوند بهصورت انباشته 23.8ms برد — اختلاف ۳٫۵ برابری از لایهٔ پیادهسازی میآید: پیادهسازی استریمی فقط در پنجرهٔ لازم به عقب نگاه میکند، خروجی را با بافر افزایشی ضمیمه میکند و متن قبلی را بارها و بارها کپی نمیکند.
پورت هستهٔ استریم jsonrepair به HarmonyOS ArkTS (تجربهٔ تطبیق کتابخانههای third-party در openHarmony) سه هزینهٔ مشخص را آشکار کرد: مسیر streaming در بالادست باید «بافر نگاه به عقب» جمع کند، پس برای اسناد کوچک نتیجه تا flush منتظر میماند — نویسنده به همین سبب برای متنهای کوتاه IncrementalRepairer جداگانهای نوشت؛ مسیر regular بالادست خروجی را بهطور کامل بارها کپی میکند که ماهیت درجهٔ دو دارد و در پورت، OutputBuilder آن را حذف کرد؛ و هنوز یک تلهٔ نویسهٔ مرزی باقی است — شرط text[i] === undefined بهعنوان آزمون «به پایان خواندم» وقتی به charAt منتقل شود فریب میخورد، چون ''.includes('') همیشه true است، پس عبور از مرز باید نخست با رشتهٔ خالی سد شود. همین جزئیات توضیح میدهند چرا «ترمیم استریمی» شایستهٔ جایگاه دستهٔ مستقل است: پیچیدگی مهندسی آن و ترمیم یکباره در یک مرتبه نیستند.
مرز شناختهشده را هم باید یادداشت کرد: issue #214 در jsonrepair گزارش میدهد که ترمیم استریمی پیشوند معتبری را که پیش از مقدار با پیشوند اسلش، کامای کم دارد، رد میکند — در حالت استریم در سطح واژگانی تشخیص «نویسهٔ بعدی هنوز نرسیده» از «ورودی نامعتبر است» دشوار است؛ پنجرهٔ نگاه به عقب همان بهایی است که برای این ابهام پرداخت میشود.
چگونه پیاده کنیم: پیشنمایش و ذخیرهسازی جدا میروند
معناشناسی بالا را در یک پایپلاین ترکیب کنید؛ اصل در یک جمله جا میشود: پیشنمایش با تجزیهٔ جزئی، ذخیرهسازی با تجزیهٔ سختگیرانه.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// مسیر ۱: پایپلاین بدونافت. وارد: قطعهها، خارج: متن JSON ترمیمشده، در پایان اعتبارسنجی سختگیرانه
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink سپس JSON.parse + اعتبارسنجی کسبوکار میکند
chunkStream.pipe(tr);
// مسیر ۲: پایپلاین پیشنمایش. هر پیشوند یک فریم UI میدهد؛ اعداد و رشتههای ناتمام را ماسک نگه میدارد
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // فقط فیلدهای پایدار را بکش؛ فیلدهای دگرگونشونده صبر کنند
}
قرارداد دو مسیر متفاوت است و یکدیگر را جایگزین نمیکنند: فریم پیشنمایش میتواند فیلد کم داشته باشد، فریم ذخیرهسازی نمیتواند؛ فریم ذخیرهسازی باید منتظر پایان استریم بماند و از یک JSON.parse کامل بههمراه اعتبارسنجی کسبوکار عبور کند، در حالی که فریم پیشنمایش هرگز جایی ذخیره نمیشود. اگر بالادست خروجی LLM است، پیش از ذخیره باید بر اساس stop_reason قضاوت شود که آیا بریده شده یا نه — جریانِ «اول stop_reason ببین، بعد از ترمیم حرف بزن» در مقالهٔ ترمیم JSON بریدهشده از LLM گسترش یافته، اینجا تکرارش نمیکنیم.
کی استریم نکنیم
سه شرط وتو؛ فقط یکی کافی است و صادقانه تجزیهٔ کامل را به کار ببرید: فایل کوچک — JSON.parse معمولی تا ~22MB را در یک نوبت معمولاً زیر یک ثانیه میخواند، استریم فقط کد اضافه میکند؛ فقط آمار یکباره — تجمیع با jq --stream یا NDJSON خطبهخط سادهتر است، ببینید راهنمای عملی JSONL؛ مصرفکنندهٔ پاییندست دادهٔ جزئی نمیپذیرد — مثلاً جمع پول، یک مقدار میانی که از پیشنمایش اشتباه ضرب شود همان زیان واقعی است؛ در آن لحظه پیشنمایش استریمی فقط ارزش «نوار پیشرفت» دارد.
مسئلهای که تجزیهٔ استریمی حل میکند همیشه «نمیتوان منتظر ماند» است، نه «سریعتر». با حجم متن برابر، CPU کل تجزیهٔ کامل همیشه از هر گزینهٔ استریمی کمتر است؛ آنچه عوض میکنید زمانِ رسیدن به نخستین بایت قابل استفاده و سطح حافظهٔ ثابت است. این معامله را شفاف بفهمید، انتخاب فناوری دیگر تکان نمیخورد.
پرسشهای پرتکرار
شیء پیشنمایش را میتوان مستقیماً در پایگاه داده ذخیره کرد؟
نمیتوان. پیشنمایش عکسِ «تا اینجا شناختهشده» است: عدد ممکن است قطعهٔ بعدی ادامهاش دهد، رشته ممکن است بریده باشد، فیلد ممکن است موقتاً غایب باشد. پیش از ذخیره باید تا پایان استریم منتظر ماند، یک نوبت JSON.parse سختگیرانهٔ کامل روی کل متن اجرا کرد و سپس اعتبارسنجی کسبوکار را پشت سر گذاشت. پیشنمایش فقط متعلق به لایهٔ UI است.
partial-json یا jsonrepair؟
بسته به اینکه متن میخواهید یا شیء. متنِ ترمیمشدهٔ بدونافت (برای ارسال به پاییندست برای تجزیه) از jsonrepair — خروجی استریمش با تجزیهٔ کل تضمینِ برابری دارد؛ شیء برای هر پیشوند برای نمایش فوری در UI از partial-json، و ماسک Allow را بر اساس ناپایداریای که تحمل میکنید تنظیم کنید.
آیا تجزیهٔ استریمی زمان کل را کاهش میدهد؟
نه. CPU کل تجزیهٔ کامل همیشه کمترین است، و گزینهٔ استریمی هزینهٔ نگهداری وضعیت را هم اضافه میکند. استریم سه چیز را عوض میکند: زمان تا نخستین قطعهٔ قابل استفاده، حافظهای که با طول کل رشد نمیکند، و توانایی پردازش در حین دریافت (ارسال مجدد، فیلتر، نمایش).
عناصر آرایه یکییکی میرسند و میخواهم یکییکی پردازششان کنم، چه کنم؟
آن مسیر دیگری است: stream-json با streamArray دقیقاً هنگام بسته شدن عنصر {key, value} میپراند، و با for await backpressure طبیعی میسازد — برای درونریزی انبوه به سبک «تجزیه کن و بنویس» مناسب است؛ این مقاله از پیشنمایش در مقیاس کل سند سخن میگوید.