JSON موثوق من أي نموذج LLM: أنماط Pydantic وZod لعام 2026

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

ملخص سريع: المخرجات المنظمة في لمحة

إن كان وقتك محدوداً، إليك المشهد في عام 2026:

دعنا الآن نفصّل كل جزء.

ما هي المخرجات المنظمة لنماذج اللغة الكبيرة؟

المخرجات المنظمة هي الفرق بين الأمل في أن يُعيد النموذج اللغوي JSON صالحاً وضمان ذلك. عندما تُفعّل المخرجات المنظمة، لا يستطيع النموذج فعلياً إنتاج رموز تنتهك مخططك. تُعرّف مخطط JSON (أو نموذج Pydantic، أو مخطط Zod)، تمرره إلى واجهة برمجية، وتحصل في كل مرة على استجابة مطابقة له.

لماذا يهم هذا؟ قبل المخرجات المنظمة، كان المطورون يكتبون محللات regex هشّة، ويُغلّفون كل استدعاء لنموذج اللغة في كتل try/catch JSON.parse، ويتعاملون مع استجابات "صحيحة تقريباً" -- JSON صالح يفتقد حقلاً أو يحمل نوعاً خاطئاً. تلك الفئة الكاملة من الأخطاء اختفت.

ثمة ثلاثة مستويات لتطبيق البنية، وتمثّل تطوراً واضحاً:

1. هندسة النصوص التحفيزية -- "يُرجى إعادة JSON بهذه الحقول." غير موثوق. قد يمتثل النموذج 80-90% من الوقت.
2. وضع JSON -- يضمن JSON صالحاً صياغياً، لكنه لا يُطبّق مخططك. قد تحصل على {"foo": "bar"} بينما كنت تتوقع {"name": string, "age": number}.
3. الوضع الصارم / الترميز المقيّد -- يضمن توافقاً بنسبة 100% مع المخطط. لا يستطيع النموذج حرفياً إصدار رموز غير صالحة. هذا ما يعنيه "المخرجات المنظمة" في عام 2026.

منذ مطلع 2026، يدعم كلٌّ من OpenAI وAnthropic وGoogle Gemini المخرجات المنظمة الأصلية. تقارب النظام البيئي.

الحكم: إذا كنت تُحلّل استجابات نماذج اللغة بالتعبيرات النمطية أو JSON.parse في الإنتاج، فأنت تسلك الطريق الصعب. تُزيل المخرجات المنظمة الأصلية تلك الفئة الكاملة من الإخفاقات.

وضع JSON مقابل الوضع الصارم: ما الذي تغيّر فعلاً؟

يُربك هذا التمييز كثيراً من المطورين لأن الأسماء تبدو متشابهة. إلا أنها ليست كذلك.

الجدول الزمني: قدّم OpenAI وضع JSON في أواخر 2023. كان خطوة للأمام، لكن المطورين أدركوا سريعاً أن "JSON صالحاً" لا يكفي -- كانوا بحاجة إلى JSON صالح وفق المخطط. في أغسطس 2024، أطلق OpenAI المخرجات المنظمة بالوضع الصارم، الذي يستخدم الترميز المقيّد لضمان توافق المخطط. بحلول 2025-2026، تبنّى كل مزود رئيسي النهج نفسه.

لا يزال لوضع JSON حالة استخدام ضيّقة: عندما لا تعرف حقاً شكل الاستجابة مسبقاً وتريد فقط أي JSON صالح للاستكشاف غير المنظم. لكن ذلك نادر في الإنتاج.

الحكم: استخدم الوضع الصارم لكل شيء في الإنتاج. وضع JSON متقادم فعلياً لحالات الاستخدام المرتبطة بالمخططات. إذا كان لديك مخطط (وينبغي أن يكون)، استخدم type: "json_schema" مع strict: true.

كيف يعمل الترميز المقيّد فعلاً؟

