# 嵌入 / RAG

嵌入模型将文本转换为捕获含义的数值向量。Agora 使用这些向量对你对话历史进行语义搜索（RAG）——通过消息的含义而非仅仅词语查找。

## 工作原理

1. 每条消息发送给嵌入模型
2. 模型返回一个表示消息含义的向量（数字列表）
3. 搜索时，你的查询也被嵌入
4. Agora 计算查询向量与所有消息向量之间的**余弦相似度**
5. 高于阈值的相似度消息作为匹配返回

## 支持的提供商

| 提供商 | Base URL | 需要 API Key | 备注 |
|----------|----------|------------------|-------|
| **OpenAI** | `https://api.openai.com/v1` | 是 | `text-embedding-3-small`、`text-embedding-3-large` |
| **Mistral** | `https://api.mistral.ai/v1` | 是 | `mistral-embed` |
| **Voyage AI** | `https://api.voyageai.com/v1` | 是 | `voyage-3`、`voyage-3-lite` |
| **SiliconFlow** | `https://api.siliconflow.cn/v1` | 是 | `BAAI/bge-large-zh-v1.5`（中文优化） |
| **Ollama** | `http://localhost:11434/v1` | 否 | `qwen3-embedding`、`nomic-embed-text` 等 |
| **自定义** | 任意 | 可选 | 任意兼容 OpenAI 的嵌入端点 |
| **本地** | 无 | 否 | 通过 llama.cpp 的 GGUF 嵌入模型 |

---

## 添加嵌入模型

### 远程 (API)

1. 前往 **设置 → 对话搜索**
2. 点按 **添加远程模型**
3. 配置：

| 字段 | 描述 |
|-------|-------------|
| **提供商** | 从下拉菜单选择（OpenAI、Mistral、Voyage、SiliconFlow、Ollama、自定义） |
| **模型名称** | 精确的模型 ID（如 `text-embedding-3-small`） |
| **Base URL** | 已知提供商自动填充；可编辑用于代理 |
| **API 密钥** | 留空自动从聊天提供商密钥解析，或输入专用密钥 |
| **批量大小** | 每次 API 请求嵌入的消息数（1–100） |

4. 点按 **添加** — 保存前运行连接测试

!!! tip
    如果你已为聊天配置了相同的提供商，API 密钥字段可选。留空，Agora 会自动解析你的聊天 API 密钥。

### 本地 (GGUF)

1. 前往 **设置 → 对话搜索**
2. 点按 **添加本地模型**
3. 导入 `.gguf` 嵌入模型文件（如 `bge-small-en-v1.5-q4_k.gguf`）
4. 命名
5. 点按 **添加**

嵌入模型通常远比聊天模型小——最多几百 MB。

### Ollama

1. 在机器上安装 Ollama
2. 拉取嵌入模型：`ollama pull qwen3-embedding:8b`
3. 在 Agora 中添加远程模型：
    - 提供商：**Ollama**
    - Base URL：`http://<host>:11434/v1`
    - 模型名称：`qwen3-embedding:8b`（包含 `:标签`）
    - API 密钥：留空
4. 点按 **添加**

!!! note
    Ollama 后缀标签如 `:8b`、`:latest` 是模型名称的一部分。使用 `ollama list` 中的精确名称。

---

## 缓存

添加模型后，需要缓存消息（生成嵌入）：

1. 在嵌入模型上点按**缓存**
2. Agora 按批次处理所有未缓存的消息
3. 圆形进度指示器显示当前进度
4. 完成："所有 N 条消息已缓存"

### 自动缓存

启用**自动缓存**以自动嵌入新消息。这保持搜索索引始终最新。

### 重新缓存

点按**重新缓存**删除所有现有嵌入并从头重建。使用场景：

- 切换到不同的嵌入模型
- 嵌入质量似乎下降
- 缓存不一致

!!! warning
    重新缓存不可撤销，对大量消息历史可能需要很长时间。

---

## 批量大小

**批量大小**设置（1–100）控制缓存期间每次 API 请求发送的消息数：

- **更高**：缓存更快，但 API 载荷更大
- **更低**：请求更小，慢但更可靠（慢速连接时）

从默认值开始，如果遇到超时（降低）或想要更快缓存（提高）则调整。

---

## 测试设置

添加远程模型时，Agora 运行自动连接测试。如果失败：

1. 检查模型名称 — Ollama 包含标签（`:8b`、`:latest`）
2. 验证 Base URL 可从设备访问
3. 确认 API 密钥有效（如需要）
4. 尝试该提供商的已知模型名称

常见错误：
- **"模型名称错误"** — 检查精确拼写，包括标签
- **"Base URL 错误"** — 确保端点支持 `/v1/embeddings`
- **"缺少 API 密钥"** — 某些提供商需要认证
- **"网络错误"** — 检查连通性

---

## 提供商推荐

| 使用场景 | 推荐提供商 |
|----------|---------------------|
| **最佳质量（英文）** | Voyage AI `voyage-3` |
| **最佳质量（中文）** | SiliconFlow `BAAI/bge-large-zh-v1.5` |
| **免费 / 自托管** | Ollama `qwen3-embedding` 或 `nomic-embed-text` |
| **完全离线** | 本地 GGUF `bge-small-en-v1.5` |
| **已使用 OpenAI** | OpenAI `text-embedding-3-small`（便宜、快速） |
