BroadRouter
ابدأ الآن

مخطط JSON (JSON Schema)

آخر تحديث

JSON Schema (مخطط JSON) مفردات مكتوبة بصيغة JSON لوصف بنية بيانات JSON والتحقق منها: الأنواع والحقول الإلزامية والقيم المسموحة والتداخل. والإصدار الحالي هو 2020-12. وتستخدمه واجهات LLM API لتعريف معاملات الأدوات والبنية الدقيقة التي يجب أن تتبعها المخرجات المنظَّمة.

يُسمّى أيضًا: مخطط JSON، مخطط جيسون، التحقق من JSON، JSON Schema، json_schema، JSON Schema draft 2020-12

الأمر الذي يقول “أجب بصيغة JSON” يترك البنية للصدفة. أما JSON Schema فيدوّن البنية كي تتمكن الآلة من التحقق منها.

كيف يعمل

للمواصفة جزءان رئيسيان: Core، الذي “defines the basic foundation of JSON Schema” (ترجمة: يحدّد الأساس الذي يقوم عليه JSON Schema)، وValidation، الذي “defines the validation keywords” (ترجمة: يحدّد الكلمات المفتاحية للتحقق). والإصدار الحالي هو 2020-12، وكان الذي قبله 2019-09.

{
  "type": "object",
  "properties": {
    "name":    {"type": "string"},
    "amount":  {"type": "number", "minimum": 0},
    "currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
    "note":    {"type": ["string", "null"]}
  },
  "required": ["name", "amount", "currency", "note"],
  "additionalProperties": false
}

تستخدم واجهات LLM API المخططات في موضعين. فتعريفات الأدوات تضع مخططًا في parameters لوصف الوسائط. والمخرجات المنظَّمة ترسل مخططًا في response_format بالشكل {"type": "json_schema", "json_schema": {...}}، وتقول OpenAI إنه “ensures the model will match your supplied JSON schema” (ترجمة: يضمن أن يطابق النموذج مخطط JSON الذي قدّمته).

لا يقبل الوضع الصارم لدى OpenAI إلا مجموعة جزئية. ومن قسم المخططات المدعومة لديها:

  • الأنواع: string وnumber وboolean وinteger وobject وarray وenum وanyOf.
  • يجب أن يكون الجذر كائنًا، ولا يجوز أن يستخدم anyOf.
  • additionalProperties: false وإدراج كل حقل في required؛ ولجعل حقل اختياريًا اسمح له بالقيمة null، كما يفعل note أعلاه.
  • حتى 5000 خاصية للكائنات و10 مستويات من التداخل، وحتى 1000 قيمة enum إجمالًا.
  • غير مدعوم: allOf وnot وdependentRequired وdependentSchemas وif وthen وelse.

لماذا يهم

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

في BroadNet Inference

يوثّق المرجع التقني لـ BroadNet استدعاء الأدوات والمخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B، لكنه لا يذكر الكلمات المفتاحية التي تُفرَض من المخطط. التزم في مخططاتك بالمجموعة البسيطة أعلاه، وتحقّق من كل رد. أنشئ المخطط بـ مولّد JSON Schema، وافحص الردود بـ مدقّق مخرجات JSON لنماذج اللغة، وراجع مقال المخرجات المنظَّمة لمثال كامل. ومع النماذج الأخرى، اطلب JSON في الأمر وتحقّق من الرد؛ فـ وضع JSON غير موثّق لدى BroadNet، فاختبره قبل الاعتماد عليه.

أخطاء شائعة

  • استخدام allOf أو الكلمات المفتاحية الشرطية مع افتراض أن الخادم يفرضها.
  • جعل الحقول اختيارية بحذفها من required في الوضع الصارم، بدل السماح بالقيمة null.

أسئلة شائعة

هل تدعم واجهات LLM API كل JSON Schema؟

لا. تدعم OpenAI مجموعة جزئية منه: مثلًا يجب أن يكون الجذر كائنًا، وأن يكون كل حقل إلزاميًا، وأن تكون additionalProperties بالقيمة false، والكلمات المفتاحية مثل allOf وnot وif/then/else غير مدعومة.

ما الفرق بين JSON Schema ووضع JSON؟

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

هل يمكنني استخدام JSON Schema مع BroadNet Inference؟

معاملات الأدوات والمخرجات المنظَّمة، وكلاهما يستخدم المخططات، موثّقة لنموذجي GLM 5.3 وQwen3.8 27B. ولا يوثّق BroadNet الكلمات المفتاحية التي يفرضها من المخطط، فتحقّق من كل رد.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity