---
title: "وضع JSON مقابل JSON Schema للمخرجات المنظَّمة، مع الشيفرة"
description: "وضع JSON يضمن JSON صالحًا؛ وjson_schema يضمن البنية التي تحددها. كيف تطلب كلًّا منهما من النماذج المتوافقة مع OpenAI، وتتحقق بـ Pydantic، وتصلح المخرجات الخاطئة."
url: https://broadrouter.com/ar/blog/structured-output-json-schema/
lang: ar
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. [اقرأ الأصل الإنجليزي](https://broadrouter.com/blog/structured-output-json-schema/) (حُدّث في 2026-11-14).

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

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

وضع JSON (response\_format من نوع json\_object) لا يضمن إلا JSON صالحًا. أما المخرجات المنظَّمة (response\_format من نوع json\_schema) فتضمن أيضًا حقولك وأنواعها، حيث يفرضها المزوّد. وفي الحالتين، افحص finish\_reason، وحلّل الرد، وتحقّق منه مقابل مخطط مثل نموذج Pydantic. وإذا فشل التحقق، فأرسل الخطأ إلى النموذج واطلب مجددًا، مع حد صارم لعدد المحاولات.

## أبرز النقاط

-   دليل OpenAI: كلا الوضعين ينتج JSON صالحًا، لكن "only Structured Outputs ensure schema adherence" (الترجمة: «المخرجات المنظَّمة وحدها تضمن الالتزام بالمخطط»).
-   يختلف الدعم بين المزوّدين المتوافقين مع OpenAI. اختبر json\_schema أولًا، ثم ارجع إلى json\_object، ثم إلى الاعتماد على الأمر وحده.
-   تحقّق من كل رد. الرد الذي قطعه max\_tokens هو JSON معطوب مهما قال المخطط.
-   حلقات الإصلاح تنجح حين ترسل خطأ التحقق بنصه إلى النموذج. حدّها بمحاولتين أو ثلاث.
-   في BroadNet Inference، يُدرج المرجع المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B.

**في هذه الصفحة**

1.  ما الفرق بين وضع JSON وjson\_schema؟
2.  كيف تطلب json\_schema؟
3.  أي وضع يدعمه مزوّدك؟
4.  كيف تتحقق من المخرجات الخاطئة وتصلحها؟
5.  ما ميزات المخطط التي تسبب المشكلات؟
6.  كيف تراقب المخرجات المنظَّمة في الإنتاج؟
7.  متى تستخدم أداة بدلًا من ذلك؟
8.  أين تقع BroadNet Inference من هذا؟

شيفرتك تحتاج إلى بيانات، والنماذج تكتب نصًا. و[المخرجات المنظَّمة](https://broadrouter.com/ar/glossary/structured-output/) تسدّ هذه الفجوة، لكن عبارة «النموذج يعيد 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؟

```python
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](https://broadrouter.com/tools/json-schema-generator/) يبني مخططًا للوضع الصارم من كائن نموذجي. وفي الوضع الصارم، تشترط OpenAI ضبط `additionalProperties: false` وإدراج كل خاصية على أنها مطلوبة.

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

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

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

في BroadNet Inference، تُدرج الوثائق المخرجات المنظَّمة لنموذجي [GLM 5.3](https://broadrouter.com/ar/models/glm-5.3/) و[Qwen3.8 27B](https://broadrouter.com/ar/models/qwen3.8-27b/) ([مقارنة بينهما جنبًا إلى جنب](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/))، لكنها لا تسمّي معامل الطلب. نفّذ الاختبار أعلاه على النموذج الذي ستطلقه.

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

```python
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`](https://broadrouter.com/ar/glossary/max-tokens/) هو JSON مبتور. وإعادة المحاولة بالحد نفسه تفشل بالطريقة نفسها. كلا النموذجين أعلاه يستدلّان منطقيًا قبل الإجابة، و[الاستدلال المنطقي يُحسب ضمن الحد](https://broadrouter.com/ar/guides/reasoning-tokens-empty-response/)، فاترك هامشًا كافيًا.
-   **تعامل مع الرفض على حدة.** يشير دليل OpenAI إلى أن الرفض “does not necessarily follow the schema you have supplied” (الترجمة: «لا يتبع بالضرورة المخطط الذي قدّمته»).
-   **أرسل الخطأ بنصه.** إعادة المحاولة العمياء تعيد الخطأ نفسه غالبًا. أما «line\_items: field required» فتعطي النموذج شيئًا محددًا يصلحه.
-   **تحقّق من قواعد العمل في الشيفرة.** لا يستطيع المخطط أن يقول إن المجموع يجب أن يساوي البنود. أما الفحص أعلاه فيستطيع.
-   **ضع حدًا للمحاولات.** كل محاولة تعيد إرسال الأمر كله بوصفه [رموز إدخال](https://broadrouter.com/ar/glossary/input-and-output-tokens/).

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

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

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

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

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

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

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

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

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

استخدم المخرجات المنظَّمة **للإجابة النهائية**: استخراج، أو تصنيف، أو خطة. واستخدم [استدعاء الأدوات](https://broadrouter.com/ar/blog/tool-calling-open-models/) حين يحتاج النموذج إلى أن **تنفّذ** شيفرتك شيئًا ثم يتابع. ويستخدم كثير من الوكلاء الاثنين معًا: الأدوات أثناء الحلقة، ومخططًا للخطوة الأخيرة. ولمثال يحوّل صورة إلى JSON، راجع [قراءة الفواتير العربية بنموذج رؤية](https://broadrouter.com/ar/guides/read-arabic-invoices-with-vision/).

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

تُدرج BroadNet Inference المخرجات المنظَّمة لنموذجي GLM 5.3 وQwen3.8 27B، عبر صيغة إكمال المحادثات القياسية، لذا تعمل الشيفرة أعلاه مع [OpenAI Python SDK](https://broadrouter.com/ar/guides/openai-python-sdk/) دون تغيير. ويقبل Qwen3.8 27B الصور أيضًا، وهذا يناسب استخراج البيانات من المستندات. لا تذكر وثائق BroadNet المخرجات المنظَّمة لنموذجي DeepSeek V4.1 Flash وGemma 4 VL 26B، فاعتمد هناك على الأمر وحده مع التحقق. وقارن الأسعار لكل رمز في [صفحة الأسعار](https://broadrouter.com/ar/pricing/).

أدوات مجانية لهذا الموضوع (بالإنجليزية)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[أدوات مجانية (بالإنجليزية)](https://broadrouter.com/tools/)

## مصطلحات في هذا المقال

[المخرجات المنظَّمة (Structured output)](https://broadrouter.com/ar/glossary/structured-output/)

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

[مخطط JSON (JSON Schema)](https://broadrouter.com/ar/glossary/json-schema/)

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

[استدعاء الأدوات (Tool calling)](https://broadrouter.com/ar/glossary/tool-calling/)

استدعاء الأدوات، ويُسمّى أيضًا استدعاء الدوال (function calling)، ميزة في واجهات LLM API يُرجع فيها النموذج طلبًا منظَّمًا لتشغيل دالة عرّفها المطوّر، مع معاملات بصيغة JSON. ويشغّل التطبيق الدالة ويعيد النتيجة؛ فالنموذج لا يشغّل الشيفرة بنفسه أبدًا.

[وضع JSON (JSON mode)](https://broadrouter.com/ar/glossary/json-mode/)

وضع JSON (JSON mode) إعداد في LLM API، هو response\_format {"type": "json\_object"} في الواجهات على طريقة OpenAI، يجعل رد النموذج JSON صالحًا قابلًا للتحليل. وبخلاف المخرجات المنظَّمة مع JSON Schema، لا يضمن المفاتيح أو الأنواع أو القيم التي يحتويها الكائن.

[الرمز (التوكن، Token)](https://broadrouter.com/ar/glossary/token/)

الرمز (التوكن) هو وحدة النص التي يقرؤها نموذج اللغة ويكتبها: كلمة، أو جزء من كلمة، أو علامة ترقيم، أو تسلسل بايتات ينتجه مجزّئ النموذج (tokenizer). وتَعُدّ واجهات LLM API الاستهلاك بالرموز، وتضع حدودها بها، وتحتسب تكلفتها بها عادةً.

## أسئلة شائعة

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

وضع JSON، أي response\_format من نوع json\_object، لا يضمن إلا أن الرد يُحلَّل بوصفه JSON. أما المخرجات المنظَّمة، من نوع json\_schema، فتضمن أيضًا الحقول والأنواع التي عرّفتها، حيث يفرضها المزوّد. وتوصي OpenAI بالمخرجات المنظَّمة بدل وضع JSON كلما أمكن.

### هل تدعم النماذج المفتوحة response\_format من نوع json\_schema؟

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

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

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

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

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

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

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

## تابع القراءة

-   [تصنيف النصوص العربية بنموذج LLM: المشاعر والنية وفرز التذاكر](https://broadrouter.com/ar/blog/arabic-text-classification-llm/)
-   [استدعاء الأدوات في النماذج المفتوحة: المخططات والتوازي والإعادة](https://broadrouter.com/ar/blog/tool-calling-open-models/)
-   [الانتقال إلى واجهة API متوافقة مع OpenAI: قائمة تحقق للترحيل](https://broadrouter.com/ar/blog/openai-compatible-api-migration-checklist/)
-   [وكيل n8n AI Agent على نموذج LLM رخيص: الإعداد والاختيار والتكلفة](https://broadrouter.com/ar/blog/n8n-ai-agent-cheap-llm/)
-   [إصلاح JSON غير الصالح من LLM: الأسباب والإصلاح وإعادة المحاولة](https://broadrouter.com/ar/blog/fix-invalid-json-from-llm/)
-   [استخراج الكيانات المسماة من النص العربي بنموذج LLM: JSON والتواريخ](https://broadrouter.com/ar/blog/arabic-named-entity-extraction-llm/)
-   [عتاد GPU لدى BroadNet وطريقة تقديم النماذج، كما تصفها BroadNet](https://broadrouter.com/ar/blog/broadnet-gpu-fleet-and-serving/)
-   [تخزين استجابات LLM API مؤقتًا لخفض التكلفة: تطابق تام بـ Python](https://broadrouter.com/ar/blog/cache-llm-responses-cut-cost/)
-   [دليل: استخدام OpenAI Python SDK مع BroadNet Inference](https://broadrouter.com/ar/guides/openai-python-sdk/)
-   [دليل: قراءة الفواتير والإيصالات العربية بنموذج رؤية](https://broadrouter.com/ar/guides/read-arabic-invoices-with-vision/)
-   [دليل: لماذا يعيد نموذج الاستدلال إجابة فارغة؟](https://broadrouter.com/ar/guides/reasoning-tokens-empty-response/)

جرّبه على مهامك الفعلية. تبدأ الحسابات الجديدة برصيد قدره $5 لاستخدام Gemma والتفريغ الصوتي. أما DeepSeek وGLM وQwen3.8 فتتطلب شحن الرصيد.

[ابدأ الآن](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ar-blog-structured-output-json-schema&utm_content=page-cta) ·

**المصادر**

-   [OpenAI، دليل Structured Outputs (تاريخ المراجعة 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [المرجع التقني لواجهة OpenAI API، إنشاء إكمال محادثة (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [وثائق Pydantic، مخططات JSON Schema والتحقق](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [المرجع التقني لواجهة BroadNet Inference، النماذج (بالإنجليزية)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ar-blog-structured-output-json-schema&utm_content=sources#models)
