# البحث الدلالي (التضمينات)
SUMMARY: بحث مفاهيمي في الذاكرة باستخدام التضمينات المتجهة — ابحث بالمعنى، لا بالكلمات المفتاحية فقط.

البحث الدلالي (التضمينات)
يدعم Synapse البحث الدلالي باستخدام التضمينات المتجهة. على عكس FTS5 (مطابقة
الكلمات المفتاحية)، يجد البحث الدلالي الذكريات بـ المعنى — حتى لو لم تتطابق
الكلمات المفتاحية.
كيفية العمل
[CODE BLOCK]
ما هي التضمينات؟
التضمينات تمثيلات متجهة عددية للنص. النص ذو المعنى المماثل له متجهات مماثلة.
يُولّد Synapse متجهًا (مثلًا 1536 بُعدًا) لكل محتوى ذاكرة.
تشابه جيب التمام
لإيجاد الذكريات المتشابهة دلاليًا، يحسب Synapse تشابه جيب التمام
بين متجه الاستعلام ومتجه كل ذاكرة. تشابه أعلى = صلة
أكبر.
متى تستخدم البحث الدلالي
استخدم البحث الدلالي عندما:
- تريد "ذكريات حول X" حيث يُوصف X بشكل مختلف عن المخزّن
- لا يُرجع FTS5 نتائج (لا مطابقة للكلمات المفتاحية)
- تريد تجميعًا مفاهيميًا (مثلًا جميع ذكريات "النشر"، حتى لو قال بعضها "release")
- الاستعلام سؤال: "كيف نتعامل مع المصادقة؟"
استخدم FTS5 عندما:
- تعرف الكلمات المفتاحية الدقيقة
- تحتاج منطقًا منطقيًا (AND، OR، NOT)
- تحتاج استجابة أقل من مللي ثانية
- تريد مطابقة العبارات
نقطة النهاية
GET /memory/semantic-search
[CODE BLOCK]
الاستجابة:
[CODE BLOCK]
أمثلة
إيجاد ذكريات النشر
[CODE BLOCK]
يُرجع الذكريات حول "deployment" و "release" و "publishing" و "rolling out"،
إلخ.
إيجاد أنماط المصادقة
[CODE BLOCK]
يُرجع الذكريات حول login و auth و JWT و إدارة الجلسة و OAuth، إلخ.
إيجاد ذكريات مماثلة
[CODE BLOCK]
يستخدم التشابه الدلالي (عبر الوسوم المشتركة AND متجهات التضمين).
توليد التضمينات
متى تُولّد التضمينات؟
- عند تخزين الذاكرة — إذا كانت خدمة التضمينات مُعدّة، يُولّد التضمين تزامنيًا
- التوليد الدفعي — يُولّد  تضمينات للذكريات المفتقرة إليها
- التحديثات غير المتزامنة — عند تحديث المحتوى، يُعاد توليد التضمين
مزوّدو التضمينات
يدعم Synapse مزوّدي تضمينات قابلين للإعداد:
- OpenAI (، )
- النماذج المحلية (عبر Ollama أو ما شابه)
- مخصص (نفّذ واجهة التضمينات)
الإعداد عبر متغيرات البيئة:
[CODE BLOCK]
التوليد الدفعي
للعقول التي تفتقر ذكرياتها الكثيرة إلى التضمينات:
[CODE BLOCK]
الأداء
| العملية | زمن الاستجابة |
|-----------|---------|
| توليد تضمين (OpenAI) | 100-200 مللي ث |
| بحث دلالي (1k ذاكرة) | 50-100 مللي ث |
| بحث دلالي (10k ذاكرة) | 200-500 مللي ث |
| توليد دفعي (100 ذاكرة) | 10-20 ث |
> [!NOTE]
> البحث الدلالي أبطأ من FTS5 بسبب حساب المتجهات. استخدم FTS5
> للكلمات المفتاحية المعروفة، والدلالي للاستعلامات المفاهيمية.
القيود
تكلفة التضمينات
إذا كنت تستخدم OpenAI، فإن توليد التضمينات يكلف مالًا ($0.02 لكل 1M رمزًا
لـ text-embedding-3-small). لـ 10,000 ذاكرة بمتوسط 100 رمز لكل واحدة،
هذا $0.02 — ضئيل.
البدء البارد
الذكريات المخزّنة قبل إعداد التضمينات لن تملك تضمينات. شغّل
 للتعبئة الخلفية.
اعتماد على المزوّد
إذا كان مزوّد التضمينات متوقفًا، يفشل البحث الدلالي بلطف (يُرجع
نتائج فارغة أو خطأ). FTS5 لا يزال يعمل.
عندما لا تتوفر التضمينات
إذا لم تُعدّ خدمة التضمينات:
- يُرجع  503 Service Unavailable
- لا يزال  يعمل (فقط لا يُولّد تضمين)
- بحث FTS5 لا يزال يعمل
أفضل الممارسات
> [!TIP]
> - استخدم الدلالي للاستعلامات المفاهيمية — "كيف نتعامل مع X؟"
> - استخدم FTS5 للمصطلحات المحددة — "docker swarm"
> - املأ التضمينات الخلفية دوريًا — 
> - راقب صحة المزوّد — البحث الدلالي يعتمد عليه
> - اجمع مع الوسوم — الدلالي + تصفية الوسوم تضيّق النتائج
الخطوات التالية
- بحث FTS5
- Memory API
- البنية