تحليل JSON الذي لم يصل كاملًا بعد: معاينة البث والإصلاح التدريجي
الخلاصة: نماذج LLM تُخرج JSON رمزًا فورًا، وواجهات API تعيد الاستجابات الكبيرة قطعة فقطعة، لكن JSON.parse يرفض العمل حتى يصل المستند كاملًا. يفصل هذا المقال ثلاثة أنماط من التنفيذ — الإصلاح الكامل، التزايد الحقيقي، والتحليل الجزئي — ويوضح كيف تحافظ قناع Allow على ثبات المعاينة، مع قياسات خط الأنابيب وكود جاهز للإنتاج.

عهد
JSON.parseهو «لن أبدأ حتى يصل المستند كاملًا»، وعهد البث هو «أسلّم البيانات قطعة فقطعة» — التناقض ليس في السرعة بل في دلالات الاكتمال: المستند الذي لم يكتمل كتابته ليس له أصلاً «نتيجة تحليل صحيحة» تُحاسب عليه.
العَرَض: ثلاثة سيناريوهات لا تحتمل انتظار النص الكامل
السيناريو الأول تطبيقات LLM. يُخرج النموذج JSON رمزًا فورًا؛ مخرَج مهيكل بحجم 8KB قد يستغرق عشرات الثواني ليكتمل بينما يحدّق المستخدم في لوحة فارغة — مع أن الحقول الأولى كانت قابلة للعرض منذ الثانية الأولى. السيناريو الثاني هو البوابات والبروكسيات: يدفع المُرسل الأعلى استجابة بحجم عشرات الميغابايتات على شكل أجزاء HTTP، والبروكسي الذي يريد تصفية الحقول قبل إعادة الإرسال يضاعف ذروة ذاكرته إذا خزّن كل شيء عبر res.json(). السيناريو الثالث هو طوابير الرسائل وأنابيب السجلات: سجلات NDJSON تصل واحدًا وراء الآخر، والمستهلك لا يريد تجميع دفعات.
القاسم المشترك واضح: البيانات تصل تدريجيًا بينما المحلل القياسي لا يقبل إلا مستندًا كاملًا. يرمي JSON.parse الخطأ Unexpected end of JSON input منذ القطعة الأولى، ويرمي الخطأ نفسه عند القطعة 65، ولا يعيد نتيجة إلا في القطعة الأخيرة. الانتظار ليس الخيار الوحيد — لكن عليك أولًا أن تحدد ماذا يعني «تحليل» مستندًا غير مكتمل.
دلالات التحليل حسب البادئات: هل كل جزء صالح؟
خذ مصفوفة طلبات بحجم 7847 بايت، قسّمها إلى أجزاء من 120 محرفًا لمحاكاة الوصول المتدفق (Node v22.13.1، jsonrepair 3.15.0، partial-json 0.1.7)، وشغّل ثلاثة محللات على كل بادئة:
| النهج | النجاحات على 66 بادئة | الوقت التراكمي | الدلالة |
|---|---|---|---|
JSON.parse |
1 (الجزء الأخير فقط) | 2.1 ms | الكل أو لا شيء |
partial-json (Allow.ALL) |
66 (منذ الجزء الأول) | 14.3 ms | يعطي دائمًا «المعروف حتى الآن» |
jsonrepair مع إعادة تشغيل الإصلاح الكامل لكل بادئة |
66 | 23.8 ms | قابل للتحليل بعد إكمال الأقواس، لكن يُحسب من الصفر في كل مرة |
خلاصتان حاسمتان. الأولى: فشل JSON.parse لا يحمل أي معلومة — الموضع المُبلَّغ عنه دائمًا في النهاية، فلا تعرف كم بقي ولا تعرف حتى إن كان الجزء المستلم متناسقًا مع نفسه. الثانية: إعادة تشغيل الإصلاح الكامل عند كل بادئة ممكنة لكنها لا تُجدي: متوسط طول النص في كل استدعاء ينمو خطيًا، والتكلفة التراكمية تنمو تربيعيًا O(n²). تبدو 23.8 ms بريئة؛ حين يبلغ النص حجم الميغابايتات يتحول المضاعف نفسه إلى ثوانٍ معالجة ضائعة.
وانتبه أيضًا: «قابل للتحليل حسب البادئات» لا يعني «البيانات مكتملة». آخر رقم في بادئة مكتملة الأقواس قد يكمله الجزء التالي، وآخر سلسلة قد تُقطع في منتصف تسلسل إفلات — هنا يكمن جذر كل عدم استقرار في معاينة البث.
ثلاثة أنماط تنفيذ وتقسيم أدوارها
تنقسم مكتبات جانب البث إلى ثلاثة مواقف، واختيار الموقف الخطأ أضرّ من اختيار المكتبة الخطأ:
| المكتبة | الموقف | مناسب | غير مناسب |
|---|---|---|---|
jsonrepair (3.15.0) |
إصلاح كامل + Transform stream | يصلك «مستند سيكتمل لاحقًا» وتريد نتيجة بلا خسارة | مجرد المعاينة (المخرَج نص كامل مُصلَّح، وليس كائن بيانات) |
partial-json (0.1.7) |
تحليل جزئي، يسمح بإسقاط الذيل غير المكتمل | معاينة الواجهة: كل بادئة تعطي فورًا كائنًا صالحًا للاستخدام | الحفظ في قاعدة البيانات (المعاينة قد تنقصها حقول، والأرقام غير مستقرة) |
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، لا يُعرض الرقم غير المكتمل
هذه أثمن ملاحظة هندسية في القياس: أرقام مثل السعر والعدّاد قد يكملها الجزء التالي، فتتغير في الواجهة مع كل إطار؛ بينما يأمرها Allow.ALL & ~Allow.NUM بأن تنتظر بصمت حتى تكتمل ثم تظهر. وسلاسل الحروف كذلك — السلسلة المقطوعة في منتصف تسلسل إفلات يونيكود يلغيها partial-json 0.1.7 بأمان بدل التخمين. ثبات المعاينة ليس هدية من المحلل؛ المستدعي يشتريه بالقناع.
كلفة تنفيذ الإصلاح المتدفق: مخزن الرجوع والنسخ التربيعي
خط أنابيب البث ليس مجرد لفّ الواجهة الكاملة في حلقة for. على العينة ذاتها من 66 جزءًا، أخذ خط الأنابيب بـ jsonrepairTransform مجموعًا 6.7ms، بينما إعادة تشغيل الإصلاح الكامل لكل بادئة تراكمت 23.8ms — فارق الـ 3.5 مرة يأتي من طبقة التنفيذ: التنفيذ المتدفق لا يلتفت إلى الخلف إلا في النافذة الضرورية، ويكتب المخرَج بمخزن تدريجي، ولا يعيد نسخ النص السابق مرارًا.
كشف نقل نواة البث في jsonrepair إلى HarmonyOS ArkTS (تجربة تكييف مكتبات الأطراف الثالثة في openHarmony) ثلاث كلف محددة: مسار streaming في المصدر يحتاج جمع «مخزن الرجوع»، فنتيجة المستندات الصغيرة تنتظر حتى flush — فكتب المؤلف IncrementalRepairer منفصلًا للنصوص القصيرة؛ ومسار regular في المصدر ينسخ المخرَج كاملًا مرارًا وهو ذو طبيعة تربيعية، فأزاله OutputBuilder عند النقل؛ وما يزال هناك فخ محرف الحد — شرط text[i] === undefined كاختبار «قرأت حتى النهاية» يُخدع حين يُحوَّل إلى charAt، لأن ''.includes('') صائبة دائمًا، فلا بد من سد تجاوز الحد بسلسلة فارغة أولًا. هذه التفاصيل تفسّر لماذا يستحق «الإصلاح المتدفق» خانة تصنيف مستقلة: تعقيده الهندسي والإصلاح لمرة واحدة ليسا في مستوى واحد.
يستحق الحد المعروف ذكرًا أيضًا: يبلّغ الإصدار 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);
// المسار ٢: خط أنابيب المعاينة. كل بادئة تعطي إطار واجهة؛ الأرقام والسلاسل غير المكتملة تحجزها القناع
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؛ المستهلك اللاحق لا يقبل بيانات جزئية — مثل مجموع المبالغ، قيمة وسيطة واحدة مضروبة خطأً من المعاينة تعني خسارة حقيقية؛ عندها لا تظل للمعاينة المتدفقة قيمة سوى «شريط التقدم».
ما يحله التحليل المتدفق دائمًا هو «لا يمكن الانتظار»، لا «أسرع». وبحجم النص نفسه، زمن المعالجة الكلية للتحليل الكامل أقل دائمًا من أي خيار متدفق؛ ما تستبدله هو زمن الوصول إلى أول بايت قابل للاستخدام ومستوى ذاكرة ثابت. افهم هذه المقايضة بوضوح، فلن يتذبذب اختيارك للتقنية.
الأسئلة الشائعة
هل يمكن حفظ كائن المعاينة في قاعدة البيانات مباشرة؟
لا. المعاينة لقطة من «المعروف حتى الآن»: الرقم قد يكمله الجزء التالي، والسلسلة قد تكون مقطوعة، والحقول قد تكون غائبة مؤقتًا. قبل الحفظ لا بد من انتظار انتهاء البث وتشغيل JSON.parse صارم كامل على النص كله ثم اجتياز تحقق منطق العمل. المعاينة مخصصة لطبقة الواجهة وحدها.
partial-json أم jsonrepair؟
بحسب ما تريد: نصًا أم كائنًا. نص مُصلَّح بلا خسارة (ترسله لاحقًا للتحليل) فـ jsonrepair — مخرَجه المتدفق مضمون التطابق مع تحليل الكل؛ كائنًا لكل بادئة لعرضه فورًا في الواجهة فـ partial-json، مع ضبط قناع Allow وفق مقدار عدم الاستقرار الذي تحتمله.
هل يقلل التحليل المتدفق الزمن الكلي؟
لا. زمن المعالجة الكلي للتحليل الكامل هو الأقل دائمًا، والخيار المتدفق يدفع كلفة إضافية لإدارة الحالة. البث يستبدل ثلاثة أمور: الزمن حتى أول جزء قابل للاستخدام، ذاكرة لا تنمو بطول الكل، والقدرة على المعالجة أثناء الاستقبال (إعادة إرسال، تصفية، عرض).
عناصر المصفوفة تصل واحدًا واحدًا وأريد معالجتها واحدًا واحدًا، ماذا أفعل؟
ذاك طريق آخر: يرمي stream-json مع streamArray القيمة {key, value} فور إغلاق العنصر، ومع for await يتشكل ضغط ارتدادي طبيعي — مناسب للاستيراد الكبير بنمط «حلّل ثم اكتب»، بينما يتحدث هذا المقال عن المعاينة على مستوى المستند كله.