إليك الآلية التي تجعل توافق المخطط بنسبة 100% ممكناً -- ليس 99.9%، بل حرفياً 100%.

عندما ترسل مخطط JSON إلى مزود مع تفعيل الوضع الصارم، يُجمَّع المخطط في آلة حالة منتهية (FSM). تُمثّل هذه الآلة كل مسار صالح عبر مخططك. عند كل خطوة توليد رموز، يتحقق محرك الاستدلال من الرموز التي ستُبقي المخرجات على مسار صالح وأيها لن تفعل ذلك. تُعيَّن قيم logit للرموز غير الصالحة على سالب اللانهاية قبل أخذ العينات، مما يعني أن احتمال اختيارها يساوي الصفر.

فكّر في الأمر كالإكمال التلقائي المعزّز. إذا أصدر النموذج للتو {"rating": وكان مخططك يقول إن rating عدد صحيح، فإن الرموز المسموح بها التالية هي رموز الأرقام فقط. علامات الاقتباس والحروف والأقواس -- كلها مخفية. لا يستطيع النموذج إصدار "خمسة" حتى لو "أراد" ذلك.

هذه هي نفس الآلية الأساسية التي تستخدمها XGrammar (المحرك خلف vLLM وSGLang ومعظم خوادم الاستدلال المحلية) وOutlines (مكتبة Python مفتوحة المصدر للتوليد المقيّد). دمج مزودو واجهات برمجية هذه الآلية في بنيتهم التحتية للاستدلال.

هناك مفاضلة يجب معرفتها: الطلب الأول بمخطط جديد يتحمل تكلفة زمن استجابة تجميع (عادةً 50-200 مللي ثانية) أثناء بناء آلة الحالة المنتهية. الطلبات اللاحقة بنفس المخطط تستخدم آلة حالة منتهية مخزّنة مؤقتاً وتضيف تقريباً صفر عبء. هناك أيضاً اعتبار جودة دقيق -- قد يُقلّل تقييد مفردات الرموز أحياناً من جودة المخرجات للحقول الإبداعية أو ذات الشكل الحر، لذا أبقِ مخططاتك مركّزة على البيانات المنظمة فعلاً.

الحكم: الترميز المقيّد هو ما يفصل "يعمل عادةً" عن "يعمل دائماً". إنه الهندسة التي تجعل المخرجات المنظمة جاهزة للإنتاج.

التنفيذ متعدد المزودين: OpenAI وAnthropic وGemini

إليك ما لا يُريك إياه أيٌّ من الأدلة الأخرى: نفس مهمة الاستخراج منفّذة عبر المزودين الثلاثة الرئيسيين. سنستخرج مراجعة منتج منظمة من نص غير منظم. للمزيد من التفاصيل، راجع أفضل مكتبات المخرجات المنظمة.

مخطط Pydantic (مشترك بين جميع المزودين):

from pydantic import BaseModel, Field
from typing import Literal

class ProductReview(BaseModel):
    reasoning: str = Field(description="Think through the review before scoring")
    rating: int = Field(description="Rating from 1-5", ge=1, le=5)
    sentiment: Literal["positive", "negative", "neutral"]
    pros: list[str] = Field(description="Key positive points")
    cons: list[str] = Field(description="Key negative points")
    summary: str = Field(description="One-sentence summary")

تنفيذ OpenAI

from openai import OpenAI

client = OpenAI()

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract a structured review from the text."},
        {"role": "user", "content": review_text}
    ],
    response_format=ProductReview,  # نموذج Pydantic مباشرة
)

review = response.choices[0].message.parsed  # كائن ProductReview مكتوب النوع

تنفيذ OpenAI هو الأكثر نضجاً. تقبل طريقة parse() نموذج Pydantic مباشرةً وتُعيد كائناً مكتوب النوع. قيد واحد: الوضع الصارم في OpenAI يدعم مجموعة فرعية من مخطط JSON -- لا $ref، وanyOf محدود، ويجب أن تكون جميع الحقول مطلوبة مع additionalProperties: false.

