{"title":"Semantic Search (Embeddings)","slug":"semantic-search","category":"concepts","summary":"การค้นหา memory เชิงแนวคิดโดยใช้ vector embedding — ค้นหาตามความหมาย ไม่ใช่แค่ keyword","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":427,"read_minutes":2,"lang":"th","translated":true,"requested_lang":"th","content_markdown":"\n# Semantic Search (Embeddings)\n\nSynapse รองรับ semantic search โดยใช้ vector embedding ต่างจาก FTS5 (keyword matching) ตรงที่ semantic search หา memory ตาม **ความหมาย** — แม้ไม่มี keyword ตรงกัน\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### embedding คืออะไร?\n\nembedding เป็นการแทน text ด้วย numerical vector text ที่มีความหมายคล้ายกันจะมี vector คล้ายกัน Synapse สร้าง vector (เช่น 1536 มิติ) สำหรับเนื้อหา memory แต่ละรายการ\n\n### Cosine similarity\n\nเพื่อหา memory ที่คล้ายเชิง semantic Synapse คำนวณ cosine similarity ระหว่าง query vector และ memory vector แต่ละตัว similarity สูง = เกี่ยวข้องมากกว่า\n\n## เมื่อใดควรใช้ Semantic Search\n\n### ใช้ semantic search เมื่อ:\n\n- คุณต้องการ \"memory เกี่ยวกับ X\" โดย X ถูกอธิบายต่างจากที่เก็บ\n- FTS5 ไม่ส่งกลับผลลัพธ์ (ไม่มี keyword ตรง)\n- คุณต้องการการจัดกลุ่มเชิงแนวคิด (เช่น memory \"deployment\" ทั้งหมด แม้บางอันพูดถึง \"release\")\n- Query เป็นคำถาม: \"เราจัดการ authentication อย่างไร?\"\n\n### ใช้ FTS5 เมื่อ:\n\n- คุณรู้ keyword ที่แน่นอน\n- คุณต้องการ logic boolean (AND, OR, NOT)\n- คุณต้องการ response ในระดับ sub-millisecond\n- คุณต้องการ phrase matching\n\n## Endpoint\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\nResponse:\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### หา memory เกี่ยวกับ deployment\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nส่งกลับ memory เกี่ยวกับ \"deployment\", \"release\", \"publishing\", \"rolling out\" ฯลฯ\n\n### หารูปแบบ authentication\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nส่งกลับ memory เกี่ยวกับ login, auth, JWT, session management, OAuth ฯลฯ\n\n### หา memory ที่คล้ายกัน\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nใช้ semantic similarity (ผ่าน tag ที่ใช้ร่วมกันและ embedding vector)\n\n## การสร้าง Embedding\n\n### เมื่อใดจะสร้าง embedding?\n\n- **เมื่อเก็บ memory** — หาก embeddings service ถูกกำหนดค่า, embedding ถูกสร้างแบบ synchronous\n- **Batch generation** — `POST /memory/embed-batch` สร้าง embedding สำหรับ memory ที่ยังไม่มี\n- **Async update** — เมื่อเนื้อหาถูกอัปเดต, embedding ถูกสร้างใหม่\n\n### Embedding provider\n\nSynapse รองรับ embedding provider ที่กำหนดค่าได้:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Local model** (ผ่าน Ollama หรือคล้ายกัน)\n- **Custom** (implement embeddings interface)\n\nกำหนดค่าผ่าน environment variable:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### การสร้างแบบ Batch\n\nสำหรับ mind ที่มี memory หลายรายการที่ยังไม่มี embedding:\n\n```bash\n# Generate embeddings for up to 100 memories\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# Check progress\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## ประสิทธิภาพ\n\n| การดำเนินการ | Latency |\n|-----------|---------|\n| สร้าง embedding (OpenAI) | 100-200ms |\n| Semantic search (1k memory) | 50-100ms |\n| Semantic search (10k memory) | 200-500ms |\n| การสร้างแบบ batch (100 memory) | 10-20s |\n\n> [!NOTE]\n> Semantic search ช้ากว่า FTS5 เนื่องจากการคำนวณ vector ใช้ FTS5 สำหรับ keyword ที่รู้ ใช้ semantic สำหรับ query เชิงแนวคิด\n\n## ข้อจำกัด\n\n### ต้นทุน embedding\n\nหากใช้ OpenAI การสร้าง embedding มีค่าใช้จ่าย (~$0.02 ต่อ 1M token สำหรับ text-embedding-3-small) สำหรับ 10,000 memory เฉลี่ย 100 token ต่อรายการ ประมาณ $0.02 — น้อยมาก\n\n### Cold start\n\nmemory ที่เก็บก่อนกำหนดค่า embedding จะไม่มี embedding รัน `POST /memory/embed-batch` เพื่อ backfill\n\n### การพึ่งพา provider\n\nหาก embedding provider ล่ม semantic search จะล้มเหลวอย่างนุ่มนวล (ส่งกลับผลลัพธ์ว่างหรือ error) FTS5 ยังทำงานได้\n\n## เมื่อ Embedding ไม่พร้อมใช้งาน\n\nหาก embeddings service ไม่ถูกกำหนดค่า:\n\n- `GET /memory/semantic-search` ส่งกลับ 503 Service Unavailable\n- `POST /memory` ยังทำงานได้ (เพียงแค่ไม่สร้าง embedding)\n- FTS5 search ยังทำงานได้\n\n## แนวทางปฏิบัติที่ดีที่สุด\n\n> [!TIP]\n> - **ใช้ semantic สำหรับ query เชิงแนวคิด** — \"เราจัดการ X อย่างไร?\"\n> - **ใช้ FTS5 สำหรับคำเฉพาะ** — \"docker swarm\"\n> - **Backfill embedding เป็นคาบ** — `POST /memory/embed-batch`\n> - **ตรวจสอบสุขภาพ provider** — semantic search พึ่งพามัน\n> - **รวมกับ tag** — semantic + tag filter จำกัดผลลัพธ์\n\n## ขั้นตอนถัดไป\n\n- [FTS5 Search](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architecture](/docs/concepts/architecture)\n","content_html":"

Semantic Search (Embeddings)

\n

Synapse รองรับ semantic search โดยใช้ vector embedding ต่างจาก FTS5 (keyword matching) ตรงที่ semantic search หา memory ตาม ความหมาย — แม้ไม่มี keyword ตรงกัน

\n

วิธีการทำงาน

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

embedding คืออะไร?

\n

embedding เป็นการแทน text ด้วย numerical vector text ที่มีความหมายคล้ายกันจะมี vector คล้ายกัน Synapse สร้าง vector (เช่น 1536 มิติ) สำหรับเนื้อหา memory แต่ละรายการ

\n

Cosine similarity

\n

เพื่อหา memory ที่คล้ายเชิง semantic Synapse คำนวณ cosine similarity ระหว่าง query vector และ memory vector แต่ละตัว similarity สูง = เกี่ยวข้องมากกว่า

\n

เมื่อใดควรใช้ Semantic Search

\n

ใช้ semantic search เมื่อ:

\n\n

ใช้ FTS5 เมื่อ:

\n\n

Endpoint

\n

GET /memory/semantic-search

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

Response:

\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

หา memory เกี่ยวกับ deployment

\n
# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process

ส่งกลับ memory เกี่ยวกับ "deployment", "release", "publishing", "rolling out" ฯลฯ

\n

หารูปแบบ authentication

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

ส่งกลับ memory เกี่ยวกับ login, auth, JWT, session management, OAuth ฯลฯ

\n

หา memory ที่คล้ายกัน

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

ใช้ semantic similarity (ผ่าน tag ที่ใช้ร่วมกันและ embedding vector)

\n

การสร้าง Embedding

\n

เมื่อใดจะสร้าง embedding?

\n\n

Embedding provider

\n

Synapse รองรับ embedding provider ที่กำหนดค่าได้:

\n\n

กำหนดค่าผ่าน environment variable:

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

การสร้างแบบ Batch

\n

สำหรับ mind ที่มี memory หลายรายการที่ยังไม่มี embedding:

\n
# Generate embeddings for up to 100 memories\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# Check progress\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
การดำเนินการLatency
สร้าง embedding (OpenAI)100-200ms
Semantic search (1k memory)50-100ms
Semantic search (10k memory)200-500ms
การสร้างแบบ batch (100 memory)10-20s
\n
Semantic search ช้ากว่า FTS5 เนื่องจากการคำนวณ vector ใช้ FTS5 สำหรับ keyword ที่รู้ ใช้ semantic สำหรับ query เชิงแนวคิด

ข้อจำกัด

\n

ต้นทุน embedding

\n

หากใช้ OpenAI การสร้าง embedding มีค่าใช้จ่าย (~$0.02 ต่อ 1M token สำหรับ text-embedding-3-small) สำหรับ 10,000 memory เฉลี่ย 100 token ต่อรายการ ประมาณ $0.02 — น้อยมาก

\n

Cold start

\n

memory ที่เก็บก่อนกำหนดค่า embedding จะไม่มี embedding รัน POST /memory/embed-batch เพื่อ backfill

\n

การพึ่งพา provider

\n

หาก embedding provider ล่ม semantic search จะล้มเหลวอย่างนุ่มนวล (ส่งกลับผลลัพธ์ว่างหรือ error) FTS5 ยังทำงานได้

\n

เมื่อ Embedding ไม่พร้อมใช้งาน

\n

หาก embeddings service ไม่ถูกกำหนดค่า:

\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"]}