Análise em lote de Inteligência Documental (visualização)

A API de análise em lote permite processar vários documentos em massa usando uma solicitação assíncrona. Em vez de ter que enviar documentos individualmente e rastrear várias IDs de solicitação, você pode analisar uma coleção de faturas, uma série de documentos de empréstimo ou um grupo de documentos de treinamento de modelo personalizado simultaneamente.

• Para utilizar a análise em lote, você precisa de uma conta de armazenamento de Blob do Azure com contêineres específicos para seus documentos de origem e as saídas processadas.
• Após a conclusão, o resultado da operação em lote lista todos os documentos individuais processados com seu status, como succeeded, skippedou failed.
• A versão de pré-visualização da API em lote está disponível através de preços pré-pagos.

Os seguintes modelos suportam a análise de lotes:

• Ler. Extraia linhas de texto, palavras, idiomas detetados e estilo manuscrito de formulários e documentos.

• Layout. Extraia texto, tabelas, marcas de seleção e estruture informações de formulários e documentos.

• Modelo personalizado. Treine modelos para extrair pares chave-valor, marcas de seleção, tabelas, campos de assinatura e regiões de formulários estruturados.

• Neural personalizado. Treine modelos para extrair campos de dados especificados de documentos estruturados, semiestruturados e não estruturados.

• Generativo personalizado. Treine modelos para extrair dados especificados de objetos complexos, como tabelas aninhadas, campos abstratos/generativos e formatos verdadeiramente não estruturados.

Orientações para a análise de lotes

• O número máximo de documentos processados por solicitação de análise de lote único (incluindo documentos ignorados) é de 10.000.

• O azureBlobFileListSource parâmetro pode ser usado para dividir solicitações maiores em solicitações menores.

• Os resultados da operação são retidos por 24 horas após a conclusão. Os documentos e resultados estão na conta de armazenamento fornecida, mas o status da operação não está mais disponível 24 horas após a conclusão.

Pronto para começar?

Pré-requisitos

• Você precisa de uma assinatura ativa do Azure. Se não tiver uma subscrição do Azure, pode criar uma gratuitamente.

• Depois de ter sua assinatura do Azure, uma instância de Document Intelligence no portal do Azure. Você pode usar o nível de preço gratuito (F0) para experimentar o serviço.

• Depois que o recurso for implantado, selecione Ir para o recurso e recupere sua chave e o ponto de extremidade.

  • Você precisa da chave e do ponto de extremidade do recurso para conectar seu aplicativo ao serviço de Inteligência Documental. Você cola sua chave e ponto de extremidade no código mais tarde no início rápido. Você pode encontrar esses valores na página Chaves e Ponto de Extremidade do portal do Azure.

• Uma conta de Armazenamento de Blob do Azure. Você criará contêineres em sua conta de Armazenamento de Blob do Azure para seus arquivos de origem e resultados:

  • Recipiente de origem. Este contentor é onde carrega os seus ficheiros para análise (obrigatório).
  • Recipiente de resultados. Este contêiner é onde seus arquivos processados são armazenados (opcional).

Você pode designar o mesmo contêiner de Armazenamento de Blob do Azure para documentos de origem e processados. No entanto, para minimizar as chances potenciais de substituição acidental de dados, recomendamos escolher contêineres separados.

Autorização de contêiner de armazenamento

Você pode escolher uma das seguintes opções para autorizar o acesso ao seu recurso Documento.

✔️ Identidade gerenciada. Uma identidade gerenciada é uma entidade de serviço que cria uma identidade do Microsoft Entra e permissões específicas para um recurso gerenciado do Azure. As identidades gerenciadas permitem que você execute seu aplicativo Document Intelligence sem precisar incorporar credenciais em seu código. As identidades gerenciadas são uma maneira mais segura de conceder acesso aos dados de armazenamento e substituir o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com suas URLs de origem e resultado.

Para saber mais, consulte Identidades gerenciadas para Document Intelligence.

