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

<Callout type="info" title="من النص إلى البيانات">
يُحوّل JSON و YAML مخرجات الذكاء الاصطناعي من نص حر إلى بيانات مُهيكلة وآمنة الأنواع يمكن للكود استهلاكها مباشرة.
</Callout>

## لماذا الصيغ المُهيكلة؟

<JsonYamlDemo />

## أساسيات التوجيه بصيغة JSON

JSON (ترميز كائنات JavaScript) هي الصيغة الأكثر شيوعاً للمخرجات البرمجية من الذكاء الاصطناعي. تركيبها الصارم يجعل تحليلها سهلاً، لكنه يعني أيضاً أن الأخطاء الصغيرة يمكن أن تُعطّل خط الأنابيب بالكامل.

### ما يجب فعله وما يجب تجنبه: طلب JSON

<Compare 
  before={{ label: "❌ لا تفعل: طلب غامض", content: "أعطني معلومات المستخدم بصيغة JSON." }}
  after={{ label: "✓ افعل: أظهر المخطط", content: "استخرج معلومات المستخدم بصيغة JSON وفق هذا المخطط:\n\n{\n  \"name\": \"string\",\n  \"age\": number,\n  \"email\": \"string\"\n}\n\nأرجع JSON صالح فقط، بدون markdown." }}
/>

### مخرجات JSON البسيطة

ابدأ بمخطط يُظهر البنية المتوقعة. سيملأ النموذج القيم بناءً على النص المُدخل.

```
استخرج المعلومات التالية بصيغة JSON:

{
  "name": "string",
  "age": number,
  "email": "string"
}

Text: "Contact John Smith, 34 years old, at john@example.com"
```

المخرج:
```json
{
  "name": "John Smith",
  "age": 34,
  "email": "john@example.com"
}
```

### بنى JSON المتداخلة

غالباً ما تحتوي البيانات الواقعية على علاقات متداخلة. حدّد كل مستوى من مخططك بوضوح، خاصة لمصفوفات الكائنات.

```
حلّل هذا الطلب إلى JSON:

{
  "order_id": "string",
  "customer": {
    "name": "string",
    "email": "string"
  },
  "items": [
    {
      "product": "string",
      "quantity": number,
      "price": number
    }
  ],
  "total": number
}

Order: "Order #12345 for Jane Doe (jane@email.com): 2x Widget ($10 each), 
1x Gadget ($25). Total: $45"
```

### ضمان صحة JSON

<Callout type="warning" title="نقطة فشل شائعة">
غالباً ما تُغلّف النماذج JSON في كتل كود markdown أو تُضيف نصاً توضيحياً. كن صريحاً في طلب JSON الخام فقط.
</Callout>

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

```
هام جداً: أرجع JSON صالح فقط. بدون markdown، بدون شرح،
بدون نص إضافي قبل أو بعد كائن JSON.

إذا تعذّر تحديد حقل ما، استخدم null.
تأكد من أن جميع النصوص محاطة بعلامات اقتباس ومُهرّبة بشكل صحيح.
الأرقام يجب ألا تكون محاطة بعلامات اقتباس.
```

## أساسيات التوجيه بصيغة YAML

YAML أكثر قابلية للقراءة البشرية من JSON وتدعم التعليقات. وهي المعيار لملفات التكوين، خاصة في DevOps (Docker، Kubernetes، GitHub Actions).

### مخرجات YAML البسيطة

تستخدم YAML المسافات البادئة بدلاً من الأقواس. قدّم قالباً يُظهر البنية المتوقعة.

```
أنشئ ملف تكوين بصيغة YAML:

server:
  host: string
  port: number
  ssl: boolean
database:
  type: string
  connection_string: string

المتطلبات: خادم إنتاج على المنفذ 443 مع SSL، قاعدة بيانات PostgreSQL
```

المخرج:
```yaml
server:
  host: "0.0.0.0"
  port: 443
  ssl: true
database:
  type: "postgresql"
  connection_string: "postgresql://user:pass@localhost:5432/prod"
```

