Dify 使用教程：从创建应用、知识库到工作流、发布与 API

本文核验日期为 2026-07-31，基于 Dify 官方稳定流程整理。本文未登录具体账号做端到端实测，界面与权益以当前实例为准；教程不依赖按钮位置，用测试和日志信号验收。产品定位见 Dify 工具页，选型对照可阅读 2026 年 AI 智能体平台排行榜，能力边界可结合 Dify 完整评测 核对，更多内容见 AI 智能体与自动化分类。

开始前先确定云端还是自部署

做什么：先决定使用 Dify Cloud，还是在自有基础设施运行 Community Edition。Cloud 由平台托管，适合把精力放在应用编排；自部署的官方入口基于 Docker Compose，涉及应用服务、工作进程、插件、数据库、缓存、反向代理、向量库和沙箱等多个组件。

为什么：两种方式的应用主线相近，但责任边界完全不同。自部署不等于官方代维，“容器能启动”也不等于生产可用；团队还要负责环境变量、密钥、持久化、容器健康、网络与 TLS、备份、升级和回滚。升级时应按目标版本 Release 指南执行，并比较新的环境变量示例，不能预设无停机。

如果计划用 Community Edition 对外提供多租户 SaaS 或托管服务，或修改 Dify 官方前端中的 LOGO、版权等标识，必须核对当前 Dify Open Source License；本文不构成法律意见。

预期结果：形成一页部署决策，写清数据位置、运维负责人、故障恢复责任和当前条款与政策的核对负责人。如何验证：Cloud 路线应能说明账号、数据处理和模型提供方边界；自部署路线应能说明 TLS、持久化、备份、升级前备份与失败回滚方案，而不只是展示启动成功。

准备账号、模型与测试资料

做什么：准备一个有适当工作区权限的账号、可用的模型提供方、用于知识库的小批真实资料，以及一组预期可回答、不可回答、表述含糊和包含异常输入的问题。资料应去除不必要的个人信息，测试问题要标记期望答案、允许引用的原文和不可执行的动作。

为什么：Dify 可以连接模型、知识与工具，但 Knowledge/RAG 只是降低幻觉风险，并不保证回答准确。提前准备可对照的测试集，才能区分模型问题、检索问题和工作流问题。

预期结果：得到“资料—问题—预期—风险”四列测试清单。如何验证：每个问题都能指出对应原文或明确标记“资料中没有答案”；至少包含正常、边界、无答案和异常输入四类，不使用生产密钥、真实账号信息或真实服务器地址。

第一步：创建工作区和应用

做什么：创建或加入工作区，确认具备创建应用和管理所需集成的权限，再选择应用类型。Workflow 面向单轮任务或事件触发；Chatflow 每轮对话触发，支持对话变量、记忆和流式输出。Agent 是简化入口，Agent Strategy 决定工具选择，不与前两者混为一种模式。

为什么：应用类型决定触发和测试方式。单轮资料问答用 Workflow；需连续追问和上下文时用 Chatflow。

预期结果：成员权限足够，应用有明确输入、输出、触发方式和责任人。如何验证：实际创建测试应用，并由负责集成的角色确认其管理范围；再说明谁在何时提供什么输入、系统返回什么结果，无法区分单轮或多轮时先不加节点。

第二步：配置模型提供方

做什么：由工作区所有者或管理员配置模型提供方，并确认生成、嵌入及需要时的重排能力。模型可由应用或节点选择，否则可能回退到工作区默认模型。凭据是工作区共享资源，应按工作区和环境隔离，保存于受控配置或环境变量，不进入提示词、截图或导出的 DSL。

为什么：模型插件已安装不等于凭据有效或已授权全部外部服务。自有提供方凭据的费用归入对应账户，数据链路随提供方和部署方式变化。

预期结果：目标模型在所需节点可被选择，嵌入流程具备可用模型，管理权限受到限制。如何验证：执行一次最小模型调用并看到正常输出、耗时和用量信息；再由非管理员确认其不能查看或修改凭据。失败时先查模型选择和凭据校验，不把安装状态当作验收。

第三步：创建知识库

做什么：按领域和数据来源创建知识库，先直接导入并按规则处理。复杂数据可用自定义 Knowledge Pipeline（知识处理管道），已有外部知识系统可评估 API 连接。记录文档版本、来源和负责人，避免混入无关领域。

为什么：Knowledge 会先检索相关分段，再把检索结果与问题组合成上下文交给模型。库的边界和资料质量会直接影响召回与引用；文件上传成功只表示进入处理流程，不代表应用已经能正确回答。