✔️ Assinatura de Acesso Compartilhado (SAS). Uma assinatura de acesso compartilhado é uma URL que concede acesso restrito por um período de tempo especificado ao seu serviço de Document Intelligence. Para usar esse método, você precisa criar tokens SAS (Assinatura de Acesso Compartilhado) para seus contêineres de origem e resultado. Os contêineres de origem e resultado devem incluir um token SAS (Assinatura de Acesso Compartilhado), anexado como uma cadeia de caracteres de consulta. O token pode ser atribuído ao seu contêiner ou blobs específicos.

• Seu contêiner ou blob de origem deve designar acesso de leitura, gravação, lista e exclusão .
• Seu contêiner ou blob de resultados deve designar acesso de gravação, lista e exclusão.

Para saber mais, consulte Criar tokens SAS.

Chamando a API de análise de lote

• Especifique a URL do contêiner de Armazenamento de Blob do Azure para seu documento de origem definido nos azureBlobSource objetos ou azureBlobFileListSource .

• Especifique a URL do contêiner do Armazenamento de Blobs do Azure para os resultados da análise em lote usando resultContainerUrlo . Para evitar substituições acidentais, recomendamos o uso de contêineres separados para documentos de origem e processados.

  • Se você usar o mesmo contêiner, defina resultContainerUrl e resultPrefix corresponda à sua entrada azureBlobSource.
  • Ao usar o mesmo contêiner, você pode incluir o overwriteExisting campo para decidir se deseja substituir quaisquer arquivos pelos arquivos de resultado da análise.

Criar e executar a solicitação POST

Antes de executar a solicitação POST, substitua {your-source-container-SAS-URL} e {your-result-container-SAS-URL} pelos valores de suas instâncias de contêiner de armazenamento de Blob do Azure.

Permitir apenas um ou azureBlobSource azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

Resposta bem-sucedida

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Recuperar resultados da API de análise em lote

Depois que a operação Batch API for executada, você poderá recuperar os resultados da análise em lote usando aGET operação. Esta operação busca informações de status da operação, porcentagem de conclusão da operação e criação da operação e data/hora de atualização.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Interpretando mensagens de status

Para cada documento um conjunto, há um status é atribuído, ou succeeded, failed, ou skipped. Para cada documento, há duas URLs fornecidas para validar os resultados: sourceUrl, que é o contêiner de armazenamento de blob de origem para o documento de entrada bem-sucedido e resultUrl, que é construído combinando resultContainerUrl eresultPrefix criando o caminho relativo para o arquivo de origem e .ocr.json.

• Status notStarted ou running. A operação de análise em lote não foi iniciada ou não foi concluída. Aguarde até que a operação seja concluída para todos os documentos.

• Situação completed. A operação de análise de lote foi concluída.

• Situação failed. A operação em lote falhou. Essa resposta geralmente ocorre se houver problemas gerais com a solicitação. Falhas em arquivos individuais são retornadas na resposta do relatório em lote, mesmo que todos os arquivos tenham falhado. Por exemplo, os erros de armazenamento não interrompem a operação em lote como um todo, para que você possa acessar resultados parciais por meio da resposta do relatório em lote.

Somente os arquivos que têm um succeeded status têm a propriedade resultUrl gerada na resposta. Isso permite que o treinamento de modelos detete nomes de arquivos que terminam com .ocr.json e os identifique como os únicos arquivos que podem ser usados para treinamento.

Exemplo de uma succeeded resposta de status:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

Exemplo de uma failed resposta de status:

• Este erro só é retornado se houver erros na solicitação de lote geral.
• Depois que a operação de análise em lote é iniciada, o status da operação de documento individual não afeta o status do trabalho em lote geral, mesmo que todos os arquivos tenham o status failed.

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

Exemplo de resposta de skipped status:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

Os resultados da análise em lote ajudam a identificar quais arquivos são analisados com êxito e validam os resultados da análise comparando o arquivo no resultUrl com o arquivo de saída no resultContainerUrl.

Próximos passos

Veja exemplos de código no GitHub.