### بنى YAML المعقدة

للتكوينات المعقدة، كن محدداً بشأن المتطلبات. يعرف النموذج الأنماط الشائعة لأدوات مثل GitHub Actions و Docker Compose و Kubernetes.

```
أنشئ سير عمل GitHub Actions بصيغة YAML:

المتطلبات:
- التشغيل عند الدفع إلى main وطلبات السحب
- التشغيل على أحدث إصدار من Ubuntu
- الخطوات: checkout، إعداد Node 18، تثبيت التبعيات، تشغيل الاختبارات
- تخزين تبعيات npm مؤقتاً
```

## تعريفات الأنواع في الموجّهات

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

### استخدام أنواع شبيهة بـ TypeScript

واجهات TypeScript مألوفة للمطورين وتصف بدقة الحقول الاختيارية وأنواع الاتحاد والمصفوفات. تستخدم منصة prompts.chat هذا النهج للموجّهات المُهيكلة.

<TryIt 
  title="استخراج بواجهة TypeScript"
  description="استخدم واجهة TypeScript لاستخراج بيانات مُهيكلة."
  prompt={`Extract data according to this type definition:

interface ChatPersona {
    name?: string;
    role?: string;
    tone?: "professional" | "casual" | "friendly" | "technical";
    expertise?: string[];
    personality?: string[];
    background?: string;
}

Return as JSON matching this interface.

Description: "A senior software engineer named Alex who reviews code. They're analytical and thorough, with expertise in backend systems and databases. Professional but approachable tone."`}
/>

### تعريف JSON Schema

<Callout type="info" title="معيار صناعي">
JSON Schema هو مواصفة رسمية لوصف بنية JSON. وهو مدعوم من قِبل العديد من مكتبات التحقق وأدوات API.
</Callout>

يوفر JSON Schema قيوداً مثل القيم الدنيا/القصوى والحقول المطلوبة وأنماط regex:

```
استخرج البيانات وفق JSON Schema هذا:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["title", "author", "year"],
  "properties": {
    "title": { "type": "string" },
    "author": { "type": "string" },
    "year": { "type": "integer", "minimum": 1000, "maximum": 2100 },
    "genres": { 
      "type": "array", 
      "items": { "type": "string" }
    },
    "rating": { 
      "type": "number", 
      "minimum": 0, 
      "maximum": 5 
    }
  }
}

Book: "1984 by George Orwell (1949) - A dystopian masterpiece. 
Genres: Science Fiction, Political Fiction. Rated 4.8/5"
```

## التعامل مع المصفوفات

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

### المصفوفات ذات الطول الثابت

عندما تحتاج بالضبط N عنصر، اذكر ذلك صراحة. سيضمن النموذج أن المصفوفة بالطول الصحيح.

```
استخرج بالضبط 3 نقاط رئيسية بصيغة JSON:

{
  "key_points": [
    "string (النقطة الأولى)",
    "string (النقطة الثانية)", 
    "string (النقطة الثالثة)"
  ]
}

Article: [نص المقال]
```

### المصفوفات متغيرة الطول

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

```
استخرج جميع الأشخاص المذكورين بصيغة JSON:

{
  "people": [
    {
      "name": "string",
      "role": "string أو null إذا لم يُذكر"
    }
  ],
  "count": number
}

إذا لم يُذكر أي شخص، أرجع مصفوفة فارغة.

Text: [النص]
```

## قيم Enum والقيود

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

### ما يجب فعله وما يجب تجنبه: قيم Enum

<Compare 
  before={{ label: "❌ لا تفعل: فئات مفتوحة", content: "صنّف هذا النص إلى فئة.\n\n{\n  \"category\": \"string\"\n}" }}
  after={{ label: "✓ افعل: قيّد إلى قيم صالحة", content: "صنّف هذا النص. الفئة يجب أن تكون بالضبط واحدة من:\n- \"technical\"\n- \"business\"\n- \"creative\"\n- \"personal\"\n\n{\n  \"category\": \"إحدى القيم أعلاه\"\n}" }}
/>

### Enum النصية

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

