JSON Toolkit

دليل إصلاح JSON: إنقاذ مخرجات LLM المعطوبة دون فقدان الثقة

الخلاصة: مخرجات LLM المغلفة بأسوار markdown، وفيها فواصل ختامية وقيم حرفية من Python، يرفضها المحلل الصارم بالكامل — وكذلك ملفات الإعداد المحررة يدويًا بلا علامات تنصيص. يرسم هذا الدليل الحد الفاصل الحقيقي بين تسعة أنواع من الأخطاء يعالجها المصلح وأربعة أنواع لن يعالجها أبدًا، ويشرح لماذا تتفوق آلة الحالات على التعبيرات النمطية، ويقدّم سلسلة تحليل جاهزة للإنتاج بأداتَي jsonrepair وjson-repair.

متوسطقراءة نحو 6 دقيقةنُشر في 2026-11-08حُدِّث في 2026-11-08
مخطط خط أنابيب إصلاح JSON: نزع السور، توحيد علامات التنصيص، موازنة الأقواس، ثم التحقق النهائي

المحلل الصارم لا يمنح المدخل المعطوب أي تساهل: رسالة خطأ واحدة، رقم سطر واحد — ولا بايت واحد من بياناتك يعود إليك. المصلح موجود لتحويل «الفشل التام» إلى «كافٍ للعمل» — لكن ما يملؤه هو دائمًا أفضل تخمين عن القصد، وليس ضمانًا للصواب.

أولًا: من أين يأتي JSON المعطوب

