JSON من نموذج لغوي مقطوع في المنتصف: اقرأ سبب التوقف أولاً ثم تحدث عن الإصلاح
الخلاصة: يعيد النموذج JSON مقطوعاً في وسط قيمة، والمحلل لا يعطيك إلا رقم عمود. إغلاق الأقواس يعيده قابلاً للتحليل، لكن كل حقل مفقود أصبح الآن مخفياً داخل البيانات. يضع هذا المقال حداً بين ما يستطيع إصلاح القطع استعادته بأمانة وما يجب طلبه من جديد.

القطع ليس خطأً نحوياً، بل بيانات مفقودة. النحو يمكن إصلاحه، أما القطع فلا يُستعاد إلا جزئياً. في اللحظة التي يسدّ فيها الأداة الفجوة، تكفّ الفجوة المتبقية عن كونها خطأ تحليل وتصبح شيئاً لا يعرفه أحد.
شكل القطع: رقم عمود واحد لا يكفي
يكتب النموذج JSON وفق مخططك، يصطدم بسقف المخرجات، فيتوقف النص. أعطِ هذا لوحدة json في بايثون 3.11:
{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"
يرمي json.loads الخطأ Expecting ':' delimiter, col 94. يشير العمود إلى المفتاح "qty" الذي لا قيمة له، لكن السبب الحقيقي أن المستند بلا نهاية. تفشل التعبيرات النمطية الجشعة التي تضيف "}؛ أما الإغلاق بالمكدس الواعي بالسلاسل (القسم السادس) فينجح في التحليل، لكن items يبقى بسجلين والسجل الثالث المكتوب نصفه يضيع. رقم العمود يخبرك أين توقف النص. لا يخبرك أبداً كم فُقد.
هذا هو الفرق الحقيقي الأول عن خطأ JSON العادي. الفاصلة الزائدة لها حالة نهائية واضحة: احذفها يكتمل المستند. القطع لا يملك تلك الحالة. حتى بعد الإصلاح يبقى شظية.
القطع ليس تلفاً نحوياً: النقطة العمياء لأدوات الإصلاح
أدوات مثل jsonrepair تحوّل JSON التالف نحوياً إلى JSON صالح: إزالة أسوار ماركداون، الفواصل الأخيرة، تحويل علامات الاقتباس المفردة. هناك تكون النية كاملة والإصلاح مجرد تنظيف. المدخل المقطوع يبدو للأداة نفسها كـ JSON تالف، فتغلق السلاسل والمصفوفات والكائنات المفتوحة وتعيد شيئاً قابلاً للتحليل. من 83 تقرير قطع مع Claude، "أصلحت" الأداة 79 وفشلت فشلاً صريحاً في 4 فقط. رأت المراقبة معدلاً أقل من الواقع بعشرين مرة.
كيف يبدو الناتج بعد الإصلاح؟ توقف تعليق السؤال السادس في منتصف جملة، الأسئلة 7 إلى 9 غير موجودة، ومصفوفة next_steps اختفت. ومع ذلك يمر Pydantic بالتحقق، لأن next_steps له قيمة افتراضية [] والقائمة بلا حد للطول. كل طبقة تؤدي عملها بشكل صحيح. المنتج يصدر تقريراً واثقاً لكنه خاطئ.
ضع إصلاح النحو على مسار القطع وسيتحول بهدوء من تنظيف إلى اختلاق. لذلك الحد أولاً: أداة الإصلاح تتعامل فقط مع أوساخ التنسيق في إجابة كاملة؛ الإجابة المقطوعة يجب ألا تصلها أصلاً. لأوساخ التنسيق، راجع دليل إصلاح JSON.
الخطوة الأولى دائماً هي سبب التوقف
كل واجهات API الكبرى تخبرك في البيانات الوصفية لماذا توقف التوليد، مجاناً. وهو أيضاً أكثر سطر كود يُتجاهل في تكاملات النماذج. يعرض Anthropic الحقل stop_reason، وتعرض واجهة محادثة OpenAI الحقل finish_reason: max_tokens يعني مقطوعاً، وend_turn أو stop يعني أن النموذج أنهى من نفسه.
resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
raise TruncatedOutput(
f"stop_reason={resp.stop_reason}, "
f"output_tokens={resp.usage.output_tokens}"
)
data = json.loads(resp.content[0].text)
عندما يصبح القطع استثناءً صريحاً، يصبح لمسار إعادة المحاولة محفّز، وللمراقبة مصدر إنذار. تلك التقارير الـ83 اكتُشفت لاحقاً باستعلام واحد على الحقل stop_reason في سجلات كانت تُخزّن دائماً ولا تُقرأ أبداً. يبلّغ Gemini بـ length وincomplete بالمعنى نفسه؛ عند إضافة مزوّد جديد راجع جدول التعيين ولا تخمّن.
max_tokens سياج أمان لا ميزانية
السبب المباشر عادةً سقف وُضع لإصدار منتج قديم: 1500 رمز يقطع 39% من التقارير الطويلة بمجرد دخول الجلسات الطويلة. رفع ذلك السقف مجاني. الفوترة تتبع الرموز المولّدة فعلاً، فسقف 4096 على تقرير من 1100 رمز يكلّف مثل 1500. السقف وظيفته إيقاف المخرجات الشاردة، لا توفير المال.
حدّده من البيانات: راقب التوزيع الحقيقي لأسبوع، خذ p99 واترك هامشاً. اختار فريق تلك الحادثة 4096 لأن p99 بعد الإصلاح كان 2350. الاتجاه الآخر هو تصغير المخرجات نفسها. المفاتيح المتكررة في المصفوفات المتجانسة تستهلك جزءاً كبيراً من الرموز؛ الترميز الجدولي قبل الاستدعاء (راجع دليل صيغة TOON) يقلل الحجم الذي يجب أن يبقى تحت السقف.
ترتيب حقول المخطط يحدد ما سيُقطع
يكتب النموذج JSON من أعلى إلى أسفل. عند نفاد الميزانية، يضيع آخر عضو في قائمة الخصائص أولاً. المخطط المرتب summary, per_question_feedback, scores, next_steps يفقد scores أولاً، وهو بالضبط ما يأخذ المستخدمون لقطة شاشة له ويقارنونه كل أسبوع. الإصلاح هو إعادة الترتيب: الحقول القصيرة الحرجة في المقدمة، والتفاصيل الطويلة القابلة لإعادة التوليد بعدها، والنص الحر في المؤخرة.
سلوك المزوّد أيضاً يغيّر نتيجة القطع نفسه:
| المزوّد | آلية المخرجات المنظمة | السلوك عند القطع |
|---|---|---|
| OpenAI | response_format مع strict: true |
ضمان على مستوى أخذ العينات، لكن أضيق لهجة؛ كثيراً ما يرفض التوليد |
| Anthropic | input_schema داخل tool use |
لا ضمان أثناء فك الترميز؛ قد يعيد أقواساً غير مغلقة |
| Gemini | responseSchema مع MIME من نوع JSON |
المفكّك يفرض التعدادات والأنواع فقط؛ القطع ما يزال ممكناً |
"المخرجات المنظمة مفعّلة، لا حاجة للتحقق" وهم. كلما كان ضمان المزوّد أكثر ارتخاءً، احتجت أكثر إلى تحقق مخططك وإلى حلقة إعادة المحاولة. طريقة بناء اختبار العقد ذلك موجودة في اختبار عقد JSON Schema.
متى تكون الاستعادة الجزئية ضرورية فعلاً: الإغلاق بالمكدس الواعي بالسلاسل
هناك حالات تفرض عصر شيء من الشظية: معاينة البث، استجابة متدهورة، أو طابور مراجعة بشرية. هناك يكون الإغلاق آخر درجة في سلّم الإصلاح ويحتاج شرطين. أولاً، مسح الأقواس يجب أن يكون واعياً بالسلاسل: تتبّع حالة الاقتباس والهروب حرفاً بحرف، وإلا أفسد { داخل قيمة المكدس. ثانياً، احذف أزواج المفتاح والقيمة غير المكتملة قبل الإغلاق. المفتاح "qty" بلا قيمة لا يمكن إغلاقه كـ {"qty"}؛ يجب طرح الزوج كله.
def close_truncated(s: str) -> str:
# 1) مسح واعٍ بالسلاسل؛ أغلق السلسلة المفتوحة أولاً
out, in_str, esc = [], False, False
for ch in s:
out.append(ch)
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str
text = ''.join(out) + ('"' if in_str else '')
# 2) احذف الأزواج الناقصة والنقطتين أو الفاصلة المعلقة
text = re.sub(r',\s*"[^"]*"\s*$', '', text)
text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
text = re.sub(r':\s*$', '', text)
text = re.sub(r',\s*$', '', text)
# 3) أعد مسح المكدس وأغلق بترتيب LIFO
stack, in_str, esc = [], False, False
for ch in text:
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str; continue
if not in_str:
if ch in '{[': stack.append(ch)
elif ch in '}]' and stack: stack.pop()
return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))
على المدخل في بداية المقال، يعيد هذا الكود {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} ببايثون 3.11 والمكتبة القياسية فقط. يُحلَّل، والسجل الثالث مفقود. على جانب النماذج المحلية، تفعل مكتبات مخصصة مثل partial-json-parser الشيء نفسه: تغلق بالمكدس وتقصّ حسب الاكتمال.
المهم هو الإفصاح. يجب أن تُبلّغ دالة الإغلاق من أي درجة جاءت النتيجة؛ كل ما يخرج من درجة truncation هو نتيجة جزئية ويجب وسمه: اطلب الجزء المفقود مجدداً، أعد المحاولة بسقف أكبر، أو أخبر المستخدم أن البيانات غير مكتملة. التظاهر بأن شيئاً لم يحدث هو صناعة هلوسة بكود حتمي.
إصلاح أم إعادة محاولة: جدول الحدود
| شكل المدخل | الإجراء الصحيح | السبب |
|---|---|---|
| أسوار، فواصل أخيرة، اقتباسات مفردة | أداة الإصلاح | النية كاملة، النحو فقط متسخ |
| قطع في منتصف سلسلة | إعادة محاولة أو استعادة جزئية مع الإفصاح | القيمة نفسها مفقودة |
| قطع في منتصف بنية | استعادة جزئية مع الإفصاح | الحقول المكتملة تبقى، الأزواج النصفية تُطرح |
| يُحلَّل لكنه يبدو خاطئاً | تحقق تجاري | ليس قطعاً، لكنه يأتي معه غالباً |
قاس فريق مالي الكلفة. قُطع فاتورة طويلة، وأنتج إغلاق الأقواس JSON صالحاً، فأخذ الحقل total المفقود القيمة الافتراضية 0، وأصدر نظام مطابقته للتنسيق 98.2% نحو 200 فاتورة خاطئة شهرياً. بعد اعتبار القطع تدهوراً صارماً وإضافة فحص الهوية (total == مجموع البنود)، هبط معدل أخطاء المال من 0.8% إلى 0.02%، بينما ارتفعت مطابقة التنسيق إلى 99.1% فقط. ثلاثة أشهر من تحسين "مطابقة التنسيق" كانت تستهدف مقياساً خاطئاً. المرور من المحلل لا يعني المرور من العمل.
قائمة من أربعة: افحص سبب التوقف قبل التحليل؛ حدّد السقف وفق p99 لا كميزانية؛ قدّم حقول المخطط الحرجة؛ أعطِ أداة الإصلاح أوساخ التنسيق في الإجابات الكاملة فقط. بهذه الأربعة يعود القطع من تلف بيانات صامت إلى فشل صاخب قابل لإعادة المحاولة.
هل يمكنني فقط إغلاق الأقواس واستخدام الناتج
لا. الإغلاق يضمن الصحة النحوية فقط؛ البيانات ما تزال شظية فيها جملة نصفها، وسجل أخير مفقود، وقيم افتراضية تحل مكان القيم الحقيقية. سمّه جزئياً، وأطلق إعادة المحاولة أو التدهور، وسجّل معدل الاستعادة.
كيف أميّز القطع عن تلف نحوي حقيقي
اقرأ سبب التوقف في البيانات الوصفية: max_tokens أو length أو incomplete يعني قطعاً؛ end_turn أو stop مع فشل في التحليل يعني تلفاً نحوياً حقيقياً. بلا بيانات وصفية، انظر النهاية: التوقف داخل اقتباس أو قوس مع بنية خارجية غير مغلقة يعني قطعاً في كل الحالات تقريباً.
لماذا القطع المُصلح أخطر من فشل صاخب
أداة الإصلاح تحسّن "قابلية التحليل"، والقطع المغلق قابل للتحليل فعلاً، فتصمت المراقبة ويمر التحقق اللاحق بفضل القيم الافتراضية. لهذا أنتج 83 تقريراً مقطوعاً 4 أخطاء فقط. الأداة لا تملك مفهوم النية ولا تعرف ما فُقد، لذا يجب اعتراض القطع في المنبع.
هل رفع max_tokens يزيد الكلفة
لا. الفوترة تتبع الرموز المولّدة فعلاً؛ السقف مجرد سياج. 4096 على 1100 رمز مولّد يكلّف مثل 1500. حدّده وفق p99 حقيقي مع هامش، واستثمر الجهد في منع المخرجات الشاردة.