Partilhar via

Análise de lote de Document Intelligence

  • Artigo

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 documentos, como faturas, uma série de documentos de empréstimo ou um grupo de documentos personalizados simultaneamente. A API em lote dá suporte à leitura dos documentos do armazenamento de blob do Azure e à gravação dos resultados no armazenamento de blobs.

  • 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.

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.

  • 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.

Captura de tela do fluxo de identidade gerenciado (controle de acesso baseado em função).

Importante

  • Ao usar identidades gerenciadas, não inclua uma URL de token SAS com suas solicitações HTTP — suas solicitações falharão. O uso de identidades gerenciadas substitui o requisito de incluir tokens de assinatura de acesso compartilhado (SAS).

✔️ 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.

Captura de tela do URI de armazenamento com o token SAS anexado.

  • 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 .

Especificar os arquivos de entrada

A API em lote suporta duas opções para especificar os arquivos a serem processados. Se você precisar de todos os arquivos em um contêiner ou pasta processada e o número de arquivos for inferior ao limite de 10000 para uma única solicitação de lote, use o azureBlobSource contêiner.

Se você tiver arquivos específicos no contêiner ou pasta para processar ou se o número de arquivos a serem processados estiver acima do limite máximo para um único lote, use o azureBlobFileListSource. Divida o conjunto de dados em vários lotes e adicione um arquivo com a lista de arquivos a serem processados em um formato JSONL na pasta raiz do contêiner. Um exemplo do formato de lista de arquivos é.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Especificar a localização dos resultados

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.

Defina a overwriteExisting propriedade boolean como false se não quiser nenhum resultado existente com os mesmos nomes de arquivo substituídos. Essa configuração não afeta o faturamento e só impede que os resultados sejam substituídos depois que o arquivo de entrada é processado.

Defina o resultPrefix namespace to os resultados dessa execução da API em lote.

  • Se você planeja usar o mesmo contêiner para entrada e saída, 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.

O exemplo a seguir mostra como adicionar a azureBlobSource propriedade à solicitação:

Permitir apenas um ou azureBlobSource azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

O exemplo a seguir mostra como adicionar a azureBlobFileListSource propriedade à solicitação:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

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.

Nota

Os resultados da análise não são retornados para arquivos individuais até que toda a análise em lote do conjunto de documentos seja concluída. Para acompanhar o progresso detalhado além percentCompleteddo , você pode monitorar *.ocr.json os arquivos à medida que são gravados no resultContainerUrl.

Próximos passos

Veja exemplos de código no GitHub.