Consumo de modelos por meio da API do Document Understanding

Acesse modelos de Extração e Processamento Inteligente (IXP) criados em nós Flow Extract por meio da API do framework Document Understanding usando pontos de extremidade de extração baseados em tags ou baseados em extractorId.

Os nós IXP Extract são acessíveis por meio da mesma API de framework do Document Understanding. Os nós de extração aparecem como ProjectType: "IXP" no Discovery e são compatíveis com endpoints baseados em tags e endpoints baseados no extractorId para extração.

Documentação relacionada:

• Visão geral da API do Document Understanding
• Criar aplicativo externo para o Document Understanding
• Gerenciando aplicativos externos

Observação:

Use a API v2 para consumir os modelos de nós Extract e use a versão mais recente das APIs públicas do Document Understanding. Os exemplos nesta página usam a API v2 (api-version=2).

Pré-requisitos

Antes de chamar qualquer API do Document Understanding ou da Extração e Processamento Inteligente (IXP), você precisa de um aplicativo externo registrado no Automation Cloud.Isso fornece o AppID e o AppSecret que você usa para a autenticação OAuth.

Criação de um aplicativo externo.

1. Navegue até o Orchestrator no nível de tenant.

2. Selecione Gerenciar acesso, em seguida, Gerenciar contas e grupos.

3. No cabeçalho Administração da UiPath, selecione Aplicativos externos.

4. Selecione Adicionar aplicativo.

5. Preencha o Nome do aplicativo, por exemplo, DU API Client.

6. Selecione Aplicativo confidencial, necessário para obter um segredo do aplicativo.

7. Em Recursos, selecione Adicionar escopos:

   • Selecione Document Understanding no menu suspenso Recurso.
   • Alterne para a guia Escopo(s) do aplicativo.
   • Verifique os escopos de que você precisa:
     • Du.Digitization.Api - digitalizar documentos
     • Du.Classification.Api - classificar documentos
     • Du.Extraction.Api – extrair dados
     • Du.Validation.Api criar tarefas de validação
     • Du.DataDeletion.Api - excluir dados do documento
   • Selecione Salvar.

8. Selecione Adicionar para criar o registro.

   Observação:

   O pop-up Copiar o segredo do aplicativo imediatamente é exibido apenas uma vez e você não poderá recuperá-lo.Você pode gerar um novo mais tarde a partir da tela de edição.

A ID do aplicativo fica visível na página Aplicativos externos a qualquer momento.

Obtenção de um token de acesso

Use a ID do Aplicativo e o Segredo do aplicativo para solicitar um token OAuth por meio do fluxo de credenciais do cliente:

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Resposta:

