Dify 能正常对话，不代表知识库已经配置成功。聊天模型负责生成答案，Embedding 模型负责把文本转成向量，Rerank 模型负责重新排序候选文档，它们是三种不同能力。
三类模型分别做什么
| 类型 | 输入 | 输出 | 用途 |
|---|---|---|---|
| Chat | 消息、上下文 | 文本或工具调用 | 生成最终回答 |
| Embedding | 文本或文本数组 | 固定维度向量 | 建库和相似度召回 |
| Rerank | 查询与候选文档 | 相关性分数和排序 | 提高候选结果顺序 |
不要把聊天模型 ID 填进 Embedding 节点，也不要认为模型名称相似就可以互换。
接入前核对
- 从当前模型目录确认 Embedding 和 Rerank 模型 ID。
- 确认它们使用 OpenAI Compatible 端点还是独立供应商协议。
- 确认向量维度、单次批量限制和最大输入长度。
- 确认 Dify 当前插件是否支持自定义 Base URL 和目标模型类型。
- 用少量测试文档先建临时知识库，不要直接重建生产索引。
查看当前模型与价格，模型类型和接口能力以控制台及 API 文档为准。
先验证 Embedding API
当目标模型明确支持 OpenAI 风格 Embedding 端点时，可以先运行：
curl https://www.aifast.club/v1/embeddings \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "控制台中的Embedding模型ID",
"input": ["退款政策是什么？", "如何申请企业发票？"]
}'检查：
- 返回数组数量是否与输入数量一致。
- 每个向量是否为数值数组。
- 所有向量维度是否一致。
usage是否存在以及账单记录是否可核对。- 输入为空、超长或批量过大时返回什么错误。
如果当前模型不是 OpenAI 风格 Embedding 协议，应使用 AI快站文档给出的专用端点，不能强行调用 /v1/embeddings。
向量维度不能随意变化
知识库建成后，查询向量和文档向量必须使用兼容的模型及维度。更换 Embedding 模型通常意味着重新向量化全部文档。
上线前记录：
{
"embedding_model": "MODEL_ID",
"dimension": 0,
"chunk_strategy": "documented-strategy",
"index_version": "2026-07-15-v1"
}不要在没有版本标记的情况下直接覆盖生产索引。先建立新索引，完成回归后再切换。
在 Dify 中配置
Dify 菜单名称会随版本和插件变化，通常从“设置 / 模型供应商”进入：
- 添加支持自定义 Endpoint 的模型供应商。
- 填写独立测试 Key。
- 按插件要求填写
https://www.aifast.club/v1；如果插件自动追加/v1，根据请求日志避免/v1/v1。 - 分别添加聊天、Embedding 和 Rerank 模型。
- 创建临时知识库，上传少量可验证文档。
- 完成向量化后运行固定问题集。
- 再启用 Rerank，并比较启用前后的检索结果。
不要一次同时更换分块、Embedding、召回数量、Rerank 和提示词，否则结果变化后无法定位原因。
如何设置分块
没有适合所有文档的固定分块大小。建议先从业务结构出发：
- FAQ：一问一答作为一个块。
- 产品手册：按标题和小节切分。
- 合同与制度：保留条款编号和上下文。
- 代码：按函数、类或模块边界切分。
每个块保留文档 ID、标题、章节、更新时间和权限标签。检索结果必须能回到原文，而不是只有一段无法定位的文本。
Rerank 怎么验收
Rerank 的输入通常是用户查询和一组候选文档，输出是相关性分数或重排结果。它不能找回召回阶段完全遗漏的文档。
建立至少包含以下情况的测试集：
- 答案明确且只有一个正确章节。
- 多个章节内容相似。
- 问题包含缩写、同义词或产品型号。
- 文档中没有答案。
- 用户无权访问某些候选文档。
同时比较 Recall@K、正确文档排名、最终答案引用和无答案拒答。只看最终回答是否流畅，会掩盖错误检索。
常见错误
对话成功但知识库一直失败
检查是否单独配置 Embedding 模型、端点和模型类型。聊天 Key 可用，不代表当前账号拥有目标向量模型权限。
dimension mismatch
查询和建库使用了不同模型或不同维度。恢复原模型，或者使用新模型重新向量化并切换索引版本。
model not found
从 /v1/models 或控制台复制精确模型 ID，并确认 Dify 节点类型与模型能力一致。
检索结果有内容但答案错误
分别检查原始召回、Rerank 后排序、提示词引用和最终生成。不要只调整聊天模型。
批量建库出现 429
降低并发和批量大小，使用有上限退避，保存已完成的文档 ID。重试时只处理失败分片，避免重复向量化整个知识库。
上线前检查
- Chat、Embedding、Rerank 使用独立且正确的模型类型。
- 向量维度、分块策略和索引版本已记录。
- 权限过滤在 Rerank 和生成前仍然有效。
- 固定问题集包含相似文档、无答案和权限场景。
- 批量建库支持断点、限流和失败重试。
- 更换 Embedding 模型会创建新索引并回归验证。
- 日志不保存完整 API Key 和敏感原文。