second round of translation fixes

Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>

docs/tech-specs/graphrag-performance-optimization.ar.md

@@ -0,0 +1,270 @@
+# مواصفات فنية لتحسين أداء 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)