انتقل إلى المحتوى الرئيسي

الوحدة 10 — مكتبة تعليمات قابلة لإعادة الاستخدام

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

القالب والمتغيّرات: أوّل خطوة نحو المكتبة​

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

# templates/extraction_email.txt
أنت مساعد استخراج بيانات لخدمة عملاء {entreprise}.

تُعيد JSON بالحقول: sujet, produit, urgence, action.
sujet ∈ {sujets_valides}
urgence ∈ {niveaux_urgence}

قواعد اللغة:
- أعِد الجواب بالعربية الفصحى الحديثة.
- الحقول الغائبة كـ null، لا كسلاسل فارغة.

{% for exemple in exemples %}
المُدخَل: «{{ exemple.entree }}»
المُخرَج: {{ exemple.sortie | tojson }}
{% endfor %}

نُحمِّل القالب في الشيفرة عبر مكتبة مثل jinja2:

from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader("templates"))
template = env.get_template("extraction_email.txt")

systeme = template.render(
    entreprise="أثاث الشرق",
    sujets_valides="{retard, defaut, facture, autre}",
    niveaux_urgence="{faible, moyenne, haute}",
    exemples=EXEMPLES_STANDARD,
)

الفصل يُتيح تحديث القالب دون لمس الشيفرة، ويُتيح إعادة استعمال نفس القالب لعدّة عملاء بتغيير المتغيّرات، ويُظهر بنية التعليمة بوضوح لمن يقرؤها.

نظام النُسَخ: كلّ تعديل يُوثَّق​

التعليمة كود. الكود يعيش في git. القاعدة قصيرة وحاسمة: تعليماتك في مستودع مصادر، لا في ملفّات متناثرة.

كلّ تعليمة تحمل رقم نسخة صريح:

templates/
  extraction_email/
    v1.txt        # الأولى، بلا أمثلة
    v2.txt        # + few-shot
    v3.txt        # + قواعد اللغة
    v4.txt        # + مقاومة الحقن
    current -> v4.txt

الاختيار بين النُسَخ يمرّ عبر متغيّر بيئة أو ملفّ إعداد:

NOM_PROMPT = os.environ.get("PROMPT_EXTRACTION_VERSION", "v4")
template = env.get_template(f"extraction_email/{NOM_PROMPT}.txt")

الفائدة الحاسمة: يمكن تشغيل نسختين في الإنتاج (A/B test) على شرائح من المستخدمين، ومقارنة نتائجهما الحقيقيّة. الوحدة 9 أعطتنا التقييم قبل النشر؛ نظام النُسَخ يُعطينا التقييم في الإنتاج.

توثيق سياق الاستعمال: README لكلّ تعليمة​

تعليمة بلا وثيقة تشرحها ستُساء استخدامها بعد أسبوعين. اجعل كلّ تعليمة تصحبها بطاقة قصيرة تجيب على الأسئلة:

# templates/extraction_email/README.md

## الهدف
استخراج الحقول المنظَّمة من رسالة شكوى عميل باللغة العربية.

## المُدخَل المتوقَّع
نصّ رسالة بريد إلكتروني، بين 20 و2000 حرف، فصحى أو دارجة.

## المُخرَج
JSON مطابق للمُخطَّط `ExtractionEmail` في `models/extraction.py`.

## غير مناسبة لـ
- رسائل بلغة غير العربية (استخدم templates/extraction_email_en/).
- محادثات متعدّدة الأدوار (استخدم templates/extraction_conversation/).
- استخراج معلومات دفع أو بطاقات ائتمان (سبب أمني).

## المقاييس على `jeu_test_v3.jsonl`
- sujet: 96%
- urgence: 89%
- produit: 87%
- action (حكم LLM): 91%

## آخر تحديث: 2026-09-05 بواسطة a.hassan.

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

مراجعة الأقران: التعليمة ليست ملكيّة شخصيّة​

في فِرَق تعمل بجدّية، لا تدخل تعليمة إلى الإنتاج دون مراجعة قرين واحد على الأقلّ. أسباب هذا:

  • قراءة ثانية تكشف غموضًا لم يره المؤلّف.
  • معرفة موزَّعة: أكثر من شخص يعرف كلّ تعليمة، فإن غاب المؤلّف لم يشلّ النظام.
  • قاعدة لسياسات مشتركة: تعليمات لا تحوي أسرارًا، تعليمات تفصل بين نظام ومستخدم، تعليمات تحدّد اللغة صراحة… كلّها تنتشر عبر المراجعة.

نموذج مراجعة عملي، على شكل قائمة تحقّق (checklist):