```
صنّف هذا النص. الفئة يجب أن تكون واحدة من هذه القيم بالضبط:
- "technical"
- "business" 
- "creative"
- "personal"

أرجع JSON:
{
  "text": "النص الأصلي (مقتطع إلى 50 حرف)",
  "category": "إحدى قيم enum أعلاه",
  "confidence": رقم بين 0 و 1
}

Text: [النص المراد تصنيفه]
```

### الأرقام المُتحقق منها

تمنع القيود الرقمية القيم خارج النطاق. حدّد النوع (integer مقابل float) والنطاق الصالح.

```
قيّم هذه الجوانب. كل درجة يجب أن تكون integer من 1 إلى 5.

{
  "quality": 1-5,
  "value": 1-5,
  "service": 1-5,
  "overall": 1-5
}

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

## التعامل مع البيانات المفقودة

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

### ما يجب فعله وما يجب تجنبه: المعلومات المفقودة

<Compare 
  before={{ label: "❌ لا تفعل: دع الذكاء الاصطناعي يخمّن", content: "استخرج جميع تفاصيل الشركة بصيغة JSON:\n{\n  \"revenue\": number,\n  \"employees\": number\n}" }}
  after={{ label: "✓ افعل: اسمح صراحة بـ null", content: "استخرج تفاصيل الشركة. استخدم null لأي حقل غير مذكور صراحة. لا تختلق أو تُقدّر القيم.\n\n{\n  \"revenue\": \"number أو null\",\n  \"employees\": \"number أو null\"\n}" }}
/>

### قيم Null

اسمح صراحة بـ null وأوعز للنموذج بعدم اختلاق المعلومات. هذا أكثر أماناً من جعل النموذج يخمّن.

```
استخرج المعلومات. استخدم null لأي حقل لا يمكن
تحديده من النص. لا تختلق المعلومات.

{
  "company": "string أو null",
  "revenue": "number أو null",
  "employees": "number أو null",
  "founded": "number (السنة) أو null",
  "headquarters": "string أو null"
}

Text: "Apple, headquartered in Cupertino, was founded in 1976."
```

المخرج:
```json
{
  "company": "Apple",
  "revenue": null,
  "employees": null,
  "founded": 1976,
  "headquarters": "Cupertino"
}
```

### القيم الافتراضية

عندما تكون القيم الافتراضية منطقية، حدّدها في المخطط. هذا شائع لاستخراج التكوينات.

```
استخرج الإعدادات مع هذه القيم الافتراضية إذا لم تُحدد:

{
  "theme": "light" (افتراضي) | "dark",
  "language": "en" (افتراضي) | رمز ISO آخر,
  "notifications": true (افتراضي) | false,
  "fontSize": 14 (افتراضي) | number
}

تفضيلات المستخدم: "أريد الوضع الداكن ونص أكبر (18px)"
```

## استجابات الكائنات المتعددة

غالباً ما تحتاج إلى استخراج عناصر متعددة من مدخل واحد. حدّد بنية المصفوفة وأي متطلبات للترتيب/التجميع.

### مصفوفة من الكائنات

لقوائم العناصر المتشابهة، حدّد مخطط الكائن مرة واحدة وحدّد أنها مصفوفة.

```
حلّل هذه القائمة إلى مصفوفة JSON:

[
  {
    "task": "string",
    "priority": "high" | "medium" | "low",
    "due": "نص تاريخ ISO أو null"
  }
]

قائمة المهام:
- إنهاء التقرير (عاجل، موعد التسليم غداً)
- الاتصال بطبيب الأسنان (أولوية منخفضة)
- مراجعة PR #123 (متوسط، موعد التسليم الجمعة)
```

### الكائنات المُجمّعة

تتطلب مهام التجميع منطق تصنيف. سيُرتّب النموذج العناصر في الفئات التي تُحدّدها.

```
صنّف هذه العناصر إلى JSON:

{
  "fruits": ["مصفوفة نصية"],
  "vegetables": ["مصفوفة نصية"],
  "other": ["مصفوفة نصية"]
}

