Dify 常见问题排查
知识库答不准
优先检查：
- 文档是否过期或混乱。
- 知识库描述是否太短。
- 是否召回了正确片段。
- Prompt 是否要求基于资料回答。
- Top K 和阈值是否合适。
不要一开始就换模型。很多 RAG 问题来自资料质量。
资料外问题乱编
处理方式：
- 在 Prompt 中明确“资料中没有答案就说无法确认”。
- 在知识库描述中写明不包含范围。
- 增加资料外测试集。
- 对高风险问题增加人工转接。
Workflow 下游节点拿不到结果
检查：
- 上游输出字段名是否正确。
- 输出是否为稳定 JSON。
- 是否有空值。
- 分支条件是否走到了预期路径。
- 节点名称和变量引用是否混淆。
Agent 不调用工具
可能原因：
- 工具描述太模糊。
- Prompt 没说明什么时候用工具。
- 用户问题不需要工具。
- 工具鉴权没有配置。
- 最大迭代次数太低。
Agent 乱调用工具
处理方式：
- 明确工具使用条件。
- 给危险操作增加确认步骤。
- 降低最大迭代次数。
- 把固定流程改成 Workflow。
- 将工具拆分成更小权限。
自部署启动失败
检查：
- Docker 是否运行。
- Docker Compose 版本是否满足要求。
- 内存是否足够。
.env是否存在。- 端口是否被占用。
- 日志中哪个容器先失败。
API 调用失败
检查：
- 应用是否发布。
- API Key 是否正确。
- 请求地址是否正确。
- 输入字段是否和应用变量一致。
- 是否超过调用限制。
- 服务端是否能访问 Dify 实例。