预期结果：文档完成处理，能够查看分段并进入检索测试。如何验证：随机抽查标题、正文和关键条款是否存在，确认没有乱码、空分段或明显重复；用一条能在原文直接定位的问题检索，结果应包含正确文档和对应内容。

第四步：检查分段和检索效果

做什么：查看分段边界，针对真实问题执行知识库检索测试，并根据资料结构调整索引方式、嵌入模型、检索策略、元数据筛选或分段内容。不要只看最终回答，应先看召回了哪些片段、顺序是否合理、原文是否支持问题。

为什么：未召回正确片段时提示无法补回事实；已召回但回答错误时检查上下文和生成约束。RAG 不保证正确，引用须回到原文。

预期结果：测试集中的有答案问题能召回支持性片段，无答案问题不会被错误资料强行填补。如何验证：逐题记录召回文档、片段、相关性和原文位置；至少能把失败归类为资料缺失、分段不当、筛选条件、检索策略或生成偏离，而不是笼统写“AI 不准”。

第五步：配置提示、变量和输出格式

做什么：定义用户输入变量、节点输出和最终输出格式，让数据在流程间有明确传递关系。提示中写清任务、可用上下文、无答案时的处理、引用要求和禁止动作；模板或输出节点只引用已存在的变量。敏感配置使用环境变量，使密钥与应用 DSL 分离。

为什么：变量名不一致、空值未处理或输出契约含糊，会让后续节点拿到错误数据。明确“资料不足就说明不足”也能减少模型把常识伪装成知识库事实。

预期结果：相同输入得到结构稳定、可被下一节点或调用方消费的结果。如何验证：检查测试运行中每个变量的实际值，分别输入正常、空白、超长和资料外问题；最终输出应满足既定字段和引用规则，且不泄露环境变量内容。

第六步：搭建工作流主路径

做什么：用“内部资料问答”贯穿主路径：以 question 接收问题；知识检索节点选择目标知识库并绑定 question；检索结果传给 LLM 上下文；提示规定仅依据资料回答、无资料拒答并引用。本文示例采用 Workflow，以 End 输出；若选 Chatflow，则使用 Answer，并另行测试多轮上下文。之后再增加其他节点。

为什么：主路径越短，越易定位输入、检索、生成或格式化问题。

预期结果：question、检索结果、LLM 上下文与最终输出逐级可追踪。如何验证：分别运行一个原文中有答案的问题和一个无答案的问题，逐个查看节点状态与 Last Run；前者应召回正确片段、回答并引用，后者应在没有支持片段时拒答，不能只看最终页面是否有文字。

第七步：添加异常分支和人工确认

做什么：使用 IF/ELSE 等分支处理空输入、无检索结果、参数不合法和外部服务失败。发送、发布、付款、删除或外部写入前必须人工确认：审批只能来自受控界面或可信后端，不能相信普通 API 输入中的布尔值。审批记录应绑定操作者、目标、参数摘要、有效期与一次性请求标识；拒绝或超时都不执行，并保留审计。若当前实例没有合适的原生能力，就把写操作拆到受控后端。

为什么：自动化会放大错误，尤其是重复写入和越权动作。模型生成一句“已完成”不能代替外部系统的真实状态，也不能代替授权审批。

预期结果：正常请求走主路径，异常请求安全结束，只有匹配且有效的一次性审批能触发写入。如何验证：构造空值、无答案、伪造审批、拒绝、过期和重复请求；上述拒绝性场景不得新增写入。已获批请求首次执行一次，重复提交不得再次写入；审计记录须对应操作者、目标与参数摘要。

第八步：连接工具与外部服务

做什么：先分清集成类别和调用方向：Model Provider 提供模型，Tool 供 Agent 或 Workflow 调用，Data Source 向知识处理管道提供文档，Trigger 由外部事件启动 Workflow，Agent Strategy 控制 Agent 的工具选择循环。Custom Endpoint 面向自定义 HTTP 调用入口，Extension 承担其他扩展能力，两者应分开核对调用方向。生产使用前审核安装来源、更新范围和权限。

为什么：“已安装集成”不等于“应用已调用”或“获得全部外部权限”。把所有扩展都叫工具，会掩盖调用方向和数据流向。

