ابنِ وكيل محادثة مدعوم بـ RAG

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

هذا يغطي دورة الحياة الكاملة لوكيل RAG إنتاجي — نوع النظام الذي قد يُطلب منك تصميمه أو تنفيذه في مقابلة مهندس وكلاء.

نظرة عامة على البنية

المستندات → التقطيع → التضمينات → مخزن المتجهات
                                        ↑
استعلام المستخدم → سياق الذاكرة         |
     ↓                                  |
تفكيك الاستعلام (RAG الوكيلي)          |
     ↓                                  |
بحث المتجهات ←──────────────────────────┘
     ↓
تخصيص ميزانية السياق
     ↓
توليد LLM (مع إسناد المصادر)
     ↓
حارس الهلوسة
     ↓
الاستجابة للمستخدم (مع الاستشهادات)

الخطوة 1: مخزن المستندات (document_store.py)

ابنِ فئة DocumentStore تستوعب المستندات النصية وتقسمها إلى أجزاء باستخدام استراتيجيات قابلة للتكوين:

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

كل جزء يجب أن يحمل بيانات وصفية: chunk_id وdocument_id وsource_filename وchunk_index وstrategy_used.

الخطوة 2: بحث المتجهات (vector_search.py)

ابنِ فئة VectorSearch توفر بحث التشابه عبر أجزاء المستندات:

• قبول دالة تضمين (callable تأخذ نصاً وتعيد قائمة أعداد عشرية)
• فهرسة الأجزاء بحساب وتخزين تضميناتها
• البحث بحساب تضمين الاستعلام وإيجاد أعلى K أجزاء تشابهاً باستخدام تشابه الجيب تمام (cosine similarity)
• دعم تصفية البيانات الوصفية (مثلاً التصفية بـ source_filename أو document_id)
• إعادة النتائج مع درجات التشابه

الخطوة 3: RAG الوكيلي (agentic_rag.py)

ابنِ فئة AgenticRAG تتجاوز نمط الاسترجاع والتوليد البسيط:

• تفكيك الاستعلام: تحليل سؤال معقد وتقسيمه إلى استعلامات فرعية أبسط يمكن البحث عن كل منها بشكل مستقل
• الاسترجاع متعدد الاستعلامات: تنفيذ كل استعلام فرعي مقابل مخزن المتجهات ودمج النتائج مع إزالة التكرارات
• التأمل الذاتي: بعد الاسترجاع، تقييم ما إذا كانت الأجزاء المسترجعة تحتوي معلومات كافية للإجابة على السؤال الأصلي. إعادة تقييم الجودة (كافٍ / جزئي / غير كافٍ) واقتراح استعلام معاد صياغته اختيارياً

الخطوة 4: مدير الذاكرة (memory_manager.py)

ابنِ فئة MemoryManager تتعامل مع ذاكرة المحادثة:

• المخزن المؤقت قصير الأمد: تخزين آخر N من أدوار المحادثة (رسائل المستخدم + استجابات الوكيل) في قائمة
• التلخيص طويل الأمد: عندما يتجاوز المخزن المؤقت حداً قابلاً للتكوين، ضغط الأدوار الأقدم في ملخص تراكمي باستخدام استدعاء LLM (قبول دالة تلخيص كمعامل)
• استرجاع الذاكرة: إعادة السياق المدمج — الملخص (إن وُجد) بالإضافة إلى الأدوار الأخيرة — منسقاً للحقن في أمر LLM

الخطوة 5: مدير ميزانية السياق (context_budget.py)

ابنِ فئة ContextBudgetManager تخصص ميزانية رموز محدودة عبر المكونات المتنافسة:

• قبول ميزانية رموز إجمالية ونسب تخصيص لكل من: أمر النظام، ذاكرة المحادثة، المستندات المسترجعة، واحتياطي المخرجات
• قبول دالة عد الرموز (callable تأخذ نصاً وتعيد عدداً صحيحاً)
• طريقة allocate(): بالنظر إلى أمر النظام وسياق الذاكرة والأجزاء المسترجعة، تقليم كل مكون ليتسع ضمن ميزانيته المخصصة. تقليم الأجزاء المسترجعة بإزالة الأقل تقييماً أولاً. تقليم الذاكرة بالتلخيص أو الاقتطاع من الأدوار الأقدم
• إعادة السياق النهائي المجمع مع كل مكون ضمن الميزانية

الخطوة 6: إسناد المصادر (source_attribution.py)

ابنِ فئة SourceAttributor تربط الادعاءات في استجابة الوكيل بأجزاء المصدر:

• قبول نص استجابة الوكيل وقائمة أجزاء المصدر المستخدمة
• تقسيم الاستجابة إلى ادعاءات فردية (على مستوى الجملة)
• لكل ادعاء، حساب التشابه مع جميع أجزاء المصدر وتعيين الجزء الأكثر تطابقاً كمصدر
• تعيين درجة ثقة (قيمة التشابه) لكل إسناد
• إعادة قائمة كائنات Attribution: claim وsource_chunk_id وsource_document وconfidence وrelevant_excerpt

الخطوة 7: حارس الهلوسة (hallucination_guard.py)

ابنِ فئة HallucinationGuard تتحقق من إجابة الوكيل مقابل المحتوى المسترجع:

• قبول استجابة الوكيل وأجزاء المصدر المسترجعة
• تقسيم الاستجابة إلى ادعاءات فردية
• لكل ادعاء، فحص ما إذا كان مدعوماً بأي جزء مصدر (التشابه فوق عتبة قابلة للتكوين)
• تصنيف كل ادعاء كـ: supported أو partially_supported أو unsupported
• إعادة GuardResult مع: قائمة الادعاءات المصنفة، ودرجة ثقة إجمالية (نسبة الادعاءات المدعومة)، وعلامة is_safe منطقية (true إذا تجاوزت درجة الثقة عتبة أمان قابلة للتكوين)

ماذا تقدّم

المحرر يحتوي على 7 أقسام ملفات مع تعليقات TODO. استبدل كل TODO بكود Python الخاص بك. سيقوم المقيّم الذكي بتقييم كل قسم وفقاً لمعايير التقييم.

تلميحات

• لتشابه الجيب تمام، استخدم حاصل الضرب النقطي مقسوماً على حاصل ضرب المقادير، أو استخدم numpy إذا فضلت
• لتقسيم الجمل، التقسيم على . (نقطة + مسافة) هو نقطة بداية معقولة
• لمعامل دالة التضمين، صمم كودك لقبول أي callable بتوقيع (str) -> List[float] — هذا يجعله قابلاً للاختبار مع تضمينات وهمية
• لعد الرموز، اقبل أي callable بتوقيع (str) -> int — تقريب بسيط هو len(text.split())
• عتبة حارس الهلوسة هي خيار تصميمي — 0.7 هو افتراضي معقول لتشابه الجيب تمام