From 70bccadf6619b75a7cc7750fafd0cbed2f9b5aab Mon Sep 17 00:00:00 2001 From: AllenWriter Date: Fri, 18 Apr 2025 12:15:23 +0800 Subject: [PATCH] Docs: update step by step run --- docs.json | 8 ++- logo/{dify-logo.svg => dify-logo-black.svg} | 0 logo/dify-logo-white.svg | 19 +++++ .../workflow/debug-and-preview/checklist.mdx | 6 +- .../workflow/debug-and-preview/debug-node.mdx | 31 ++++++++ .../workflow/debug-and-preview/history.mdx | 20 +++++- .../guides/workflow/debug-and-preview/log.mdx | 2 +- .../debug-and-preview/preview-and-run.mdx | 49 +++++++++++-- .../debug-and-preview/step-by-step-run.mdx | 15 ++++ .../workflow/debug-and-preview/step-run.mdx | 6 +- .../debug-and-preview/variable-inspector.mdx | 71 +++++++++++++++++++ 11 files changed, 212 insertions(+), 15 deletions(-) rename logo/{dify-logo.svg => dify-logo-black.svg} (100%) create mode 100644 logo/dify-logo-white.svg create mode 100644 zh-hans/guides/workflow/debug-and-preview/debug-node.mdx create mode 100644 zh-hans/guides/workflow/debug-and-preview/step-by-step-run.mdx create mode 100644 zh-hans/guides/workflow/debug-and-preview/variable-inspector.mdx diff --git a/docs.json b/docs.json index 623e581d..22d80f92 100644 --- a/docs.json +++ b/docs.json @@ -9,8 +9,8 @@ }, "favicon": "/dify-logo.png", "logo": { - "light": "/logo/dify-logo.svg", - "dark": "/logo/dify-logo.svg" + "light": "/logo/dify-logo-black.svg", + "dark": "/logo/dify-logo-white.svg" }, "navigation": { "languages": [ @@ -554,9 +554,11 @@ "pages": [ "zh-hans/guides/workflow/debug-and-preview/preview-and-run", "zh-hans/guides/workflow/debug-and-preview/step-run", + "zh-hans/guides/workflow/debug-and-preview/debug-node", "zh-hans/guides/workflow/debug-and-preview/log", "zh-hans/guides/workflow/debug-and-preview/checklist", - "zh-hans/guides/workflow/debug-and-preview/history" + "zh-hans/guides/workflow/debug-and-preview/history", + "zh-hans/guides/workflow/debug-and-preview/variable-inspector" ] }, "zh-hans/guides/workflow/publish", diff --git a/logo/dify-logo.svg b/logo/dify-logo-black.svg similarity index 100% rename from logo/dify-logo.svg rename to logo/dify-logo-black.svg diff --git a/logo/dify-logo-white.svg b/logo/dify-logo-white.svg new file mode 100644 index 00000000..468518a0 --- /dev/null +++ b/logo/dify-logo-white.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/zh-hans/guides/workflow/debug-and-preview/checklist.mdx b/zh-hans/guides/workflow/debug-and-preview/checklist.mdx index cd705d96..67234eba 100644 --- a/zh-hans/guides/workflow/debug-and-preview/checklist.mdx +++ b/zh-hans/guides/workflow/debug-and-preview/checklist.mdx @@ -1,7 +1,11 @@ --- -title: 检查清单 +title: 检查清单（待归档） --- + + 本篇内容已归档至 [预览应用](/zh-hans/guides/workflow/debug-and-preview/preview-and-run)。 + + 在进入调试运行之前，你可以在检查清单内检查是否有未完成配置或者未连线的节点。 ![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/16201deaa47a518ff73c983a33ab4002.png) diff --git a/zh-hans/guides/workflow/debug-and-preview/debug-node.mdx b/zh-hans/guides/workflow/debug-and-preview/debug-node.mdx new file mode 100644 index 00000000..a0e1882d --- /dev/null +++ b/zh-hans/guides/workflow/debug-and-preview/debug-node.mdx @@ -0,0 +1,31 @@ +--- +title: 调试节点 +--- + +Workflow / Chatflow 类型应用通常包含多个节点，每个节点互有关联。若要确保应用整体运行正常，需要确认每个节点的输入输出符合预期。调试工具将帮助开发者检测应用是否按照设计预期提供服务，提前暴露问题。 + +你可以通过以下两种模式调试应用。 + +## 单步调试 + +单步调试指的是对工作流内的某个节点进行单独调试。例如在工作流内添加了一个 HTTP 节点，为确保该节点能够正确运行，不影响其它节点。开发者可以点击节点右上角的 **run step** 按钮，使用单步调试功能模拟节点的输入输出数据。 + +调试完成后，你可以看到当前节点的运行状态、输入/输出、元数据信息。如遇报错，可通过报错信息快速排查错误，避免节点异常导致的应用整体运行失败。 + +![](https://assets-docs.dify.ai/2025/04/376c9de6f92cb7a5f97a6661c5e0e9eb.png) + +## 逐步执行 + +单步调试主要用于单个节点的输入输出调试。而逐步执行更加适合于需要上游节点配合调试的节点场景。例如 B 节点的功能依赖于 A 节点的输出结果，使用逐步调试功能可以更加高效的验证多个节点流的工作效果。 + +点击右上角的 run to 按钮，将启用逐步执行按钮。调试过程将从开始节点执行到当前节点，你可以在此过程中观测到一小段节点的运行情况，基于结果及时调整节点的规划合理性、路径最优性。 + +![](https://assets-docs.dify.ai/2025/04/5bb7e8c6e2f0af38d272d2f4bfa3e90a.png) + +## 查看节点调试记录 + +每个节点运行完成后都会生成操作日志，你可以点击节点详情页中的 Last run 查看运行历史。 + +![](https://assets-docs.dify.ai/2025/04/5ee92e6406979f5101d21865f95a86e5.png) + +如需查看应用整体的运行历史，详细说明请参考[运行历史](/zh-hans/guides/workflow/debug-and-preview/history)。 diff --git a/zh-hans/guides/workflow/debug-and-preview/history.mdx b/zh-hans/guides/workflow/debug-and-preview/history.mdx index 23b2088f..73845011 100644 --- a/zh-hans/guides/workflow/debug-and-preview/history.mdx +++ b/zh-hans/guides/workflow/debug-and-preview/history.mdx @@ -2,6 +2,22 @@ title: 运行历史 --- -在「运行历史」中可以查看当前工作流历史调试的运行结果和日志信息。 +## 查看应用运行历史 -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/5ff3e82563c43b41e359c83483fd0f9b.png) +在「运行历史」中查看当前应用的所有历史运行结果以及各个节点的详细运行日志信息。 + +![](https://assets-docs.dify.ai/2025/04/08a885858cfa6e8863faac891a5be319.png) + +点击日志详情下方的日志按钮即可查看各个节点在当前轮次中的完整输入输出日志。 + +![](https://assets-docs.dify.ai/2025/04/415d26a0aa899d1f89c5a3761eb81719.png) + +## 查看节点运行日志 + +点击「查看日志 — 详情」可以在详情中查看运行总览信息、输入/输出 、元数据信息等。 + +![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/9b88af156ab35bb5b05b00ffc3e84dc7.png) + +点击「查看日志-追踪」可以查看工作流完整运行过程各节点的输入/输出、Token 消耗、运行时长等。 + +![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/b1e0a84aabbafd96897d277d787019de.png) diff --git a/zh-hans/guides/workflow/debug-and-preview/log.mdx b/zh-hans/guides/workflow/debug-and-preview/log.mdx index 26114aa1..7f2daa76 100644 --- a/zh-hans/guides/workflow/debug-and-preview/log.mdx +++ b/zh-hans/guides/workflow/debug-and-preview/log.mdx @@ -1,5 +1,5 @@ --- -title: 对话/运行日志 +title: 对话/运行日志（待归档） --- 点击「查看日志—详情」可以在详情中查看运行总览信息、输入/输出 、元数据信息等。 diff --git a/zh-hans/guides/workflow/debug-and-preview/preview-and-run.mdx b/zh-hans/guides/workflow/debug-and-preview/preview-and-run.mdx index 8283de8c..bc52b71a 100644 --- a/zh-hans/guides/workflow/debug-and-preview/preview-and-run.mdx +++ b/zh-hans/guides/workflow/debug-and-preview/preview-and-run.mdx @@ -1,15 +1,50 @@ --- -title: 预览与运行 +title: 预览应用 --- -Dify Workflow 提供了一套完整的运行调试功能，在对话型应用中点击「预览」进入调试模式。 +在 AI 应用从开发环境迈向真实用户的过程中，为确保最终交付质量，建议开发者以用户视角预览应用最终的呈现效果，确保应用能够从开发阶段无缝过渡到生产阶段。 -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/91379dc42d0d815e52ddad0cc5450a46.png) +在 Dify 平台中，“预览”和“运行”是两个密切相关但用途不同的概念： -在工作流应用中点击「运行」进入调试模式。 +- **预览**：在开发环境中，以最终用户的视角体验和验证应用功能。 +- **运行**：应用部署后，实际面向真实用户执行的状态。 -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/b92d7536392b1e1f2423d0e3aa113915.png) +本文将重点介绍如何使用“预览”功能，以及在应用发布前需要关注的质量保障要点。 -进入调试模式内在界面右侧调试已配置好的工作流。 +## 为什么要预览应用？ -![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/4c81791508592e0f8019b8ebf8f119ea.png) +- 以用户视角验证应用使用流程 + + 开发者往往专注于功能实现，而忽视了终端用户实际体验到的整体流程。建议模拟普通用户行为，完整验证应用功能。同时，用户可能在不同设备和界面上访问应用，确保用户的一致性体验尤为重要。 + +- 测试大模型的响应稳定性 + + 大语言模型在相同输入下可能输出不同内容。建议从多个角度输入不同内容进行测试，以评估模型输出的一致性与可控性。 + +- 验证大模型上下文窗口限制 + + 复杂工作流可能触发大模型上下文窗口限制，导致响应被截断。建议在预览阶段进行极限测试，模拟实际生产环境中的高负载场景。 + +- 确认外部依赖项的真实影响 + + AI 应用可能依赖多个外部 API 或数据源。其响应时延、可用性波动以及调用频率，均可能在生产环境中放大。建议在预览阶段测试其稳定性，同时评估资源消耗与成本风险。 + +## 预览应用 + +预览应用指的是整体查看应用的最终交互效果并模拟真实用户的使用体验。点击应用右上角的「预览」按钮，在该模式下，开发者可以模拟用户输入、触发工作流，整体查看应用的实际呈现与运行效果。 + +![](https://assets-docs.dify.ai/2025/04/2cf08e02c2ce4d82be81c1c24d7dafb2.png) + +**自动检查清单** + +系统将自动检查每个节点的配置和连线状态，如存在异常，将在页面右上角提示。将应用正式发布至生产环境前，建议检查应用是否已通过所有检查项。 + +![](https://assets-docs.dify.ai/2025/04/e439c296d22c001066cfcf57d5a1b267.png) + +## 调试节点 + +若发现部分节点运行异常，导致应用预览失败；或者开发者希望通过优化部分节点从而提升整体应用表现，可以针对应用中的节点进行调试。详细说明请参考[调试节点](/zh-hans/guides/workflow/debug-and-preview/debug-node)。 + +## 查看应用运行历史 + +应用的运行历史可以帮助开发者监视各个环节的运行情况。你可以在“运行历史”中查看每一轮对话的执行记录和各节点的运行日志，帮助复盘问题与优化逻辑。详细说明请参考：[运行历史](/zh-hans/guides/workflow/debug-and-preview/history)。 diff --git a/zh-hans/guides/workflow/debug-and-preview/step-by-step-run.mdx b/zh-hans/guides/workflow/debug-and-preview/step-by-step-run.mdx new file mode 100644 index 00000000..51deb251 --- /dev/null +++ b/zh-hans/guides/workflow/debug-and-preview/step-by-step-run.mdx @@ -0,0 +1,15 @@ +--- +title: 单步调试 +--- + + + 本篇内容已归档至 [调试节点](/zh-hans/guides/workflow/debug-and-preview/debug-node)。 + + +工作流支持节点的单步调试，在单步调试中你可以重复测试当前节点的执行是否符合预期。 + +![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/36e547165a5088510c99baee4ce42bcd.png) + +单步测试运行后可以查看运行状态、输入/输出、元数据信息。 + +![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/040e1051d33b94d35e4683d3c89691a8.png) diff --git a/zh-hans/guides/workflow/debug-and-preview/step-run.mdx b/zh-hans/guides/workflow/debug-and-preview/step-run.mdx index 20dad386..230b69b3 100644 --- a/zh-hans/guides/workflow/debug-and-preview/step-run.mdx +++ b/zh-hans/guides/workflow/debug-and-preview/step-run.mdx @@ -1,7 +1,11 @@ --- -title: 单步调试 +title: 单步调试（待归档） --- + + 本篇内容已归档至 [调试节点](/zh-hans/guides/workflow/debug-and-preview/debug-node)。 + + 工作流支持节点的单步调试，在单步调试中你可以重复测试当前节点的执行是否符合预期。 ![](https://assets-docs.dify.ai/dify-enterprise-mintlify/zh_CN/guides/workflow/debug-and-preview/36e547165a5088510c99baee4ce42bcd.png) diff --git a/zh-hans/guides/workflow/debug-and-preview/variable-inspector.mdx b/zh-hans/guides/workflow/debug-and-preview/variable-inspector.mdx new file mode 100644 index 00000000..a508b5c9 --- /dev/null +++ b/zh-hans/guides/workflow/debug-and-preview/variable-inspector.mdx @@ -0,0 +1,71 @@ +--- +title: 变量池 / 变量检视器 +--- + +变量池（Variable Inspector）用于帮助开发者实时追踪、检查与编辑当前应用中各类变量背后所对应的数据。通过变量池，开发者可以直观地观察和理解数据如何通过变量在应用内进行流转，并基于变量的实时值进行调试、验证与问题定位，提升应用的调试效率。 + +![](https://assets-docs.dify.ai/2025/04/c09ea3d640099d58cfa82757738a6446.png) + +## 功能与价值 + +[变量](/zh-hans/guides/workflow/variables)是连接节点之间的重要桥梁，也是实现动态流程控制的基础。在工作流应用中，变量不仅承载用户输入与模型输出，还用于保存对话历史上下文、配置参数等场景。变量池可以帮助开发者更好的管理各个变量，提供以下功能场景： + +- **可视化变量流转**：清晰查看每个节点的输出结果与其对应变量值； +- **辅助调试分析**：快速定位节点中出现异常数据或结构错误，提升排查效率； +- **灵活变量模拟**：支持手动修改变量值，模拟不同输入或边界条件； +- **全局变量管理**：集中查看应用内的所有环境变量、系统变量、节点变量等，理解当前工作流的运行状态。 + +## 使用说明 + +变量池位于画布底部，随着工作流运行实时更新变量值。当某个节点运行后，其输出变量将自动出现在变量池中，开发者可以展开查看具体内容。 + +支持的主要操作包括： + +- **查看值**：展开变量查看当前结构及内容（支持对象/数组层级展开） +- **编辑值**：对于部分变量（如 string、object）支持直接手动修改 +- **清除变量**：点击「Clear」按钮清除当前变量缓存，常用于重新调试 +- **重置值**：恢复至上一次运行时的变量状态 + +当画布中无任何节点运行时，变量池将自动收起，并显示默认提示。 + +## 变量池支持的变量类型 + +### 变量类型 + +| 变量类别 | 示例变量 | 描述 | +|---------|---------|------| +| **系统变量** | sys.query, sys.user_id, sys.conversation_id | 系统提供的当前会话信息 | +| **会话历史变量** | chat_history, custom_chat_history | 对话历史记录 | +| **节点输出变量** | output, structured_output, usage | LLM节点输出结果 | +| **工具结果变量** | result, error_message | 工具调用返回值 | +| **知识库变量** | similar_docs, knowledge, score | 知识库检索结果 | +| **流程控制变量** | condition_result, current_item, index | 条件和循环节点状态 | +| **自定义变量** | [用户定义名称] | 通过变量节点创建的变量 | +| **环境变量** | OPENAI_KEY, PORT | 系统环境配置 | + +### 数据类型 + +| 类型 | 描述 | 示例 | 是否可编辑 | +|------|------|------|--------------| +| `string` | 文本类型，常用于模型输入输出 | `"Hello, world!"` | ✅ | +| `number` | 数值类型，适用于评分、标记等场景 | `0.85` | ✅ | +| `boolean` | 布尔值，用于条件判断节点 | `true` / `false` | ✅ | +| `object` | 结构化 JSON 数据 | `{ "key": "value" }` | ✅ | +| `array` | 列表数组，适用于多项输出/上下文记录 | `[1, 2, 3]` | ✅ | +| `secret` | 隐私变量（如 API 密钥） | `******` | ❌ | + +## 最佳实践 + +- 在流程开发过程中，建议每完成一步配置后通过变量池验证节点输出是否正确。 +- 出现节点报错时，优先查看变量池中的 `error_message` 和 `error_type` 获取诊断信息。 +- 编辑变量值后可直接运行下游节点，模拟真实运行情况，辅助判断流程稳定性。 + +变量池是提升工作流构建效率与质量的重要工具。合理利用变量池，可显著降低调试成本，加速从构建到交付的过程。 + +为了便于查看整体的变量所承载的背后数据，以及帮助开发者通过变量更好的调试应用，变量池可以帮助开发者管理当前工作流应用内所涉及的所有变量所对应的数据，它展示工作流中所有已创建变量及其当前值，包含节点输出变量、会话变量/循环变量。其状态为可编辑/清除，代表当前工作流的实时状态。 + +## 相关内容 + +- [调试节点](/zh-hans/guides/workflow/debug-and-preview/debug-node) +- [运行历史](/zh-hans/guides/workflow/debug-and-preview/history) +- [工作流构建概览](/zh-hans/guides/workflow/build-flow-app)