الإصلاح ليس سحرًا — ابدأ بفحص المدخل. في المشاريع الحقيقية، يأتي JSON غير القياسي من ثلاثة مصادر مركزة:

  1. مخرجات LLM. تولّد نماذج اللغة النص رمزًا تلو رمز؛ ولا تُشغّل أي مُسلسِل JSON. حتى لو طلبت «JSON فقط»، يغلف النموذج الرد بسياج ```json, ويضيف قبله «تفضل بياناتك»، ويترك فاصلة ختامية، أو يصطدم بسقف الرموز ويتوقف في وسط كائن.
  2. النسخ من لغات أخرى. كائن JavaScript المطبوع عبر console.log يحمل علامات تنصيص مفردة ومفاتيح بلا تنصيص؛ وقاموس Python يُطبع بصيغة True/False/None. هذه النصوص «الشبيهة بـ JSON» تنفجر عند أول تلامس مع JSON.parse.
  3. ملفات إعداد JSON5/JSONC. ملفات مثل tsconfig تسمح شرعيًا بالتعليقات والفواصل الختامية. الصق واحدًا في محلل صارم — سيرفض الملف بأكمله.

المصادر الثلاثة تتطلب معالجة مختلفة، لكن المصلحين يغطونها جميعًا — بشرط أن يكون الخطأ ضمن قائمة الحالات القابلة للإصلاح التي يعلنونها.

ثانيًا: تسعة أنواع من الأخطاء يعالجها المصلح فعلًا

بدمج وثائق مكتبة jsonrepair مع قوائم القدرات المنشورة من مقدمي الأدوات، تنقسم الأخطاء القابلة للإصلاح تلقائيًا إلى تسعة أنواع:

النوع المدخل المعطوب النتيجة بعد الإصلاح
فاصلة ختامية [1, 2, 3,] [1, 2, 3]
تنصيص مفرد / منحنٍ {'a': 'b'}、{"a": "b"} {"a": "b"}
مفاتيح بلا تنصيص {name: 'Ada'} {"name": "Ada"}
تعليقات {"a": 1 /* ملاحظة */} {"a": 1}
قيم حرفية من Python {"ok": True, "v": None} {"ok": true, "v": null}
أسوار markdown ```json {...} ``` {...}
فواصل ناقصة [1 2] [1, 2]
أقواس / تنصيص غير مغلق {"a": [1, 2 {"a": [1, 2]}
JSONP / إسناد نصي cb({...})、"x" + "y" {...}、"xy"

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

  • الأرقام التي تبدأ بصفر تتحول إلى نصوص. يُصلح 007 إلى "007" لا إلى 7، حتى لا تفقد الأرقام خاناتها. إن كان الحقل رمزًا نصيًا فعلًا فهذا صحيح؛ وإن كان رقمًا حقيقيًا فالقرار لك.
  • الكلمات العارية تتحول إلى نصوص. لا يمكن إصلاح NaN إلى رقم — بعض التنفيذات تعطي "NaN" وأخرى null. السلوك يختلف بين المكتبات؛ اختبر مكتبتك قبل ربطها بخط الأنابيب.
  • المدخل الصحيح يعامل كمدخل سليم. كل مصلح جاد يُشغّل أولًا مسارًا سريعًا للتحليل الصارم. الـ JSON الصحيح لا يدخل منطق الإصلاح أبدًا، فلا يمكن «إصلاح وثيقة سليمة إلى معطوبة».

ثالثًا: أربعة أشياء لا يعالجها المصلح

الحد من الجهة الأخرى واضح بالقدر نفسه. لا تتوقع إصلاحًا لأي مما يلي:

  1. صفحات أخطاء HTML أو نثر صِرف. لا يوجد أي بنية JSON في المدخل، ولا توجد أداة قادرة على ابتداع البيانات من العدم.
  2. بيانات صحيحة تركيبيًا لكنها خاطئة. مفتاح بخطأ إملائي، قيمة في موضع خاطئ، رقم مخزن كنص — هذه مشكلات دلالية يتركها أي محلل، ومن ضمنهم المصلحون، تمر بلا اعتراض.
  3. بيانات فُقدت بفعل القطع. يمكن للإكمال تحويل {"items": [{"id": 1}, {"na إلى JSON صحيح، لكن قيمة الحقل name لن تعود أبدًا. ما تحصل عليه كائن «صحيح لكن ناقص». في الإنتاج، افحص stopReason === "max_tokens" قبل أن تقرر بين الإكمال وإعادة المحاولة.
  4. المفاتيح المكررة والبنى الملتبسة. أي مفتاحين متطابقين يفوز يعتمد على تنفيذ المحلل. المصلحون المسؤولون يوفرون وضع strict الذي يرمي خطأ بدل اختيار أحدهما بصمت.

حد الثقة في جملة واحدة: الإصلاح «أفضل تخمين» وليس «ضمانًا للصواب». تمرير نتيجة إصلاح غير مُتحقَّق منها إلى المصب يعني استبدال خطأ تركيبي صاخب بخطأ بيانات خفي.

رابعًا: مدرستان في التنفيذ — رابط واحد يحسم النقاش

المصلحون في السوق نوعان، والفجوة تظهر فورًا مع نوع معين من المدخلات.

مدرسة الاستبدال بالتعبيرات النمطية تطبق بحثًا واستبدالًا شاملًا على الأنماط المعطوبة. انظر هذا المدخل:

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

تعبير نمطي يحوّل التنصيص المفرد إلى مزدوج سيطعن في محتوى الرابط أيضًا؛ وتعبير تنظيف التعليقات الذي يحذف كل // سيقطع http:// إلى نصفين. داخل نص وخارج بنية تبدو المحارف متطابقة — والتعبير النمطي لا يستطيع تمييزها.

مدرسة آلة الحالات حرفًا بحرف تتتبع حالة التحليل: داخل نص بعلامات تنصيص مزدوجة، أو مفردة، داخل تعليق سطري، أو تعليق كتلي، أو في انتظار قيمة. حين يرى '، يسأل أولًا «هل أنا داخل نص؟» ثم يقرر هل يبدّل علامة التنصيص أو يتجاوزها. http://example.com يقع داخل نص بعلامات تنصيص مزدوجة، فتعرف آلة الحالات أن // هناك بيانات وليست تعليقًا، فتحفظها. يتبع jsonrepair وjson-healer هذه المدرسة، ويشير شعار المجتمع الشائع «المصلح ليس بحثًا واستبدالًا» إلى هذا التحديدًا.

الترتيب الكامل لخط أنابيب الإصلاح (كما كشفته تنفيذات devkits) يستحق نظرة أيضًا: نزع الأسوار → توحيد علامات التنصيص المنحنية → استخراج أول كتلة متوازنة → إزالة التعليقات → تغليف المفاتيح العارية بعلامات تنصيص → إزالة الفواصل الختامية → تحويل القيم الحرفية → في النهاية إعادة التسلسل عبر JSON.stringify. إعادة التسلسل النهائية هي الخطوة المفصلية: مهما فعلته المراحل السابقة، يُعاد توليد المخرجات من نتيجة التحليل، فيبتلعها أي محلل صارم في المصب.

خامسًا: الربط في الكود — سلسلة تحليل متسلسلة

عندما تربط الإصلاح في الكود، يكون الترتيب أهم من اختيار المكتبة. وفق الأنماط المنشورة من json2toon وaijsonmedic، ينبغي أن يكون التسلسل: فحص القطع → استخراج نطاق JSON → تحليل صارم → الإصلاح كخطة بديلة → التحقق بالمخطط.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // إصلاح مخرج مقطوع يبقى ناقص البيانات — أعد المحاولة بدلًا من ذلك
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // استخرج نطاق JSON: قد يتثرثر النموذج في البداية والنهاية
  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);   // مسار سريع للمدخل الصحيح
  } catch {
    return JSON.parse(jsonrepair(candidate));  // الإصلاح كخطة بديلة
  }
}

في جانب Python، توفر الحزمة json-repair (أكثر من 4700 نجمة) دالة loads() التي تعيد كائنًا مباشرة:

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}

تفصيلان هندسيان إضافيان:

  • وحّد حزمك. إن كان الواجهة الأمامية والخلفية كلاهما يصلحان، فاختر تنفيذات بمعنى مشترك — مكتبة json-repair لبايثون ومنفذها إلى TypeScript ‏@yarmu/json-repair، أو jsonmend الذي تمرّ نسختاه من Python وJS بجسم اتساق واحد من 485 حالة. وإلا فسيُصلح المخرج نفسه إلى A على العميل وB على الخادم، ويصبح تنقيح الأخطاء كابوسًا.
  • شغّل سجل الإصلاحات. يُرجع @yarmu/json-repair مع logging: true مصفوفة بكل عملية إصلاح. الارتفاع المفاجئ في معدل الإصلاحات يعني عادة تغيّر المطالِب أو إصدار النموذج — إشارة أسبق من أي تقرير أخطاء.

وهناك خطوة بعد الإصلاح غير قابلة للتفاوض: التحقق بالمخطط. الصحة التركيبية لا تعني القابلية للاستخدام. الحقول الناقصة والأنواع الخاطئة والمفاتيح غير المتوقعة يلتقطها المخطط. ينطبق أسلوب اختبارات العقد هنا مباشرة؛ راجع دليلنا عن اختبارات عقد JSON Schema.

سادسًا: قائمة الوقاية — أرخص إصلاح هو الذي لا تحتاجه

الإصلاح هو الحل الاحتياطي. النصر الحقيقي هو إنتاج JSON معطوب أقل من المنبع، بترتيب الأولوية:

  1. Structured Outputs (وضع json_schema). فك الترميز مقيد بالمخطط، فلا يمكن توليد فاصلة ختامية أصلًا. يفشل وضع strict لدى OpenAI بنسبة 0.1% تقريبًا — مقابل اشتراطات صارمة مثل additionalProperties: false.
  2. وضع JSON (json_object). يضمن السلامة التركيبية فقط — لا الشكل — والقطع بسبب سقف الرموز ما يزال يحدث.
  3. التعليمات الصريحة. على نقاط النهاية دون وضع JSON، الصياغة «بلا أسوار، بلا تعليقات، بلا فواصل ختامية، أخرج الكائن فقط» تخفض معدل الأخطاء 70–80%.
  4. خفّض temperature وارفع سقف الرموز. الأول يقلل الانحراف إلى النثر؛ والثاني يقلل القطع.
  5. أعد المحاولة مع إرفاق الخطأ. عندما يفشل التحقق، أضف إلى المحادثة المخرج المعطوب مع «مسار JSON + رسالة الخطأ» واطلب مرة أخرى. مع خطأ دقيق، تصحح النماذج نفسها عادة.

عمليًا، تكديس «structured outputs + إصلاح احتياطي + تحقق بالمخطط» يغطي كل سيناريو تقريبًا.

سابعًا: تقسيم العمل — تحويل اللهجة ليس إصلاحًا

في صندوق أدوات هذا الموقع وجهتان تغطيان مقطعين مختلفين من هذا الخط:

  • مشكلات اللهجة (تعليقات، تنصيص مفرد، فواصل ختامية) تذهب مباشرة إلى محوّل JSON5. التحويل المتبادل بين JSON5 وJSON القياسي يغطي هذه الأنواع الثلاثة تحديدًا، بدلالة واضحة وبلا تخمين. إن كان المدخل بأكمله ملف JSONC/JSON5، فالتحويل أثبت من الإصلاح. عن مقايضات اللهجات ذاتها، راجع دليل JSON5 وJSONC.
  • بعد الإصلاح، مرّر النتيجة عبر أداة تحليل JSON للتحقق والتنسيق — مع تحديد الأخطاء إلى سطر وعمود، لتتأكد أن محللًا صارمًا يقبل المخرج فعلًا.
  • مشكلات فئة المكتبات (قيم Python الحرفية، إكمال القطع، أغلفة JSONP، أسوار markdown) ما تزال تتطلب jsonrepair / json-repair في جانب الكود — لا يوجد إصلاح بنقرة واحدة مكافئ في المتصفح، لأن هذه الإصلاحات تستلزم استنتاج القصد، والمكتبة المحلية بيت أكثر أمانًا لها من محوّل عام.

إن كان بيديك رسالة خطأ لا بيانات معطوبة، فابدأ من دليل إصلاح أخطاء تحليل JSON لتترجم الرسالة إلى إحداثيات، ثم قرر: تحرير يدوي أم إصلاح.

الأسئلة الشائعة

هل يتلف إصلاح JSON بياناتي؟

للأنواع التسعة القابلة للإصلاح تتغير علامات الترقيم والأغلفة فقط — القيم تبقى سليمة، و// والفواصل والأقواس المعقوفة داخل النصوص تحفظها آلة الحالات. لكن إكمال القطع يعطي كائنات ناقصة، والأرقام ذات الصفر الافتتاحي تصبح نصوصًا، ومعالجة NaN تختلف بين المكتبات. فحص الحقول المفتاحية بعد الإصلاح إجراء إلزامي.

ما علاقة الإصلاح بالتحقق؟

التحقق يخبرك أين المدخل غير قانوني؛ والإصلاح يناولك وثيقة قانونية. الأسلوب الموثوق يجمع الاثنين: أصلح ثم تحقق — يلتقط المخطط الأنواع والحقول الإلزامية، ويؤكد الفحص التركيبي أن محللًا صارمًا يقبل النتيجة. الإصلاح دون تحقق يعني استبدال خطأ تركيبي صاخب بخطأ بيانات خفي.

يغلف النموذج المخرج دائمًا بسياج ```json — ماذا أفعل؟

على المدى القصير: استخرج. خذ النص من أول { أو [ إلى آخر } أو ] وحلله؛ والمصلح الذي ينزع الأسوار يبتلع الرسالة كاملة أيضًا. على المدى الطويل: استخدم structured outputs أو تعليمة صريحة «بلا أسوار markdown» حتى لا يتولد السيج أصلًا.

jsonrepair أم json-repair — أيهما أختار؟

لجافاسكربت حزمة npm ‏jsonrepair (تدعم transform التدفقية)؛ ولبايثون json-repair من PyPI. إن كان الطرفان يصلحان، فاختر زوجًا متوافق الدلالة — مثل json-repair ومنفذ TS الخاص به — ليُصلح المدخل نفسه بالطريقة نفسها في الجهتين.

هل يتعامل المصلحون مع العربية وعلامات التنصيص المنحنية؟

نعم. علامات التنصيص الناتجة عن لوحات المفاتيح العربية (« »)، والمسافات بعرض كامل، وBOM في أول الملف، كلها ضمن قائمة الإصلاح القياسية؛ وتُوحَّد علامات التنصيص المنحنية إلى مستقيمة. مرّر النتيجة عبر أداة تحقق مرة واحدة وينتهي الأمر.