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

<Callout type="info" title="من النص إلى البيانات">
المخرجات المهيكلة تحول استجابات الذكاء الاصطناعي من نص حر إلى بيانات قابلة للتنفيذ والتحليل.
</Callout>

## أهمية الهيكلة

<StructuredOutputDemo />

## تقنيات التنسيق الأساسية

### القوائم

القوائم مثالية للتعليمات خطوة بخطوة، والعناصر المرتبة، أو مجموعات النقاط المترابطة. يسهل مسحها وتحليلها. استخدم **القوائم المرقمة** عندما يكون الترتيب مهماً (الخطوات، التصنيفات) و**النقاط النقطية** للمجموعات غير المرتبة.

<TryIt 
  compact
  title="تنسيق القوائم"
  prompt={`قدم 5 نصائح لنوم أفضل.

التنسيق: قائمة مرقمة مع شرح موجز لكل نصيحة.
يجب أن تكون كل نصيحة بخط عريض، متبوعة بشرطة وتوضيح.`}
/>

<Callout type="tip" title="أفضل ممارسات القوائم">
حدد العدد الدقيق للعناصر التي تريدها، وما إذا كنت تريد تضمين شروحات، وما إذا كان يجب أن تكون العناصر بخط عريض أو لها هيكل معين.
</Callout>

### الجداول

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

<TryIt 
  compact
  title="تنسيق الجداول"
  prompt={`قارن بين أفضل 4 أطر عمل Python للويب.

التنسيق كجدول markdown بأعمدة:
| إطار العمل | الأفضل لـ | منحنى التعلم | الأداء |`}
/>

<Callout type="tip" title="أفضل ممارسات الجداول">
حدد أسماء الأعمدة، وأنواع البيانات المتوقعة (نص، أرقام، تقييمات)، وعدد الصفوف التي تحتاجها. للمقارنات المعقدة، اقتصر على 4-6 أعمدة لسهولة القراءة.
</Callout>

### العناوين والأقسام