العناصر: apple, carrot, bread, banana, broccoli, milk, orange, spinach
```

## YAML لتوليد التكوينات

تتألق YAML في تكوينات DevOps. يعرف النموذج الأنماط القياسية للأدوات الشائعة ويمكنه توليد تكوينات جاهزة للإنتاج.

### ما يجب فعله وما يجب تجنبه: تكوينات YAML

<Compare 
  before={{ label: "❌ لا تفعل: متطلبات غامضة", content: "أنشئ ملف docker-compose لتطبيقي." }}
  after={{ label: "✓ افعل: حدّد المكونات والاحتياجات", content: "أنشئ docker-compose.yml لـ:\n- تطبيق Node.js (المنفذ 3000)\n- قاعدة بيانات PostgreSQL\n- ذاكرة Redis المؤقتة\n\nتضمين: فحوصات الصحة، استمرارية الأقراص، البيئة من ملف .env" }}
/>

### Docker Compose

حدّد الخدمات التي تحتاجها وأي متطلبات خاصة. سيتولى النموذج تركيب YAML وأفضل الممارسات.

```
أنشئ docker-compose.yml لـ:
- تطبيق Node.js على المنفذ 3000
- قاعدة بيانات PostgreSQL
- ذاكرة Redis المؤقتة
- وكيل Nginx العكسي

تضمين:
- فحوصات الصحة
- استمرارية الأقراص
- متغيرات البيئة من ملف .env
- عزل الشبكة
```

### ملفات Kubernetes Manifests

ملفات Kubernetes manifests مُطوّلة لكنها تتبع أنماطاً يمكن التنبؤ بها. قدّم المعاملات الرئيسية وسيُولّد النموذج YAML متوافقة.

```
أنشئ YAML لنشر Kubernetes:

Deployment:
- الاسم: api-server
- الصورة: myapp:v1.2.3
- النسخ المتماثلة: 3
- الموارد: ذاكرة 256Mi، وحدة معالجة 250m (الطلبات)
- فحوصات الصحة: نقطة النهاية /health
- البيئة من ConfigMap: api-config

أنشئ أيضاً Service مطابقة (ClusterIP، المنفذ 8080)
```

## التحقق ومعالجة الأخطاء

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

### موجّه التحقق الذاتي

اطلب من النموذج التحقق من مخرجاته مقابل القواعد التي تُحدّدها. هذا يلتقط أخطاء الصيغة والقيم غير الصالحة.

```
استخرج البيانات بصيغة JSON، ثم تحقق من مخرجاتك.

المخطط:
{
  "email": "صيغة بريد إلكتروني صالحة",
  "phone": "صيغة E.164 (+1234567890)",
  "date": "صيغة ISO 8601 (YYYY-MM-DD)"
}

بعد توليد JSON، تحقق من:
1. البريد الإلكتروني يحتوي @ ونطاق صالح
2. الهاتف يبدأ بـ + ويحتوي أرقام فقط
3. التاريخ صالح وقابل للتحليل

إذا فشل التحقق، أصلح المشكلات قبل الرد.

Text: [معلومات الاتصال]
```

### صيغة استجابة الخطأ

حدّد صيغ نجاح وخطأ منفصلة. هذا يجعل المعالجة البرمجية أسهل بكثير.

```
حاول استخراج البيانات. إذا فشل الاستخراج، أرجع صيغة الخطأ:

صيغة النجاح:
{
  "success": true,
  "data": { ... البيانات المستخرجة ... }
}

