# مواصفات فنية لتحسين أداء GraphRAG

## نظرة عامة

تصف هذه المواصفات تحسينات شاملة للأداء لخوارزمية GraphRAG (Graph Retrieval-Augmented Generation) في TrustGraph. تعاني التنفيذ الحالي من نقاط اختناق كبيرة في الأداء تؤثر على قابلية التوسع وأوقات الاستجابة. تعالج هذه المواصفات أربعة مجالات رئيسية للتحسين:

1. **تحسين اجتياز الرسم البياني**: التخلص من استعلامات قاعدة البيانات المتكررة وغير الفعالة وتنفيذ استكشاف الرسم البياني المجمّع.
2. **تحسين حل التسميات**: استبدال استرداد التسميات التسلسلي بعمليات متوازية/مجمعة.
3. **تحسين استراتيجية التخزين المؤقت**: تنفيذ تخزين مؤقت ذكي مع الإخلاء حسب الأقل استخدامًا (LRU) والتحميل المسبق.
4. **تحسين الاستعلام**: إضافة تجميع النتائج وتخزين تضمينات الاستعلام لتحسين أوقات الاستجابة.

## الأهداف

- **تقليل حجم استعلامات قاعدة البيانات**: تحقيق تقليل بنسبة 50-80% في إجمالي استعلامات قاعدة البيانات من خلال التجميع والتخزين المؤقت.
- **تحسين أوقات الاستجابة**: استهداف سرعة بناء الرسوم البيانية الفرعية 3-5 مرات أسرع وحل التسميات 2-3 مرات أسرع.
- **تعزيز قابلية التوسع**: دعم رسوم بيانية معرفية أكبر مع إدارة أفضل للذاكرة.
- **الحفاظ على الدقة**: الحفاظ على وظائف GraphRAG الحالية وجودة النتائج.
- **تمكين التزامن**: تحسين إمكانات المعالجة المتوازية للطلبات المتزامنة المتعددة.
- **تقليل البصمة الذاكرة**: تنفيذ هياكل بيانات وإدارة ذاكرة فعالة.
- **إضافة إمكانية المراقبة**: تضمين مقاييس الأداء وقدرات المراقبة.
- **ضمان الموثوقية**: إضافة معالجة مناسبة للأخطاء وآليات المهلة.

## الخلفية

يظهر التنفيذ الحالي لـ GraphRAG في `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` عدة مشاكل أداء حرجة تؤثر بشدة على قابلية توسع النظام:

### المشاكل الحالية في الأداء

**1. اجتياز الرسم البياني غير الفعال (`follow_edges` function، الأسطر 79-127)**
- يقوم بإجراء 3 استعلامات منفصلة لقاعدة البيانات لكل كيان ولكل مستوى عمق.
- نمط الاستعلام: استعلامات تعتمد على الموضوع، تعتمد على المرجع، وتعتمد على الكائن لكل كيان.
- لا يوجد تجميع: يعالج كل استعلام كيانًا واحدًا فقط في كل مرة.
- لا يوجد اكتشاف دورة: يمكن إعادة زيارة نفس العقد عدة مرات.
- يؤدي التنفيذ المتكرر بدون تجميع إلى تعقيد أسي.
- التعقيد الزمني: O(entities × max_path_length × triple_limit³)

**2. حل تسلسلي للتسميات (`get_labelgraph` function، الأسطر 144-171)**
- يعالج كل مكون ثلاثي (الموضوع، المرجع، الكائن) بالتسلسل.
- قد يؤدي كل استدعاء `maybe_label` إلى تشغيل استعلام قاعدة بيانات.
- لا يوجد تنفيذ متوازي أو تجميع لاستعلامات التسميات.
- يؤدي إلى ما يصل إلى 3 × مكالمات قاعدة بيانات فردية لحجم الرسوم البيانية الفرعية.

