🧠 قاعدة بيانات متجهات تعليمية (Educational Vector Database)

مرحبًا بكم في مشروع قاعدة المتجهات التعليمية - مشروع مبسّط ومكتوب بلغة بايثون يهدف إلى شرح فكرة Vector Databases بطريقة واضحة وسهلة القراءة، بعيدًا عن التعقيد الموجود في الأنظمة الإنتاجية مثل Pinecone أو Milvus أو FAISS أو Chroma.

🎯 الهدف من المشروع هو التعليم والفهم الداخلي لكيفية عمل قواعد المتجهات وليس المنافسة مع أنظمة الإنتاج.

---

🚀 ما هي قاعدة المتجهات؟

قاعدة المتجهات هي نظام يقوم بتخزين متجهات (Vectors) تمثل:

• نصوص
• صور
• جمل
• منتجات
• مستخدمين

ثم البحث عن أقرب المتجهات باستخدام خوارزميات مثل:

• Cosine Similarity
• Dot Product
• Euclidean Distance

هذه التقنية تُستخدم اليوم في:

• أنظمة البحث الدلالي (Semantic Search)
• الذكاء الاصطناعي التوليدي
• RAG (Retrieval-Augmented Generation)
• توصية المحتوى (Recommendations)
• فهرسة النصوص

وهذا المشروع يشرح كل ذلك بشكل مبسّط.

---

🧩 لماذا هذا المشروع؟

لأن معظم قواعد المتجهات الحديثة:

• معقدة جدًا
• غير مناسبة للطلاب أو المبتدئين
• تحتوي آلاف الأسطر من الكود
• مبنية لأغراض الإنتاج وليس التعليم

بينما هذا المشروع:

✔️ بسيط ومقروء
✔️ مناسب للدراسة والتجارب
✔️ يحتوي على مثال واضح
✔️ قابل للتطوير خطوة بخطوة
✔️ يساعدك تفهم "كيف يعمل Vector DB من الداخل"

---

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

src/
  vectordb/
    api.py          # الواجهة الرئيسية لقاعدة المتجهات
    storage.py      # تخزين المتجهات والـ metadata داخل الذاكرة
    index.py        # حساب Cosine Similarity
    embeddings.py   # واجهة Embeddings + نموذج تجريبي DummyEmbeddings
examples/
  basic_text_search.py
requirements.txt
README.md
setup.cfg
pyproject.toml

---

🔧 التثبيت والتشغيل

1️⃣ تثبيت المتطلبات

pip install -r requirements.txt

2️⃣ تثبيت المشروع كمكتبة محلية (وضع التطوير)

من داخل مجلد المشروع (الذي يحتوي setup.cfg و pyproject.toml):

pip install -e .

3️⃣ تشغيل المثال الجاهز

python examples/basic_text_search.py

---

🧪 مثال مبسّط

from vectordb import VectorDB, DummyEmbeddings

dim = 16
embed = DummyEmbeddings(dim)
db = VectorDB(dim, embeddings=embed)

db.add_text("I love machine learning")
db.add_text("Neural networks learn patterns")
db.add_text("Football is my hobby")

results = db.search_text("deep learning", k=2)

for r in results:
    print(r["score"], r["metadata"].get("text"))

---

🧠 كيف يعمل البحث؟

1. تحويل النص إلى متجه باستخدام Embeddings
2. جلب جميع المتجهات المخزنة من InMemoryStorage
3. تطبيع المتجهات (Normalization)
4. حساب Cosine Similarity بين الاستعلام وباقي المتجهات
5. ترتيب النتائج من الأعلى إلى الأقل
6. إرجاع أفضل K نتائج مع id و score و metadata

---

📌 الخصائص المتوفرة في الإصدار الأول (v1)

الخاصية	متوفرة؟
تخزين في الذاكرة In-Memory	✔️
Cosine Similarity	✔️
دعم metadata	✔️
البحث عن أقرب K نتائج	✔️
Embeddings تجريبية (Dummy)	✔️
مثال جاهز	✔️
قابلية التوسع	✔️

---

🛣️ خارطة الطريق (Roadmap)

🚀 الإصدار الثاني (v2)

• التخزين على القرص (save/load)
• واجهة REST باستخدام FastAPI
• دعم مسافات أخرى (Euclidean, Dot Product)
• دعم نماذج Embeddings حقيقية

🚀 الإصدار الثالث (v3)

• لوحة تحكم بسيطة لعرض النتائج
• RAG pipeline مبسّط
• Indexing أسرع (ANN مثل HNSW)

---

💡 لمن هذا المشروع؟

هذا المشروع مناسب لـ:

• الطلاب
• الجامعات
• معلمي الذكاء الاصطناعي
• مطوري NLP و ML
• الباحثين في RAG
• الهواة الذين يريدون بناء Vector DB بأنفسهم

---

📜 الرخصة

المشروع مرخص تحت:
MIT License