شيفرتك تحتاج إلى بيانات، والنماذج تكتب نصًا. والمخرجات المنظَّمة تسدّ هذه الفجوة، لكن عبارة «النموذج يعيد 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 وإدراج كل خاصية على أنها مطلوبة.
أي وضع يدعمه مزوّدك؟
نفّذ هذا الاختبار مرة واحدة لكل نموذج قبل أن تبني عليه:
- أرسل
json_schemaمع أمر يدعو إلى إضافة حقل زائد («أضف أيضًا تعليقًا قصيرًا»). - إذا أعاد الطلب خطأً، فالمزوّد لا يقبل
json_schema. جرّبjson_object. - إذا احتوى الرد على الحقل الزائد، فالمخطط غير مفروض. تعامل معه على أنه وضع JSON.
- إذا أعاد
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» فتعطي النموذج شيئًا محددًا يصلحه.
- تحقّق من قواعد العمل في الشيفرة. لا يستطيع المخطط أن يقول إن المجموع يجب أن يساوي البنود. أما الفحص أعلاه فيستطيع.
- ضع حدًا للمحاولات. كل محاولة تعيد إرسال الأمر كله بوصفه رموز إدخال.
ما ميزات المخطط التي تسبب المشكلات؟
اجعل مخططاتك بسيطة ومملة:
- المسطّح أفضل من المتداخل. مستويان يكفيان لمعظم مهام الاستخراج.
- القيم المعدودة (enums) بدل النصوص الحرة للفئات.
- لا كائنات مفتوحة. حقول
dictالحرة تُفقد المخطط فائدته. - أسماء حقول قصيرة مع أوصاف. الأوصاف في المخطط توجّه النموذج.
- الحقول الاختيارية قابلة لأن تكون 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، فاعتمد هناك على الأمر وحده مع التحقق. وقارن الأسعار لكل رمز في صفحة الأسعار.