**3. استراتيجية تخزين مؤقت بدائية (`maybe_label` function، الأسطر 62-77)**
- ذاكرة تخزين مؤقت بسيطة للقواميس بدون حدود حجم أو TTL (وقت انتهاء الصلاحية).
- لا توجد سياسة إخلاء ذاكرة التخزين المؤقت تؤدي إلى نمو غير محدود للذاكرة.
- تؤدي أخطاء ذاكرة التخزين المؤقت إلى استعلامات قاعدة بيانات فردية.
- لا يوجد تحميل مسبق أو تسخين ذكي لذاكرة التخزين المؤقت.

**4. أنماط استعلام غير مثالية**
- استعلامات تشابه متجه الكيان غير مخزنة مؤقتًا بين الطلبات المتشابهة.
- لا يوجد تجميع للنتائج لـ أنماط الاستعلام المتكررة.
- استعلامات غير محسنة لـ الأنماط الشائعة للوصول.

**5. مشاكل حرجة في دورة حياة الكائنات (`rag.py:96-102`)**
- **كائن GraphRag يتم إعادة إنشاؤه لكل طلب**: يتم إنشاء نسخة جديدة لكل استعلام، مما يؤدي إلى فقدان جميع فوائد ذاكرة التخزين المؤقت.
- **عمر كائن الاستعلام قصير للغاية**: يتم إنشاؤه وتدميره داخل تنفيذ استعلام واحد (الأسطر 201-207).
- **تتم إعادة تعيين ذاكرة التخزين المؤقت للتسميات لكل طلب**: يتم فقدان تسخين ذاكرة التخزين المؤقت والمعرفة المتراكمة بين الطلبات.
- **نفقات إعادة إنشاء العميل**: قد يتم إعادة إنشاء عملاء قاعدة البيانات لكل طلب.
- **لا يوجد تحسين عبر الطلبات**: لا يمكن الاستفادة من أنماط الاستعلام أو مشاركة النتائج.

### تحليل تأثير الأداء

السيناريو الأسوأ حاليًا لطلب نموذجي:
- **استرداد الكيان**: استعلام تشابه متجه واحد.
- **اجتياز الرسم البياني**: entities × max_path_length × 3 × triple_limit استعلامات.
- **حل التسميات**: subgraph_size × 3 استعلامات تسمية فردية.

بالإعدادات الافتراضية (50 كيانًا، طول المسار 2، حد ثلاثي 30، حجم الرسم البياني الفرعية 150):
- **الحد الأدنى من الاستعلامات**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **9,451 استعلام لقاعدة البيانات**.
- **وقت الاستجابة**: 15-30 ثانية للرسوم البيانية متوسطة الحجم.
- **استخدام الذاكرة**: نمو غير محدود لذاكرة التخزين المؤقت بمرور الوقت.
- **فعالية ذاكرة التخزين المؤقت**: 0% - تتم إعادة تعيين ذاكرة التخزين المؤقت في كل طلب.
- **نفقات إنشاء الكائنات**: يتم إنشاء/تدمير كائنات GraphRag + Query لكل طلب.

تعالج هذه المواصفات هذه الثغرات من خلال تنفيذ استعلامات مجمعة، وتخزين مؤقت ذكي، ومعالجة متوازية. من خلال تحسين أنماط الاستعلام والوصول إلى البيانات، يمكن لـ TrustGraph:
- دعم الرسوم البيانية المعرفية على مستوى المؤسسات مع ملايين الكيانات.
- توفير أوقات استجابة فرعية من الثانية للطلبات النموذجية.
- التعامل مع مئات الطلبات المتزامنة لـ GraphRAG.
- التوسع بكفاءة مع حجم الرسم البيانية وتعقيدها.

## التصميم التقني

### البنية التحتية

يتطلب تحسين أداء GraphRAG المكونات التقنية التالية:

