AI 工作流调试指南：常见失败模式与排查清单

先固定一次失败，而不是反复点执行

AI 工作流的问题常被误判成“模型不稳定”，实际原因可能是字段引用错、批次混合、接口限流、输出格式漂移或重试造成副作用。调试第一步是保存一份脱敏的失败输入、执行 ID、节点错误、外部响应状态和预期结果。复制为测试工作流，关闭发消息、写生产库、发布内容等副作用节点，再逐节点重放。

建议给所有入口生成 requestId，并贯穿模型调用、工具调用、数据库记录和通知。日志记录阶段、耗时、item 数、错误类别与重试次数，但不输出凭证、完整个人数据或不必要的提示词。这样才能回答“慢在哪里”“哪条数据失败”“是否已执行过”。

超时：先找边界，再决定重试

当执行显示超时，先看具体节点耗时：Webhook 是否等待整条链路；HTTP Request 是否没有超时；模型输入是否过长；Agent 是否反复调用同一工具；子工作流是否没有结束。将入口快速确认与后台处理分离，给每个外部请求设置超时，并限制 Agent 最大迭代或通过状态防止循环。

重试只适用于临时网络错误、限流和部分服务端错误。认证失败、参数校验失败、内容被拒绝不会因重试恢复。退避应有次数上限并加入抖动，超过上限进入错误队列。对发布、发送、扣减等动作，重试前必须有外部幂等键或查询远端结果；“请求超时”不等于“远端没有成功”。

{
  "requestId": "req_001",
  "stage": "model_generate",
  "attempt": 2,
  "retryable": true,
  "nextAction": "backoff",
  "safeMessage": "上游服务暂时不可用"
}

JSON 解析错误：约束、清洗、验证三层处理

典型症状是模型在 JSON 前后添加解释、使用 Markdown 代码围栏、漏引号，或字段类型变化。优先使用模型节点支持的结构化输出能力，并提供明确 schema、枚举与示例。提示词写“仅输出 JSON”有帮助，但不能替代验证。

解析前可以去除确定的代码围栏，却不要用复杂正则从长文本里“猜”一段 JSON。Code 节点捕获 JSON.parse 错误，验证必需字段、类型、长度和额外字段。失败后最多进行一次专门的格式修复，修复模型只接收待修复文本与 schema，不接触业务工具。仍失败则转人工或返回降级结果。

const value = JSON.parse($json.output);
const allowed = new Set(["faq", "order_status", "human"]);
if (typeof value.reply !== "string" || !allowed.has(value.intent)) {
  throw new Error("MODEL_OUTPUT_SCHEMA_INVALID");
}
return [{ json: { reply: value.reply, intent: value.intent } }];

如果同一批 item 只有一条失败，确认 Code 节点运行模式和 $json、$input.all() 的用法。把整批数组误当单条对象，是 N8N 数据映射中常见的问题。

Prompt 注入：失败的不是提示词，而是权限设计

用户文本、网页、邮件和 RAG 文档都可能包含“忽略之前规则”“调用某工具”等指令。把外部内容用清晰分隔包在数据区，并在 System Prompt 中声明其不具备指令权限，但不要止步于此。工具必须执行自己的鉴权、参数白名单、范围限制和只读策略；检索必须在向量库侧按权限过滤；高风险动作必须有人工批准。

建立攻击样本集，包括索取系统提示、伪造管理员、查询他人数据、要求批量导出、通过文档间接下令。验收目标不是模型每次都说同一句拒绝，而是无论输出如何，未授权工具都无法成功执行，公开响应也不会带出内部字段。

若发现注入成功，先停用危险工具或关闭自动动作，再检查实际权限边界。仅继续添加“绝对不要”之类提示词，通常只能改变表现，无法修复根因。

Agent 循环与工具调用失败

Agent 重复调用工具时，检查工具描述是否重叠、返回值是否明确、错误是否被模型误解为“再试一次”。工具返回应包含稳定状态，例如 found、errorCode、retryable，不要只返回空字符串。为相同 requestId、工具名和规范化参数建立调用记录，阻止短时间内重复副作用。

工具参数经常因为字段名称、日期格式或枚举不一致而失败。描述中给出 schema，工具入口再次校验，并把安全错误返回给 Agent；内部堆栈只进日志。对于“先查询再修改”的流程，把查询与修改拆成不同工具，让修改工具要求一次性审批令牌，而不是让模型自行宣称已获得同意。

成本失控：从输入、分支和重试检查

模型费用或资源消耗突然上升时，检查输入长度、调用次数、Agent 迭代、循环节点 item 数、错误重试和并发。常见原因是把完整执行历史反复拼入提示、Split Out 后每条都调用模型、Webhook 重放、RAG 返回片段过多，或失败路径再次触发主工作流。

在调用前记录字符或 token 估算、item 数和用途标签；限制会话历史，只保留必要摘要；先用确定性规则过滤无需模型处理的数据；批处理时明确上限；为每日或每次执行设置业务级配额，超过阈值暂停并告警。缓存只适合输入与权限上下文一致、结果允许复用的任务，不能为了省调用而跨用户共享敏感回答。

{
  "usageGuard": {
    "workflow": "content-draft",
    "items": 12,
    "estimatedInputSize": 18400,
    "decision": "require_review"
  }
}

不要在教程中硬编码价格做告警条件；服务价格与计量可能变化。以模型服务返回的真实 usage 数据和团队可接受预算建立监控，并定期核对账单与执行记录。

数据丢失、重复与表达式错位

节点显示成功不代表数据正确。每一步都核对输入 item 数、输出 item 数和关键字段。Merge、Loop、聚合和子工作流容易改变数据形状；用 Set 节点在阶段边界建立明确契约，不要长期依赖 $node["某节点"] 中偶然存在的测试数据。

写入数据库或外部系统时使用业务幂等键和唯一约束。部分成功的批次应保存逐项状态，从失败项恢复，而非重跑整批。若流程被手动重试，先查询哪些动作已经完成。对于空输入，显式走 no_data 分支并正常结束，避免后续节点引用不存在字段。

推荐的排查顺序

1. 确认失败输入、预期结果、执行 ID 与第一个异常节点。
2. 检查该节点实际收到的数据，而不是只看上游配置界面。
3. 关闭副作用，用固定样本单步执行并比较 item 数和字段类型。
4. 检查凭证权限、请求参数、状态码和响应体中的安全错误摘要。
5. 若涉及模型，保存模型输入结构、工具列表和原始输出，再判断是内容问题还是解析问题。
6. 验证重试、循环、并发和 Webhook 重放是否放大故障。
7. 修复后用正常、边界、恶意和依赖不可用四类用例回归。

上线前检查清单

• 每个外部调用都有超时、错误分类和有限重试策略。
• 每个副作用动作都有幂等键，未知结果不会盲目重试。
• 模型结构化输出经过运行时校验，失败有降级路径。
• Agent 工具执行独立权限检查，提示词注入无法突破权限。
• 循环、批量、会话历史与检索片段都有明确上限。
• 日志能按 requestId 串联，同时不泄露密钥和敏感数据。
• 告警包含可行动信息：失败阶段、影响范围、是否可重试和执行链接。

调试的核心是把概率性模型包在确定性的工程边界里。输入契约、权限、schema、幂等、超时和日志越清楚，模型偶尔偏离时造成的影响就越小，故障也越容易复现。