GuidesOneMux

Crie um fluxo confiável de extração de dados no n8n com validação de JSON Schema

Projete um pipeline de extração no n8n que valide saídas estruturadas de modelos, repita tentativas em caso de falhas temporárias e encaminhe registros incertos ou inválidos para revisão humana.

AI

Resumo · TL;DR

Um fluxo de extração robusto trata a saída do modelo como entrada não confiável. Defina um contrato JSON restrito, valide o resultado analisado antes de gravá-lo em qualquer lugar, repita tentativas apenas para falhas temporárias e encaminhe casos não resolvidos ou de alto impacto para uma pessoa.

Principais pontos

  • Peça um único objeto JSON previsível e valide-o independentemente do modelo.
  • Separe falhas temporárias de API de resultados de extração malformados ou incompletos.
  • Limite as novas tentativas e preserve o registro de origem para que reprocessamentos não criem duplicatas.
  • A revisão humana é especialmente importante antes de ações com consequências; o n8n permite aprovar ferramentas selecionadas do AI Agent.
  • Mantenha um registro de auditoria com a origem, o resultado extraído, os erros de validação, o número de tentativas e a decisão do revisor.
Nesta página (7)

A decisão de design: valide antes de agir

O fato de um modelo retornar um JSON aparentemente válido não comprova que os dados estejam completos, com os tipos corretos ou seguros para uso. No n8n, trate a extração como um pipeline com um contrato claro: obtenha um registro de origem, solicite um resultado estruturado, analise e valide esse resultado e, em seguida, prossiga, tente novamente ou encaminhe para revisão. Não conecte diretamente a saída do modelo a uma atualização no banco de dados ou a uma mensagem externa.

Este artigo usa como exemplo ilustrativo um registro semelhante a uma fatura. O schema e a configuração dos nodes são exemplos, não uma exportação do n8n testada ou específica de uma versão. Confira as opções dos nodes disponíveis na sua versão do n8n e o formato de saída aceito pelo endpoint do modelo escolhido.

1. Defina primeiro o contrato de saída

Limite o schema aos campos realmente necessários na etapa seguinte. Especifique os campos obrigatórios, use tipos estáveis e defina como representar informações ausentes. Por exemplo, uma data de fatura ausente deve ser null, não uma data inventada nem uma explicação em texto livre.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["invoice_number", "invoice_date", "currency", "total"],
  "properties": {
    "invoice_number": { "type": "string", "minLength": 1 },
    "invoice_date": { "type": ["string", "null"] },
    "currency": { "type": "string", "minLength": 3, "maxLength": 3 },
    "total": { "type": "number", "minimum": 0 }
  }
}

O schema expressa regras estruturais; ele não permite determinar se o total extraído corresponde ao documento de origem. Acrescente verificações de domínio separadas, como confirmar se uma data pode ser analisada ou se o código da moeda consta na lista de valores aceitos. Evite converter valores inesperados sem registrar isso: transformar um valor em texto em um número pode ser útil, mas registre a conversão e rejeite formatos ambíguos.

2. Monte o fluxo de trabalho do n8n em etapas

Uma organização prática do canvas é:

  1. Acionador e obtenção da origem: receba um arquivo, registro ou payload de webhook. Atribua um ID de origem estável e mantenha o texto original ou uma referência a ele.
  2. Solicitação de extração: envie o texto e uma instrução concisa ao modelo escolhido. Peça apenas o objeto definido e informe que valores incertos ou ausentes devem ser representados conforme especificado no contrato.
  3. Análise e validação: analise a resposta como JSON e, em seguida, verifique as chaves obrigatórias, os tipos, os valores permitidos e as regras de negócio. Use um node de validação de schema, se houver um disponível na sua configuração, ou um node Code com um validador que você tenha instalado e testado deliberadamente. Não presuma que determinado pacote de validação esteja disponível em todos os ambientes do n8n.
  4. Roteamento pelo resultado: registros válidos seguem para o destino; falhas passíveis de nova tentativa passam por um caminho com limite de tentativas; falhas persistentes de validação e casos ambíguos vão para revisão.
  5. Registro do resultado: armazene o ID de origem, o status, o objeto extraído, os erros de validação, o número de tentativas e a decisão final.

Mantenha a etapa de validação fora da solicitação ao modelo. As instruções do prompt podem melhorar a resposta, mas não substituem a validação.

3. Repita as tentativas para as falhas certas

Novas tentativas ajudam em caso de erros temporários de transporte, limites de taxa ou falhas do lado do serviço. Elas não corrigem um número de fatura ausente nem uma resposta que viola o schema repetidamente. Configure um limite baixo de tentativas e, quando houver suporte no node, um intervalo entre elas. Confirme os controles exatos de novas tentativas na sua versão do n8n; as configurações e o comportamento podem variar conforme o node.

