AI 工作流总在某个节点卡住，怎么定位和排查？

学完这篇，你能在一分钟内判断出 AI 工作流到底卡在哪个节点，并知道该看哪几个字段、按什么顺序排查。

第一步：先分清「卡住」是哪一种卡

打开执行记录，先给现象归类，不同类的排查路径完全不同。三种常见形态：一是真挂起，节点转圈不停、没有超时也没有报错；二是超时报错，节点变红并给出错误信息；三是静默失败，流程跑完了但结果明显不对。

入口位置：Dify 社区版在左侧「日志与标注」→「工作流日志」，点进具体某一次运行，右侧会出现「追踪」面板；n8n 在左侧导航栏的 Executions，点开某一条执行记录；扣子（Coze）在工作流编辑页右上角「试运行」旁边的运行历史。自建框架就直接看服务端 stdout 或日志文件。

第二步：在追踪面板里找「最后一个没走完的节点」

跑一次，把追踪面板的时间轴从头往下拉到底。成功的节点是绿色对勾，失败的是红色叉，从未执行的是灰色，正在跑或卡住的是转圈。

注意：如果有并行分支，画布上一个分支转圈可能只是它在等另一个慢分支，不代表它坏了。先看时间戳——卡住节点的开始时间如果和另一个节点几乎相同，就是并发等待，不是故障。

第三步：看这个节点的输入，九成问题出在上游

点开卡住节点，切到 INPUT / 输入 标签页，看它实际收到了什么。「输入不对」比「节点本身坏了」常见得多。两个高频情况：

一是上游 LLM 节点要求输出 JSON，结果模型返回了被 ```json 包裹的文本，或者前面多了一句「好的，以下是结果」。下游的 JSON 解析节点拿到这种字符串会直接抛异常，有时表现为长时间无响应。

二是变量引用为空。比如 URL 里拼了 {{查询结果.url}}，而这个变量实际是空字符串，HTTP 请求节点就会一直等一个不存在的地址，直到超时。

第四步：看输出和错误码，区分「AI 太慢」和「真出错」

切到 OUTPUT / 输出 和错误信息区，找这几个关键词：

• 504、Read timed out、context deadline exceeded、ESOCKETTIMEDOUT：连接或读取超时，多半是模型侧慢或超时阈值设太短。
• 429、rate limit：被限流，常见于批量并行调用大模型。
• LLM 节点额外看 finish_reason。如果是 length，说明输出被 max_tokens 截断，下游拿到的 JSON 是残缺的，解析当然失败。
• 同时看 token 消耗数。输入 token 逼近模型上限时，请求可能被静默丢弃。

第五步：单节点复现，把变量固定住

把卡住节点的输入 JSON 整段复制出来，用平台的「单节点运行」「试运行此节点」按钮单独跑一次。n8n 是在节点上右键选「Execute step」；Dify 是点节点右上角的运行图标。

如果是 HTTP 请求节点，也可以直接脱离平台用命令行验证：

curl -X POST 'https://api.example.com/v1/chat' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"xxx","messages":[{"role":"user","content":"测试"}]}' \
  --max-time 30 -v

加上 --max-time 和 -v，能立刻分清是网络层慢还是接口本身返回错误。能单独跑通、放回工作流就失败，问题一定在数据传递，不在节点配置。

第六步：按清单逐条排掉高频原因

1. 节点超时设置太短（默认常见 30 秒，长文本生成建议 120 秒以上）。
2. 上下文超限，尤其是带知识库检索的节点，召回条数开太大。
3. 循环 / 迭代节点的终止条件写错，条数上千时看起来就像卡死——先看迭代次数计数是否在正常增长。
4. 上游输出格式不稳定，缺少结构化输出约束（应在提示词里明确「只输出 JSON，不要任何解释」）。
5. 代理、白名单、VPC 网络策略把出站请求拦了，表现为长时间无响应而非拒绝。

第七步：改完加三道兜底，避免下次再卡

一是给所有外部调用节点显式设超时和重试次数（重试 2 次、间隔 2 秒即可，别设 5 次以上，会放大限流）。二是给关键的 LLM 节点加格式校验，解析失败就走失败分支返回原始文本，而不是让整个流程中断。三是在每个节点前后打一条含运行 ID 的日志，下次出问题直接按 ID 搜。

小结

• 先分类：真挂起、超时报错、静默失败，三条路径不同。
• 定位靠追踪面板的最后一个非绿色节点，并行分支要看时间戳排除干扰。
• 优先怀疑输入：上游 JSON 格式污染、变量为空占两个大头。
• 用错误码区分超时、限流、截断，别一股脑归因于「模型慢」。
• 单节点复现是分水岭：能单独跑通就是数据传递问题。
• 修完必须补超时、重试、失败分支，否则下次还会卡在同一个地方。