# Semantic Search (Embeddings)
SUMMARY: การค้นหา memory เชิงแนวคิดโดยใช้ vector embedding — ค้นหาตามความหมาย ไม่ใช่แค่ keyword

Semantic Search (Embeddings)
Synapse รองรับ semantic search โดยใช้ vector embedding ต่างจาก FTS5 (keyword matching) ตรงที่ semantic search หา memory ตาม ความหมาย — แม้ไม่มี keyword ตรงกัน
วิธีการทำงาน
[CODE BLOCK]
embedding คืออะไร?
embedding เป็นการแทน text ด้วย numerical vector text ที่มีความหมายคล้ายกันจะมี vector คล้ายกัน Synapse สร้าง vector (เช่น 1536 มิติ) สำหรับเนื้อหา memory แต่ละรายการ
Cosine similarity
เพื่อหา memory ที่คล้ายเชิง semantic Synapse คำนวณ cosine similarity ระหว่าง query vector และ memory vector แต่ละตัว similarity สูง = เกี่ยวข้องมากกว่า
เมื่อใดควรใช้ Semantic Search
ใช้ semantic search เมื่อ:
- คุณต้องการ "memory เกี่ยวกับ X" โดย X ถูกอธิบายต่างจากที่เก็บ
- FTS5 ไม่ส่งกลับผลลัพธ์ (ไม่มี keyword ตรง)
- คุณต้องการการจัดกลุ่มเชิงแนวคิด (เช่น memory "deployment" ทั้งหมด แม้บางอันพูดถึง "release")
- Query เป็นคำถาม: "เราจัดการ authentication อย่างไร?"
ใช้ FTS5 เมื่อ:
- คุณรู้ keyword ที่แน่นอน
- คุณต้องการ logic boolean (AND, OR, NOT)
- คุณต้องการ response ในระดับ sub-millisecond
- คุณต้องการ phrase matching
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Response:
[CODE BLOCK]
ตัวอย่าง
หา memory เกี่ยวกับ deployment
[CODE BLOCK]
ส่งกลับ memory เกี่ยวกับ "deployment", "release", "publishing", "rolling out" ฯลฯ
หารูปแบบ authentication
[CODE BLOCK]
ส่งกลับ memory เกี่ยวกับ login, auth, JWT, session management, OAuth ฯลฯ
หา memory ที่คล้ายกัน
[CODE BLOCK]
ใช้ semantic similarity (ผ่าน tag ที่ใช้ร่วมกันและ embedding vector)
การสร้าง Embedding
เมื่อใดจะสร้าง embedding?
- เมื่อเก็บ memory — หาก embeddings service ถูกกำหนดค่า, embedding ถูกสร้างแบบ synchronous
- Batch generation —  สร้าง embedding สำหรับ memory ที่ยังไม่มี
- Async update — เมื่อเนื้อหาถูกอัปเดต, embedding ถูกสร้างใหม่
Embedding provider
Synapse รองรับ embedding provider ที่กำหนดค่าได้:
- OpenAI (, )
- Local model (ผ่าน Ollama หรือคล้ายกัน)
- Custom (implement embeddings interface)
กำหนดค่าผ่าน environment variable:
[CODE BLOCK]
การสร้างแบบ Batch
สำหรับ mind ที่มี memory หลายรายการที่ยังไม่มี embedding:
[CODE BLOCK]
ประสิทธิภาพ
| การดำเนินการ | Latency |
|-----------|---------|
| สร้าง embedding (OpenAI) | 100-200ms |
| Semantic search (1k memory) | 50-100ms |
| Semantic search (10k memory) | 200-500ms |
| การสร้างแบบ batch (100 memory) | 10-20s |
> [!NOTE]
> Semantic search ช้ากว่า FTS5 เนื่องจากการคำนวณ vector ใช้ FTS5 สำหรับ keyword ที่รู้ ใช้ semantic สำหรับ query เชิงแนวคิด
ข้อจำกัด
ต้นทุน embedding
หากใช้ OpenAI การสร้าง embedding มีค่าใช้จ่าย ($0.02 ต่อ 1M token สำหรับ text-embedding-3-small) สำหรับ 10,000 memory เฉลี่ย 100 token ต่อรายการ ประมาณ $0.02 — น้อยมาก
Cold start
memory ที่เก็บก่อนกำหนดค่า embedding จะไม่มี embedding รัน  เพื่อ backfill
การพึ่งพา provider
หาก embedding provider ล่ม semantic search จะล้มเหลวอย่างนุ่มนวล (ส่งกลับผลลัพธ์ว่างหรือ error) FTS5 ยังทำงานได้
เมื่อ Embedding ไม่พร้อมใช้งาน
หาก embeddings service ไม่ถูกกำหนดค่า:
-  ส่งกลับ 503 Service Unavailable
-  ยังทำงานได้ (เพียงแค่ไม่สร้าง embedding)
- FTS5 search ยังทำงานได้
แนวทางปฏิบัติที่ดีที่สุด
> [!TIP]
> - ใช้ semantic สำหรับ query เชิงแนวคิด — "เราจัดการ X อย่างไร?"
> - ใช้ FTS5 สำหรับคำเฉพาะ — "docker swarm"
> - Backfill embedding เป็นคาบ — 
> - ตรวจสอบสุขภาพ provider — semantic search พึ่งพามัน
> - รวมกับ tag — semantic + tag filter จำกัดผลลัพธ์
ขั้นตอนถัดไป
- FTS5 Search
- Memory API
- Architecture