{"title":"Tìm kiếm ngữ nghĩa (Embeddings)","slug":"semantic-search","category":"concepts","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.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":698,"read_minutes":3,"lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Tìm kiếm ngữ nghĩa (Embeddings)\n\nSynapse hỗ trợ tìm kiếm ngữ nghĩa sử dụng vector embeddings. Khác với FTS5 (khớp\ntừ khóa), tìm kiếm ngữ nghĩa tìm bộ nhớ theo **ý nghĩa** — ngay cả khi không có\ntừ khóa nào khớp.\n\n## Cách hoạt động\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### Embeddings là gì?\n\nEmbeddings là biểu diễn vector số của văn bản. Văn bản có ý nghĩa tương tự có\nvector tương tự. Synapse tạo một vector (ví dụ 1536 chiều) cho nội dung mỗi bộ\nnhớ.\n\n### Tương đồng cosine\n\nĐể tìm bộ nhớ tương tự về mặt ngữ nghĩa, Synapse tính tương đồng cosine giữa\nvector truy vấn và mỗi vector bộ nhớ. Tương đồng cao hơn = liên quan hơn.\n\n## Khi nào sử dụng tìm kiếm ngữ nghĩa\n\n### Sử dụng tìm kiếm ngữ nghĩa khi:\n\n- Bạn muốn \"bộ nhớ về X\" khi X được mô tả khác với lưu trữ\n- FTS5 trả về không kết quả (không khớp từ khóa)\n- 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\")\n- Truy vấn là một câu hỏi: \"làm thế nào chúng ta xử lý xác thực?\"\n\n### Sử dụng FTS5 khi:\n\n- Bạn biết từ khóa chính xác\n- Bạn cần logic boolean (AND, OR, NOT)\n- Bạn cần phản hồi dưới mili giây\n- Bạn muốn khớp cụm từ\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\nPhản hồi:\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## Ví dụ\n\n### Tìm bộ nhớ triển khai\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nTrả về bộ nhớ về \"deployment\", \"release\", \"publishing\", \"rolling out\", v.v.\n\n### Tìm mẫu xác thực\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nTrả về bộ nhớ về đăng nhập, xác thực, JWT, quản lý phiên, OAuth, v.v.\n\n### Tìm bộ nhớ tương tự\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nSử dụng tương đồng ngữ nghĩa (qua tag chung VÀ vector embedding).\n\n## Tạo embedding\n\n### Khi nào embeddings được tạo?\n\n- **Khi lưu bộ nhớ** — nếu dịch vụ embeddings được cấu hình, embedding được tạo đồng bộ\n- **Tạo hàng loạt** — `POST /memory/embed-batch` tạo embeddings cho bộ nhớ thiếu\n- **Cập nhật bất đồng bộ** — khi nội dung được cập nhật, embedding được tạo lại\n\n### Provider embedding\n\nSynapse hỗ trợ provider embedding có thể cấu hình:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Mô hình cục bộ** (qua Ollama hoặc tương tự)\n- **Tùy chỉnh** (triển khai giao diện embeddings)\n\nCấu hình qua biến môi trường:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Tạo hàng loạt\n\nCho mind với nhiều bộ nhớ thiếu embeddings:\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## Hiệu suất\n\n| Thao tác | Độ trễ |\n|-----------|---------|\n| Tạo embedding (OpenAI) | 100-200ms |\n| Tìm kiếm ngữ nghĩa (1k bộ nhớ) | 50-100ms |\n| Tìm kiếm ngữ nghĩa (10k bộ nhớ) | 200-500ms |\n| Tạo hàng loạt (100 bộ nhớ) | 10-20s |\n\n> [!NOTE]\n> Tìm kiếm ngữ nghĩa chậm hơn FTS5 do tính toán vector. Sử dụng FTS5 cho từ\n> khóa đã biết, ngữ nghĩa cho truy vấn khái niệm.\n\n## Giới hạn\n\n### Chi phí embeddings\n\nNếu sử dụng OpenAI, tạo embeddings tốn tiền (~$0.02 mỗi 1M token cho\ntext-embedding-3-small). Cho 10.000 bộ nhớ trung bình 100 token mỗi cái, đó là\n~$0.02 — không đáng kể.\n\n### Khởi động lạnh\n\nBộ nhớ lưu trước khi embeddings được cấu hình sẽ không có embeddings. Chạy\n`POST /memory/embed-batch` để backfill.\n\n### Phụ thuộc provider\n\nNếu provider embeddings ngừng hoạt động, tìm kiếm ngữ nghĩa thất bại một cách\nmềm mại (trả về kết quả rỗng hoặc lỗi). FTS5 vẫn hoạt động.\n\n## Khi Embeddings không khả dụng\n\nNếu dịch vụ embeddings không được cấu hình:\n\n- `GET /memory/semantic-search` trả về 503 Service Unavailable\n- `POST /memory` vẫn hoạt động (chỉ không có embedding được tạo)\n- Tìm kiếm FTS5 vẫn hoạt động\n\n## Thực hành tốt nhất\n\n> [!TIP]\n> - **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?\"\n> - **Sử dụng FTS5 cho thuật ngữ cụ thể** — \"docker swarm\"\n> - **Backfill embeddings thường xuyên** — `POST /memory/embed-batch`\n> - **Giám sát sức khỏe provider** — tìm kiếm ngữ nghĩa phụ thuộc vào nó\n> - **Kết hợp với tag** — ngữ nghĩa + bộ lọc tag thu hẹp kết quả\n\n## Bước tiếp theo\n\n- [Tìm kiếm FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Kiến trúc](/docs/concepts/architecture)\n","content_html":"

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

\n

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

\n

Cách hoạt động

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

Embeddings là gì?

\n

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ó\nvector tương tự. Synapse tạo một vector (ví dụ 1536 chiều) cho nội dung mỗi bộ\nnhớ.

\n

Tương đồng cosine

\n

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

\n

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

\n

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

\n\n

Sử dụng FTS5 khi:

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

Phản hồi:

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

Ví dụ

\n

Tìm bộ nhớ triển khai

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

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

\n

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

\n
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.

\n

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

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

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

\n

Tạo embedding

\n

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

\n\n

Provider embedding

\n

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

\n\n

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

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

Tạo hàng loạt

\n

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

\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

Hiệu suất

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
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
\n
Tìm kiếm ngữ nghĩa chậm hơn FTS5 do tính toán vector. Sử dụng FTS5 cho từ\nkhóa đã biết, ngữ nghĩa cho truy vấn khái niệm.

Giới hạn

\n

Chi phí embeddings

\n

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

\n

Khởi động lạnh

\n

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

\n

Phụ thuộc provider

\n

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

\n

Khi Embeddings không khả dụng

\n

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

\n\n

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

\n

Bước tiếp theo

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