# Tìm kiếm ngữ nghĩa (Embeddings)
SUMMARY: Tìm kiếm bộ nhớ khái niệm sử dụng vector embeddings — tìm theo ý nghĩa, không chỉ từ khóa.

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
[CODE BLOCK]
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
[CODE BLOCK]
Phản hồi:
[CODE BLOCK]
Ví dụ
Tìm bộ nhớ triển khai
[CODE BLOCK]
Trả về bộ nhớ về "deployment", "release", "publishing", "rolling out", v.v.
Tìm mẫu xác thực
[CODE BLOCK]
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ự
[CODE BLOCK]
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 —  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 (, )
- 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:
[CODE BLOCK]
Tạo hàng loạt
Cho mind với nhiều bộ nhớ thiếu embeddings:
[CODE BLOCK]
Hiệu suất
| Thao tác | Độ trễ |
|-----------|---------|
| Tạo embedding (OpenAI) | 100-200ms |
| Tìm kiếm ngữ nghĩa (1k bộ nhớ) | 50-100ms |
| Tìm kiếm ngữ nghĩa (10k bộ nhớ) | 200-500ms |
| Tạo hàng loạt (100 bộ nhớ) | 10-20s |
> [!NOTE]
> Tìm kiếm ngữ nghĩa chậm hơn FTS5 do tính toán vector. Sử dụng FTS5 cho từ
> khóa đã biết, ngữ nghĩa cho truy vấn khái niệm.
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
 để 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:
-  trả về 503 Service Unavailable
-  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
> [!TIP]
> - Sử dụng ngữ nghĩa cho truy vấn khái niệm — "làm thế nào chúng ta xử lý X?"
> - Sử dụng FTS5 cho thuật ngữ cụ thể — "docker swarm"
> - Backfill embeddings thường xuyên — 
> - Giám sát sức khỏe provider — tìm kiếm ngữ nghĩa phụ thuộc vào nó
> - Kết hợp với tag — ngữ nghĩa + bộ lọc tag thu hẹp kết quả
Bước tiếp theo
- Tìm kiếm FTS5
- Memory API
- Kiến trúc