تنفيذ Anthropic

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": f"Extract a structured review:\n\n{review_text}"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "json_schema": ProductReview.model_json_schema()
        }
    }
)

import json
review_data = json.loads(response.content[0].text)
review = ProductReview(**review_data)

تستخدم المخرجات المنظمة الأصلية في Anthropic output_config.format مع مخطط JSON. وصلت إلى التوفر العام في مطلع 2026. تدعم Anthropic أيضاً النمط الأقدم المتمثل في تعريف أداة "وهمية" والاستخراج عبر tool_use -- يعمل هذا النمط مازال، لكن المخرجات المنظمة الأصلية أنظف للاستخراج الخالص.

تنفيذ Gemini

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=f"Extract a structured review:\n\n{review_text}",
    config={
        "response_mime_type": "application/json",
        "response_schema": ProductReview,  # نموذج Pydantic مباشرة
    }
)

import json
review = ProductReview(**json.loads(response.text))

يدعم Gemini نماذج Pydantic مباشرةً في Python SDK عبر response_schema. ميزة فريدة: يحترم Gemini propertyOrdering في المخطط، مما يتيح التحكم في ترتيب إخراج الحقول (مفيد لنمط التفكير-أولاً).

مقارنة المزودين

الحكم: يتمتع OpenAI بأكثر تجربة مطور مصقولة مع طريقة parse(). يوفر Anthropic نماذج أساسية أكثر قدرة. ترتيب خصائص Gemini مفيد بصورة فريدة. تنجز الثلاثة المهمة -- اختر بناءً على علاقتك الحالية مع المزود.

أنماط Pydantic لمطوري Python

Pydantic هو المعيار الفعلي لتعريف مخططات المخرجات المنظمة في Python. إليك الأنماط المهمة.

مخطط أساسي مع الأوصاف

from pydantic import BaseModel, Field
from typing import Literal, Optional

class ExtractedEntity(BaseModel):
    reasoning: str = Field(description="Think step by step about the entity")
    name: str = Field(description="Full name of the entity")
    entity_type: Literal["person", "company", "location"]
    confidence: float = Field(description="Confidence score 0.0-1.0", ge=0.0, le=1.0)
    context: Optional[str] = Field(description="Surrounding context, if relevant")

سلاسل description هذه ليست للتوثيق فقط -- تصبح جزءاً من مخطط JSON المُرسَل إلى النموذج وتؤثر مباشرةً على ما يُولّده. فكّر فيها كهندسة نصوص تحفيزية داخل المخطط.

النماذج المتداخلة

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: Optional[str] = None

class Company(BaseModel):
    reasoning: str = Field(description="Analysis of the company details")
    name: str
    industry: Literal["tech", "finance", "healthcare", "retail", "other"]
    headquarters: Address  # نموذج متداخل
    key_products: list[str] = Field(description="Top 3 products or services")

أبقِ التداخل عند 2-3 مستويات كحد أقصى. تزيد المخططات المتداخلة بعمق من معدلات الأخطاء وتُبطئ تجميع المخطط.

نمط التفكير-أولاً

هذا هو نمط تصميم المخططات الأعلى تأثيراً. ضع حقل reasoning قبل حقول الإجابة:

# سيء -- يلتزم النموذج بإجابة قبل أن يفكر
class ClassificationBad(BaseModel):
    category: Literal["spam", "ham"]
    confidence: float

# جيد -- يفكر النموذج في المشكلة أولاً
class ClassificationGood(BaseModel):
    reasoning: str = Field(description="Analyze the text before classifying")
    category: Literal["spam", "ham"]
    confidence: float = Field(ge=0.0, le=1.0)

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

تصدير مخطط JSON

# توليد مخطط JSON لأي نموذج Pydantic
schema = ProductReview.model_json_schema()
# مرّره إلى أي مزود يقبل مخطط JSON الخام

