# 语义搜索（向量嵌入）

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

## 工作原理

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

### 什么是嵌入？

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

### 余弦相似度

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

## 何时使用语义搜索

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

- 想要“关于 X 的记忆”，而 X 与存储时的描述不同
- FTS5 返回零结果（无关键词匹配）
- 想要概念聚合（例如所有“部署”相关记忆，即使有些写的是“发布”）
- 查询是一个问题：“我们如何处理认证？”

### 在以下场景使用 FTS5：

- 已知精确关键词
- 需要布尔逻辑（AND、OR、NOT）
- 需要亚毫秒级响应
- 想要短语匹配

## 端点

### GET /memory/semantic-search

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

响应：

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

## 示例

### 查找部署相关记忆

```bash
# FTS5 可能遗漏部分 — 语义搜索能全部捕获
curl .../memory/semantic-search?q=deployment+process
```

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

### 查找认证模式

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

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

### 查找相似记忆

```bash
# 查找与某条记忆相似的记忆
curl .../memory/related/mem_001
```

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

## 嵌入生成

### 何时生成嵌入？

- **存储记忆时** — 若配置了嵌入服务，则同步生成嵌入
- **批量生成** — `POST /memory/embed-batch` 为缺失嵌入的记忆生成
- **异步更新** — 内容更新时重新生成嵌入

### 嵌入提供方

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

- **OpenAI**（`text-embedding-3-small`、`text-embedding-3-large`）
- **本地模型**（通过 Ollama 等）
- **自定义**（实现 embeddings 接口）

通过环境变量配置：

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

### 批量生成

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

```bash
# 为最多 100 条记忆生成嵌入
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# 检查进度
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## 性能

| 操作 | 延迟 |
|-----------|---------|
| 生成嵌入（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 — 可忽略不计。

### 冷启动

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

### 提供方依赖

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

## 当嵌入不可用时

如果未配置嵌入服务：

- `GET /memory/semantic-search` 返回 503 Service Unavailable
- `POST /memory` 仍可正常工作（只是不生成嵌入）
- FTS5 搜索仍可正常工作

## 最佳实践

> [!TIP]
> - **概念查询用语义搜索** — "我们如何处理 X？"
> - **具体术语用 FTS5** — "docker swarm"
> - **定期补齐嵌入** — `POST /memory/embed-batch`
> - **监控提供方健康** — 语义搜索依赖它
> - **与标签结合** — 语义 + 标签过滤缩小结果范围

## 下一步

- [FTS5 搜索](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [架构](/docs/concepts/architecture)