指南OneMux

在 n8n 中构建可恢复的数据提取工作流

设计一个 n8n 数据提取工作流,验证记录、重试暂时性故障,并将异常交由人工审核,同时避免重复写入。

AI

摘要 · TL;DR

介绍一种在 n8n 中提取结构化记录的实用设计,将暂时性故障与无效数据区分开来,并在中断后安全恢复。

核心要点

  • 在向下游写入之前验证提取的字段;将无效记录交由审核,而不是反复重试。
  • 对暂时性故障采用有限重试,持久化重试记录,并在达到上限时提供明确的升级处理路径。
  • 使用原子性的幂等机制保护下游写入,并在重试前核对结果不明的操作。
  • 对 AI Agent 发起的高风险操作使用 n8n 工具审批;修正提取数据时则构建单独的审核流程。
文章目录 (8)

从恢复约定开始

对于生产环境中的 n8n 数据提取,应确保每份文档都能独立恢复:保存文档标识和处理状态,在写入前验证提取字段,仅重试有可能自行消除的故障,并将未解决的问题交由人工处理。成功的工作流不仅要能再次运行,还要能在重新运行时避免悄然重复写入或丢失记录。

下面的示例提取发票数据,并将通过审核的记录写入目标系统。这是一个示意性设计,并非经过测试的工作流。节点选项和集成方式会因 n8n 版本及目标系统而异,请在自己的环境中验证。

前提条件与工作流结构

你需要一个 n8n 实例、文档源和提取服务的访问权限、持久化数据库或等效的状态存储、已验证记录的目标系统,以及一个审核渠道。根据源文档和审核消息的敏感程度限制访问权限。

采用以下逻辑顺序:

  1. **触发并登记:**接收文档引用。使用稳定的源 ID 和文档版本创建或查找持久化任务。
  2. **提取:**获取文档,并向选定的提取器请求结构化字段。
  3. **验证:**根据明确的数据约定检查返回结果。
  4. **路由:**将有效记录送入写入流程,将无效记录送入审核队列。
  5. **写入并核对:**使用稳定的幂等键执行写入,然后记录目标系统 ID 和操作结果。
  6. **恢复:**由独立的定时工作流查找到了重试时间或卡住时间超过运维阈值的任务。

触发器执行 ID 有助于追踪,但不能作为跨多次运行的可靠文档标识。优先使用源系统的文档 ID 加版本号或内容摘要。启用自动重新处理之前,应先定义修正文档如何获得新版本。

写入前验证提取的记录

在本例中,invoice_id、currency 和 amount_minor 为必填字段。金额使用货币最小单位表示,例如分,以避免验证时出现浮点舍入问题。该约定假设提取器已按照相应货币的规则完成金额转换;实际实现还必须检查是否支持该货币,以及转换是否恰当。

在提取步骤之后放置一个 Code 节点。以下示例 JavaScript 会检查每个传入项,并在数据有误时返回可供审核的结果,而不是抛出异常。将节点配置为处理所有传入项,并确保运行此节点前,每个项的 JSON 都是提取出的记录。

return $input.all().map((item) => {
  const record = item.json;
  const errors = [];

  if (typeof record.invoice_id !== 'string' || !record.invoice_id.trim()) {
    errors.push('invoice_id must be a non-empty string');
  }
  if (typeof record.currency !== 'string' || !/^[A-Z]{3}$/.test(record.currency)) {
    errors.push('currency must be a three-letter uppercase code');
  }
  if (!Number.isSafeInteger(record.amount_minor) || record.amount_minor < 0) {
    errors.push('amount_minor must be a non-negative safe integer');
  }

  return {
    json: {
      record,
      validation: { valid: errors.length === 0, errors },
    },
  };
});

随后添加一个检查 validation.valid 的 IF 节点。将任务 ID 和源引用与此输出一同保留:可以放在项中,也可以从状态存储中查找。正则表达式只检查货币代码的格式,并不验证它是否为实际支持的货币。写入前还应增加业务检查,例如供应商匹配和重复发票检测。

无法解析为项的格式错误响应需要单独的错误处理路径。不要假设每次提取失败后,验证节点都能收到可用记录。保存安全的诊断信息,并将持续发生的解析失败交由审核。

定义重试和升级处理规则

明确规定何时重试。下表可作为初始策略,但不能保证每项服务都以相同方式使用这些状态码。