预期结果：每个集成都有用途、调用方向、权限范围、数据范围和停用负责人。如何验证：在受控测试中触发一次允许动作并看到节点成功，再用无权限场景确认请求被拒绝；高风险外写仍需人工确认，不能通过扩大权限来绕过错误。

第九步：用测试集调试

做什么：把准备阶段的问题逐条运行，记录完整流程结果和单节点状态。必要时调整缓存变量复测单个节点，再重新执行端到端流程。测试集应包含预期成功、无答案、边界输入、权限不足和外部失败。

为什么：局部复测能快速定位问题，但缓存或替身数据不能证明正式输入可用。测试运行的节点信息也不等同于发布后的正式 Logs，两者不能互相替代。

预期结果：每条测试都有通过或失败结论、实际输出、失败节点和修正记录。如何验证：通过项应同时满足答案、引用、格式和分支预期；失败项能定位到具体节点及输入。修改后重跑相关用例与关键回归用例，而不是只测试刚修的那一题。

第十步：发布网页应用

做什么：测试通过后发布 Web 应用，完善说明，并设置访问控制、速率限制和请求大小控制。若当前实例或方案不能提供足够控制，不要直接公开；改用带认证的自有前端、API 网关、反向代理或仅限内网，并在外层落实认证、限流与请求大小控制。修改后要再次发布，发布前保留剥离凭据的可回滚 DSL 或版本记录。

为什么：编辑态成功不代表用户看到的已发布版本已经更新。公开 Web 入口还会扩大输入范围和滥用风险，需要单独检查暴露面。

Web、网站嵌入和 MCP 可共用业务配置，但认证与暴露须分别验收。嵌入核对宿主访问控制、来源限制和实际 Logs。MCP 连接信息视为凭据并限制分发；实例若提供认证、撤销、权限与审计就直接验收，否则用 API 网关、网络限制或客户端侧审计补足。日志证据来自 Dify Logs（若实际记录）或执行认证的网关、客户端记录；不承诺原生逐客户端权限。不使用时关闭。

预期结果：目标用户能访问正确版本，未授权或超限请求被拒绝。如何验证：测试允许与拒绝身份、超限和过大请求；嵌入应受宿主控制，MCP 按实际控制验证允许、拒绝、撤销和审计证据，不可用时关闭；同时确认可恢复上一版本。

第十一步：发布和调用 API

做什么：发布应用后，从当前实例的已发布应用进入 API 文档。为该应用和该环境生成独立调用凭据，只保存在服务端；它与模型提供方凭据用途不同，不能混用。按当前文档复制其端点、认证头和请求结构，以最小测试输入发送请求。契约还要写清同步或流式输出、错误、超时、限流和重试责任；外写审批不能来自普通请求字段。

为什么：API 是生产入口，错误重试可能重复写入，缺少超时和限流会放大成本或故障。端点、认证头和请求结构随应用与实例而变化，只能从当前文档取得，正文不写固定值或凭据示例。

预期结果：调用方能处理成功、业务拒绝、认证失败、限流、超时和服务错误，并区分应用调用凭据与模型提供方凭据。如何验证：核对 HTTP 状态、返回字段或流结束信号、错误结构、超时与限流响应，再到正式 Logs 找到交互；未获得可信后端审批的外写不得执行。

第十二步：设置权限、密钥和成本控制

做什么：按最小权限分配工作区成员角色，限制谁能管理模型提供方、安装或升级集成、查看日志和发布应用。凭据按开发、测试、生产环境隔离，保存在环境变量或受控配置中；定期盘点模型、工具和外部服务的调用范围。价格、额度、方案名和具体权益只在实施时核对官方实时页面。

为什么：模型凭据是工作区共享资源，泄露会带来数据和费用风险。Cloud、自部署、模型与工具链路不同，须分别核对隐私政策、DPA、次级处理商和合同。

预期结果：成员只拥有工作所需权限，密钥不进入内容资产，成本能按应用或用途追踪。如何验证：执行角色矩阵检查、导出 DSL 与截图扫描、非管理员越权测试，并在日志或提供方侧核对用量归属；发现异常时能停用对应集成或轮换凭据而不改正文。

第十三步：查看日志和监控失败

做什么：上线后检查 Dify Logs 中的 Web/API 输入输出历史、耗时、系统元数据、模型、Token 用量、错误、警告和用户反馈，并建立失败、延迟、成本变化和知识缺口的处理流程。限制日志访问，按适用法规提供隐私说明和必要同意。

为什么：调试会话和提示测试不计入正式交互日志，因此测试运行只能证明构建阶段，正式 Logs 才反映真实入口；反过来，正式 Logs 也不能替代节点级测试。