#### 1. **إعادة هيكلة معمارية لدورة حياة الكائنات**
   - **جعل GraphRag طويل الأمد**: نقل مثيل GraphRag إلى مستوى المعالج للاستمرار عبر الطلبات.
   - **الحفاظ على ذاكرات التخزين المؤقت**: الحفاظ على ذاكرة التخزين المؤقت للتسميات، وذاكرة التخزين المؤقت للتضمينات، وذاكرة التخزين المؤقت لنتائج الاستعلام بين الطلبات.
   - **تحسين كائن الاستعلام**: إعادة هيكلة الاستعلام كسياق تنفيذ خفيف الوزن، وليس حاوية بيانات.
   - **استمرارية الاتصال**: الحفاظ على اتصالات عملاء قاعدة البيانات عبر الطلبات.

   الوحدة: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (تم التعديل)

#### 2. **محرك اجتياز محسّن للرسم البياني**
   - استبدال `follow_edges` المتكرر ببحث عرضي تكراري.
   - تنفيذ معالجة مجمعة للكيانات على كل مستوى من مستويات الاجتياز.
   - إضافة اكتشاف دورة باستخدام تتبع العقد التي تمت زيارتها.
   - تضمين إنهاء مبكر عند الوصول إلى الحدود.

   الوحدة: `trustgraph-flow/trustgraph/retrieval/graph_rag/optimized_traversal.py`

