dify 工作流 agent 怎么排查?先分清是编排坏了还是模型没接上

接入与开发

给一套分层排查顺序:先看节点编排与变量传递,再看模型供应商与工具调用,最后才动提示词,附对照表和逐项检查清单。

Dify 里跑一个工作流 agent,最容易出现的情况是:日志里没红字,输出就是不对。这时候多数人第一反应是回去改提示词,改了三版还是不对。问题往往不在提示词。这篇给一条从编排层往模型层走的排查顺序,每一步都有能直接看的地方,也有什么时候这套顺序不适用的说明。

Dify 里跑一个工作流 agent,最常见的情况是日志干干净净,没有一行红字,输出就是不对。这时候多数人的第一反应是回去改提示词。改到第三版,第四版,结果还是那样。花掉的时间全砸在最后一层,前面的问题没动过。

我建议反过来走:从编排层往模型层查。先确认变量进没进来、节点跑没跑、工具发没发出去,最后才轮到提示词。下面这条顺序每一站都有能直接看的地方,也写了什么情况下这套顺序不适用。

先判断卡在哪一层,别急着改提示词

一次失败的运行,其实可以拆成四段看:输入变量有没有真的进来、节点有没有按顺序执行、模型有没有正常返回、工具调用有没有真的发出去。任何一段断了,输出都会歪,但表现出来可能长得一模一样——都是「结果不对」。

最省事的做法是用单节点运行,一个节点一个节点试。哪一步单独跑就不对,问题就在那一节点,不用把整条链路从头读到尾。这一步能挡掉大半无效排查。输出为空又没报错,八成是变量没传进来,或者上游节点的输出字段名对不上,而不是模型不听话。

编排层的三个高频坑:变量、字段名、条件分支

编排层的问题最隐蔽,因为界面不报错。第一个坑是变量引用:节点引用上游输出时,要看清选的是哪个节点的哪个字段。你把上游节点改了个名,引用不会自动跟着变,界面上看着还是绿的,跑起来就是空的。改完名记得回头把每一处引用点一遍。

第二个坑是条件分支。判断值要和上游实际输出的类型一致。上游吐的是字符串「3」,你拿数字 3 去比,分支会静默走错,不报错,也不提示。第三个坑在迭代和循环节点:每一轮的输出怎么合并要提前想清楚,只留最后一条是最常见的丢数据原因,尤其下游还要汇总的时候。

  • 节点改名或换输出结构后,逐个检查下游引用是否还指向存在的字段
  • 条件分支两边的值类型对齐,字符串对字符串,数字对数字
  • 迭代节点的输出合并方式确认一遍,是需要全部结果还是只要最后一条
  • 用单节点运行验证每个分支的走向,别只看最终输出

模型接得上不等于调用得对

能连通和调得对是两件事。工作流里要先确认选中的供应商和模型名,是当前配好的那一个。换过中转或者自定义供应商之后,很多节点还指着旧配置,你得重新指一遍。各家供应商当前的模型清单和价格,到 /sites 里核对当时的数字,别凭记忆填。

工具节点报参数错误,先比对你的参数定义和工具实际接收的字段名与类型。最常见的错是多包了一层对象:工具要的是平铺的字段,你传了个嵌套结构进去。模型能返回但格式不对,也别急着让模型「注意格式」,先把该节点的输出改成结构化字段,再去要求下游能解析它。

现象先查哪里判断标准
输出为空、无报错变量引用与上游输出字段名单节点跑上游,看输出是否真有你引用的字段
分支走错方向条件判断的值类型把两边的值打出来对比,类型是否一致
工具报参数错误参数定义与工具入参结构字段名、类型、层级三者对得上
模型返回但下游解析失败该节点输出结构改成结构化字段后下游能否稳定读取
同一输入两次结果差很多温度与链路稳定性调低温度后是否收敛,不收敛就不是提示词问题

留一份能复盘的记录,比反复手试管用

排查到后面你会发现,真正拖时间的是「记不清上次改了什么、跑的是哪组输入」。每次运行记三样就够:输入变量快照、各节点耗时、最终输出,纯文本存一份,比截图强。

  1. 固定一组测试输入挑一组能复现问题的输入存成文本,后面每次改动都用它跑,不要换新案例。
  2. 跑单节点定位从第一个可疑节点开始逐个单跑,记录哪个节点单独跑就不对。
  3. 改一处配置重跑同组输入一次只改一个地方,改完用同一组输入再跑,对比输出差异,判断改动是否真生效。
  4. 存一份运行记录输入快照、节点耗时、最终输出三样落成文本,下次接着查有据可依。

同一份输入跑两次结果差异很大,先把温度调低看是否收敛。收敛了说明是随机性带来的波动,之前纠结的「不对」可能只是采样差异;不收敛,那就是链路本身不稳,跟提示词没关系,别再去改措辞了。

下一步如果你手上还在挑供应商或中转,先去 /price-watch 看价格变动记录,再到 /tools/speed-test 测一下连通和延迟,把模型这一层的前提确认好,再回来查工作流会省很多来回。

常见问题

工作流跑通了但结果不稳定,是不是模型不行?

先别急着换模型。用同一组输入连跑几次,看差异出在哪一步。如果检索或工具返回的内容每次都不同,换模型解决不了。只有输入和中间结果都一致、输出还在飘,才轮到考虑模型和温度设置。

日志里没有任何报错,输出却是空的,从哪查起?

先单节点运行最后一个节点,看它的输入有没有值。空输入基本就是上游变量没传下来,常见于节点改名后引用没更新,或者迭代节点没把每轮结果汇总。确认输入有值再往模型那一层看。

工作流里接的是中转站,排查顺序要变吗?

多一步:先确认这个供应商在工作流里能单独调通,再谈编排。连通性没确认就调链路,等于在两个未知之间找原因。可以先到站内的接口测速页量一下延迟基线,再回来逐节点跑。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。