كيفية كتابة Prompt برمجي للحصول على نتائج ثابتة JSON

الحصول على مخرجات ثابتة من النماذج اللغوية لم يعد رفاهية، بل ضرورة عملية لكل من يبني أدوات أتمتة، خطوط معالجة بيانات، أو تطبيقات تعتمد على AI APIs. المشكلة أن كثيراً من المطورين يكتبون Prompt عاماً، ثم يتفاجؤون بأن الرد يتغير في البنية، أو يضيف شرحاً خارج التنسيق المطلوب، فيتعطل السكربت بالكامل.

عندما يكون هدفك إنتاج كائن JSON صالحاً للمعالجة البرمجية، فإن نجاحك لا يعتمد فقط على “ذكاء النموذج”، بل على دقة تصميم التعليمات، وحدود الحقول، وآلية التحقق بعد الاستجابة. لهذا السبب يرتبط هذا الموضوع مباشرة بمقال أساسيات التعامل مع ملفات JSON (لغة التفاهم بين الأنظمة) وبفهم مفهوم الـ API: كيف نطلب البيانات من Google وOpenAI.

لماذا يفشل Prompt في إنتاج JSON ثابت؟

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

في مشاريع الأتمتة، هذا السلوك كارثي. إذا كنت تبني نظاماً يسحب الرد ثم يمرره إلى parser أو إلى Google Sheets أو قاعدة بيانات، فإن أي اختلاف بسيط في البنية قد يفشل المهمة بالكامل. وهنا تظهر أهمية التفكير وفق منطق البرمجة المعتمد على المهام (Task-Oriented Programming) لا وفق المحادثة الحرة.

القاعدة الذهبية: لا تطلب “إجابة”، بل اطلب “بنية”

أفضل Prompt برمجي هو الذي يصف شكل المخرجات قبل مضمونها. بمعنى آخر، أنت لا تقول للنموذج “حلل هذا النص”، بل تقول: “أعد النتيجة في كائن JSON بالمفاتيح التالية، وبأنواع بيانات محددة، وبدون أي نص خارج الكائن”.

هذه النقطة هي الفاصل بين استخدام تجريبي واستخدام إنتاجي production-ready. وكلما اقتربت من تعريف عقد بيانات واضح data contract زادت ثبات النتائج.

المكونات الأساسية لأي Prompt ثابت

1) تحديد الدور بدقة

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

2) تعريف المهمة في سطر مباشر

صف المطلوب بجملة تنفيذية واضحة، مثل: “استخرج الكيانات من النص التالي”، أو “صنف الكلمة المفتاحية حسب نية البحث”. إذا كنت تعمل في السياق العملي، فستجد ذلك مشابهاً لما نطبقه في كود لتصنيف الكلمات المفتاحية حسب نية البحث (Search Intent).

3) فرض مخطط إخراج واضح

اكتب أسماء المفاتيح المطلوبة وأنواعها وقيمها المتوقعة. لا تكتفِ بعرض مثال؛ بل اشرح إن كان الحقل نصياً string أو رقمياً integer أو قائمة array.

4) منع أي نص إضافي

من أهم الأسطر التي يجب ألا تغيب: “أعد JSON فقط بدون شرح أو مقدمة أو تنسيق Markdown”. هذه العبارة وحدها تقلل نسبة الأخطاء بشكل ملحوظ.

5) تعريف قواعد الفشل

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

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

قالب عملي لكتابة Prompt احترافي

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

أنت نظام استخراج بيانات منضبط.
المهمة: حلل الإدخال وأعد النتيجة في كائن JSON فقط.
القواعد:
1. لا تضف أي شرح أو نص خارج JSON.
2. استخدم هذه المفاتيح فقط: title, intent, confidence.
3. يجب أن تكون confidence رقماً من 0 إلى 1.
4. إذا لم يمكن تحديد النية بدقة، أعد القيمة null.
5. الإدخال سيأتي كنص خام.

كيف تطبق ذلك برمجياً في Python؟

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

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

prompt = """
أنت نظام استخراج بيانات منضبط.
أعد JSON فقط بدون أي شرح أو Markdown.
استخدم المفاتيح التالية فقط:
- title: string
- intent: string or null
- confidence: float
إذا تعذر تحديد intent فأعد null.
"""