故障初始处理达到上限或调查后的处理
超时、连接失败或临时服务错误在有限延迟后重试,并加入抖动。如服务提供了重试延迟说明,应遵循该说明。标记为需要运维人员调查。
速率限制按服务的指导延迟;必要时降低并发量。如果任务无法在其服务时间窗口内继续推进,则升级处理。
字段缺失或业务验证失败不要无限重复相同请求;将记录和错误交由审核。写入前重新验证修正后的记录。
身份验证或权限错误停止自动重试并通知运维人员。凭据或权限修正后恢复。
写入超时且结果未知再次写入前,使用稳定的操作键查询目标系统。如果结果仍然未知,进行人工核对。

例如,允许总共最多提取三次,两次重试前分别等待约一分钟和五分钟,并加入抖动。持久化记录尝试次数、最近一次错误类别、下次可执行时间和最终处理结果。决定服务提供方指定的延迟是否优先于上述示例等待时间。不要在未同时计入两者的情况下叠加节点级重试和定时重试,否则实际尝试次数可能超过策略上限。

适当使用 n8n 提供的错误处理和重试设置,但不要仅依赖执行日志充当队列。定时恢复工作流应查询持久化任务状态,并以原子方式认领符合条件的任务,避免两个工作进程同时处理同一任务。请在部署环境中验证具体节点设置和数据库锁定行为。

确保写入能够安全恢复

首次向目标系统写入之前,持久化一个由源文档标识和版本派生的稳定操作键。每次重试都使用同一个键。目标系统必须以原子方式强制唯一性或遵守幂等键;先检查记录是否存在、再单独插入的做法容易受到并发工作进程影响。

如果目标系统不具备这种能力,可以使用具有原子唯一性约束的中间存储,并建立核对流程。但仅凭这一措施无法保证独立系统中的操作效果恰好发生一次:写入可能已在目标系统成功,而你的进程却未收到响应。这种情况下,重试前应使用稳定的外部引用查询目标系统;如果无法可靠查询,则交由运维人员处理。

跟踪 received、extracting、review_required、ready_to_write、write_unknown 和 completed 等状态。为进行中的工作设置租约或截止时间,并让恢复流程检查已过期的租约。只有在确认写入成功后才保存目标系统记录 ID。保留尝试历史和状态变更记录,使运维人员能够说明发生了什么,同时避免在日志中暴露不必要的文档内容。

在合适的环节引入人工审核

对于无效的提取结果,创建包含源引用、提取出的待审核字段、验证错误和任务 ID 的审核任务。提供经过身份验证的方式,以批准修正或拒绝任务。发生修正时,保存修改人和修改时间,重新执行验证,并使用相同的受保护写入流程。为无人处理的审核任务指定升级处理负责人和超时时间;不要悄然将未回应视为批准。

当 AI Agent 调用工具时,适用另一项独立的 n8n 功能。n8n 人工介入文档说明,选定的工具调用可以暂停,等待批准或拒绝,并向审核人员展示拟调用的工具及其参数。在 Agent 的 Tools 面板中,添加人工审核步骤、配置受支持的渠道,并连接需要审批的工具。文档还建议在系统提示词中告知 agent 哪些工具需要审批,以及如何处理拒绝结果。

工具审批不能替代模式验证,也不是通用的记录修正队列。获批工具会使用 AI 提出的输入执行;如果审核人员需要修改提取字段,应使用修正流程,并在任何写入之前再次验证。

上线前的运维检查

  • 测试字段缺失、提取响应格式错误、速率限制、凭据过期和审核被拒绝等情况。
  • 模拟目标系统写入成功但未返回响应的情况;确认恢复流程会先核对,而不是盲目再次插入。
  • 确认并发恢复工作进程无法认领同一任务,并且重试上限涵盖所有重试层级。
  • 对积压过久的审核任务、重试次数耗尽、租约过期和写入结果未知的情况设置告警。检查运维人员能否定位源文档,并安全地恢复或关闭每个任务。

从保守的重试上限和审核规则开始,再根据观察到的故障类别进行调整。即使自动化范围扩大,也要保留验证和幂等性防护环节。

参考资料

常见问题

n8n 工作流应该重试未通过模式验证的记录吗?

通常不应使用相同输入和配置重试。应将记录交由审核或送入已定义的修正流程,并在写入前验证修正后的记录。如果原因是暂时性的,单独制定有次数上限的重新提取策略可能是合适的。

n8n 人工审核会自动验证提取的数据吗?

不会。文档介绍的 AI Agent 工具审核功能是请人工批准或拒绝拟议的工具调用。模式验证和记录修正流程都需要单独设计工作流。

工作流如何避免超时后重复写入?

重复使用稳定的操作键,并让目标系统以原子方式执行幂等约束。如果结果未知,应在重试前与目标系统核对;无法确定结果时,应升级处理。

相关文章