البحث الدلالي (التضمينات)

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

كيفية العمل

1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned

ما هي التضمينات؟

التضمينات تمثيلات متجهة عددية للنص. النص ذو المعنى المماثل له متجهات مماثلة. يُولّد Synapse متجهًا (مثلًا 1536 بُعدًا) لكل محتوى ذاكرة.

تشابه جيب التمام

لإيجاد الذكريات المتشابهة دلاليًا، يحسب Synapse تشابه جيب التمام بين متجه الاستعلام ومتجه كل ذاكرة. تشابه أعلى = صلة أكبر.

متى تستخدم البحث الدلالي

استخدم البحث الدلالي عندما:

• تريد "ذكريات حول X" حيث يُوصف X بشكل مختلف عن المخزّن
• لا يُرجع FTS5 نتائج (لا مطابقة للكلمات المفتاحية)
• تريد تجميعًا مفاهيميًا (مثلًا جميع ذكريات "النشر"، حتى لو قال بعضها "release")
• الاستعلام سؤال: "كيف نتعامل مع المصادقة؟"

استخدم FTS5 عندما:

• تعرف الكلمات المفتاحية الدقيقة
• تحتاج منطقًا منطقيًا (AND، OR، NOT)
• تحتاج استجابة أقل من مللي ثانية
• تريد مطابقة العبارات

نقطة النهاية

GET /memory/semantic-search

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

الاستجابة:

{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}

أمثلة

إيجاد ذكريات النشر

# قد يفوّت FTS5 بعضها — الدلالي يلتقط الكل
curl .../memory/semantic-search?q=deployment+process

يُرجع الذكريات حول "deployment" و "release" و "publishing" و "rolling out"، إلخ.

إيجاد أنماط المصادقة

curl .../memory/semantic-search?q=how+do+users+log+in

يُرجع الذكريات حول login و auth و JWT و إدارة الجلسة و OAuth، إلخ.

إيجاد ذكريات مماثلة

# إيجاد ذكريات مشابهة لذاكرة محددة
curl .../memory/related/mem_001

يستخدم التشابه الدلالي (عبر الوسوم المشتركة AND متجهات التضمين).

توليد التضمينات

متى تُولّد التضمينات؟

• عند تخزين الذاكرة — إذا كانت خدمة التضمينات مُعدّة، يُولّد التضمين تزامنيًا
• التوليد الدفعي — يُولّد POST /memory/embed-batch تضمينات للذكريات المفتقرة إليها
• التحديثات غير المتزامنة — عند تحديث المحتوى، يُعاد توليد التضمين

مزوّدو التضمينات

يدعم Synapse مزوّدي تضمينات قابلين للإعداد:

• OpenAI (text-embedding-3-small، text-embedding-3-large)
• النماذج المحلية (عبر Ollama أو ما شابه)
• مخصص (نفّذ واجهة التضمينات)

الإعداد عبر متغيرات البيئة:

EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small

التوليد الدفعي

للعقول التي تفتقر ذكرياتها الكثيرة إلى التضمينات:

# توليد تضمينات لما يصل إلى 100 ذاكرة
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# تحقق من التقدّم
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

الأداء

القيود

تكلفة التضمينات

إذا كنت تستخدم OpenAI، فإن توليد التضمينات يكلف مالًا (~$0.02 لكل 1M رمزًا لـ text-embedding-3-small). لـ 10,000 ذاكرة بمتوسط 100 رمز لكل واحدة، هذا ~$0.02 — ضئيل.

البدء البارد

الذكريات المخزّنة قبل إعداد التضمينات لن تملك تضمينات. شغّل POST /memory/embed-batch للتعبئة الخلفية.

اعتماد على المزوّد

إذا كان مزوّد التضمينات متوقفًا، يفشل البحث الدلالي بلطف (يُرجع نتائج فارغة أو خطأ). FTS5 لا يزال يعمل.

عندما لا تتوفر التضمينات

إذا لم تُعدّ خدمة التضمينات:

• يُرجع GET /memory/semantic-search 503 Service Unavailable
• لا يزال POST /memory يعمل (فقط لا يُولّد تضمين)
• بحث FTS5 لا يزال يعمل

أفضل الممارسات

الخطوات التالية

• بحث FTS5
• Memory API
• البنية