صيغة الخطأ:
{
  "success": false,
  "error": "وصف ما حدث خطأ",
  "partial_data": { ... أي بيانات يمكن استخراجها ... }
}
```

## JSON مقابل YAML: متى تستخدم أيهما

<div className="my-4 grid md:grid-cols-2 gap-4">
  <div className="p-4 bg-amber-50 dark:bg-amber-950/30 rounded-lg border border-amber-200 dark:border-amber-800">
    <div className="font-semibold text-amber-700 dark:text-amber-300 mb-2">استخدم JSON عندما</div>
    <div className="text-sm space-y-1">
      <p className="m-0!">التحليل البرمجي مطلوب</p>
      <p className="m-0!">استجابات API</p>
      <p className="m-0!">متطلبات أنواع صارمة</p>
      <p className="m-0!">تكامل JavaScript/الويب</p>
      <p className="m-0!">تمثيل مُدمج</p>
    </div>
  </div>
  <div className="p-4 bg-purple-50 dark:bg-purple-950/30 rounded-lg border border-purple-200 dark:border-purple-800">
    <div className="font-semibold text-purple-700 dark:text-purple-300 mb-2">استخدم YAML عندما</div>
    <div className="text-sm space-y-1">
      <p className="m-0!">القابلية للقراءة البشرية مهمة</p>
      <p className="m-0!">ملفات التكوين</p>
      <p className="m-0!">التعليقات مطلوبة</p>
      <p className="m-0!">DevOps/البنية التحتية</p>
      <p className="m-0!">البنى المتداخلة العميقة</p>
    </div>
  </div>
</div>

## الموجّهات المُهيكلة في Prompts.chat

على prompts.chat، يمكنك إنشاء موجّهات بصيغ مخرجات مُهيكلة:

```
عند إنشاء موجّه على prompts.chat، يمكنك تحديد:

Type: STRUCTURED
Format: JSON أو YAML

ستقوم المنصة بـ:
- التحقق من المخرجات مقابل مخططك
- توفير تمييز بناء الجملة
- تمكين النسخ السهل للمخرجات المُهيكلة
- دعم متغيرات القالب في مخططك
```

## المزالق الشائعة

<Callout type="warning" title="تصحيح هذه أولاً">
تتسبب هذه المشكلات الثلاث في معظم فشل تحليل JSON. تحقق منها عندما لا يستطيع كودك تحليل مخرجات الذكاء الاصطناعي.
</Callout>

### 1. كتل كود Markdown

**المشكلة:** يُغلّف النموذج JSON في كتل ```json

**الحل:** 
```
أرجع كائن JSON فقط. لا تُغلّفه في كتل كود markdown.
لا تُضمّن علامات ```json أو ```.
```

### 2. الفواصل الزائدة

**المشكلة:** JSON غير صالح بسبب الفواصل الزائدة

**الحل:**
```
تأكد من صحة تركيب JSON. لا فواصل زائدة بعد العنصر
الأخير في المصفوفات أو الكائنات.
```

### 3. النصوص غير المُهرّبة

**المشكلة:** علامات الاقتباس أو الأحرف الخاصة تُعطّل JSON

**الحل:**
```
هرّب الأحرف الخاصة في النصوص بشكل صحيح:
- \" لعلامات الاقتباس
- \\ للشرطات المائلة العكسية
- \n للأسطر الجديدة
```

## الملخص

<Callout type="tip" title="التقنيات الرئيسية">
حدّد المخططات صراحة باستخدام واجهات TypeScript أو JSON Schema. حدّد الأنواع والقيود، تعامل مع null والقيم الافتراضية، اطلب التحقق الذاتي، واختر الصيغة المناسبة لحالة الاستخدام.
</Callout>

<Quiz 
  question="متى يجب تفضيل YAML على JSON لمخرجات الذكاء الاصطناعي؟"
  options={[
    "عند بناء واجهات REST APIs",
    "عندما يحتاج المخرج أن يكون قابلاً للقراءة البشرية وقد يتضمن تعليقات",
    "عند العمل مع تطبيقات JavaScript",
    "عندما تحتاج التمثيل الأكثر إدماجاً"
  ]}
  correctIndex={1}
  explanation="يُفضّل YAML عندما تكون القابلية للقراءة البشرية مهمة، مثل ملفات التكوين وملفات DevOps manifests والتوثيق. كما أنها تدعم التعليقات، على عكس JSON."
/>

هذا يُكمل الجزء الثاني حول التقنيات. في الجزء الثالث، سنستكشف التطبيقات العملية عبر مجالات مختلفة.
