كيف تنشئ JSON منظماً وموثوقاً باستخدام النماذج اللغوية

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

ابدأ بتعريف معنى «صالح»

هناك مستويان مختلفان للتحقق. المستوى الأول بنيوي: هل الإخراج كائن JSON صحيح؟ وهل يحتوي الحقول المطلوبة بالأنواع المتوقعة؟ أما المستوى الثاني فهو دلالي: هل القيمة نفسها منطقية بالنسبة إلى قاعدة العمل؟ يعرّف JSON Schema البنية والقيود، لكن قد يظل التحقق الدلالي على مستوى التطبيق مطلوبًا. هذه نقطة أساسية: قد يطابق الإخراج المخطط، مع أن محتواه لا ينسجم مع قواعد منتجك.

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

صمّم مخططًا صغيرًا ومحددًا

المواصفة الحالية لـ JSON Schema هي Draft 2020-12، وفق المواصفة الرسمية. لا يعني ذلك أن كل مزوّد أو واجهة برمجة تطبيقات يدعم كل إمكانات المواصفة. يذكر توثيق OpenAI أن الالتزام الصارم بالمخطط يدعم مجموعة فرعية من JSON Schema، كما يذكر توثيق Gemini أن Structured Outputs يدعم مجموعة فرعية من JSON Schema؛ لذلك فالحفاظ على مخطط ضحل ومتوافق مع المزوّد هو توصية تصميمية في هذا الدليل، وليس وعدًا بتوافق شامل.

اجعل الحقول الضرورية صريحة، واختر أنواعًا محددة، واستخدم القيم المسموح بها عندما تكون الفئات معروفة. يوصي توثيق Gemini باستخدام الأوصاف الواضحة، والأنواع القوية، وenum الصريح بوصفها تقنيات لتحسين موثوقية الإخراج؛ راجع التوثيق. أما منع الخصائص غير المتوقعة، فاستخدمه عندما يدعم المزوّد هذه الإمكانية، ولا تفترض دعمه لمجرد أن JSON Schema يصفها.

مثال تحريري صغير، وليس عقدًا عامًا لأي مزوّد:

{
  "type": "object",
  "properties": {
    "status": {"type": "string", "enum": ["new", "review", "closed"]},
    "summary": {"type": "string"}
  },
  "required": ["status", "summary"]
}

هذا المثال يحدد الشكل فقط. لا يثبت أن الملخص دقيق، ولا أن الحالة المختارة صحيحة في سياق العمل.

استخدم ميزة الإخراج المنظمة بدل الاعتماد على الطلب النصي وحده

توصي وثائق OpenAI باستخدام Structured Outputs المعتمد على json_schema بدل وضع JSON الأقدم json_object عندما يكون الخيار مدعومًا؛ انظر مرجع Chat Completions API. وفي المقابل، يشرح توثيق Gemini Structured Outputs وحدود المجموعة الفرعية التي يدعمها؛ انظر توثيق Gemini. عمليًا، اجعل واجهة المزوّد مسؤولة عن تقييد الشكل، ولا تجعل عبارة مثل «أعد JSON فقط» وسيلتك الوحيدة للتحكم.

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

طبقات التحقق بعد الاستجابة

بعد استقبال النص، افصل المعالجة إلى مراحل يمكن تشخيصها:

1. التحليل: حوّل النص إلى قيمة JSON، وسجّل فشل التحليل كخطأ مستقل.
2. التحقق البنيوي: مرّر القيمة على مدقّق JSON Schema متوافق مع المخطط الذي اعتمدته.
3. التحقق الدلالي: افحص قواعد التطبيق، مثل ارتباط حقلين، أو قبول قيمة ضمن قائمة عمل داخلية، أو توافق تاريخ مع سياق المعاملة.
4. قرار التشغيل: اقبل، أو اطلب مراجعة، أو أعد المحاولة وفق سياسة معلنة.

المرحلتان الثانية والثالثة ليستا الشيء نفسه. قد يكون الحقل من النوع string ويمر بالمخطط، لكنه لا يحمل القيمة التي يتطلبها سير العمل. يؤكد توثيق Gemini أن التطبيق ينبغي أن يتحقق من القيم لأن الإخراج المتوافق مع المخطط قد يظل غير صحيح دلاليًا؛ راجع التوصية الأصلية.

تعامل مع الحالات غير المكتملة بدل إخفائها

ينبغي أن يميّز نظامك بين الرفض، والاستجابة المقتطعة، والمخطط غير المدعوم، وJSON غير القابل للتحليل، وفشل التحقق البنيوي، وفشل التحقق الدلالي. هذه قائمة تصميمية مقترحة لهذا المقال؛ لا تُقدَّم كقائمة ميزات مضمونة لدى مزوّد بعينه.

• احتفظ بسبب الخطأ ونسخة المخطط المستخدمة.
• لا تستبدل قيمة مفقودة بتخمين صامت.
• حدّد شروط إعادة المحاولة، واجعلها محدودة وقابلة للتتبع.
• حوّل الحالات التي تحتاج حكمًا بشريًا إلى مسار مراجعة واضح.

إذا أعدت المحاولة، فاختبر هل تغير سبب الفشل فعلًا. إعادة الطلب نفسه بلا تغيير قد تكون سلوكًا تشغيليًا غير مفيد؛ وهذه ملاحظة تصميمية تستحق القياس في بيئتك.

فرّق بين صحة JSON وثقة البيانات

يمكن استخدام مخطط بسيط لاختبار البنية، ثم اختبارات دلالية بعينات تمثل القيم المتوقعة والحالات الملتبسة. صمّم حالات اختبار تتضمن حقولًا ناقصة، قيمة enum غير مقبولة، نصًا صحيح النوع لكنه خارج قواعد العمل، واستجابة غير مكتملة. لا تقدّم نتيجة هذه الاختبارات كبرهان عام على أداء نموذج أو مزوّد؛ هي أداة تقييم محلية لسير عملك.

التصميم المقترح هنا هو جعل السجل النهائي يضم الاستجابة الخام، ونتائج التحقق، وقرار القبول أو المراجعة، مع تقليل البيانات الحساسة وفق سياسة نظامك. هذا اقتراح هندسي، وليس ادعاءً أمنيًا عن أي مزوّد.

خلاصة عملية

لإنشاء JSON منظم بصورة يمكن الاعتماد عليها، ابدأ بمخطط صغير، واجعل الحقول المطلوبة والأنواع والقيم المسموحة واضحة، واستخدم ميزة Structured Outputs عندما يدعمها المزوّد، ثم نفّذ تحققًا بنيويًا ودلاليًا داخل التطبيق. تذكّر أن Draft 2020-12 هو الإصدار الحالي للمواصفة، وأن تطبيقات Structured Outputs قد تدعم مجموعات فرعية منها؛ المواصفة الرسمية وتوثيق OpenAI وتوثيق Gemini هي مراجع القرار المناسبة. بهذه الطريقة يصبح «JSON صالحًا» مرحلة قابلة للفحص، لا نهاية عملية التحقق.