# 语义搜索（向量嵌入）
SUMMARY: 使用向量嵌入进行概念性记忆搜索 — 按意义查找，而非仅按关键词。

语义搜索（向量嵌入）
Synapse 支持基于向量嵌入的语义搜索。与 FTS5（关键词匹配）不同，语义搜索按意义查找记忆 — 即使没有关键词匹配也能找到。
工作原理
[CODE BLOCK]
什么是嵌入？
嵌入是文本的数值向量表示。意义相近的文本有相近的向量。Synapse 为每条记忆的内容生成一个向量（例如 1536 维）。
余弦相似度
为找到语义相似的记忆，Synapse 计算查询向量与每条记忆向量之间的余弦相似度。相似度越高 = 越相关。
何时使用语义搜索
在以下场景使用语义搜索：
- 想要“关于 X 的记忆”，而 X 与存储时的描述不同
- FTS5 返回零结果（无关键词匹配）
- 想要概念聚合（例如所有“部署”相关记忆，即使有些写的是“发布”）
- 查询是一个问题：“我们如何处理认证？”
在以下场景使用 FTS5：
- 已知精确关键词
- 需要布尔逻辑（AND、OR、NOT）
- 需要亚毫秒级响应
- 想要短语匹配
端点
GET /memory/semantic-search
[CODE BLOCK]
响应：
[CODE BLOCK]
示例
查找部署相关记忆
[CODE BLOCK]
返回关于 "deployment"、"release"、"publishing"、"rolling out" 等的记忆。
查找认证模式
[CODE BLOCK]
返回关于 login、auth、JWT、session 管理、OAuth 等的记忆。
查找相似记忆
[CODE BLOCK]
使用语义相似度（基于共享标签 + 嵌入向量）。
嵌入生成
何时生成嵌入？
- 存储记忆时 — 若配置了嵌入服务，则同步生成嵌入
- 批量生成 —  为缺失嵌入的记忆生成
- 异步更新 — 内容更新时重新生成嵌入
嵌入提供方
Synapse 支持可配置的嵌入提供方：
- OpenAI（、）
- 本地模型（通过 Ollama 等）
- 自定义（实现 embeddings 接口）
通过环境变量配置：
[CODE BLOCK]
批量生成
对于很多记忆缺少嵌入的 Mind：
[CODE BLOCK]
性能
| 操作 | 延迟 |
|-----------|---------|
| 生成嵌入（OpenAI） | 100-200ms |
| 语义搜索（1k 条记忆） | 50-100ms |
| 语义搜索（10k 条记忆） | 200-500ms |
| 批量生成（100 条记忆） | 10-20s |
> [!NOTE]
> 由于向量计算，语义搜索比 FTS5 慢。已知关键词时用 FTS5，概念查询用语义搜索。
局限性
嵌入成本
若使用 OpenAI，生成嵌入需要付费（text-embedding-3-small 约 $0.02 / 1M tokens）。对于平均每条 100 tokens 的 10,000 条记忆，约 $0.02 — 可忽略不计。
冷启动
在配置嵌入之前存储的记忆没有嵌入。请运行  补齐。
提供方依赖
如果嵌入提供方宕机，语义搜索会优雅降级（返回空结果或错误）。FTS5 仍可正常工作。
当嵌入不可用时
如果未配置嵌入服务：
-  返回 503 Service Unavailable
-  仍可正常工作（只是不生成嵌入）
- FTS5 搜索仍可正常工作
最佳实践
> [!TIP]
> - 概念查询用语义搜索 — "我们如何处理 X？"
> - 具体术语用 FTS5 — "docker swarm"
> - 定期补齐嵌入 — 
> - 监控提供方健康 — 语义搜索依赖它
> - 与标签结合 — 语义 + 标签过滤缩小结果范围
下一步
- FTS5 搜索
- Memory API
- 架构