Tìm kiếm ngữ nghĩa (Embeddings)

Synapse hỗ trợ tìm kiếm ngữ nghĩa sử dụng vector embeddings. Khác với FTS5 (khớp từ khóa), tìm kiếm ngữ nghĩa tìm bộ nhớ theo ý nghĩa — ngay cả khi không có từ khóa nào khớp.

Cách hoạt động

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

Embeddings là gì?

Embeddings là biểu diễn vector số của văn bản. Văn bản có ý nghĩa tương tự có vector tương tự. Synapse tạo một vector (ví dụ 1536 chiều) cho nội dung mỗi bộ nhớ.

Tương đồng cosine

Để tìm bộ nhớ tương tự về mặt ngữ nghĩa, Synapse tính tương đồng cosine giữa vector truy vấn và mỗi vector bộ nhớ. Tương đồng cao hơn = liên quan hơn.

Khi nào sử dụng tìm kiếm ngữ nghĩa

Sử dụng tìm kiếm ngữ nghĩa khi:

• Bạn muốn "bộ nhớ về X" khi X được mô tả khác với lưu trữ
• FTS5 trả về không kết quả (không khớp từ khóa)
• Bạn muốn nhóm khái niệm (ví dụ tất cả bộ nhớ "deployment", ngay cả khi một số nói "release")
• Truy vấn là một câu hỏi: "làm thế nào chúng ta xử lý xác thực?"

Sử dụng FTS5 khi:

• Bạn biết từ khóa chính xác
• Bạn cần logic boolean (AND, OR, NOT)
• Bạn cần phản hồi dưới mili giây
• Bạn muốn khớp cụm từ

Endpoint

GET /memory/semantic-search

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

Phản hồi:

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

Ví dụ

Tìm bộ nhớ triển khai

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

Trả về bộ nhớ về "deployment", "release", "publishing", "rolling out", v.v.

Tìm mẫu xác thực

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

Trả về bộ nhớ về đăng nhập, xác thực, JWT, quản lý phiên, OAuth, v.v.

Tìm bộ nhớ tương tự

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

Sử dụng tương đồng ngữ nghĩa (qua tag chung VÀ vector embedding).

Tạo embedding

Khi nào embeddings được tạo?

• Khi lưu bộ nhớ — nếu dịch vụ embeddings được cấu hình, embedding được tạo đồng bộ
• Tạo hàng loạt — POST /memory/embed-batch tạo embeddings cho bộ nhớ thiếu
• Cập nhật bất đồng bộ — khi nội dung được cập nhật, embedding được tạo lại

Provider embedding

Synapse hỗ trợ provider embedding có thể cấu hình:

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• Mô hình cục bộ (qua Ollama hoặc tương tự)
• Tùy chỉnh (triển khai giao diện embeddings)

Cấu hình qua biến môi trường:

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

Tạo hàng loạt

Cho mind với nhiều bộ nhớ thiếu embeddings:

# 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

Hiệu suất

Giới hạn

Chi phí embeddings

Nếu sử dụng OpenAI, tạo embeddings tốn tiền (~$0.02 mỗi 1M token cho text-embedding-3-small). Cho 10.000 bộ nhớ trung bình 100 token mỗi cái, đó là ~$0.02 — không đáng kể.

Khởi động lạnh

Bộ nhớ lưu trước khi embeddings được cấu hình sẽ không có embeddings. Chạy POST /memory/embed-batch để backfill.

Phụ thuộc provider

Nếu provider embeddings ngừng hoạt động, tìm kiếm ngữ nghĩa thất bại một cách mềm mại (trả về kết quả rỗng hoặc lỗi). FTS5 vẫn hoạt động.

Khi Embeddings không khả dụng

Nếu dịch vụ embeddings không được cấu hình:

• GET /memory/semantic-search trả về 503 Service Unavailable
• POST /memory vẫn hoạt động (chỉ không có embedding được tạo)
• Tìm kiếm FTS5 vẫn hoạt động

Thực hành tốt nhất

Bước tiếp theo

• Tìm kiếm FTS5
• Memory API
• Kiến trúc