أوامر JSON و YAML

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

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

interface ChatPersona {
  name?: string;
  role?: string;
  tone?: PersonaTone | PersonaTone[];
  expertise?: PersonaExpertise[];
  personality?: string[];
  background?: string;
}

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

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

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

أعطني معلومات المستخدم بصيغة JSON.

استخرج معلومات المستخدم بصيغة JSON وفق هذا المخطط:

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

أرجع JSON صالح فقط، بدون markdown.

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

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

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

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

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

المخرج:

{
  "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

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

هام جداً: أرجع 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

المخرج:

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 مألوفة للمطورين وتصف بدقة الحقول الاختيارية وأنواع الاتحاد والمصفوفات. تستخدم منصة halaGPT هذا النهج للموجّهات المُهيكلة.

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

يوفر 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

صنّف هذا النص إلى فئة.

{
  "category": "string"
}

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

{
  "category": "إحدى القيم أعلاه"
}

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: [نص المراجعة]

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

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

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

استخرج جميع تفاصيل الشركة بصيغة JSON:
{
  "revenue": number,
  "employees": number
}

استخرج تفاصيل الشركة. استخدم null لأي حقل غير مذكور صراحة. لا تختلق أو تُقدّر القيم.

{
  "revenue": "number أو null",
  "employees": "number أو null"
}

قيم 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."

المخرج:

{
  "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

أنشئ ملف docker-compose لتطبيقي.

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

تضمين: فحوصات الصحة، استمرارية الأقراص، البيئة من ملف .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: متى تستخدم أيهما

الموجّهات المُهيكلة في halaGPT

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

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

Type: STRUCTURED
Format: JSON أو YAML

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

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

1. كتل كود Markdown

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

الحل:

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

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

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

الحل:

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

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

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

الحل:

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

الملخص

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