BroadRouter
ابدأ الآن

المخرجات المنظَّمة (Structured output)

آخر تحديث

المخرجات المنظَّمة هي ميزة في LLM API تقيّد رد النموذج بصيغة يحدّدها المطوّر، عادةً JSON Schema، لكي تحلّلها الشيفرة بموثوقية. وهي أكثر صرامة من وضع JSON (JSON mode)، الذي يضمن JSON صالحًا لكن لا يضمن بنية معيّنة.

يُسمّى أيضًا: مخرجات منظمة، المخرجات المهيكلة، مخرجات JSON، مخطط JSON، structured output، structured outputs، JSON schema output، response_format

تحتاج الشيفرة إلى مدخلات متوقعة. والمخرجات المنظَّمة تحوّل النص الحر الذي يكتبه النموذج إلى بيانات يستطيع برنامجك الوثوق بها.

كيف تعمل

هناك ثلاثة مستويات من التحكم:

الطريقة ما تحصل عليه
الطلب في الأمر 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 قبل التحليل.

أسئلة شائعة

ما الفرق بين JSON mode والمخرجات المنظَّمة؟

يعد JSON mode فقط بأن الرد يُحلَّل بوصفه JSON. أما المخرجات المنظَّمة مع مخطط فتعد أيضًا بالحقول والأنواع والمفاتيح الإلزامية التي حدّدتها. ويقول دليل OpenAI إن Structured Outputs وحدها تضمن الالتزام بالمخطط.

هل ما زلت بحاجة إلى التحقق من المخرجات؟

نعم. قد يكون الرد رفضًا، أو قد يُقطع بسبب max_tokens، ولا يستطيع المخطط التعبير عن كل قاعدة عمل، مثل إجمالي يجب أن يساوي مجموع البنود.

هل أستخدم المخرجات المنظَّمة أم استدعاء الأدوات؟

استخدم المخرجات المنظَّمة حين تريد الإجابة النهائية بصيغة ثابتة. واستخدم استدعاء الأدوات حين ينبغي أن يطلب النموذج من شيفرتك تنفيذ شيء ثم يتابع.

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