#### 3. **نظام حل تسميات متوازي**
   - تجميع استعلامات التسميات لعدة كيانات في وقت واحد.
   - تنفيذ أنماط async/await للوصول المتزامن إلى قاعدة البيانات.
   - إضافة تحميل مسبق ذكي لـ أنماط التسميات الشائعة.
   - تضمين استراتيجيات تسخين لذاكرة التخزين المؤقت للتسميات.

   الوحدة: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolver.py`

#### 4. **طبقة تخزين مؤقت محافظة للتسميات**
   - ذاكرة تخزين مؤقت LRU مع TTL قصير للتسميات فقط (5 دقائق) لتحقيق التوازن بين الأداء مقابل الاتساق.
   - مقاييس ذاكرة التخزين المؤقت ونسبة الضبط.
   - **لا يوجد تخزين مؤقت للتضمينات**: يتم بالفعل تخزين التضمينات مؤقتًا لكل استعلام.
   - **لا يوجد تخزين مؤقت للنتائج**: يمنع نتائج الرسوم البيانية الفرعية القديمة من الكيانات/العلاقات المحذوفة.

   الوحدة: `trustgraph-flow/trust/graph/label_cache.py`

#### 5. **تحسين الاستعلام والمراقبة**
   - جمع مقاييس الأداء.
   - تطبيق مهلة على الاستعلامات.
   - إضافة دائرة كهربائية لمنع الاستخدام المفرط للموارد.

   الوحدة: `trustgraph-flow/trust/graph/query_optimizer.py`

## اعتبارات الاتساق للذاكرة المؤقتة

**موازنات بين بيانات قديمة**:
- **ذاكرة التخزين المؤقت للتسميات (TTL 5 دقائق)**: خطر تقديم تسميات الكيانات المحذوفة/المتجددة.
- **لا يوجد تخزين مؤقت للتضمينات**: ليس مطلوبًا - يتم تخزين التضمينات بالفعل مؤقتًا لكل استعلام.
- **لا يوجد تخزين مؤقت للنتائج**: يمنع نتائج الرسم البياني الفرعية القديمة من الكيانات/العلاقات المحذوفة.

**استراتيجيات التخفيف**:
- **قيم TTL متحفظة**: الموازنة بين مكاسب الأداء (10-20٪) مقابل نضارة البيانات.
- **خطافات إبطال ذاكرة التخزين المؤقت**: تكامل اختياري مع أحداث تعديل الرسم البياني.
- **لوحات معلومات المراقبة**: تتبع معدلات ضرب ذاكرة التخزين المؤقت مقابل حوادث التقادم.
- **سياسات ذاكرة التخزين المؤقت القابلة للتكوين**: السماح بضبط لكل نشر بناءً على تكرار التعديل.

**تكوين ذاكرة التخزين المؤقت الموصى به حسب معدل تعديل الرسم البياني**:
- **تعديل عالي (>100 تغيير / ساعة)**: TTL = 60 ثانية، أحجام ذاكرة تخزين مؤقت أصغر.
- **تعديل متوسط (10-100 تغيير / ساعة)**: TTL = 300 ثانية (افتراضي).
- **تعديل منخفض (<10 تغيير / ساعة)**: TTL = 600 ثانية، أحجام ذاكرة تخزين مؤقت أكبر.

## الاعتبارات الأمنية

**منع حقن الاستعلام**:
- التحقق من صحة جميع معرفات الكيانات ومعلمات الاستعلام.
- استخدام استعلامات مُعلمات لجميع التفاعلات مع قاعدة البيانات.
- تنفيذ حدود تعقيد الاستعلام لمنع هجمات الحرمان من الخدمة.

**حماية الموارد**:
- فرض حدود قصوى لحجم الرسم البياني الفرعية.
- تنفيذ مهلات على الاستعلام لمنع استنفاد الموارد.
- إضافة مراقبة استخدام الذاكرة وحدود.

**التحكم في الوصول**:
- الحفاظ على عزل المستخدم والمجموعة الحالي.
- إضافة تسجيل تدقيق للعمليات التي تؤثر على الأداء.
- تنفيذ تحديد المعدل للعمليات المكلفة.

## اعتبارات الأداء

### التحسينات المتوقعة في الأداء

**تقليل الاستعلام**:
- الحالي: ~ 9000+ استعلام لطلب نموذجي.
- مُحسَّن: ~ 50-100 استعلام مجمعة (تقليل بنسبة 98٪).

**تحسينات أوقات الاستجابة**:
- اجتياز الرسم البياني: 15-20 ثانية → 3-5 ثوانٍ (4-5 مرات أسرع).
- حل التسميات: 8-12 ثانية → 2-4 ثوانٍ (3 مرات أسرع).
- الاستعلام الإجمالي: 25-35 ثانية → 6-10 ثوانٍ (تحسين بمقدار 3-4 مرات).

**كفاءة الذاكرة**:
- أحجام ذاكرة التخزين المؤقت المحدودة تمنع تسرب الذاكرة.
- هياكل بيانات فعالة تقلل البصمة الذاكرة بنسبة ~ 40٪.
- إدارة أفضل للذاكرة من خلال التنظيف المناسب للموارد.

**تحسينات قابلية التوسع**:
- دعم رسوم بيانية معرفية أكبر بنسبة 3-5 مرات (محدود باحتياجات اتساق ذاكرة التخزين المؤقت).
- سعة أعلى للطلبات المتزامنة بنسبة 3-5 مرات.
- استخدام أفضل للموارد من خلال إعادة استخدام الاتصال.

### مراقبة الأداء

**مقاييس في الوقت الفعلي**:
- أوقات تنفيذ الاستعلام حسب نوع العملية.
- معدلات ضرب وفعالية ذاكرة التخزين المؤقت.
- استخدام مجموعة اتصالات قاعدة البيانات.
- استخدام الذاكرة وجمع البيانات المهملة.

**قياس الأداء**:
- اختبار أداء مقابل التنفيذ الحالي.
- اختبار التحميل بأحجام بيانات وتعقيدات مختلفة.
- اختبار الضغط لحدود الموارد.
- اختبار الانحدار للتحسينات في الأداء.

## استراتيجية الاختبار

### اختبار الوحدة
- اختبار مكون فردي لـ الاجتياز، والتخزين المؤقت، وحل التسميات.
- محاكاة تفاعلات قاعدة البيانات لاختبار الأداء.
- اختبار الإخلاء و TTL ذاكرة التخزين المؤقت.
- سيناريوهات معالجة الأخطاء والمهلات.

### اختبار التكامل
- اختبار GraphRAG الشامل مع التحسينات.
- اختبار تفاعل قاعدة البيانات مع بيانات حقيقية.
- اختبار التعامل مع الطلبات المتزامنة وإدارة الموارد.
- الكشف عن تسرب الذاكرة والتحقق من تنظيف الموارد.

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

### اختبار التوافق
- التحقق من توافق واجهة برمجة تطبيقات GraphRAG الحالية.
- الاختبار مع خلفيات قاعدة بيانات رسم بياني مختلفة.
- التحقق من دقة النتائج مقارنة بالتنفيذ الحالي.

## خطة التنفيذ

### النهج المباشر للتنفيذ
نظرًا للسماح بتغييرات واجهة برمجة التطبيقات، قم بتنفيذ التحسينات مباشرة دون تعقيد الترحيل:

1. **استبدل طريقة `follow_edges`**: أعد كتابة مع اجتياز مجمّع تكراري.
2. **تحسين `get_labelgraph`**: قم بتنفيذ حل تسميات متوازي.
3. **أضف GraphRag طويل الأمد**: قم بتعديل المعالج لاستخدام نسخة مستمرة.
4. **قم بتنفيذ استراتيجية التخزين المؤقت**: أضف طبقة تخزين مؤقت إلى فئة GraphRag.

### نطاق التغييرات
- **فئة الاستعلام**: استبدل ~50 سطرًا في `follow_edges`، وأضف ~30 سطرًا للتعامل مع التجميع.
- **فئة GraphRag**: أضف طبقة تخزين مؤقت (~40 سطرًا).
- **فئة المعالج**: قم بتعديل لاستخدام مثيل GraphRag دائم (~20 سطرًا).
- **إجمالي**: ~ 140 سطرًا من التغييرات المركزة، في الغالب داخل الفئات الحالية.

## جدول زمني

**الأسبوع 1: التنفيذ الأساسي**
- استبدل `follow_edges` باجتياز تكراري مجمّع.
- قم بتنفيذ حل تسميات متوازي في `get_labelgraph`.
- أضف مثيل GraphRag طويل الأمد إلى المعالج.
- قم بتنفيذ طبقة التخزين المؤقت للتسميات.

**الأسبوع 2: الاختبار والتكامل**
- اختبارات الوحدة لمنطق الاجتياز والتخزين المؤقت الجديد.
- قياس الأداء مقابل التنفيذ الحالي.
- اختبار التكامل مع بيانات الرسم البياني الحقيقية.
- مراجعة الكود والتحسين.

**الأسبوع 3: النشر**
- نشر التنفيذ المُحسَّن.
- مراقبة تحسينات الأداء.
- ضبط TTL ذاكرة التخزين المؤقت وأحجام الدفعات بناءً على الاستخدام الفعلي.

## أسئلة مفتوحة

- **تجميع الاتصال بقاعدة البيانات**: هل يجب علينا تنفيذ تجميع اتصال مخصص أم الاعتماد على تجميع عملاء قاعدة البيانات الحالي؟
- **استمرارية ذاكرة التخزين المؤقت**: هل يجب أن تستمر ذاكرات التخزين المؤقت للتسميات والتضمينات عبر عمليات إعادة تشغيل الخدمة؟
- **التخزين المؤقت الموزع**: بالنسبة لنشر متعدد المثيلات، هل يجب علينا تنفيذ تخزين مؤقت موزع باستخدام Redis/Memcached؟
- **تنسيق نتيجة الاستعلام**: هل يجب علينا تحسين التمثيل الداخلي للثلاثي لتحسين كفاءة الذاكرة؟
- **تكامل المراقبة**: ما هي المقاييس التي يجب عرضها على أنظمة المراقبة الحالية (Prometheus، إلخ)؟

## المراجع

- [التنفيذ الأصلي لـ GraphRAG](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
- [مبادئ معمارية TrustGraph](architecture-principles.md)
- [مواصفات إدارة المجموعة](collection-management.md)