Watch the video  |  Streamlit Deployed App

---

الباحث القرآني المُحسَّن

منظومة استرجاع تجمع بين الأبعاد اللغوية والدلالية لربط أسئلة المستخدم بلغة القرآن

بعد نص الآية استرجاع دلالي يعتمد على ألفاظ القرآن نفسها، لتقريب النتائج عندما تكون صياغة السؤال قريبة من النص. quran_verses

البعد اللغوي استرجاع منظم عبر الجذر والصيغة المعجمية وسمات الكلمة، مستند إلى بيانات لغوية على مستوى الكلمة. Data/Linguistic/Quranic.csv

بعد التفسير الميسر وسيط لغوي قريب من أسئلة المستخدم، يساعد على ربط السؤال بلغة الآية عندما تكون الصياغة بعيدة. quran_tafsir

---

فهرس المحتوى

• استضف نسختك الخاصة
• نبذة عن المشروع
• تقنيات الاسترجاع وما يميّزها
• مصطلحات أساسية
• نبذة عن البيانات المستخدمة
• ملاحظات حول الواجهة
• هيكل المشروع
• الدوال/المكوّنات المهمة (داخل app.py)
• المتطلبات البرمجية (Dependencies)
• التشغيل محليًا

---

استضف نسختك الخاصة

1. قم بعمل Fork للمستودع على GitHub
2. افتح Streamlit Community Cloud
3. اضغط New app ← اختر المستودع ← Deploy

---

نبذة عن المشروع

الفكرة ليست مطابقة نصية فقط، بل منظومة استرجاع تنظر للنص القرآني من أكثر من زاوية، وتستخدم التفسير كجسر لغوي بين سؤال/استعلام المستخدم ولغة القرآن.

ملاحظة مهمة: التضمينات تُبنى مسبقًا وتُحفظ داخل ChromaDB، لذا وقت التشغيل يقتصر على ترميز نص المستخدم فقط ثم البحث في قاعدة المتجهات.

لماذا التفسير؟ بعد التفسير الميسر يعمل كطبقة وسيطة بين لغة السؤال الشائعة ولغة القرآن الأعلى كثافة، ما يحسن استرجاع المعاني عندما تكون صياغة السؤال بعيدة عن ألفاظ الآية.

---

تقنيات الاسترجاع وما يميّزها

يعتمد المشروع على أبعاد/زوايا متعددة في الاسترجاع، ثم يدمج إشاراتها بطريقة قابلة للضبط:

1) توحيد الصياغة العربية لرفع جودة المطابقة

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

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

2) الاسترجاع اللغوي اعتمادًا على بيانات الكلمة

بدل البحث داخل نص الآية الخام، يعتمد المحرك على بيانات لغوية على مستوى الكلمة، ثم ينتج تمثيلًا مجمّعًا على مستوى الآية للعرض. عمليًا يتيح ذلك:

• البحث بالجذر والصيغة المعجمية بطريقة مباشرة في حقول مستقلة.
• قابلية توسيع النظام مستقبلًا لإضافة شروط لغوية (مثل نوع الكلمة أو سمات صرفية) دون إعادة بناء البيانات من الصفر.

3) البحث بالجذر بطريقتين

• إدخال الجذر مباشرة.
• إدخال كلمة، ثم محاولة استخراج جذرها عبر PySarf واستخدام الناتج في الاسترجاع.

4) الاسترجاع الدلالي عبر قاعدة متجهات (ChromaDB)

• تُحوَّل النصوص إلى متجهات عددية تمثل معناها.
• عند إدخال المستخدم نصًا للبحث، يُحوَّل نصه إلى متجه واحد، ثم تُسترجع أقرب المتجهات الموجودة في قاعدة المتجهات.

ملاحظة: التضمينات تُبنى مسبقًا وتُحفظ على القرص داخل ChromaDB؛ لذلك وقت التشغيل يقتصر على ترميز نص المستخدم فقط، ما يقلّل زمن الإقلاع ويرفع سرعة الاستجابة.

5) بعد الآية وبعد التفسير ثم دمج النتائج

يتم الاسترجاع الدلالي من مصدرين مستقلين:

• quran_verses: تشابه معنوي مع نص الآية.
• quran_tafsir: تشابه معنوي مع نص التفسير.

ثم تُدمج الإشارتان في درجة نهائية (دمج مرجّح، آية فقط، تفسير فقط، أو اختيار الأعلى).

6) تقييد نطاق البحث بسورة/سور

عند تحديد سورة يتم تطبيق التقييد داخل أصل عملية الاسترجاع (عبر metadata chapter_id) على مستوى قاعدة المتجهات.

---

مصطلحات أساسية

• الجذر (Root): أصل الكلمة الذي تُشتق منه الكلمات.
• الصيغة المعجمية (Lemma): الصورة المعتمدة للكلمة في المعجم/الفهرسة.
• التضمينات (Embeddings): تمثيل عددي يلتقط المعنى العام للنص.
• قاعدة المتجهات (Vector Database): قاعدة بيانات مخصصة لاسترجاع أقرب المتجهات بسرعة.

