BroadRouter
ابدأ الآن

وضع JSON أم json_schema: مخرجات منظَّمة يمكن الاعتماد عليها

بقلم فريق BroadNet Inference · قراءة في 4 دقائق · تاريخ النشر

وضع JSON (response_format من نوع json_object) لا يضمن إلا JSON صالحًا. أما المخرجات المنظَّمة (response_format من نوع json_schema) فتضمن أيضًا حقولك وأنواعها، حيث يفرضها المزوّد. وفي الحالتين، افحص finish_reason، وحلّل الرد، وتحقّق منه مقابل مخطط مثل نموذج Pydantic. وإذا فشل التحقق، فأرسل الخطأ إلى النموذج واطلب مجددًا، مع حد صارم لعدد المحاولات.

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

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

الطريقة الطلب ما الذي تضمنه لك
الأمر وحده «أجب بصيغة JSON تتضمن الحقول…» لا شيء؛ غالبًا JSON، وأحيانًا مع نص إضافي
وضع JSON response_format: {"type": "json_object"} JSON صالح، بأي بنية
المخرجات المنظَّمة response_format: {"type": "json_schema", ...} JSON مطابق لمخططك، حيث يُفرض

يقولها دليل Structured Outputs من OpenAI صراحةً: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (الترجمة: «مع أن كليهما يضمن إنتاج JSON صالح، فإن المخرجات المنظَّمة وحدها تضمن الالتزام بالمخطط.») ويوصي الدليل بالمخرجات المنظَّمة بدل وضع JSON كلما أمكن.

أما لدى مزوّدي النماذج المفتوحة، فيعتمد الضمان على طريقة تنفيذ الخادم له. كثيرون يستخدمون التوليد المقيَّد (constrained decoding)، الذي يمنع الرموز التي قد تكسر المخطط. وبعضهم يقبل الحقل لكنه لا يفرضه. ولهذا تتحقق الشيفرة أدناه في كل الأحوال.

كيف تطلب json_schema؟

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

تولّد Pydantic مخطط JSON Schema من الصنف (class) الذي تكتبه، فلا يفترق المخطط عن أداة التحقق أبدًا. وإن كنت لا تستخدم Pydantic، فإن مولّد مخطط JSON يبني مخططًا للوضع الصارم من كائن نموذجي. وفي الوضع الصارم، تشترط OpenAI ضبط additionalProperties: false وإدراج كل خاصية على أنها مطلوبة.

أي وضع يدعمه مزوّدك؟

نفّذ هذا الاختبار مرة واحدة لكل نموذج قبل أن تبني عليه:

  1. أرسل json_schema مع أمر يدعو إلى إضافة حقل زائد («أضف أيضًا تعليقًا قصيرًا»).
  2. إذا أعاد الطلب خطأً، فالمزوّد لا يقبل json_schema. جرّب json_object.
  3. إذا احتوى الرد على الحقل الزائد، فالمخطط غير مفروض. تعامل معه على أنه وضع JSON.
  4. إذا أعاد json_object خطأً أيضًا، فاعتمد على الأمر وحده مع التحقق.

في BroadNet Inference، تُدرج الوثائق المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B (مقارنة بينهما جنبًا إلى جنب)، لكنها لا تسمّي معامل الطلب. نفّذ الاختبار أعلاه على النموذج الذي ستطلقه.

كيف تتحقق من المخرجات الخاطئة وتصلحها؟

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

ما الذي يجعل هذه الحلقة تنجح:

  • افحص finish_reason أولًا. الرد الذي بلغ max_tokens هو JSON مبتور. وإعادة المحاولة بالحد نفسه تفشل بالطريقة نفسها. كلا النموذجين أعلاه يستدلّان منطقيًا قبل الإجابة، والاستدلال المنطقي يُحسب ضمن الحد، فاترك هامشًا كافيًا.
  • تعامل مع الرفض على حدة. يشير دليل OpenAI إلى أن الرفض “does not necessarily follow the schema you have supplied” (الترجمة: «لا يتبع بالضرورة المخطط الذي قدّمته»).
  • أرسل الخطأ بنصه. إعادة المحاولة العمياء تعيد الخطأ نفسه غالبًا. أما «line_items: field required» فتعطي النموذج شيئًا محددًا يصلحه.
  • تحقّق من قواعد العمل في الشيفرة. لا يستطيع المخطط أن يقول إن المجموع يجب أن يساوي البنود. أما الفحص أعلاه فيستطيع.
  • ضع حدًا للمحاولات. كل محاولة تعيد إرسال الأمر كله بوصفه رموز إدخال.

ما ميزات المخطط التي تسبب المشكلات؟

اجعل مخططاتك بسيطة ومملة:

  1. المسطّح أفضل من المتداخل. مستويان يكفيان لمعظم مهام الاستخراج.
  2. القيم المعدودة (enums) بدل النصوص الحرة للفئات.
  3. لا كائنات مفتوحة. حقول dict الحرة تُفقد المخطط فائدته.
  4. أسماء حقول قصيرة مع أوصاف. الأوصاف في المخطط توجّه النموذج.
  5. الحقول الاختيارية قابلة لأن تكون null. في الوضع الصارم، أدرج كل حقل على أنه مطلوب واسمح بقيمة null.

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

كيف تراقب المخرجات المنظَّمة في الإنتاج؟

الحلقة التي تصلح بصمت قد تخفي مشكلة تكلّفك رموزًا كل يوم. سجّل ثلاثة أرقام لكل موضع استدعاء:

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

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

متى تستخدم أداة بدلًا من ذلك؟

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

أين تقع BroadNet Inference من هذا؟

تُدرج BroadNet Inference المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B، عبر صيغة إكمال المحادثات القياسية، لذا تعمل الشيفرة أعلاه مع OpenAI Python SDK دون تغيير. ويقبل Qwen3.8 27B الصور أيضًا، وهذا يناسب استخراج البيانات من المستندات. لا تذكر وثائق BroadNet المخرجات المنظَّمة لنموذجي DeepSeek V4.1 Flash وGemma 4 VL 26B، فاعتمد هناك على الأمر وحده مع التحقق. وقارن الأسعار لكل رمز في صفحة الأسعار.

أسئلة شائعة

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

وضع JSON، أي response_format من نوع json_object، لا يضمن إلا أن الرد يُحلَّل بوصفه JSON. أما المخرجات المنظَّمة، من نوع json_schema، فتضمن أيضًا الحقول والأنواع التي عرّفتها، حيث يفرضها المزوّد. وتوصي OpenAI بالمخرجات المنظَّمة بدل وضع JSON كلما أمكن.

هل تدعم النماذج المفتوحة response_format من نوع json_schema؟

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

هل ما زلت أحتاج إلى التحقق من المخرجات المنظَّمة؟

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

كم مرة أعيد المحاولة عند JSON غير صالح؟

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

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

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

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