嵌入 / 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（便宜、快速）