تحتاج الشيفرة إلى مدخلات متوقعة. والمخرجات المنظَّمة تحوّل النص الحر الذي يكتبه النموذج إلى بيانات يستطيع برنامجك الوثوق بها.
كيف تعمل
هناك ثلاثة مستويات من التحكم:
| الطريقة | ما تحصل عليه |
|---|---|
| الطلب في الأمر | JSON غالبًا، مع نص زائد أو حقول ناقصة أحيانًا |
| JSON mode | JSON صالح بأي بنية |
| المخرجات المنظَّمة مع مخطط | JSON يطابق مخططك |
في صيغة OpenAI، يُفعَّل JSON mode بـ response_format: {"type": "json_object"}. أما المخرجات المنظَّمة فتمرّر مخططًا:
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice",
"strict": true,
"schema": {
"type": "object",
"properties": {
"vendor": { "type": "string" },
"total": { "type": "number" }
},
"required": ["vendor", "total"],
"additionalProperties": false
}
}
}
يقول المرجع التقني لدى OpenAI إن النوع json_schema “ensures the model will match your supplied JSON schema” (ترجمة: يضمن أن يطابق النموذج مخطط JSON الذي قدّمته). ويحقّق كثير من المزوّدين ذلك بالتوليد المقيَّد: تقييد الرموز التي يُسمح للنموذج بإنتاجها في كل خطوة، فلا يمكن توليد مخرجات تخالف المخطط.
لماذا تهم
- أخطاء تحليل أقل. تستطيع خطوط الاستخراج والمصنِّفات والوكلاء قراءة الحقول مباشرة.
- أوامر أبسط. يحلّ المخطط محل تعليمات التنسيق الطويلة.
- ليست ضمانًا كاملًا. يقول دليل OpenAI إن تطبيقك يجب أن يتعامل مع حالات الرفض والاستجابات غير المكتملة والأخطاء. والرد الذي قطعه
max_tokensهو JSON معطوب مهما قال المخطط.
يتفاوت الدعم بين واجهات API المتوافقة مع OpenAI. بعضها لا يقبل إلا json_schema، وبعضها لا يقبل إلا json_object، وبعضها يتجاهل الحقل. تحقّق قبل أن تعتمد عليه.
في BroadNet Inference
تذكر وثائق BroadNet المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B. ولا تسمّي الوثائق معامل الطلب، فاختبر response_format على نموذجك، واحتفظ بمحلّل JSON مع معالجة للأخطاء في كل الأحوال. ويوضّح مدقّق مخرجات JSON لنماذج اللغة موضع انكسار الرد ويتحقق منه مقابل مخططك. ويستدل النموذجان كلاهما منطقيًا أولًا، فامنح max_tokens مساحة للتفكير وللـ JSON معًا.
تعمل المخرجات المنظَّمة جيدًا مع نماذج الرؤية. يرسل دليل الفواتير العربية صورة ويطلب الحقول بصيغة JSON. وللأفعال بدل الإجابات، استخدم استدعاء الأدوات.
أخطاء شائعة
- نسيان
additionalProperties: false، أو عدم إدراج كل حقل فيrequired، عند استخدام الوضع الصارم. - عدم فحص
finish_reasonقبل التحليل.