user_input = "أفضل أدوات تحليل الكلمات المفتاحية للمواقع الجديدة"

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    temperature=0,
    messages=[
        {"role": "system", "content": prompt},
        {"role": "user", "content": user_input}
    ]
)

raw_text = response.choices[0].message.content.strip()

try:
    data = json.loads(raw_text)
    assert "title" in data
    assert "intent" in data
    assert "confidence" in data
    print("Valid JSON:", data)
except Exception as e:
    print("Parsing failed:", e)
    print("Raw output:", raw_text)

لاحظ هنا استخدام temperature=0 لتقليل التباين، ثم استخدام json.loads() للتحقق من صحة التنسيق. هذه الخطوة لا غنى عنها في أي بيئة أتمتة حقيقية.

استراتيجيات تجعل النتائج أكثر ثباتاً

• استخدم مخططاً ثابتاً للمفاتيح ولا تغيّره بين الطلبات.
• قلل الحرية اللغوية عبر تعليمات موجزة ومباشرة.
• اضبط temperature إلى قيمة منخفضة عند الحاجة للاتساق.
• أضف أمثلة قليلة few-shot examples إذا كانت المهمة معقدة.
• افصل بين تعليمات النظام وبين بيانات المستخدم.
• تحقق دائماً من الأنواع والقيم بعد الاستجابة، لا تثق بالرد الخام وحده.

هذه المبادئ مفيدة جداً في مشاريع السيو المؤتمتة، خصوصاً عندما تربط النتائج لاحقاً مع استخدام مكتبة Pandas لتحليل بيانات الـ SEO الضخمة أو تبني تقارير ولوحات عبر بناء “Dashboard” تفاعلي لبيانات الموقع باستخدام Google Looker Studio.

أخطاء شائعة يجب تجنبها

الخطأ الأول: طلب “أفضل تنسيق ممكن”

هذه العبارة تمنح النموذج حرية غير مرغوبة. الأفضل هو فرض تنسيق واحد فقط بلا بدائل.

الخطأ الثاني: عدم تحديد نوع كل حقل

إذا لم تقل إن الحقل رقم أو نص أو قائمة، فقد تحصل على بنى متغيرة بين استجابة وأخرى.

الخطأ الثالث: تجاهل مرحلة التحقق البرمجي

حتى أفضل Prompt لا يغني عن التحقق عبر validation. في البيئات الإنتاجية، من الأفضل إعادة المحاولة أو تسجيل الخطأ إن فشل التحليل.

الخطأ الرابع: مزج التعليمات مع المحتوى الخام

كلما اختلطت القواعد بمدخلات المستخدم، زادت احتمالية سوء الفهم. افصلها دائماً داخل رسائل منظمة أو متغيرات مستقلة.

إذا كان الرد سيُستهلك برمجياً، فاعتبر أي جملة خارج JSON خطأً يجب منعه لا “تحسيناً” في تجربة القراءة.

متى تحتاج إلى طبقة تحقق إضافية؟

كلما ارتفعت حساسية المشروع، احتجت إلى طبقة تحقق أقوى. مثلاً، في أدوات استخراج بيانات من صفحات كثيرة أو دمج النتائج في أنظمة خارجية مثل كيفية ربط Google Sheets بالعالم الخارجي عبر Script، ينبغي فحص الحقول المطلوبة، واختبار القيم الفارغة، وتسجيل الرد الخام عند الفشل للمراجعة اللاحقة.

كما أن المشاريع الأكبر التي تجمع بين الأتمتة والسيو، مثل تحليل الكلمات، مراقبة الصفحات، أو بناء أنظمة تقارير، تستفيد من هذا النهج بنفس القدر الذي تستفيد به من المقال التأسيسي مدخل إلى عالم أتمتة الـ SEO: لماذا الآن؟.

الخلاصة

كتابة Prompt برمجي للحصول على نتائج ثابتة في JSON ليست مهارة لغوية فقط، بل هي تصميم واجهة تعاقدية بين النموذج وسكربتك. كلما حددت الدور، والمهمة، والمفاتيح، والأنواع، وحالات الفشل، أصبحت مخرجاتك أكثر قابلية للاعتماد والأتمتة.

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