{"title":"语义搜索（向量嵌入）","slug":"semantic-search","category":"concepts","summary":"使用向量嵌入进行概念性记忆搜索 — 按意义查找，而非仅按关键词。","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":221,"read_minutes":1,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 语义搜索（向量嵌入）\n\nSynapse 支持基于向量嵌入的语义搜索。与 FTS5（关键词匹配）不同，语义搜索按**意义**查找记忆 — 即使没有关键词匹配也能找到。\n\n## 工作原理\n\n```\n1. 记忆存储 → 生成嵌入 → 存储向量\n2. 搜索查询 → 生成嵌入 → 比较向量\n3. 余弦相似度 → 返回前 N 个结果\n```\n\n### 什么是嵌入？\n\n嵌入是文本的数值向量表示。意义相近的文本有相近的向量。Synapse 为每条记忆的内容生成一个向量（例如 1536 维）。\n\n### 余弦相似度\n\n为找到语义相似的记忆，Synapse 计算查询向量与每条记忆向量之间的余弦相似度。相似度越高 = 越相关。\n\n## 何时使用语义搜索\n\n### 在以下场景使用语义搜索：\n\n- 想要“关于 X 的记忆”，而 X 与存储时的描述不同\n- FTS5 返回零结果（无关键词匹配）\n- 想要概念聚合（例如所有“部署”相关记忆，即使有些写的是“发布”）\n- 查询是一个问题：“我们如何处理认证？”\n\n### 在以下场景使用 FTS5：\n\n- 已知精确关键词\n- 需要布尔逻辑（AND、OR、NOT）\n- 需要亚毫秒级响应\n- 想要短语匹配\n\n## 端点\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\n响应：\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## 示例\n\n### 查找部署相关记忆\n\n```bash\n# FTS5 可能遗漏部分 — 语义搜索能全部捕获\ncurl .../memory/semantic-search?q=deployment+process\n```\n\n返回关于 \"deployment\"、\"release\"、\"publishing\"、\"rolling out\" 等的记忆。\n\n### 查找认证模式\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\n返回关于 login、auth、JWT、session 管理、OAuth 等的记忆。\n\n### 查找相似记忆\n\n```bash\n# 查找与某条记忆相似的记忆\ncurl .../memory/related/mem_001\n```\n\n使用语义相似度（基于共享标签 + 嵌入向量）。\n\n## 嵌入生成\n\n### 何时生成嵌入？\n\n- **存储记忆时** — 若配置了嵌入服务，则同步生成嵌入\n- **批量生成** — `POST /memory/embed-batch` 为缺失嵌入的记忆生成\n- **异步更新** — 内容更新时重新生成嵌入\n\n### 嵌入提供方\n\nSynapse 支持可配置的嵌入提供方：\n\n- **OpenAI**（`text-embedding-3-small`、`text-embedding-3-large`）\n- **本地模型**（通过 Ollama 等）\n- **自定义**（实现 embeddings 接口）\n\n通过环境变量配置：\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### 批量生成\n\n对于很多记忆缺少嵌入的 Mind：\n\n```bash\n# 为最多 100 条记忆生成嵌入\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# 检查进度\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## 性能\n\n| 操作 | 延迟 |\n|-----------|---------|\n| 生成嵌入（OpenAI） | 100-200ms |\n| 语义搜索（1k 条记忆） | 50-100ms |\n| 语义搜索（10k 条记忆） | 200-500ms |\n| 批量生成（100 条记忆） | 10-20s |\n\n> [!NOTE]\n> 由于向量计算，语义搜索比 FTS5 慢。已知关键词时用 FTS5，概念查询用语义搜索。\n\n## 局限性\n\n### 嵌入成本\n\n若使用 OpenAI，生成嵌入需要付费（text-embedding-3-small 约 $0.02 / 1M tokens）。对于平均每条 100 tokens 的 10,000 条记忆，约 $0.02 — 可忽略不计。\n\n### 冷启动\n\n在配置嵌入之前存储的记忆没有嵌入。请运行 `POST /memory/embed-batch` 补齐。\n\n### 提供方依赖\n\n如果嵌入提供方宕机，语义搜索会优雅降级（返回空结果或错误）。FTS5 仍可正常工作。\n\n## 当嵌入不可用时\n\n如果未配置嵌入服务：\n\n- `GET /memory/semantic-search` 返回 503 Service Unavailable\n- `POST /memory` 仍可正常工作（只是不生成嵌入）\n- FTS5 搜索仍可正常工作\n\n## 最佳实践\n\n> [!TIP]\n> - **概念查询用语义搜索** — \"我们如何处理 X？\"\n> - **具体术语用 FTS5** — \"docker swarm\"\n> - **定期补齐嵌入** — `POST /memory/embed-batch`\n> - **监控提供方健康** — 语义搜索依赖它\n> - **与标签结合** — 语义 + 标签过滤缩小结果范围\n\n## 下一步\n\n- [FTS5 搜索](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [架构](/docs/concepts/architecture)\n","content_html":"

语义搜索（向量嵌入）

\n

Synapse 支持基于向量嵌入的语义搜索。与 FTS5（关键词匹配）不同，语义搜索按意义查找记忆 — 即使没有关键词匹配也能找到。

\n

工作原理

\n
1. 记忆存储 → 生成嵌入 → 存储向量\n2. 搜索查询 → 生成嵌入 → 比较向量\n3. 余弦相似度 → 返回前 N 个结果

什么是嵌入？

\n

嵌入是文本的数值向量表示。意义相近的文本有相近的向量。Synapse 为每条记忆的内容生成一个向量（例如 1536 维）。

\n

余弦相似度

\n

为找到语义相似的记忆，Synapse 计算查询向量与每条记忆向量之间的余弦相似度。相似度越高 = 越相关。

\n

何时使用语义搜索

\n

在以下场景使用语义搜索：

\n\n

在以下场景使用 FTS5：

\n\n

端点

\n

GET /memory/semantic-search

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

响应：

\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
# FTS5 可能遗漏部分 — 语义搜索能全部捕获\ncurl .../memory/semantic-search?q=deployment+process

返回关于 "deployment"、"release"、"publishing"、"rolling out" 等的记忆。

\n

查找认证模式

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

返回关于 login、auth、JWT、session 管理、OAuth 等的记忆。

\n

查找相似记忆

\n
# 查找与某条记忆相似的记忆\ncurl .../memory/related/mem_001

使用语义相似度（基于共享标签 + 嵌入向量）。

\n

嵌入生成

\n

何时生成嵌入？

\n\n

嵌入提供方

\n

Synapse 支持可配置的嵌入提供方：

\n\n

通过环境变量配置：

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

批量生成

\n

对于很多记忆缺少嵌入的 Mind：

\n
# 为最多 100 条记忆生成嵌入\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# 检查进度\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

性能

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
操作延迟
生成嵌入（OpenAI）100-200ms
语义搜索（1k 条记忆）50-100ms
语义搜索（10k 条记忆）200-500ms
批量生成（100 条记忆）10-20s
\n
由于向量计算，语义搜索比 FTS5 慢。已知关键词时用 FTS5，概念查询用语义搜索。

局限性

\n

嵌入成本

\n

若使用 OpenAI，生成嵌入需要付费（text-embedding-3-small 约 $0.02 / 1M tokens）。对于平均每条 100 tokens 的 10,000 条记忆，约 $0.02 — 可忽略不计。

\n

冷启动

\n

在配置嵌入之前存储的记忆没有嵌入。请运行 POST /memory/embed-batch 补齐。

\n

提供方依赖

\n

如果嵌入提供方宕机，语义搜索会优雅降级（返回空结果或错误）。FTS5 仍可正常工作。

\n

当嵌入不可用时

\n

如果未配置嵌入服务：

\n\n

最佳实践

\n

下一步

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