预期结果：团队能从一次失败交互定位入口、模型、耗时、错误和相关输入，并分派负责人。如何验证：发布后从 Web 或 API 发起受控请求，在正式 Logs 找到记录并与测试运行对照；确认敏感字段的访问范围符合角色设计，不写死日志保留天数。

第十四步：更新知识库并验证回归

做什么：更新文档或分段时记录来源版本，重新处理受影响内容，再执行检索与应用测试。更换嵌入模型或索引方式时，先保留旧配置和恢复步骤，确认受影响文档已重新处理、索引重建完成，再抽查分段和召回；之后扩大应用回归，确认结果后重新发布。

为什么：知识库变化可能修复旧答案，也可能改变其他问题的召回顺序。上传新文件、检索测试、应用测试和重新发布是不同验收点，不能省略其中任何一个。

预期结果：新事实可召回，旧关键问题仍符合答案与引用要求，失败时可恢复旧配置。如何验证：确认处理和重建任务完成，比较更新前后分段、召回与输出，跑受影响用例和核心回归；再从已发布 Web/API 测试，并在 Logs 确认新配置生效。

常见问题一：知识库没有回答

先确认原文确有答案，再看文档处理状态和原始召回。没有目标片段时依次查分段、元数据筛选、嵌入模型和检索策略；已有片段却未回答时，才查变量绑定、LLM 上下文和提示约束。以目标片段稳定召回且答案回指原文为通过。

常见问题二：引用不准确

先逐句判断引用是否真的支持结论，再核对文档版本。若引用来自重复或过期资料，清理来源；若片段缺标题或上下文，修订分段；若模型拼接出原文没有的结论，收紧提示并要求资料不足时拒答。通过标准是来源正确、片段支持结论、无答案时无伪引用。

常见问题三：工作流节点失败

从失败节点的输入、输出和 Last Run 开始，依次查空值或类型、模型或集成可用性、权限和外部错误。先复测单节点，再跑完整流程；涉及外写时，重试前确认是否已执行及是否幂等。通过标准是原因定位到具体输入，且正常、异常分支都通过。

常见问题四：API 超时或成本异常

先按契约查超时、重试、并发和限流，再从 Logs 对照耗时、模型、Token 用量与错误。超时不代表没有执行，外写不可盲目重试；成本异常重点查输入长度、检索上下文、循环、模型和重复请求。通过标准是受控复现后超时边界、单次写入和用量趋势恢复正常。

上线前检查清单

• 已确定 Cloud 或自部署责任；自部署具备 TLS、持久化、备份、升级和回滚安排。
• 已明确 Workflow 单轮/事件触发或 Chatflow 多轮模式，Agent 与 Agent Strategy 的职责没有混淆。
• 模型、嵌入和必要的重排能力已通过最小调用验证，凭据使用环境变量并按环境隔离。
• 知识库完成分段抽查和真实问题检索测试，答案与引用回到原文核验，不宣称 RAG 保证准确。
• 主路径、异常分支、人工确认和测试集均通过；测试运行与正式 Logs 分别验收。
• Web、API、网站嵌入与 MCP 即使共用业务配置，也已分别检查认证、暴露方式、访问控制和限流。
• API 契约覆盖认证、输入输出、错误、超时、限流、重试和外写审批，没有在内容中公开凭据。
• 成员、插件、日志和发布权限符合最小权限；当前隐私政策、许可、方案权益与数据处理边界已由负责人核对。
• 人工审批来自受控界面或可信后端，绑定操作者、目标、参数摘要、有效期和一次性请求标识；拒绝、超时或重复请求不写入。
• Web 控制不足时不直接公开；嵌入与 MCP 已按实例能力核对访问控制、暴露、撤销和审计补偿，不使用的入口已关闭。
• 已保留剥离凭据的 DSL、旧索引配置与恢复步骤，知识更新或重建索引后完成分段抽查、召回与应用回归。

总结

Dify 上线是一条可验证链路：确定部署责任，配置模型，建立知识库并验证检索，再搭建主路径、异常分支和人工确认，最后分别治理 Web、API、嵌入与 MCP。可靠信号来自原文支持的召回、节点测试、正式 Logs、最小权限和可回滚版本，而非按钮位置或一次正确回答。若需比较跨系统自动化，可阅读 n8n 工具页；无论平台，都应把真实业务测试和持续监控放在功能清单前。