Extrair

Extraia campos estruturados de documentos usando modelos de Extração e Processamento Inteligente (IXP).

O nó Extrair extrai campos estruturados de um documento (uma fatura, recibo, formulário ou contrato) usando um modelo de Extração e Processamento Inteligente (IXP) da UiPath e retorna o resultado para os nós subsequentes agirem. Use-o quando uma etapa do seu processo precisar de dados digitados retirados de um arquivo não estruturado.

Antes de começar: faça a implantação de um modelo de IXP

O nó Extrair não tem um extrator integrado por si só. Ele revela os modelos de IXP implantados em sua organização, portanto você deve realizar a implantação de pelo menos um modelo de extração IXP antes que quaisquer opções apareçam no nó.

• Crie e implante um modelo na Extração e Processamento Inteligente (IXP). Consulte a documentação da Extração e Processamento Inteligente (IXP) para obter mais informações.
• Você deve implantar o modelo 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 você não implantar nenhum modelo, a categoria Extrair aparece na paleta, mas fica vazia.

Seu tenant também deve ter os serviços de Extração e Processamento Inteligente (IXP) e Document Understanding habilitados (Admin → Tenant → Serviços). O nó Extrair depende do provisionamento de ambos, mesmo quando você usa apenas modelos de Extração e Processamento Inteligente (IXP).

Como funciona

Modelos de extração carregam dinamicamente a partir da sua organização, da mesma forma que os nós de conector carregam 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ó Extrair vinculado a esse modelo específico.

Quando o nó é executado, o Fluxo envia o documento para o modelo de Extração e Processamento Inteligente (IXP), o modelo o digitaliza e extrai e o resultado estruturado retorna no output do nó. A extração é executada de forma assíncrona: o nó aguarda o modelo finalizar antes de continuar, portanto, reserve um tempo para documentos grandes.

Configuração

Configure o nó Extrair no painel de propriedades depois de adicioná-lo à tela.

Campo	Required	Padrão	Description
Modelo	Sim	Modelo selecionado	Modelo de IXP implantado para executar. Você define isso quando adiciona o nó da paleta, e vincula a pasta e a versão do modelo automaticamente.
Documento	Sim	Nenhum	Arquivo a extrair de. Vincule-o a um arquivo que você produziu anteriormente no fluxo, como um anexo de um gatilho ou de uma saída de nó anterior.
Intervalo de Página	Não	Vazio	Páginas a extrair de, por exemplo, 1-3. Deixe-o vazio para processar todo o documento.

Saída

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

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

Leitura do 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 um Array 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 subsequente, acesse ExtractionResult.ResultsDocument.Fields, localize o campo por 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 campo carregam espaços e capitalização do esquema de 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: lendo Fields.find((f) => f.FieldName === "Total").Value retorna undefined. Os campos estão em ResultsDocument.Fields (um nível mais profundo do que ExtractionResult), e o valor reside no array Values, não no campo diretamente. Os exemplos copiados de fluxos de trabalho legados do Document Understanding usam uma forma mais plana e não funcionam aqui.

Campos ausentes

Um campo que o modelo não conseguiu localizar tem IsMissing: true e um array Values vazio ou nulo. Proteja sempre com Values?.[0] (como os fragmentos acima fazem) para que um campo ausente seja lido como undefined em vez de lançar.

Pontuações de confiança

Each extracted value carries a Confidence and an OcrConfidence, both floats from 0 to 1 where higher is more certain. They sit on the value object, at Values[0].Confidence. A value of -1.0 is a sentinel meaning "not applicable" (for example, on table header rows), so filter those out before comparing. Use a Decision node to route low-confidence extractions to a Human node for review.

Campos de tabela

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

Tratamento de Erro

O nó Extrair oferece suporte a um identificador de erro. Se a extração falhar e o identificador de erro estiver conectado, a execução roteia para o caminho do erro com o objeto de erro em $vars.<nodeName>.error. Consulte Tratamento de erro para obter mais informações.

Observações

• A lista de modelos na categoria Extrair reflete o que está implantado em sua organização no momento do design. Implante ou reimplante um modelo na Extração e Processamento Inteligente (IXP) e, em seguida, abra novamente a paleta para ver a alteração.
• Os valores dos campos são sempre strings em 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).