---

نبذة عن البيانات المستخدمة

يعتمد المشروع على بيانات ثرية متوفرة حول النص القرآني، وأهمها:

• Data/Linguistic/Quranic.csv
  بيانات لغوية على مستوى الكلمة (جذر، صيغة معجمية، نوع الكلمة، ترجمة، وغيرها) تُستخدم لبناء الاسترجاع اللغوي وتجميع نص الآية وترجمتها.

• Data/Interpretation/ar.muyassar.csv
  نص التفسير الميسر ويُستخدم كبعد دلالي وسيط بين لغة المستخدم ولغة الآية.

كما يعتمد البحث الدلالي على فهرس تضمينات محفوظ على القرص داخل أحد المسارات التالية (وفق البيئة):

• Data/.chromadb أو .chromadb أو chroma_db

ويُتوقع وجود مجموعتين داخلها:

• quran_verses
• quran_tafsir

---

ملاحظات حول الواجهة

الواجهة مبنية بـ Streamlit وتقوم بدور تقديمي: إدخال نص المستخدم، اختيار نوع البحث، ضبط بعض الإعدادات، ثم عرض النتائج.

---

هيكل المشروع

• app.py التطبيق الرئيسي (محرك الاسترجاع + تحميل البيانات + الواجهة)
• Code/build_full_embeddings.py تجهيز وبناء تضمينات ChromaDB (تشغيل مسبق)
• Data/ مصادر البيانات والفهارس
• Assets/ مواد العرض

---

الدوال/المكوّنات المهمة (داخل app.py)

• normalize_arabic(text: str) -> str

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

• get_root_pysarf(word: str) -> str

  • المدخل: كلمة يكتبها المستخدم (أو جذر).
  • المخرج: جذر أقرب للصحيح (موحّد الصياغة).
  • ماذا تفعل؟ تحاول تحليل الكلمة عبر PySarf لاستخراج الجذر، ثم توحّد صياغته لاستخدامه في البحث.

• process_word_level(df_linguistic: pd.DataFrame) -> pd.DataFrame

  • المدخل: بيانات Quranic.csv.
  • المخرج: جدول كلمات Word-level.
  • ماذا تفعل؟ تنظّف الصفوف غير اللازمة، توحّد صياغة الجذور والصيغ المعجمية، ثم تبني حقولًا تسمح بالبحث المنظم على مستوى الكلمة.

• create_verses(word_level: pd.DataFrame) -> pd.DataFrame

  • المدخل: جدول Word-level.
  • المخرج: جدول آيات Verse-level.
  • ماذا تفعل؟ تجمع كلمات الآية في نص واحد، وتجمع ترجمتها، وتولّد مرجعًا موحدًا.

• load_semantic_model()

  • المخرج: نموذج التضمين المستخدم لترميز نص المستخدم فقط.

• load_chroma_collections()

  • المخرج: مجموعتا ChromaDB (quran_verses, quran_tafsir) من القرص.

• semantic_search(query: str, verse_col, tafsir_col, model, ...) -> pd.DataFrame

  • المدخل: نص البحث من المستخدم، مجموعات ChromaDB، نموذج التضمين، إعدادات الدمج والفلترة.
  • المخرج: نتائج مرتبة تتضمن النص والمرجع والدرجات.
  • ماذا تفعل؟ ترمز نص المستخدم إلى متجه، تسترجع الأقرب من الآيات ومن التفسير، ثم تدمج الدرجات وفق الاستراتيجية المختارة.

• search_by_word(...) / search_by_lemma(...) / search_by_root(...) -> pd.DataFrame

  • المخرج: نتائج الاسترجاع اللغوي.
  • ماذا تفعل؟ تبحث في حقول منظمة (كلمة/صيغة معجمية/جذر) بعد توحيد الصياغة.

---

المتطلبات البرمجية (Dependencies)

يعمل المشروع على Python ويعتمد على مكتبات موجودة في ملف requirements.txt. في الوضع الافتراضي يكفي تثبيت المتطلبات عبر مدير الحزم pip.

التثبيت (موصى به):

pip install -r requirements.txt

ملاحظة حول استخراج الجذور:

• يعتمد استخراج الجذر من كلمة مدخلة على PySarf. إذا لم تكن PySarf متاحة في بيئتك، سيعمل المشروع مع تعطّل هذا الجزء تحديدًا (ويبقى البحث بالجذر ممكنًا عند إدخال الجذر مباشرة).

تثبيت PySarf (عند الحاجة):

git clone https://github.com/Rashidbm/pysarf.git
cd pysarf
pip install -e .

---

التشغيل محليًا

• ثبّت المتطلبات من requirements.txt.

pip install -r requirements.txt

• شغّل Streamlit على ملف app.py.

streamlit run app.py

ملاحظة: البحث الدلالي يفترض وجود فهرس ChromaDB مُنشأ مسبقًا على القرص. إذا لم يكن موجودًا، ابنِ التضمينات مرة واحدة عبر: python Code/build_full_embeddings.py

---