[ ] المهمّة صريحة في السطر الأوّل من تعليمة النظام.
[ ] القيود قابلة للقياس، لا صفات مبهمة.
[ ] الشكل المطلوب محدَّد صراحةً (JSON، مخطَّط، عدد جُمَل).
[ ] الأمثلة، إن وُجدت، تُغطّي حالة `null` وحالة الأصناف كلّها.
[ ] لا أسرار (مفاتيح، أسماء داخلية، عناوين URL خاصّة) في التعليمة.
[ ] فواصل واضحة لبيانات المستخدم (مقاومة الحقن).
[ ] لغة التعليمة = لغة الجواب المتوقَّع.
[ ] رقم نسخة صريح؛ بطاقة README محدَّثة.
[ ] جملة اختبار مُرِّرت؛ مقاييس مرفقة بطلب المراجعة.

هذه القائمة تُلصَق بقالب طلب المراجعة (pull request template)، فتصير المراجعة موحَّدة وسريعة.

الحوكمة: من يُقرِّر ماذا​

في فريق يعدّ عشرات الأشخاص وعشرات التعليمات، الفوضى تصير عاجلة. مبادئ حوكمة تعمل:

  • مالك لكلّ تعليمة: شخص واحد مسؤول عن التحديث والتقييم. قد يتغيّر، لكنّ الحقل لا يفرغ أبدًا.
  • دورة مراجعة دوريّة: كلّ تعليمة تُراجَع بالكامل مرّة كلّ ثلاثة أشهر، حتّى لو لم تتغيّر. النماذج تتغيّر، وسلوك التعليمة يتغيّر معها.
  • تعليمات حرِجة تحت رقابة إضافيّة: أيّ تعليمة تُنفَّذ في سياقات ذات أثر مالي، أو تحوي بيانات شخصيّة، تخضع لمراجعة أمنيّة قبل النشر.
  • سجلّ التغييرات: ملفّ CHANGELOG.md لكلّ تعليمة يُوثِّق ما تغيّر ولماذا، لا فقط ما تغيّر.

التعليمات الفنّية مقابل التعليمات المرئيّة للمستخدم​

تمييز مفيد في نهاية الرحلة: بعض التعليمات موجَّهة إلى النموذج فقط، وبعضها الآخر يُنتج مُخرَجًا يقرؤه المستخدم مباشرةً. الحوكمة تختلف:

  • التعليمة الفنّية (استخراج، تصنيف): مراجعة تقنيّة كافية، والمعيار هو المقاييس.
  • التعليمة المرئيّة (ردود، ملخّصات، مقترحات): مراجعة تقنيّة وناطق باللغة يُقيِّم النبرة والدقّة الأسلوبيّة. لا اثنين متشابهين.

في الفيل الأحمر، تعليمة الاستخراج فنّية، وتعليمة توليد الردّ (الوحدة 6) مرئيّة. الأخيرة تحتاج مراجعة زميل من فريق دعم العملاء، لا مطوّرًا وحده. القاعدة الذهبية: كلّ ما يقرؤه العميل مباشرةً يستحقّ مراجعة زميل يعرف كيف يقرأ به العميل، لا فقط زميل يعرف كيف يقرأ به النموذج.

قياس القيمة الاقتصادية للمكتبة​

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

تعليمة ذاتيّة الترقية ليست حلًّا

ظهر مؤخّرًا نمط «التعليمات التي تُحسِّن نفسها»: نموذج يستقبل تعليمة الحاليّة والنتائج، ويقترح تعليمة أفضل. مغرٍ لكنّه خطر. النموذج يميل إلى تعليمات أطول وأعقد بلا مبرِّر مقيس. استخدم اقتراحاته إلهامًا، لا تلقائيًّا؛ اجعل الإنسان حكمًا نهائيًّا مع جملة الاختبار.

ابدأ مكتبتك حتى لو كنت وحدك

ثلاث تعليمات في مستودع مع نسخة v1 وبطاقة README قصيرة أفضل من عشر تعليمات متناثرة في محادثات دردشة. البنية تنمو، لكنّها لا تظهر بعد الأزمة الأولى. ابدأ صغيرًا وبسيطًا في اليوم الأوّل.

في الخلاصة​

  • افصِل القالب عن المتغيّرات ومنطق الاستدعاء؛ استعمِل مكتبة قوالب معيارية (jinja2) بدلًا من سلاسل نصّية.
  • نظام النُسَخ الصريح في git يُتيح المقارنة والانحدار الآمن؛ لا تعليمات في محادثات.
  • بطاقة README لكلّ تعليمة تصف الغرض والحدود والمقاييس؛ توثيق أهمّ من نصّ التعليمة نفسه.
  • مراجعة الأقران والمالِك المسمّى والدورات الدوريّة يُحوِّلون التعليمات إلى مكوّنات مؤسّسيّة قابلة للاعتماد.

الوحدة التالية: مراجعة كامل الدورة، وقائمة تحقّق قبل النشر، وإعلان امتحان الأربعين سؤالًا الذي يُثمِّن ما تعلّمناه.