跳转至

# 嵌入 / 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）

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

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`（便宜、快速）