{"title":"البحث الدلالي (التضمينات)","slug":"semantic-search","category":"concepts","summary":"بحث مفاهيمي في الذاكرة باستخدام التضمينات المتجهة — ابحث بالمعنى، لا بالكلمات المفتاحية فقط.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":516,"read_minutes":3,"lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# البحث الدلالي (التضمينات)\n\nيدعم Synapse البحث الدلالي باستخدام التضمينات المتجهة. على عكس FTS5 (مطابقة\nالكلمات المفتاحية)، يجد البحث الدلالي الذكريات بـ **المعنى** — حتى لو لم تتطابق\nالكلمات المفتاحية.\n\n## كيفية العمل\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### ما هي التضمينات؟\n\nالتضمينات تمثيلات متجهة عددية للنص. النص ذو المعنى المماثل له متجهات مماثلة.\nيُولّد Synapse متجهًا (مثلًا 1536 بُعدًا) لكل محتوى ذاكرة.\n\n### تشابه جيب التمام\n\nلإيجاد الذكريات المتشابهة دلاليًا، يحسب Synapse تشابه جيب التمام\nبين متجه الاستعلام ومتجه كل ذاكرة. تشابه أعلى = صلة\nأكبر.\n\n## متى تستخدم البحث الدلالي\n\n### استخدم البحث الدلالي عندما:\n\n- تريد \"ذكريات حول X\" حيث يُوصف X بشكل مختلف عن المخزّن\n- لا يُرجع FTS5 نتائج (لا مطابقة للكلمات المفتاحية)\n- تريد تجميعًا مفاهيميًا (مثلًا جميع ذكريات \"النشر\"، حتى لو قال بعضها \"release\")\n- الاستعلام سؤال: \"كيف نتعامل مع المصادقة؟\"\n\n### استخدم FTS5 عندما:\n\n- تعرف الكلمات المفتاحية الدقيقة\n- تحتاج منطقًا منطقيًا (AND، OR، NOT)\n- تحتاج استجابة أقل من مللي ثانية\n- تريد مطابقة العبارات\n\n## نقطة النهاية\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nالاستجابة:\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## أمثلة\n\n### إيجاد ذكريات النشر\n\n```bash\n# قد يفوّت FTS5 بعضها — الدلالي يلتقط الكل\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nيُرجع الذكريات حول \"deployment\" و \"release\" و \"publishing\" و \"rolling out\"،\nإلخ.\n\n### إيجاد أنماط المصادقة\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nيُرجع الذكريات حول login و auth و JWT و إدارة الجلسة و OAuth، إلخ.\n\n### إيجاد ذكريات مماثلة\n\n```bash\n# إيجاد ذكريات مشابهة لذاكرة محددة\ncurl .../memory/related/mem_001\n```\n\nيستخدم التشابه الدلالي (عبر الوسوم المشتركة AND متجهات التضمين).\n\n## توليد التضمينات\n\n### متى تُولّد التضمينات؟\n\n- **عند تخزين الذاكرة** — إذا كانت خدمة التضمينات مُعدّة، يُولّد التضمين تزامنيًا\n- **التوليد الدفعي** — يُولّد `POST /memory/embed-batch` تضمينات للذكريات المفتقرة إليها\n- **التحديثات غير المتزامنة** — عند تحديث المحتوى، يُعاد توليد التضمين\n\n### مزوّدو التضمينات\n\nيدعم Synapse مزوّدي تضمينات قابلين للإعداد:\n\n- **OpenAI** (`text-embedding-3-small`، `text-embedding-3-large`)\n- **النماذج المحلية** (عبر Ollama أو ما شابه)\n- **مخصص** (نفّذ واجهة التضمينات)\n\nالإعداد عبر متغيرات البيئة:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### التوليد الدفعي\n\nللعقول التي تفتقر ذكرياتها الكثيرة إلى التضمينات:\n\n```bash\n# توليد تضمينات لما يصل إلى 100 ذاكرة\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# تحقق من التقدّم\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## الأداء\n\n| العملية | زمن الاستجابة |\n|-----------|---------|\n| توليد تضمين (OpenAI) | 100-200 مللي ث |\n| بحث دلالي (1k ذاكرة) | 50-100 مللي ث |\n| بحث دلالي (10k ذاكرة) | 200-500 مللي ث |\n| توليد دفعي (100 ذاكرة) | 10-20 ث |\n\n> [!NOTE]\n> البحث الدلالي أبطأ من FTS5 بسبب حساب المتجهات. استخدم FTS5\n> للكلمات المفتاحية المعروفة، والدلالي للاستعلامات المفاهيمية.\n\n## القيود\n\n### تكلفة التضمينات\n\nإذا كنت تستخدم OpenAI، فإن توليد التضمينات يكلف مالًا (~$0.02 لكل 1M رمزًا\nلـ text-embedding-3-small). لـ 10,000 ذاكرة بمتوسط 100 رمز لكل واحدة،\nهذا ~$0.02 — ضئيل.\n\n### البدء البارد\n\nالذكريات المخزّنة قبل إعداد التضمينات لن تملك تضمينات. شغّل\n`POST /memory/embed-batch` للتعبئة الخلفية.\n\n### اعتماد على المزوّد\n\nإذا كان مزوّد التضمينات متوقفًا، يفشل البحث الدلالي بلطف (يُرجع\nنتائج فارغة أو خطأ). FTS5 لا يزال يعمل.\n\n## عندما لا تتوفر التضمينات\n\nإذا لم تُعدّ خدمة التضمينات:\n\n- يُرجع `GET /memory/semantic-search` 503 Service Unavailable\n- لا يزال `POST /memory` يعمل (فقط لا يُولّد تضمين)\n- بحث FTS5 لا يزال يعمل\n\n## أفضل الممارسات\n\n> [!TIP]\n> - **استخدم الدلالي للاستعلامات المفاهيمية** — \"كيف نتعامل مع X؟\"\n> - **استخدم FTS5 للمصطلحات المحددة** — \"docker swarm\"\n> - **املأ التضمينات الخلفية دوريًا** — `POST /memory/embed-batch`\n> - **راقب صحة المزوّد** — البحث الدلالي يعتمد عليه\n> - **اجمع مع الوسوم** — الدلالي + تصفية الوسوم تضيّق النتائج\n\n## الخطوات التالية\n\n- [بحث FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [البنية](/docs/concepts/architecture)\n","content_html":"

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

\n

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

\n

كيفية العمل

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

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

\n

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

\n

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

\n

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

\n

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

\n

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

\n\n

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

\n\n

نقطة النهاية

\n

GET /memory/semantic-search

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

الاستجابة:

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

أمثلة

\n

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

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

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

\n

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

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

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

\n

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

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

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

\n

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

\n

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

\n\n

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

\n

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

\n\n

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

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

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

\n

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

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

الأداء

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
العمليةزمن الاستجابة
توليد تضمين (OpenAI)100-200 مللي ث
بحث دلالي (1k ذاكرة)50-100 مللي ث
بحث دلالي (10k ذاكرة)200-500 مللي ث
توليد دفعي (100 ذاكرة)10-20 ث
\n
البحث الدلالي أبطأ من FTS5 بسبب حساب المتجهات. استخدم FTS5\nللكلمات المفتاحية المعروفة، والدلالي للاستعلامات المفاهيمية.

القيود

\n

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

\n

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

\n

البدء البارد

\n

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

\n

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

\n

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

\n

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

\n

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

\n\n

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

\n

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

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}