{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

O token expira após 1 hora. Use-o como Authorization: Bearer <your-access-token> em todas as chamadas de API subsequentes.

Observação:

Se você perder o Segredo do aplicativo, acesse Admin e, em seguida, Aplicativos externos, edite o aplicativo e selecione Gerar novo em Segredo do aplicativo.Atualize todas as integrações com o novo segredo.

Principais diferenças

A tabela a seguir mostra as principais diferenças entre projetos Document Understanding e da Extração e Processamento Inteligente (IXP):

	Document Understanding (Clássico ou Moderno)	IXP (Extração e Processamento Inteligente)
Tipo de Projeto	Classic ou Modern	IXP
Classificação	Sim	Não (apenas extração)
Roteamento da extração	Por tag + documentTypeId (recomendado) ou extractorId	Por tag + documentTypeId ou por extractorId (gpt_ixp_[version])
Modelo de extração	Especializado ou Generativo	Apenas generativo (GPT-4o, Gemini)
Definição de esquema	No projeto ou por meio de solicitações	Definido na interface gráfica do Extração e Processamento Inteligente (IXP) (da taxonomia)

O fluxo de trabalho da Extração e Processamento Inteligente (IXP)

1. Descobrir projeto e tags.
2. Digitalize o documento e pesquise até que a digitalização seja concluída.
3. Extraia e pesquise até que a extração seja concluída.
4. Validar (opcional).

Observação:

Não há etapa de classificação, pois a Extração e Processamento Inteligente (IXP) lida apenas com extrações.

Etapa 1: descobrir o projeto de Extração e Processamento Inteligente (IXP)

# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

A partir da resposta, observe o id do projeto IXP.

Obter tags (versões publicadas)

As tags correspondem a versões do modelo publicadas marcadas como Preparação ou Produção na interface do usuário de Extração e Processamento Inteligente (IXP). Cada tag inclui seus extratores e tipos de documentos associados. Para obter tags, execute o seguinte:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Obter tipos de documentos

Para obter tipos de documentos, execute o seguinte:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Observação:

Depois de saber o ID do projeto, a tag e o ID do tipo de documento, você não precisa executar as chamadas de descoberta no runtime todas as vezes. Em vez disso, reutilize esses valores em sua automação.

Etapa 2: digitalizar o documento

Observação:

A digitalização é uma etapa obrigatória. Você não pode extrair dados de um documento antes de digitalizá-lo.

Semelhante ao Document Understanding, carregue o arquivo para obter um documentId:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

Retorna { "documentId": "..." }.

Enquete para o resultado da digitalização:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Pesquise até que status seja Succeeded e, em seguida, inicie a extração. Para os status e respostas possíveis, marque Respostas da pesquisa.

Etapa 3: extrair

A extração de Extração e Processamento Inteligente (IXP) suporta as seguintes abordagens de roteamento:

• Baseado em tags - Roteamento por tag e documentTypeId. Recomendamos isso para fluxos de trabalho de produção ou preparação.
• Baseado em ExtractorId - Rotear por extractorId usando o formato: gpt_ixp_[version]. Por exemplo, gpt_ixp_67. Isso é o mesmo que para projetos do Document Understanding Clássico ou Moderno.

Extração baseada em tags

Usa o caminho baseado em tags com o documentTypeId do Discovery.

Síncrono (até 5 páginas)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Assíncrono (várias páginas)

Iniciar:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Retorna { "operationId": "..." }. Sondar resultado:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Pesquise até que status seja Succeeded ou Failed. Para os status e respostas possíveis, marque Respostas da pesquisa.

Extração baseada no ExtractorId

Usa os mesmos pontos de extremidade baseados em extrator que o Document Understanding clássico ou moderno.O ExtractorId para Extração e Processamento Inteligente (IXP) segue o formato gpt_ixp_[version], visível na resposta de descoberta.Síncrono (até 5 páginas):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Assíncrono (várias páginas):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Retorna { "operationId": "..." }. Sondar resultado:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Pesquise até que status seja Succeeded ou Failed. Para os status e respostas possíveis, marque Respostas da pesquisa.

Etapa 4: validar (opcional)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

Respostas da enquete

As chamadas de digitalização assíncronas na Etapa 2 e as chamadas de extração assíncronas na Etapa 3 retornam seus resultados por meio de pesquisas. Cada resposta à enquete contém um status, que é um dos seguintes:

• NotStarted - O trabalho foi criado e está aguardando para ser processado.
• Running - O trabalho foi selecionado e está sendo processado.
• Succeeded - O trabalho foi concluído com sucesso. A resposta contém o result.
• Failed - O trabalho terminou com um erro. A resposta contém o error.

Continue a pesquisa enquanto o status for NotStarted ou Running.

Enquanto o trabalho está sendo processado, a resposta contém o status e os carimbos de data/hora do trabalho:

{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}

Quando o trabalho for bem-sucedido, a resposta também conterá o result. Para extração, o resultado está em result.extractionResult. Para sua estrutura, consulte Estrutura de resposta de extração de IXP.

{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}

Quando o trabalho falhar, a resposta contém um objeto error com os seguintes detalhes:

• message - A descrição do erro.
• severity - A gravidade da falha, mais comumente Error.
• code - O código que identifica o tipo de erro.
• parameters - Informações adicionais sobre o erro, se aplicável.

Para obter detalhes, consulte Solicita esquemas de resposta no guia da API do Document Understanding.

Estrutura de resposta à extração do IXP

Na API v2, todos os campos e valores relatados pelo IXP usam tipos de campo corretos, incluindo grupos de campos e campos filhos, usando um mapeamento exato do grupo de campos IXP e das definições de campos filhos.

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Observação:

Recomendamos usar a API v2 para consumo de IXP, devido ao mapeamento direto entre os grupos de campos e tipos de campos do projeto de IXP e os resultados relatados.

Estrutura de resposta de descoberta de IXP

Os projetos de Extração e Processamento Inteligente (IXP) expõem o controle de versão por meio de tags e projectVersions:

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

O nome da tag, por exemplo, live, mapeia para o rótulo de Produção ou de Preparação na interface do usuário da Extração e Processamento Inteligente (IXP).

Considere o seguinte ao chamar os pontos de extremidade de extração do IXP:

• Tag = versão do modelo: use a tag que corresponde à versão de produção ou de preparação que deseja chamar.
• IDdoTipoDeDocumento: projetos de Extração e Processamento Inteligente (IXP) normalmente usam um único tipo de documento padrão (00000000-0000-0000-0000-000000000000).
• Limites de página: para limites de páginas e tokens, consulte Limites de processamento de documentos.
• Medição: para obter detalhes sobre como a extração de IXP é cobrada, consulte Plano de Preços Flex do IXP, Unified Pricing e Medição e lógica de cobrança (Plano Flex).
• Retenção de dados: para obter detalhes sobre por quanto tempo os resultados da digitalização e extração são retidos, consulte a Visão geral da API do Document Understanding.