Semantic Search (Embeddings)

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

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

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

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

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

Response:

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

ตัวอย่าง

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

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

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

หารูปแบบ authentication

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

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

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

# Find memories similar to a specific one
curl .../memory/related/mem_001

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

การสร้าง Embedding

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

• เมื่อเก็บ memory — หาก embeddings service ถูกกำหนดค่า, embedding ถูกสร้างแบบ synchronous
• Batch generation — POST /memory/embed-batch สร้าง embedding สำหรับ memory ที่ยังไม่มี
• Async update — เมื่อเนื้อหาถูกอัปเดต, embedding ถูกสร้างใหม่

Embedding provider

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

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• Local model (ผ่าน Ollama หรือคล้ายกัน)
• Custom (implement embeddings interface)

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

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

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

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

# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

ประสิทธิภาพ

ข้อจำกัด

ต้นทุน embedding

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

Cold start

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

การพึ่งพา provider

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

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

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

• GET /memory/semantic-search ส่งกลับ 503 Service Unavailable
• POST /memory ยังทำงานได้ (เพียงแค่ไม่สร้าง embedding)
• FTS5 search ยังทำงานได้

แนวทางปฏิบัติที่ดีที่สุด

ขั้นตอนถัดไป

• FTS5 Search
• Memory API
• Architecture