الحكم: Pydantic + الحقول الوصفية + ترتيب التفكير-أولاً هو ثالوث Python للمخرجات المنظمة. أتقن هذه الأنماط الثلاثة وستتعامل مع 90% من حالات الاستخدام.

أنماط Zod لمطوري TypeScript

Zod هو مكافئ Pydantic في TypeScript -- وهو بنفس القدر مركزي لتدفقات عمل المخرجات المنظمة.

مخطط أساسي مع الأوصاف

import { z } from "zod";

const ProductReview = z.object({
  reasoning: z.string().describe("Think through the review before scoring"),
  rating: z.number().int().min(1).max(5),
  sentiment: z.enum(["positive", "negative", "neutral"]),
  pros: z.array(z.string()).describe("Key positive points"),
  cons: z.array(z.string()).describe("Key negative points"),
  summary: z.string().describe("One-sentence summary"),
});

// استنتاج نوع TypeScript تلقائياً
type ProductReview = z.infer<typeof ProductReview>;

مثل Field(description=...) في Pydantic، يصبح .describe() في Zod جزءاً من مخطط JSON ويُوجّه مخرجات النموذج.

التكامل مع OpenAI Node SDK

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";

const client = new OpenAI();

const response = await client.beta.chat.completions.parse({
  model: "gpt-4o-2024-08-06",
  messages: [
    { role: "system", content: "Extract a structured review." },
    { role: "user", content: reviewText },
  ],
  response_format: zodResponseFormat(ProductReview, "product_review"),
});

const review = response.choices[0].message.parsed; // مكتوب النوع!

التكامل مع Vercel AI SDK

import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";

const { object: review } = await generateObject({
  model: openai("gpt-4o"),
  schema: ProductReview,
  prompt: `Extract a structured review:\n\n${reviewText}`,
});
// review مكتوب النوع بالكامل كـ ProductReview

يستخدم Vercel AI SDK Zod بصورة أصلية مع generateObject()، مما يجعله أنظف تكامل لـ TypeScript. يعمل مع OpenAI وAnthropic وGemini ومزودين آخرين عبر واجهة برمجية موحّدة.

تحويل مخطط JSON

import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(ProductReview);
// استخدمه مع أي مزود يقبل مخطط JSON الخام

الحكم: Zod + .describe() + Vercel AI SDK هو مجموعة TypeScript للمخرجات المنظمة. إذا كنت في نظام Node/Next.js البيئي، هذا هو طريق المقاومة الأقل.

المخرجات المنظمة مقابل استدعاء الدوال: متى تستخدم كلاً منهما؟

هذا أحد أكثر مصادر الارتباك شيوعاً. كلاهما يتضمن مخططات، وكلاهما يُعيد بيانات منظمة -- لكنهما يحلّان مشكلتين مختلفتين.

المخرجات المنظمة تقول: "أعطني بيانات بهذا الشكل تحديداً." إنها للاستخراج والتصنيف والتنسيق. تستخرج معلومات منظمة من نص غير منظم.

استدعاء الدوال (استخدام الأدوات) يقول: "إليك الإجراءات التي يمكنك اتخاذها -- قرّر أيها تُشغّل وقدّم الوسائط." إنه لتدفقات عمل العملاء حيث يختار النموذج من بين أدوات متعددة ويُشغّل الإجراءات.

الارتباك منطقي تاريخياً. كانت "المخرجات المنظمة" الأصلية في Anthropic هي حرفياً استدعاء الدوال -- كنت تُعرّف أداة "وهمية" تسمى extract_review وتأخذ الوسائط. يعمل هذا مازال، لكن المخرجات المنظمة الأصلية أبسط للاستخراج الخالص.

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

