README.md

---
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`](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`) للتجربة |

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

---

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

```bash
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` أو كمتغيّر بيئة.

---

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

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

لرفع الملفات الكبيرة إلى Hugging Face Hub (عشان التطبيق المنشور ينزّلها):
```bash
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](reverse-dictionary/DEPLOY.md).

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

---

## 🧭 من أين أبدأ القراءة؟
1. [`backend/config.py`](reverse-dictionary/backend/config.py) — الإعدادات وتعريف النماذج.
2. [`backend/app/search.py`](reverse-dictionary/backend/app/search.py) — قلب المشروع (منطق البحث).
3. [`backend/app/database.py`](reverse-dictionary/backend/app/database.py) — حفظ التقييمات.
4. [`frontend/streamlit_app.py`](reverse-dictionary/frontend/streamlit_app.py) — الواجهة كاملة.