Partilhar via

Análise de lote de Document Intelligence

A API de análise em lote permite processar em massa até 10.000 documentos usando uma solicitação. Em vez de analisar documentos um a um e manter o controle de seus respetivos IDs de solicitação, você pode analisar simultaneamente uma coleção de documentos, como faturas, papéis de empréstimo ou documentos personalizados. Os documentos de entrada devem ser armazenados em um contêiner de armazenamento de blob do Azure. Depois que os documentos são processados, a API grava os resultados em um contêiner de armazenamento especificado.

Limites de análise de lote

  • O número máximo de arquivos de documentos que podem estar em uma única solicitação de lote é 10.000.
  • Os resultados da operação em lote são retidos por 24 horas após a conclusão. O status da operação em lote não está mais disponível 24 horas após a conclusão do processamento em lote. Os documentos de entrada e respetivos arquivos de resultados permanecem nos contêineres de armazenamento fornecidos.

Pré-requisitos

  • Uma assinatura ativa do Azure. Se não tiver uma subscrição do Azure, pode criar uma gratuitamente.

  • Um Recurso do Azure de Inteligência Documental: depois de ter sua assinatura do Azure, crie um recurso de Inteligência de Documentos 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" para recuperar a chave e o ponto de extremidade. Você precisa da chave de recurso e do ponto de extremidade para conectar seu aplicativo ao serviço de Inteligência Documental. Você também pode encontrar esses valores na página Chaves e Ponto de Extremidade no portal do Azure.

  • Uma conta de Armazenamento de Blob do Azure. Crie dois contêineres em sua conta de Armazenamento de Blob do Azure para seus arquivos de origem e de resultado:

    • Contêiner de origem: esse contêiner é onde você carrega arquivos de documentos para análise.
    • Recipiente de resultados: este contêiner é onde os resultados da API de análise de lote são armazenados.

Autorização de contêiner de armazenamento

Para permitir que a API processe documentos e escreva resultados em seus contêineres de armazenamento do Azure, você deve autorizar usando uma das duas opções a seguir:

✔️ 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, uma maneira mais segura de conceder acesso a dados de armazenamento sem incluir tokens de assinatura de acesso (SAS) em seu código.

Analise Identidades gerenciadas para Document Intelligence para saber como habilitar uma identidade gerenciada para seu recurso e conceder-lhe acesso ao contêiner de armazenamento.

Importante

Ao usar identidades gerenciadas, não inclua uma URL de token SAS com suas solicitações HTTP. 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 ao seu contêiner de armazenamento. Para usar esse método, crie tokens SAS (Assinatura de Acesso Compartilhado) para seus contêineres de origem e resultado. Vá para o contêiner de armazenamento no portal do Azure e selecione "Tokens de acesso compartilhado" para gerar token SAS e URL.

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

Captura de ecrã que mostra os campos de permissão SAS no portal do Azure.

Consulte Criar tokens SAS para saber mais sobre como gerar tokens SAS e como eles funcionam.

Chamar a API de análise de lote

1. Especifique os arquivos de entrada

A API em lote suporta duas opções para especificar os arquivos a serem processados.

  • Se você quiser processar todos os arquivos em um contêiner ou uma pasta, e o número de arquivos for inferior ao limite de 10000, use o azureBlobSource objeto em sua solicitação.

    POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"

},
{
   "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
   "resultPrefix": "trainingDocsResult/"
}

  • Se você não quiser processar todos os arquivos em um contêiner ou pasta, mas sim arquivos específicos nesse contêiner ou pasta, use o azureBlobFileListSource objeto. Esta operação requer um arquivo JSONL de lista de arquivos que lista os arquivos a serem processados. Armazene o arquivo JSONL na pasta raiz do contêiner. Aqui está um exemplo de arquivo JSONL com dois arquivos listados:

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