الحكم: استخدم المخرجات المنظمة عندما تعرف الشكل الذي يجب أن تكون عليه البيانات. استخدم استدعاء الدوال عندما يحتاج النموذج إلى اختيار إجراء. في الممارسة العملية، تستخدم معظم التطبيقات كليهما -- المخرجات المنظمة لاستخراج البيانات واستدعاء الدوال لتنسيق العملاء.

أنماط الإنتاج: الأخطاء والمحاولات والبث

تشغيل المخرجات المنظمة في نموذج عرض توضيحي أمر سهل. الحفاظ على موثوقيتها في الإنتاج يتطلب معالجة ثلاثة أشياء: الرفض وأخطاء التحقق والبث.

معالجة الرفض

في بعض الأحيان يرفض النموذج توليد المخرجات المطلوبة -- عادةً لأن مرشحات الأمان علّمت المدخلات. في هذه الحالة، لا تُعيد واجهات برمجية المخرجات المنظمة مخططك. تُعيد رفضاً. قد يهمك أيضاً دليل استدعاء الدوال في LLM.

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=messages,
    response_format=ProductReview,
)

# تحقق دائماً من الرفض قبل الوصول إلى المحتوى المُحلَّل
if response.choices[0].message.refusal:
    print(f"Model refused: {response.choices[0].message.refusal}")
else:
    review = response.choices[0].message.parsed

إذا تجاوزت فحص الرفض وحاولت الوصول إلى .parsed عند الرفض، ستحصل على None وخطأ مُربِك في المجرى. تحقق دائماً أولاً.

أنماط إعادة المحاولة مع ملاحظات التحقق

توافق المخطط مضمون بالترميز المقيّد، لكن الصحة الدلالية ليست كذلك. قد يُعيد النموذج {"rating": 1, "sentiment": "positive"} -- مخطط صالح، محتوى متناقض. هنا يأتي دور التحقق + إعادة المحاولة.

import instructor

client = instructor.from_openai(OpenAI())

# يتعامل Instructor مع إعادة المحاولة تلقائياً
review = client.chat.completions.create(
    model="gpt-4o",
    response_model=ProductReview,
    max_retries=3,  # إعادة محاولة مع ملاحظات خطأ التحقق
    messages=[
        {"role": "user", "content": review_text}
    ],
)

يُعيد Instructor خطأ التحقق إلى النموذج عند إعادة المحاولة، ليتمكن من تصحيح نفسه. لأنماط إعادة المحاولة اليدوية دون Instructor:

from pydantic import ValidationError

for attempt in range(3):
    try:
        response = client.beta.chat.completions.parse(
            model="gpt-4o-2024-08-06",
            messages=messages,
            response_format=ProductReview,
        )
        review = response.choices[0].message.parsed
        # نفّذ تحققاً دلالياً إضافياً هنا
        break
    except ValidationError as e:
        messages.append({"role": "assistant", "content": str(response)})
        messages.append({"role": "user", "content": f"Validation error: {e}. Fix it."})

بث المخرجات المنظمة

للاستجابات المنظمة الكبيرة -- المصفوفات الطويلة والحقول الكثيرة والكائنات المتداخلة المعقدة -- يتيح لك البث عرض النتائج الجزئية تدريجياً.

import instructor

client = instructor.from_openai(OpenAI())

# بث نتائج جزئية مع امتلاء الحقول
review_stream = client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=ProductReview,
    messages=[{"role": "user", "content": review_text}],
)

for partial_review in review_stream:
    # تمتلئ الحقول واحداً تلو الآخر مع وصول الرموز في البث
    if partial_review.summary:
        print(f"Summary so far: {partial_review.summary}")

مخاطرة واحدة: أجزاء البث الفردية ليست صالحة وفق المخطط بمفردها. قد يكون حقل reasoning ممتلئاً بينما rating لا يزال None. خطّط لواجهتك وفقاً لذلك -- أظهر حالة تحميل للحقول غير الممتلئة.

