Extrair

Extraia campos estruturados de documentos usando modelos de extração de IXP.

O nó Extract extrai campos estruturados de um documento (uma fatura, recibo, formulário ou contrato) usando um modelo UiPath Intelligent eXtraction Platform (IXP) e retorna o resultado para os nós downstream agirem. Use-o quando uma etapa no seu processo precisar de dados digitados extraídos de um arquivo não estruturado.

Antes de começar: implantar um modelo de IXP

O nó Extract não tem extrator integrado próprio. Ela revela os modelos de IXP implantados em sua organização, portanto, você deve implantar pelo menos um modelo de extração de IXP antes que quaisquer opções apareçam no nó.

• Crie e implante um modelo no IXP. Consulte a documentação do IXP para obter mais informações.
• O modelo deve ser implantado em uma pasta que você possa acessar. Os modelos são listados por seu nome totalmente qualificado, <Folder>/<ModelName> (por exemplo, Shared/Finance/invoice-extraction).
• Se nenhum modelo for implantado, a categoria Extrair aparece na paleta, mas está vazia.

Seu tenant também deve ter os serviços IXP e Document Understanding habilitados (Admin → Tenant → Serviços). O nó Extract depende de ambos serem provisionados, mesmo quando você usa apenas modelos IXP.

Como funciona

Os modelos de extração são carregados dinamicamente de sua organização, da mesma forma que os nós de conector são carregados do Integration Service. Na paleta de nós, os modelos implantados aparecem em Processamento de documentos → Extrair, cada um como seu próprio nó. Adicionar um à tela cria um nó Extract associado a esse modelo específico.

Quando o nó é executado, o Flow envia o documento para o modelo do IXP, o modelo o digitaliza e o extrai, e o resultado estruturado retorna no output do nó. A extração é executada de forma assíncrona: o nó aguarda o modelo terminar antes de continuar; portanto, permita tempo para documentos grandes.

Configuração

Configure o nó Extract no painel de propriedades após adicioná-lo à tela.

Campo	Required	Padrão	Description
Modelo	Sim	Modelo selecionado	Modelo de Extração e Processamento Inteligente (IXP) implantado a ser executado. Isso é definido quando você adiciona o nó da paleta, e a pasta e a versão do modelo são vinculadas automaticamente.
Documento	Sim	Nenhum	Arquivo do qual extrair. Associe-o a um arquivo produzido anteriormente no fluxo, como um anexo de um gatilho ou uma saída de nó anterior.
Intervalo de Página	Não	Vazio	Páginas das quais extrair, por exemplo, 1-3. Deixe vazio para processar todo o documento.

Saída

O nó Extract retorna seu resultado $vars.<nodeName>.output.

Variável	Description
output	Resultado da extração. Contém um único objeto ExtractionResult com metadados de documento, campos extraídos e pontuações de confiança por campo. A forma é detalhada na Leitura do resultado.
error	O erro detalha quando o nó falha. Contém code, message, detail, category, e status. Disponível quando o identificador de erro do nó está conectado.

Lendo o resultado

O resultado da extração é uma estrutura aninhada. Os campos extraídos estão em ExtractionResult.ResultsDocument.Fields, e o valor de cada campo está em uma matriz Values , não diretamente no campo:

$vars.<nodeName>.output = {
  ExtractionResult: {
    DocumentId: "<id>",
    ResultsVersion: 0,
    ResultsDocument: {
      DocumentTypeField: { Value: "Invoice", Confidence: 1.0, OcrConfidence: -1.0 },
      Fields: [
        {
          FieldId: "Test.Financial.Invoice.Total", // model-qualified id
          FieldName: "Total",                        // leaf label, use this for lookups
          FieldType: "Text",
          IsMissing: false,
          Values: [
            { Value: "12.57", Confidence: 0.604, OcrConfidence: 0.604, Components: [], Reference: {} }
          ]
        }
        // ...one entry per field in the model schema
      ]
    }
  }
}

Para ler o valor de um único campo em um nó de Script downstream, alcance ExtractionResult.ResultsDocument.Fields, encontre o campo pelo seu FieldName, e leia Values[0].Value:

const value =
  $vars.extract1.output
    ?.ExtractionResult?.ResultsDocument?.Fields
    ?.find((f) => f.FieldName === "Total")
    ?.Values?.[0]?.Value;

Como os nomes de campos carregam espaços e maiúsculas/minúsculas do esquema do modelo (Invoice No., Vendor Name), uma pesquisa normalizada é mais robusta:

const fields = $vars.extract1.output?.ExtractionResult?.ResultsDocument?.Fields || [];
const norm = (s) => String(s || "").toLowerCase().replace(/\s+/g, "");
const get = (name) => {
  const f = fields.find((x) => norm(x.FieldName) === norm(name));
  return f && Array.isArray(f.Values) && f.Values[0] ? f.Values[0].Value : undefined;
};

const total = get("Total");
const vendor = get("Vendor Name");

Observação:

Erro comum: a leitura de Fields.find((f) => f.FieldName === "Total").Value retorna undefined. Os campos ficam sob ResultsDocument.Fields (um nível mais profundo que ExtractionResult), e o valor reside na matriz Values , não no campo diretamente. Os exemplos copiados de fluxos de trabalho legados do Document Understanding usam uma forma mais plano e não funcionarão aqui.

Campos ausentes

Um campo que o modelo não pôde encontrar tem IsMissing: true e uma matriz Values vazia ou nula. Sempre se proteja com Values?.[0] (como os fragmentos acima fazem) para que um campo ausente seja lido como undefined em vez de lançado.

Pontuações de confiança

Cada valor extraído carrega um Confidence e um OcrConfidence, ambos flutuantes de 0 para 1 onde maior é mais certo. Eles ficam no objeto de valor, em Values[0].Confidence. Um valor de -1.0 é um sentimento que significa "não aplicável" (por exemplo, em linhas de cabeçalho de tabela), então filtre-os antes de comparar. Use um nó de decisão para rotear extrações de baixa confiança para uma tarefa humana para revisão.

Campos de tabela

Um campo com FieldType é Table mantém suas linhas em Values, não na forma escalar acima. Cada valor da tabela carrega uma matriz Components (uma linha Header e uma linha Body ), e cada componente, por sua vez, contém os campos da célula sob seu próprio Components, cada um com o familiar Values[0].Value. Caminho Components recursivamente para alcançar células individuais.

Tratamento de Erro

O nó Extrair é compatível com um identificador de erro. Se a extração falhar e o identificador de erro estiver conectado, a execução roteará para o caminho do erro com o objeto de erro $vars.<nodeName>.error. Consulte Tratamento de erros para obter mais informações.

Observações

• A lista de modelos na categoria Extrair reflete o que é implantado em sua organização no período de design. Implante ou reimplante um modelo no IXP e, em seguida, reabra a paleta para ver a alteração.
• Os valores dos campos são sempre Values[0].Value, mesmo para datas e números. O modelo também pode retornar partes analisadas em DerivedFields (por exemplo, Year, Month, Day em uma data ou City e Country em um endereço).