Use um arquivo de lista JSONL de arquivos com as seguintes condições:

  • Quando você precisa processar arquivos específicos em vez de todos os arquivos em um contêiner;
  • Quando o número total de arquivos no contêiner ou pasta de entrada exceder o limite de processamento em lote de 10.000 arquivos;
  • Quando você quer mais controle sobre quais arquivos são processados em cada solicitação de lote;
POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

Uma URL de contêiner ou uma URL SAS de contêiner é necessária em ambas as opções. Use a URL do contêiner se estiver usando a Identidade gerenciada para acessar seu contêiner de armazenamento. Se estiver a utilizar a Assinatura de Acesso Partilhado (SAS), utilize um URL SAS.

2. Especifique a localização dos resultados

  • Especifique a URL do contêiner do Armazenamento de Blobs do Azure (ou URL SAS do contêiner) para onde você deseja que seus resultados sejam armazenados usando resultContainerURL o parâmetro. Recomendamos o uso de contêineres separados para origem e resultados para evitar substituições acidentais.

  • Defina a overwriteExisting propriedade Boolean como False e impeça a substituição de quaisquer resultados existentes para o mesmo documento. Se você quiser substituir quaisquer resultados existentes, defina o Boolean como True. Você ainda será cobrado pelo processamento do documento, mesmo que os resultados existentes não sejam substituídos.

  • Use resultPrefix para agrupar e armazenar resultados em uma pasta de contêiner específica.

3. Crie e execute a solicitação POST

Lembre-se de substituir os seguintes valores de URL de contêiner de exemplo por valores reais de seus contêineres de armazenamento de Blob do Azure.

Este exemplo mostra uma solicitação POST com azureBlobSource entrada

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

Este exemplo mostra uma solicitação POST com azureBlobFileListSource e uma entrada de lista de arquivos

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

Aqui está um exemplo de resposta bem-sucedida :

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. Recuperar resultados da API

Use a GET operação para recuperar os resultados da análise em lote depois que a operação POST for executada. A operação GET busca informações de status, porcentagem de conclusão do lote e criação da operação e data/hora de atualização. Esta informação só é retida durante 24 horas após a conclusão da análise do lote.

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
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"
...
}

5. Interpretar mensagens de status

Para cada documento processado, um status é atribuído, seja succeeded, failed, running, notStarted, ou skipped. Uma URL de origem, que é o contêiner de armazenamento de blob de origem para o documento de entrada, é fornecida.

  • 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 succeeded. A operação em lote foi bem-sucedida e o documento de entrada foi processado. Os resultados estão disponíveis em resultUrl, que é criado pela combinação resultContainerUrlde , resultPrefix, input filename, e .ocr.json extensão. Somente os arquivos que foram bem-sucedidos têm a propriedade resultUrl.

    Exemplo de uma succeeded resposta de status:

    {
    "resultId": "myresultId-",
    "status": "succeeded",
    "percentCompleted": 100,
    "createdDateTime": "2025-01-01T00:00:000",
    "lastUpdatedDateTime": "2025-01-01T00:00:000",
    "result": {
        "succeededCount": 10,000,
        "failedCount": 0,
        "skippedCount": 0,
        "details": [
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                "status": "succeeded"
            },
          ...
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                "status": "succeeded"
            }
       ]

     }
}

  • Situação failed. 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.

    Exemplo de uma failed resposta de status:

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

  • Status skipped: Normalmente, esse status acontece quando a saída do documento já está presente na pasta de saída especificada e a overwriteExisting propriedade Boolean está definida como false.

    Exemplo de resposta de skipped status:

    [
     "result": {
     "succeededCount": 3,
     "failedCount": 0,
     "skippedCount": 2,
     "details": [
         ...
         "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
         "status": "skipped",
         "error": {
             "code": "OutputExists",
             "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
              }
         ]
     }
]
...

    Nota

    Os resultados da análise não são retornados para arquivos individuais até que a análise de todo o lote 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.

  • Last updated on