الحكم: فحوصات الرفض غير قابلة للتفاوض. إعادة المحاولة مع ملاحظات التحقق تلتقط الأخطاء الدلالية. البث يستحق العناء لأي استجابة تستغرق أكثر من ثانيتين.

مقارنة مكتبات المخرجات المنظمة

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

Instructor هو الخيار الأكثر شعبية بأكثر من 11,000 نجمة على GitHub وأكثر من 3 ملايين تنزيل شهري. يُغلّف OpenAI وAnthropic وGemini وCohere وOllama وغيرها بواجهة موحّدة تعتمد على Pydantic. الميزات الرئيسية: إعادة محاولة تلقائية مع ملاحظات التحقق، والبث عبر create_partial()، والإعداد السهل (instructor.from_openai(client)). إذا كنت فريق Python، ابدأ من هنا.

BAML يتبع نهجاً مختلفاً: المخطط-أولاً عبر لغة DSL مخصصة. تُعرّف المخططات في ملفات .baml وتُولّد عملاء تلقائياً لـ Python وTypeScript وRuby وغيرها. يتعامل خوارزمية SAP (التحليل المنسجم مع المخطط) مع مخرجات النماذج الفوضوية ببراعة. الأفضل للفرق متعددة اللغات أو عند الرغبة في عقود بين طبقة نموذج اللغة وطبقة التطبيق. المفاضلة: خطوة بناء إضافية وصيغة جديدة للتعلم.

LangChain يوفر .with_structured_output(schema) لمخرجات منظمة مستقلة عن المزود. مريح إذا كنت في نظام LangChain البيئي. المفاضلة: تبعية ثقيلة، وقد يُخفي التجريد الميزات الخاصة بالمزود التي قد تحتاجها.

واجهات برمجية أصلية -- استدعاءات مباشرة مع response_format / output_config -- لا تتطلب تبعيات تتجاوز SDK المزود. تحصل على تحكم كامل ورؤية كاملة. الأفضل لحالات الاستخدام البسيطة أو الفرق التي تُفضّل الحد الأدنى من التجريد.

اختيار مكتبة المخرجات المنظمة المناسبة جزء من قرار مجموعة الذكاء الاصطناعي الأشمل. نفصّل المجموعة الكاملة في دليلنا لأفضل مجموعة ذكاء اصطناعي للـ SaaS.

اطّلع على أفضل مكتبات للمخرجات المنظمة لنماذج اللغة الكبيرة [قريباً] للحصول على مقارنة معمّقة لـ Instructor وBAML وMirascope وغيرها.

الحكم: ابدأ بـ Instructor لـ Python، وواجهات برمجية أصلية لـ TypeScript. انتقل إلى BAML إذا احتجت عقود مخطط متعددة اللغات. تجنّب LangChain فقط للمخرجات المنظمة -- إنه مبالغة.

أفضل ممارسات تصميم المخططات (والأخطاء الشائعة)

تصميم مخططك يؤثر مباشرةً على جودة المخرجات. إليك الأنماط المهمة والأخطاء التي تُكلّفك الدقة.

وضع التفكير قبل الإجابات

غطّينا هذا في قسم Pydantic، لكنه يستحق التكرار لأنه أكثر قرار تصميم تأثيراً:

# قبل: يخمّن النموذج الإجابة، ثم يُبرّرها
class Bad(BaseModel):
    answer: str
    reasoning: str

# بعد: يفكر النموذج أولاً، ثم يلتزم
class Good(BaseModel):
    reasoning: str = Field(description="Think step by step")
    answer: str

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

جدول الأنماط السلبية

التعامل الصريح مع القيم الفارغة

إذا كان حقل ما قد لا يحتوي على بيانات في النص المصدر، اجعله اختيارياً. إرغام حقل مطلوب عند غياب البيانات يؤدي إلى الهلوسة:

class PersonInfo(BaseModel):
    name: str  # موجود دائماً
    email: Optional[str] = Field(None, description="Email if mentioned, null otherwise")
    phone: Optional[str] = Field(None, description="Phone if mentioned, null otherwise")