Use ramificações separadas para resultados diferentes:

  • Erro temporário na solicitação: tente novamente dentro do limite e, depois, marque o registro como falha para investigação posterior.
  • JSON inválido: se for útil, permita uma tentativa controlada de correção, solicitando os mesmos campos e o mesmo contrato. Valide novamente a nova resposta; nunca presuma que a correção funcionou.
  • Falha de schema ou regra de negócio: encaminhe para revisão em vez de repetir indefinidamente.
  • Resultado válido: prossiga para o destino, usando o ID de origem para evitar gravações duplicadas se o fluxo for executado novamente.

Uma nova tentativa não deve repetir uma ação subsequente irreversível. Mantenha a extração pelo modelo e a gravação dos dados em etapas separadas e, sempre que possível, torne a gravação idempotente.

4. Inclua revisão humana quando ela reduzir riscos

A revisão humana é útil quando um valor é ambíguo, uma regra de validação falha ou a ação seguinte pode ter consequências relevantes. Mostre ao revisor a origem original, os campos propostos, os erros de validação específicos e uma opção clara para aprovar, editar ou rejeitar. Preserve a decisão do revisor e quaisquer correções.

A documentação do n8n descreve a aprovação humana para ferramentas selecionadas conectadas a um AI Agent: o fluxo pausa, um revisor pode aprovar ou negar a chamada de ferramenta proposta, e a ferramenta só é executada se aprovada. A aprovação pode ser encaminhada por canais compatíveis, como Slack, Telegram ou n8n Chat. A documentação também descreve o uso de $tool.name e $tool.parameters para mostrar ao revisor a ferramenta proposta e seus parâmetros. Trata-se da aprovação de uma chamada de ferramenta do AI Agent; por si só, não é uma interface geral de revisão para todos os registros extraídos. Para revisão em nível de registro, crie uma tarefa humana adequada e um caminho de retomada para sua implantação.

Fonte: Documentação do n8n: Human-in-the-loop para ferramentas.

5. Solucione problemas com base em evidências

Se registros válidos forem rejeitados repetidamente, examine a resposta bruta e os erros do validador antes de alterar o schema. Verifique se a resposta contém delimitadores Markdown, texto adicional, campos anuláveis ausentes ou números representados como strings. Se as novas tentativas gerarem registros duplicados, mova a gravação para depois da validação e use um identificador de origem estável. Se os revisores não conseguirem decidir rapidamente, inclua o trecho exato da origem que sustenta cada campo questionável, em vez de enviar apenas um objeto JSON.

Não flexibilize o schema apenas para aumentar a taxa de aprovação. Uma alteração no contrato deve refletir uma necessidade real nas etapas seguintes, e seus efeitos devem ser testados com entradas representativas, incluindo campos ausentes, documentos malformados e valores conflitantes.

Lista de verificação reutilizável para a implantação

  • Os campos obrigatórios, o comportamento de null, os tipos e a política para campos adicionais estão definidos.
  • A análise, as verificações do schema e as verificações de domínio ocorrem antes das gravações nas etapas seguintes.
  • As novas tentativas têm um limite e se aplicam apenas a falhas com possibilidade razoável de recuperação.
  • O reprocessamento não pode duplicar acidentalmente ações com consequências.
  • Os revisores veem a origem, os valores propostos e o motivo do encaminhamento.
  • Os logs preservam informações suficientes para investigação sem ocultar a saída rejeitada.

O padrão confiável é simples: extrair, validar, encaminhar e só então agir. Um schema detecta problemas estruturais; novas tentativas limitadas lidam com falhas temporárias; a revisão humana trata ambiguidades e riscos que a automação não deve resolver silenciosamente.

Perguntas frequentes

Pedir JSON ao modelo garante uma saída válida de acordo com o schema?

Não. Trate a resposta como entrada não confiável: analise-a e valide os campos obrigatórios, os tipos e as regras de negócio no fluxo antes de usá-la.

O n8n deve repetir a tentativa quando o JSON extraído falhar na validação?

Não automaticamente e sem limite. Uma única tentativa de correção pode ser útil, mas falhas repetidas de schema geralmente devem ser encaminhadas ou marcadas para investigação, em vez de provocar novas tentativas indefinidamente.

A aprovação com human-in-the-loop do n8n pode revisar registros extraídos?

O recurso do n8n citado aprova ou nega chamadas de ferramentas feitas por um AI Agent. Ele não oferece, por si só, uma interface geral para revisar registros; implemente uma tarefa humana adequada e um caminho de retomada para casos de extração.

O que o revisor deve ver?

Mostre a origem original ou o trecho relevante, os campos estruturados propostos, os erros de validação ou as incertezas e uma opção explícita para aprovar, editar ou rejeitar.

Artigos relacionados