العناوين تنشئ هيكلاً واضحاً للمستند، مما يجعل الاستجابات الطويلة قابلة للمسح ومنظمة. استخدمها للتقارير، والتحليلات، أو أي استجابة متعددة الأجزاء. العناوين الهرمية (##، ###) تُظهر العلاقات بين الأقسام.

```
حلل هذا الاقتراح التجاري.

هيكل استجابتك بهذه الأقسام:
## الملخص التنفيذي
## نقاط القوة
## نقاط الضعف
## التوصيات
## تقييم المخاطر
```

<Callout type="tip" title="أفضل ممارسات الأقسام">
اذكر أقسامك بالترتيب الذي تريده. للاتساق، حدد ما يجب أن يحتويه كل قسم (مثلاً، "الملخص التنفيذي: 2-3 جمل فقط").
</Callout>

### التأكيد بالتوجيهات بالأحرف الكبيرة

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

**التوجيهات الشائعة بالأحرف الكبيرة:**

<InfoGrid items={[
  { label: "NEVER", description: "منع مطلق: \"NEVER تضمين آراء شخصية\"", color: "red" },
  { label: "ALWAYS", description: "متطلب إلزامي: \"ALWAYS اذكر المصادر\"", color: "green" },
  { label: "IMPORTANT", description: "تعليمات حرجة: \"IMPORTANT: اجعل الاستجابات أقل من 100 كلمة\"", color: "amber" },
  { label: "DO NOT", description: "منع قوي: \"DO NOT اختلاق إحصائيات\"", color: "red" },
  { label: "MUST", description: "إجراء مطلوب: \"المخرجات MUST أن تكون JSON صالح\"", color: "blue" },
  { label: "ONLY", description: "تقييد: \"أرجع ONLY الكود، بدون شروحات\"", color: "purple" },
]} />

```
لخص هذا المقال.

IMPORTANT: اجعل الملخص أقل من 100 كلمة.
NEVER تضف معلومات غير موجودة في النص الأصلي.
ALWAYS حافظ على النبرة والمنظور الأصلي.
DO NOT تضمن آراءك أو تحليلاتك الخاصة.
```

<Callout type="warning" title="استخدم باعتدال">
إذا كان كل شيء بأحرف كبيرة أو مُعلّم كحرج، فلن يبرز شيء. احتفظ بهذه التوجيهات للقيود المهمة حقاً.
</Callout>

## مخرجات JSON

JSON (ترميز كائنات JavaScript) هو الشكل الأكثر شيوعاً للمخرجات المهيكلة من الذكاء الاصطناعي. إنه قابل للقراءة آلياً، مدعوم على نطاق واسع من لغات البرمجة، ومثالي لواجهات API، وقواعد البيانات، وسير عمل الأتمتة. المفتاح للحصول على JSON موثوق هو توفير مخطط واضح.

### طلب JSON أساسي

ابدأ بقالب يُظهر الهيكل الدقيق الذي تريده. ضمّن أسماء الحقول، وأنواع البيانات، وقيم المثال. هذا يعمل كعقد سيتبعه النموذج.

<TryIt 
  title="استخراج JSON"
  description="استخرج بيانات مهيكلة من نص غير مهيكل."
  prompt={`استخرج المعلومات من هذا النص وأرجعها كـ JSON:

{
    "company_name": "string",
    "founding_year": number,
    "headquarters": "string",
    "employees": number,
    "industry": "string"
}

النص: "شركة Apple Inc.، تأسست عام 1976، ومقرها في كوبرتينو، كاليفورنيا. توظف هذه الشركة التقنية العملاقة حوالي 164,000 شخص حول العالم."`}
/>

### هياكل JSON المعقدة

للبيانات المتداخلة، استخدم JSON هرمي مع كائنات داخل كائنات، ومصفوفات من الكائنات، وأنواع مختلطة. حدد كل مستوى بوضوح واستخدم تعليقات توضيحية بأسلوب TypeScript (`"positive" | "negative"`) لتقييد القيم.

```
حلل مراجعة هذا المنتج وأرجع JSON:

{
  "review_id": "string (generate unique)",
  "sentiment": {
    "overall": "positive" | "negative" | "mixed" | "neutral",
    "score": 0.0-1.0
  },
  "aspects": [
    {
      "aspect": "string (e.g., 'price', 'quality')",
      "sentiment": "positive" | "negative" | "neutral",
      "mentions": ["exact quotes from review"]
    }
  ],
  "purchase_intent": {
    "would_recommend": boolean,
    "confidence": 0.0-1.0
  },
  "key_phrases": ["string array of notable phrases"]
}

أرجع ONLY JSON صالح، بدون نص إضافي.

المراجعة: "[نص المراجعة]"
```

### ضمان JSON صالح

النماذج أحياناً تضيف نصاً توضيحياً أو تنسيق markdown حول JSON. امنع هذا بتعليمات صريحة حول شكل المخرجات. يمكنك طلب JSON خام أو JSON داخل كتل كود—اختر بناءً على احتياجات التحليل الخاصة بك.

أضف تعليمات صريحة:

```
IMPORTANT:
- أرجع ONLY كائن JSON، بدون كتل كود markdown
- تأكد من أن جميع السلاسل النصية محذوفة بشكل صحيح
- استخدم null للقيم المفقودة، وليس undefined
- تحقق من أن المخرجات قابلة للتحليل كـ JSON
```

أو اطلب كتل الكود بأن تطلب من النموذج تغليف مخرجاته:

````
أرجع النتيجة ككتلة كود JSON:
```json
{ ... }
```
````

## مخرجات YAML

YAML أكثر قابلية للقراءة البشرية من JSON، باستخدام المسافات البادئة بدلاً من الأقواس. إنه المعيار لملفات التكوين (Docker، Kubernetes، GitHub Actions) ويعمل جيداً عندما ستُقرأ المخرجات من قبل البشر أو تُستخدم في سياقات DevOps. YAML حساس للمسافات البادئة، لذا كن محدداً بشأن متطلبات التنسيق.

<TryIt 
  compact
  title="توليد YAML"
  prompt={`أنشئ سير عمل GitHub Actions لمشروع Node.js.

أرجعه كـ YAML صالح:
- تضمين: مراحل التثبيت، والفحص، والاختبار، والبناء
- استخدم Node.js 18
- تخزين مؤقت لاعتماديات npm
- تشغيل عند الدفع إلى main وطلبات السحب`}
/>

## مخرجات XML

XML لا يزال مطلوباً للعديد من أنظمة المؤسسات، وواجهات SOAP API، والتكاملات القديمة. إنه أكثر إسهاباً من JSON لكنه يوفر ميزات مثل السمات، ومساحات الأسماء، وأقسام CDATA للبيانات المعقدة. حدد أسماء العناصر، وهيكل التداخل، ومتى تستخدم السمات مقابل العناصر الفرعية.

```
حول هذه البيانات إلى تنسيق XML:

المتطلبات:
- العنصر الجذري: <catalog>
- كل عنصر في عنصر <book>
- تضمين السمات حيثما كان مناسباً
- استخدم CDATA لنص الوصف

البيانات: [بيانات الكتب]
```

## التنسيقات المخصصة

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

### تنسيق التحليل المهيكل

استخدم المحددات (===، ---، [SECTION]) لإنشاء مستندات قابلة للمسح مع حدود واضحة بين الأقسام. هذا التنسيق رائع لمراجعات الكود، والتدقيقات، والتحليلات.

```
حلل هذا الكود باستخدام هذا التنسيق بالضبط:

=== CODE ANALYSIS ===

[SUMMARY]
فقرة نظرة عامة واحدة

[ISSUES]
• CRITICAL: [المشكلة] — [الملف:السطر]
• WARNING: [المشكلة] — [الملف:السطر]  
• INFO: [المشكلة] — [الملف:السطر]

[METRICS]
التعقيد: [منخفض/متوسط/عالي]
قابلية الصيانة: [الدرجة]/10
تغطية الاختبار: [نسبة تقديرية %]

[RECOMMENDATIONS]
1. [توصية الأولوية 1]
2. [توصية الأولوية 2]

=== END ANALYSIS ===
```

### تنسيق ملء الفراغات

القوالب ذات الفراغات (___) توجه النموذج لملء حقول محددة مع الحفاظ على التنسيق الدقيق. هذا النهج ممتاز للنماذج، والموجزات، والمستندات الموحدة حيث يهم الاتساق.

```
أكمل هذا القالب للمنتج المُعطى:

PRODUCT BRIEF
─────────────
الاسم: _______________
الشعار: _______________
المستخدم المستهدف: _______________
المشكلة المحلولة: _______________
الميزات الرئيسية:
  1. _______________
  2. _______________
  3. _______________
المُميِّز: _______________

المنتج: [وصف المنتج]
```

## الاستجابات المُنمَّطة

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

<TryIt 
  compact
  title="استخراج الكيانات"
  prompt={`استخرج الكيانات من هذا النص.

أنواع الكيانات:
- PERSON: الأسماء الكاملة للأشخاص
- ORG: أسماء المنظمات/الشركات
- LOCATION: المدن، البلدان، العناوين
- DATE: التواريخ بتنسيق ISO (YYYY-MM-DD)
- MONEY: المبالغ المالية مع العملة

نسق كل واحدة كـ: [TYPE]: [القيمة]

النص: "أعلن تيم كوك أن Apple ستستثمر مليار دولار في منشأة جديدة في أوستن بحلول ديسمبر 2024."`}
/>

## الاستجابات المهيكلة متعددة الأجزاء

عندما تحتاج مخرجات شاملة تغطي جوانب متعددة، حدد أجزاء مميزة بحدود واضحة. حدد بالضبط ما يدخل في كل جزء—التنسيق، والطول، ونوع المحتوى. هذا يمنع النموذج من خلط الأقسام أو حذف أجزاء.

```
ابحث في هذا الموضوع وقدم:

### الجزء 1: الملخص التنفيذي
[نظرة عامة من 2-3 جمل]

### الجزء 2: النتائج الرئيسية
[بالضبط 5 نقاط]

### الجزء 3: جدول البيانات
| المقياس | القيمة | المصدر |
|--------|-------|--------|
[تضمين 5 صفوف كحد أدنى]

### الجزء 4: التوصيات
[قائمة مرقمة من 3 توصيات قابلة للتنفيذ]

### الجزء 5: قراءات إضافية
[3 موارد مقترحة مع أوصاف موجزة]
```

## التنسيق الشرطي

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

<TryIt 
  compact
  title="تصنيف التذاكر"
  prompt={`صنف تذكرة الدعم هذه.

إذا كانت URGENT (نظام معطل، مشكلة أمنية، فقدان بيانات):
  أرجع: 🔴 URGENT | [الفئة] | [الإجراء المقترح]

إذا كانت HIGH (تؤثر على مستخدمين متعددين، تأثير على الإيرادات):
  أرجع: 🟠 HIGH | [الفئة] | [الإجراء المقترح]

إذا كانت MEDIUM (مستخدم واحد متأثر، يوجد حل بديل):
  أرجع: 🟡 MEDIUM | [الفئة] | [الإجراء المقترح]

إذا كانت LOW (أسئلة، طلبات ميزات):
  أرجع: 🟢 LOW | [الفئة] | [الإجراء المقترح]

التذكرة: "لا أستطيع تسجيل الدخول إلى حسابي. حاولت إعادة تعيين كلمة المرور مرتين لكنني لا زلت أحصل على خطأ. هذا يمنع فريقي بالكامل من الوصول إلى لوحة التحكم."`}
/>

## المصفوفات والقوائم في JSON

استخراج عناصر متعددة إلى مصفوفات يتطلب تعريف مخطط دقيق. حدد هيكل المصفوفة، وما يجب أن يحتويه كل عنصر، وكيفية التعامل مع الحالات الحدية (المصفوفات الفارغة، العناصر المفردة). تضمين حقل العدد يساعد في التحقق من الاكتمال.

```
استخرج جميع بنود العمل من محضر هذا الاجتماع.

أرجع كمصفوفة JSON:
{
  "action_items": [
    {
      "task": "سلسلة تصف المهمة",
      "assignee": "اسم الشخص أو 'غير مُعيَّن'",
      "deadline": "التاريخ إذا ذُكر، وإلا null",
      "priority": "high" | "medium" | "low",
      "context": "اقتباس ذو صلة من المحضر"
    }
  ],
  "total_count": number
}

المحضر: "[محضر الاجتماع]"
```

## تعليمات التحقق

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

```
أنشئ التقرير، ثم:

قائمة التحقق:
□ جميع الأقسام المطلوبة موجودة
□ لا يوجد نص بديل متبقي
□ جميع الإحصائيات تتضمن مصادر
□ عدد الكلمات ضمن 500-700 كلمة
□ الخاتمة ترتبط بالمقدمة

إذا فشل أي فحص، أصلحه قبل الاستجابة.
```

## التعامل مع الحقول الاختيارية

البيانات الحقيقية غالباً ما تحتوي على قيم مفقودة. أوجه النموذج صراحةً حول كيفية التعامل مع الحقول الاختيارية—استخدام `null` أنظف من السلاسل الفارغة وأسهل في المعالجة برمجياً. أيضاً امنع "الهلوسة" للبيانات المفقودة بالتأكيد على أن النموذج يجب ألا يخترع معلومات أبداً.

```
استخرج معلومات الاتصال. استخدم null للحقول المفقودة.

{
  "name": "string (مطلوب)",
  "email": "string أو null",
  "phone": "string أو null", 
  "company": "string أو null",
  "role": "string أو null",
  "linkedin": "URL string أو null"
}

IMPORTANT: 
- لا تخترع أبداً معلومات غير موجودة في المصدر
- استخدم null، وليس السلاسل الفارغة، للبيانات المفقودة
- أرقام الهواتف بتنسيق E.164 إن أمكن
```

## الملخص

<Callout type="tip" title="التقنيات الرئيسية">
كن صريحاً بشأن التنسيق، استخدم الأمثلة، حدد الأنواع، تعامل مع الحالات الحدية بقيم null، واطلب من النموذج التحقق من مخرجاته.
</Callout>

<Quiz 
  question="ما هي الميزة الرئيسية للمخرجات المهيكلة مقارنة بالنص غير المهيكل؟"
  options={[
    "تستخدم عدداً أقل من الرموز",
    "أسهل للذكاء الاصطناعي في توليدها",
    "يمكن تحليلها برمجياً والتحقق منها",
    "تنتج دائماً معلومات صحيحة"
  ]}
  correctIndex={2}
  explanation="المخرجات المهيكلة مثل JSON يمكن تحليلها بالكود، ومقارنتها عبر الاستعلامات، ودمجها في سير العمل، والتحقق من اكتمالها—أشياء صعبة أو مستحيلة مع النص الحر."
/>

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