إبقاء المخططات مركّزة

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

الحكم: التفكير-أولاً، الحقول الوصفية، القيم الفارغة الصريحة، والمخططات المركّزة. أتقن هذه الأربعة وترتفع دقة مخرجاتك المنظمة بشكل قابل للقياس.

المخرجات المنظمة مع نماذج اللغة المحلية

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

Ollama

أسهل طريق للمخرجات المنظمة المحلية. يقبل Ollama مخطط JSON عبر معامل format:

import ollama
from pydantic import BaseModel

class Country(BaseModel):
    name: str
    capital: str
    languages: list[str]

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Tell me about Japan."}],
    format=Country.model_json_schema(),
)

import json
country = Country(**json.loads(response.message.content))

يستخدم Ollama XGrammar داخلياً للترميز المقيّد. نفس ضمان مزودي واجهة برمجية: توافق مخطط بنسبة 100%.

vLLM وSGLang

للاستدلال المحلي بجودة إنتاجية، يدعم كلٌّ من vLLM وSGLang المخرجات المنظمة عبر معاملات guided_json وguided_regex. XGrammar هو الواجهة الخلفية الافتراضية، توفر تقريباً صفر عبء على توليد JSON -- أسرع بما يصل إلى 3.5 مرة من محركات القواعد البديلة.

Outlines

Outlines هي مكتبة Python مفتوحة المصدر رائدة في التوليد المقيّد القائم على القواعد. تعمل مع أي نموذج Hugging Face وتدعم قيود مخطط JSON والتعبيرات النمطية والقواعد الخالية من السياق الكاملة (CFG/EBNF). متكاملة أيضاً في vLLM وSGLang كخيار واجهة خلفية للقواعد.

الفارق الرئيسي عن مزودي واجهة برمجية: المخرجات المنظمة المحلية ليس لها قيود على مجموعة فرعية من المخطط. تتحكم في القواعد بالكامل. لكن جودة النموذج تتفاوت أكثر -- نموذج محلي بـ 7 مليار معامل لن يُضاهي GPT-4o أو Claude في مهام الاستخراج المعقدة. المخطط سيكون صالحاً دائماً؛ جودة المحتوى تعتمد على النموذج.

الحكم: Ollama للتطوير، vLLM/SGLang مع XGrammar للإنتاج. المخرجات المنظمة المحلية ناضجة بما يكفي لمعظم حالات الاستخدام، مع التحفظ بأن النماذج الأصغر تنتج محتوى أدنى جودة داخل المخطط.

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

ما هي المخرجات المنظمة في نماذج اللغة الكبيرة؟

المخرجات المنظمة آلية تضمن أن استجابة النموذج اللغوي تتوافق مع مخطط JSON محدد مسبقاً. خلافاً للنص العادي أو حتى وضع JSON، تستخدم المخرجات المنظمة الترميز المقيّد لضمان أن كل حقل ونوع وقيد في مخططك محترَم -- 100% من الوقت، لا "عادةً".

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

يضمن وضع JSON صيغة JSON صالحة لكنه لا يُطبّق مخططك -- قد تحصل على أي كائن JSON صالح. تضمن المخرجات المنظمة (الوضع الصارم) توافقاً كاملاً مع المخطط عبر الترميز المقيّد. استخدم الوضع الصارم للإنتاج؛ وضع JSON ذو صلة فقط عند عدم امتلاك مخطط مسبقاً.

أي مزودي نماذج اللغة الكبيرة يدعم المخرجات المنظمة أصلياً؟

يدعم OpenAI (منذ أغسطس 2024) وGoogle Gemini (2024، موسَّع 2026) وAnthropic (بيتا نوفمبر 2025، توفر عام مطلع 2026) وCohere وxAI (Grok) جميعهم المخرجات المنظمة الأصلية. على الجانب المحلي، يدعم Ollama وvLLM وSGLang هذا عبر الترميز المقيّد القائم على القواعد.

