管理节点变量并排查传值错误课程归属Dify 自动化实战第 6 节管理节点变量并排查传值错误在 Dify Workflow 中节点连接线画对了不代表数据一定传对。常见现象包括LLM 节点拿到空文本、提示词里引用了错误的变量、输出节点返回空字符串或上游节点明明有结果下游却看不到。本文继续使用“资料报告助手”沿用files、report_topic和summary这组字段通过一条固定数据链路解释变量选择、类型匹配、节点输出引用以及如何利用缓存变量和运行记录定位传值错误。完成后你能按节点逐段验证数据而不是盲目重写提示词。一、先区分节点、变量与连线Dify 中的连线表达执行依赖变量引用表达数据依赖两者相关但不是同一件事。A 节点连到 B通常意味着 B 可以在 A 执行后继续运行但 B 的输入字段仍要绑定到正确的上游输出。如果连线正确、变量却选错B 仍然可能收到错误数据。本文以 Dify 官方文档介绍的变量选择器为准在节点配置中选择上游节点及其输出变量或在支持动态变量的文本输入框里输入/后从菜单中选取。不要仅凭显示名称手写一个看似合理的变量路径。Dify 的节点输出是供后续节点引用的数据运行时应检查实际值而不是只看配置面板上的变量名。Dify Key Concepts1.1 本篇固定的工作流本课程“资料报告助手”使用 Workflow 类型前序章节约定了以下变量User Input/files用户上传的多文件对象列表不是本地路径字符串数组。User Input/report_topic用户填写的摘要主题类型为 String。Doc Extractor/text文档提取节点在当前画布中实际输出的文本字段如果你的实例显示为其他输出名以变量选择器中真实字段为准。LLM/textLLM 节点生成的摘要文本。Output/summary工作流最终对外返回的摘要字符串。图 1资料摘要工作流的执行与数据流report_topicUser Inputfiles、report_topicList Operator筛选文档Doc Extractor提取文本LLM生成摘要Outputsummary这张图把文件和主题的流向画在同一处files要先经过列表筛选和文档提取才会成为文本report_topic则直接传给 LLM限定总结重点。不要把上传文件对象直接当成正文文本也不要把 LLM 节点的完整对象当成summary。二、给每个关键变量建立“来源—类型—用途”记录排错时不要只记变量名。至少要确认三件事变量从哪个节点产生、实际数据类型是什么、哪个下游节点使用它。变量名相同并不保证类型相同例如files是文件列表而Doc Extractor/text是文本两者不可互换。表 1本篇工作流的变量契约变量来源预期类型主要用途filesUser Input文件列表交给 List Operator 筛选report_topicUser InputString传给 LLM 作为摘要方向提取文本Doc ExtractorString 或当前版本显示的文本输出作为模型总结的事实材料textLLMString作为模型生成的摘要正文summaryOutput 配置String最终返回给用户或调用方的摘要节点显示名可以重命名例如把默认的“LLM”改成“生成摘要”让画布更容易读。但重命名后仍应通过变量选择器确认实际来源节点与字段。不要因为节点名改变就推断它的输出字段也会同步改变以配置面板和运行输出显示的字段为准。2.1 如何正确选择变量在下游节点配置输入时按这套顺序操作点开目标节点找到需要填入变量的字段。点击变量选择器先选来源节点再选具体输出字段。检查所选变量的语义与字段类型是否匹配。保存后执行一次测试确认运行时输入中确实出现了预期内容。若是 LLM 提示词先输入固定说明文字再输入/并选择变量。例如摘要主题/ 选择 User Input / report_topic 资料正文/ 选择 Doc Extractor / 实际文本输出字段 只根据提供的正文围绕摘要主题生成简体中文摘要。若正文为空或没有相关信息请明确说明资料不足不要自行补充事实。上面方括号式说明是操作指引不要把“选择 User Input”这些文字原样留在提示词中。实际画布里应插入 Dify 的变量引用组件。三、排查变量类型不匹配Dify 的变量类型约束能在节点接线和配置阶段提前暴露一部分错误但不是所有错误都会在编辑时拦截。比如把文件列表选进只接受文本的输入字段通常会出现类型不兼容或下游无法按预期读取的情况即使编辑器允许保存也需要在运行时检查内容是否真的是文本。表 2常见变量类型与正确连接方式上游变量不应直接替代正确做法files文件列表文档正文字符串先用文件处理节点提取文本report_topicString文件列表或文件对象绑定到 LLM 提示词的主题位置Doc Extractor 的文本输出原始文件对象绑定到 LLM 的资料正文位置LLM/textString整个 LLM 节点或其他元数据绑定到 Output 的summary如果下游变量选择器里根本看不到某个输出先检查上游节点是否已添加并保存、两节点之间的执行顺序是否合理以及输出字段是否存在。不要用字符串拼接伪造文件对象也不要用固定示例文本掩盖真实变量没有传来的问题。四、用“逐节点检查”定位传值断点Dify 提供 Test Run、节点运行结果和缓存变量等调试能力。官方快速入门指出可以在节点配置面板中运行单个步骤也可以查看画布下方的缓存变量如果执行报错应检查对应节点的 Last Run 信息。Dify Quick Start4.1 先跑一遍完整流程使用课程教学文件办公流程_教学样例.txt在 User Input 中上传文件并设置主题请总结新员工需要完成的入职流程并突出信息安全和报销方面的注意事项。点击 Test Run等待运行结束。先不要急着评价摘要质量而是确认每个节点的实际输入和输出User Inputfiles列表是否有文件report_topic是否为非空字符串。List Operator筛选结果是否仍包含目标文档。Doc Extractor输出文本是否能看到样例里的“信息安全培训”“合规票据”等内容。LLM输入中是否同时出现主题与提取文本输出是否有摘要。Outputsummary的值是否绑定到 LLM 的文本输出。图 2按数据断点排错的顺序运行 Test Run检查 User Input检查 List Operator 输出检查 Doc Extractor 文本检查 LLM 输入与输出检查 Output 绑定确认 summary 非空按顺序检查能够把问题缩到一个区间。比如 Doc Extractor 已经返回了正确文本就没必要先改文件上传设置LLM 输出有摘要但 Output 为空则应该优先检查末端绑定。4.2 查看缓存变量和节点运行记录在画布下方打开View cached variables缓存变量或当前版本对应的变量面板查看最近一次运行捕获的各节点数据。选择节点后比较该节点的输入和输出是否符合预期。快速入门还说明可以用缓存变量修改测试输入来验证单个节点不必每次都完整重跑整个工作流。Dify Quick Start对于已发布应用的真实运行可以在应用的 Logs 页面筛选运行记录打开单次 Workflow run 查看输入、输出、状态以及按节点展开的执行轨迹编辑器内的 Test Run 和已发布应用日志并非完全相同的记录范围。Dify Logs五、用一个典型错误案例说明修复方法假设 Test Run 结果是User Input 显示文件已上传Doc Extractor 也能看到正文但 LLM 生成“资料未提供足够信息”或者摘要只谈主题、完全没有引用材料内容。此时先检查 LLM 的资料正文输入是否真正绑定到 Doc Extractor 输出而不是又绑定回User Input/files。另一种情况是 LLM 节点输出了完整摘要但最终结果区域为空。这通常说明下游 Output 绑定错了字段或者绑定到了没有执行的节点而不是模型没有工作。表 3问题现象—证据—修复动作现象需要看的证据可能的错误修复动作LLM 说资料为空Doc Extractor 输出文本、LLM 实际输入正文引用遗漏或引用错字段将实际文本输出重新绑定到 LLM摘要不围绕主题LLM 输入里的report_topic主题变量未插入或选错来源用变量选择器重新选择User Input/report_topic最终输出为空LLM 输出、Output 节点输出配置Output 指向错误字段将summary绑定到 LLM 的文本字段文档没有进入提取节点List Operator 输入、过滤后输出条件过滤错类型或错字段检查files输入及type in Doc条件变量下拉列表没有所需值上游节点配置和连线节点未保存、输出字段不存在或依赖关系不正确保存上游配置再刷新选择器并确认节点顺序六、验证一个修复是否真正有效不要只改完变量引用就结束。修复后至少执行一次完整正常用例并尽可能对出错节点运行单步测试。若原问题是主题丢失应确认 LLM 输入中能看到主题若原问题是文本丢失应确认 LLM 输入中能看到文档正文的关键句若原问题是 Output 为空应确认summary最终值与LLM/text一致。表 4最小回归测试集用例输入条件观察位置通过标准正常摘要有效文档 非空主题各节点输入输出提取文本可见摘要引用材料事实summary非空缺少主题report_topic为空User Input 表单必填校验阻止提交若空白字符串仍通过记录为下一步语义校验问题提取为空空文本文件或无法提取的资料Doc Extractor、LLM能看到提取异常或空文本不得把模型猜测当成材料事实修复输出绑定LLM 有输出但 Output 绑定错误LLM 和 Output修正后summary对应 LLM 的实际文本输出这里的通过标准是测试判据并非声称本文已连接到真实 Dify 实例运行。请根据自己的测试记录确认每项是否通过如果只验证了静态配置不应在交付记录中写成“端到端测试通过”。七、维护变量命名和调试记录节点数量增加后模糊的默认名如LLM 1、LLM 2会让变量来源难以辨认。建议把节点重命名为能表达职责的名字例如“筛选文档”“提取资料文本”“生成摘要”。对外变量名仍保持稳定内部节点可以使用清晰的描述性名称。表 5推荐命名约定对象推荐命名不建议用户上传文件filesfile_path会误导为路径字符串摘要主题report_topictopic2、text1文档提取节点提取资料文本Node 3LLM 节点生成摘要LLM 1对外输出summary同时用多个名称表达同一字段含义每次排错记录四项即可运行时间或 Run ID、失败节点、该节点关键输入/输出的脱敏摘要、修复动作和回归结果。不要把完整 API Key、用户隐私资料或整份敏感文件内容贴进问题记录。Dify 的执行日志可能包含完整输入输出和用户提交的信息日志排查本身也要符合资料权限和隐私要求。Dify Logs八、发布前的最终检查发布“资料报告助手”前用下面的检查表复核files是文件列表变量而不是本地路径字符串。report_topic已正确绑定到 LLM 提示词。文档正文来自 Doc Extractor 的实际输出。LLM 节点的输出字段已确认通常是文本结果。Output 的summary指向 LLM 文本输出而不是错误的节点或元数据。已用正常资料执行完整流程并检查各节点实际运行值。至少测试一次缺少主题或提取文本为空的边界情况。真实运行日志中的输入和输出已按需要脱敏。图 3排错完成的判断流程否是发现摘要异常定位第一个不符合预期的节点修正变量引用或输入类型单节点测试完整 Workflow 回归测试输入、输出都符合预期记录结果并保存画布核心方法是找到“第一个数据不对的节点”而不是从最终输出倒推猜测。上游值正确、下游输入错误多半是变量引用配置的问题上游本身为空则要回到产生该值的节点排查。保存画布后如果应用已经发布还要按发布流程更新线上版本并重新做端到端验证。参考资料Dify 官方文档Key Concepts变量引用与节点输出Dify 官方文档30-Minute Quick Start变量选择、缓存变量与节点调试Dify 官方文档LogsWorkflow 运行记录与节点执行轨迹Dify 官方文档User Input 节点Dify 官方 GitHub Releases