README.md

metadata

title: 'البحث الدلالي '
emoji: 🔍
colorFrom: green
colorTo: gray
sdk: streamlit
sdk_version: 1.58.0
app_file: reverse-dictionary/frontend/streamlit_app.py
pinned: false

🔍 تقييم البحث الدلالي

تطبيق Streamlit لتقييم ومقارنة 4 نماذج Embedding على بيانات معجمية عربية: تُدخل تعريفًا، فيعرض لك كل نموذج أقرب الكلمات، ويقيّمها المُقيّمون (صح/خطأ لكل كلمة)، وتُجمَّع التقييمات في قاعدة بيانات MongoDB سحابية مركزية.

🔗 التطبيق المنشور: https://huggingface.co/spaces/shahdAI/Semantic-Search

---

🗂️ هيكل المشروع

reverse-dictionary/
│
├── frontend/
│   └── streamlit_app.py        # 🎨 الواجهة (Streamlit) — التطبيق بالكامل
│
├── backend/                    # 🧠 المنطق (وحدات يستوردها التطبيق مباشرة)
│   ├── config.py               # ⚙️ الإعدادات + تعريف النماذج (ابدأ من هنا)
│   ├── requirements.txt        # مكتبات بايثون (للتطوير المحلي)
│   ├── .env.example            # نموذج متغيّرات البيئة
│   │
│   ├── app/
│   │   ├── models_loader.py    # تحميل النماذج والـ embeddings (مرة واحدة، كسولًا)
│   │   ├── search.py           # 🔎 منطق البحث الدلالي (cosine)
│   │   ├── database.py         # 🗄️ حفظ التقييمات (SQLite Cloud / Supabase / SQLite محلي)
│   │   └── assets.py           # 📥 تنزيل الملفات الكبيرة من Hugging Face Hub
│   │
│   └── scripts/                # سكربتات تُشغّل مرة واحدة
│       ├── prepare_data.py     # تنظيف البيانات الخام
│       ├── build_embeddings.py # بناء الـ embeddings
│       └── upload_assets.py    # رفع الملفات الكبيرة إلى HF Hub
│
├── data/                       # 📦 البيانات (لا تُرفع على Git — تُبنى/تُنزَّل)
└── models/                     # النموذج الثالث المحلي (لا يُرفع على Git)

---

🤖 النماذج الثلاثة

الاسم الظاهر	المصدر
النموذج الأول	intfloat/multilingual-e5-large
النموذج الثاني	Omartificial-Intelligence-Space/Arabic-Triplet-Matryoshka-V2
النموذج الثالث	نموذج محلي (مساره في .env عبر MODEL_3_PATH)

النموذج الأول فقط محدود بـ 10 نتائج، والباقي بدون حد. أي تعديل على النماذج أو أسمائها أو إعداداتها يكون في reverse-dictionary/backend/config.py فقط.

---

🔄 كيف يعمل؟

الواجهة (streamlit_app.py)
   └─ cached_search()  →  search.py: search_one_model()
        ├─ models_loader.get_model()   # تحميل النموذج (كسولًا)
        └─ model.encode(query) + cosine مع الـ embeddings
   └─ db.save_evaluation()  →  database.py  →  SQLite Cloud

• التسجيل: كل مُقيّم يُدخل اسمه وإيميله قبل التقييم.
• التقييم: لكل نموذج تظهر أفضل 5 كلمات، ويؤشّر المُقيّم ✓ على الصحيحة.
• التخزين: التقييمات تُحفظ في جدول ratings (والمقيّمون في evaluators).

---

🗄️ التخزين (قاعدة التقييمات)

يُقرأ رابط القاعدة من DATABASE_URL (في الأسرار أو متغيّرات البيئة)، والكود يتعرّف على النوع تلقائيًا:

الرابط	القاعدة
sqlitecloud://...	SQLite Cloud (المستخدم حاليًا)
postgresql://...	Supabase (Postgres)
غير مضبوط	SQLite محلية (data/eval_local.db) للتجربة

الجداول تُنشأ تلقائيًا عند أول تشغيل. كل مُقيّم يرى تقييماته فقط في الواجهة، بينما تتجمّع كل التقييمات مركزيًا لدى صاحب المشروع.

---

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

cd reverse-dictionary

# بيئة افتراضية + المكتبات
python -m venv backend/.venv
source backend/.venv/bin/activate
pip install -r backend/requirements.txt

# (اختياري) إعداد المسار المحلي للنموذج الثالث
cp backend/.env.example backend/.env      # عدّل MODEL_3_PATH

# تشغيل التطبيق
streamlit run frontend/streamlit_app.py

ثم افتح: http://localhost:8501

بدون DATABASE_URL يستخدم التطبيق قاعدة SQLite محلية للتجربة. لربط SQLite Cloud محليًا، ضع الرابط في .streamlit/secrets.toml أو كمتغيّر بيئة.

---

🛠️ الإعداد لمرة واحدة (بناء البيانات والنماذج)

cd reverse-dictionary/backend
python scripts/prepare_data.py        # تنظيف → data/processed/data.csv
python scripts/build_embeddings.py    # بناء → data/embeddings/*.npy

لرفع الملفات الكبيرة إلى Hugging Face Hub (عشان التطبيق المنشور ينزّلها):

export HF_TOKEN=hf_xxx
export HF_DATA_REPO="USERNAME/reverse-dictionary-assets"
python scripts/upload_assets.py

---

🚀 النشر (Hugging Face Spaces)

التطبيق منشور على HF Spaces. التفاصيل خطوة بخطوة في README_STREAMLIT_CLOUD.md.

الأسرار المطلوبة في الـ Space:

• HF_DATA_REPO — مستودع HF الذي يحوي النماذج والـ embeddings (تُنزَّل تلقائيًا).
• DATABASE_URL — رابط قاعدة التقييمات (SQLite Cloud sqlitecloud://...).

---

🧭 من أين أبدأ القراءة؟

1. backend/config.py — الإعدادات وتعريف النماذج.
2. backend/app/search.py — قلب المشروع (منطق البحث).
3. backend/app/database.py — حفظ التقييمات.
4. frontend/streamlit_app.py — الواجهة كاملة.