كيف يضمن الترميز المقيّد توافق المخطط؟

يُجمَّع مخطط JSON في آلة حالة منتهية (FSM). عند كل خطوة توليد رموز، تُسمح فقط الرموز التي تُبقي المخرجات على مسار صالح عبر آلة الحالة المنتهية -- تُعيَّن قيم logit للرموز غير الصالحة على سالب اللانهاية. يعني هذا أن الرموز غير الصالحة لها احتمال توليد يساوي الصفر، مما يمنحك ضماناً رياضياً لا إحصائياً.

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

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

هل يمكنني بث المخرجات المنظمة؟

نعم. يدعم OpenAI البث مع طريقة parse()، ويوفر Instructor create_partial() لبث نماذج Pydantic التي تمتلئ حقلاً حقلاً. ضع في اعتبارك أن أجزاء البث الفردية ليست صالحة وفق المخطط بمفردها -- تمتلئ الحقول بصورة تدريجية.

ما هي مكتبة Instructor؟

Instructor هي أكثر مكتبات المخرجات المنظمة شعبية (11,000+ نجمة على GitHub، 3 ملايين+ تنزيل شهري). تُغلّف حزم SDK الخاصة بالمزودين بالتحقق القائم على Pydantic وإعادة المحاولة التلقائية مع ملاحظات التحقق ودعم البث. تعمل مع OpenAI وAnthropic وGemini وCohere وOllama و10+ مزودين آخرين.

هل تعمل المخرجات المنظمة مع نماذج اللغة المحلية؟

نعم. يدعم Ollama المخرجات المنظمة عبر معامل format مع مخطط JSON. يدعم vLLM وSGLang هذا عبر معاملات guided_json. تستخدم الثلاثة XGrammar أو Outlines للترميز المقيّد. ضمان توافق المخطط هو نفسه مع مزودي واجهة برمجية؛ جودة المحتوى تعتمد على النموذج.

ما هي أخطاء تصميم المخططات الشائعة؟

أبرز الأخطاء: وضع حقل التفكير بعد حقل الإجابة (يقرر النموذج قبل أن يفكر)، المخططات المتداخلة بعمق (4+ مستويات تزيد الأخطاء)، الحقول الوصفية المفقودة (يخمّن النموذج النية)، عدم معالجة القيم الفارغة للبيانات الاختيارية (يُرغم على الهلوسة)، والمخططات الكبيرة جداً (50+ حقل يُدهور الجودة).

هل تُضيف المخرجات المنظمة زمن استجابة؟

يوجد عبء تجميع مخطط في الطلب الأول -- عادةً 50-200 مللي ثانية أثناء بناء آلة الحالة المنتهية. الطلبات اللاحقة بنفس المخطط تستخدم آلة حالة منتهية مخزّنة مؤقتاً وتُضيف تقريباً صفر زمن استجابة. لمعظم التطبيقات، هذا ضئيل مقارنةً بإجمالي وقت استدلال النموذج.

هل يمكنني استخدام المخرجات المنظمة مع الصور أو المدخلات متعددة الوسائط؟

نعم. تنطبق المخرجات المنظمة على تنسيق الاستجابة، لا المدخلات. يمكنك إرسال صورة إلى GPT-4o أو Gemini مع مخطط مخرجات منظمة والحصول على تحليل للصورة متوافق مع المخطط. هذا قوي لتدفقات عمل الاستخراج المرئي -- استخراج بيانات منظمة من الإيصالات والنماذج وصور المنتجات.

المصادر

• OpenAI Structured Outputs Guide
• Anthropic Tool Use Documentation
• Google Gemini Structured Output
• Instructor Library Documentation
• BAML Documentation
• Pydantic Documentation
• Zod Documentation
• Outlines Library
• XGrammar GitHub
• Ollama Structured Outputs
• Vercel AI SDK