Analyse par lots pour Intelligence documentaire

Article
12/15/2024

L’API d’analyse par lots vous permet de traiter en bloc plusieurs documents à l’aide d’une requête asynchrone. Au lieu d’avoir à soumettre des documents individuellement et à suivre plusieurs ID de requête, vous pouvez analyser simultanément un ensemble de documents tels que des factures, une série de documents de prêt ou un lot de documents personnalisés. L’API de lots prend en charge la lecture des documents à partir du stockage Blob Azure et l’écriture des résultats dans le stockage d’objets blob.

Pour utiliser l’analyse par lots, vous avez besoin d’un compte de stockage Blob Azure avec des conteneurs spécifiques pour vos documents sources et les résultats traités.
Une fois l’opération terminée, le résultat de l’opération de traitement par lots répertorie tous les documents individuels traités avec leur état, par exemple succeeded, skippedou failed.
La préversion de l’API de traitement par lots est disponible en paiement à l’utilisation.

Instructions concernant l’analyse par lots

Le nombre maximal de documents pouvant être traités par requête d’analyse par lots (y compris les documents ignorés) est de 10 000.
Les résultats de l’opération sont conservés pendant 24 heures à l’issue de celle-ci. Les documents et les résultats se trouvent dans le compte de stockage fourni, mais l’état de l’opération n’est plus disponible 24 heures après la fin du traitement.

Prêt à vous lancer ?

Prérequis

Vous avez besoin d’un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, vous pouvez en créer un gratuitement.
Une fois que vous disposez de votre abonnement Azure, une instance Intelligence documentaire dans le portail Azure. Vous pouvez utiliser le niveau tarifaire gratuit (F0) pour tester le service.
Une fois votre ressource déployée, sélectionnez Accéder à la ressource et récupérez votre clé et votre point de terminaison.
- Vous avez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application au service d’Intelligence documentaire. Vous insérez votre clé et votre point de terminaison dans le code plus loin dans ce guide de démarrage rapide. Vous pouvez trouver ces valeurs dans la page Clés et point de terminaison du portail Azure.
Un compte de stockage Blob Azure. Vous devez créer des conteneurs dans votre compte de stockage blob Azure pour les fichiers sources et cible :
- Conteneur source. Ce conteneur est l’emplacement où vous importez vos fichiers pour l’analyse (obligatoire).
- Conteneur de résultats. Ce conteneur est l’emplacement où vos fichiers traités sont stockés (facultatif).

Vous pouvez désigner le même conteneur Stockage Blob Azure pour les documents sources et traités. Toutefois, pour réduire les risques potentiels de remplacer accidentellement les données, nous recommandons d’opter pour des conteneurs distincts.

Autorisation du conteneur de stockage

Vous pouvez choisir l’une des options suivantes pour autoriser l’accès à votre ressource Document.

✔️ Identité managée. Une identité managée est un principal de service qui crée une identité Microsoft Entra et des autorisations spécifiques pour une ressource managée Azure. Les identités managées vous permettent d’exécuter votre application Intelligence documentaire sans avoir à incorporer des informations de connexion dans votre code. Les identités managées sont un moyen plus sûr d’accorder l’accès aux données de stockage et remplacent la nécessité d’inclure des jetons de signature d’accès partagé (SAP) avec vos URL source et cible.

Pour en savoir plus, consultezIdentités managées pour l’Intelligence documentaire.

Capture d’écran du flux d’identité managée (contrôle d’accès en fonction du rôle).

Important

Lorsque vous utilisez des identités managées, n’incluez pas d’URL de jeton SAS avec vos requêtes HTTP, sinon vos requêtes échouent. L’utilisation d’identités managées remplace la nécessité d’inclure des jetons de signature d’accès partagé (SAP).

✔️ Signature d’accès partagé (SAP). Une signature d’accès partagé est une URL qui accorde un accès restreint pendant une durée spécifiée à votre service Intelligence documentaire. Pour utiliser cette méthode, vous devez créer des jetons de signature d’accès partagé (SAP) pour vos conteneurs source et cible. Les conteneurs source et cible doivent inclure un jeton de signature d’accès partagé (SAP), ajouté en tant que chaîne de requête. Le jeton peut être attribué à votre conteneur ou à des blobs spécifiques.

Capture d’écran de l’URI du stockage avec un jeton SAS ajouté.

Votre conteneur source ou objet blob doit désigner l’accès en lecture, écriture,liste et suppression.
Votre conteneur cible ou votre objet blob doit désigner l’accès en écriture, liste et suppression.

Pour en savoir plus, consultezCréer des jetons SAP.

Appel de l’API d’analyse par lots

Spécifiez l’URL du conteneur de Stockage Blob Azure pour votre jeu de documents source dans les objets azureBlobSource ou azureBlobFileListSource.

Spécifier les fichiers d’entrée

L’API de lots prend en charge deux options pour spécifier les fichiers à traiter. Si vous avez besoin de tous les fichiers d’un conteneur ou d’un dossier traité, et que le nombre de fichiers est inférieur à la limite de 10 000 pour une requête par lot unique, utilisez le conteneur azureBlobSource.

Si vous avez de fichiers spécifiques dans le conteneur ou le dossier à traiter ou si le nombre de fichiers à traiter dépasse la limite maximale d’un lot unique, utilisez azureBlobFileListSource. Fractionnez le jeu de données en plusieurs lots et ajoutez un fichier avec la liste des fichiers à traiter dans un format JSONL dans le dossier racine du conteneur. Voici un exemple de format de liste de fichiers.

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

Spécifier l’emplacement des résultats

Spécifiez l’URL du conteneur de Stockage Blob Azure pour vos résultats d’analyse par lots en utilisant resultContainerUrl. Pour éviter le remplacement accidentel, nous recommandons d’utiliser des conteneurs distincts pour les documents sources et traités.

Définissez la propriété booléenne overwriteExisting sur « false » si vous ne souhaitez pas que les résultats présentant le même nom de fichiers soient remplacés. Ce paramètre n’affecte pas la facturation et empêche uniquement le remplacement des résultats après le traitement du fichier d’entrée.

Définissez resultPrefix sur l’espace de noms des résultats de cette exécution de l’API de lots.

Si vous envisagez d’utiliser le même conteneur pour l’entrée et la sortie, définissez resultContainerUrl et resultPrefix pour qu’ils correspondent à votre entrée azureBlobSource.
Lorsque vous utilisez le même conteneur, vous pouvez inclure le champ overwriteExisting pour décider s’il faut remplacer des fichiers par les fichiers cible d’analyse.

Générer et exécuter la requête POST

Avant d’exécuter la requête POST, remplacez {your-source-container-SAS-URL} et {your-result-container-SAS-URL} par les valeurs de vos instances de conteneur de Stockage Blob Azure.

L’exemple suivant montre comment ajouter la propriété azureBlobSource à la requête :

Autorisez une seule possibilité azureBlobSource ou 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
}

L’exemple suivant montre comment ajouter la propriété azureBlobFileListSource à la requête :

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
}

Réponse correcte

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

Récupérez les résultats de l’API d’analyse par lots

Une fois l’opération de l’’API de traitement par lots terminée, vous pouvez récupérer les résultats d’analyse par lots au moyen de l’opérationGET. Cette opération extrait les informations d’état de l’opération, le pourcentage d’avancement de l’opération et la date et l’heure de création et de mise à jour d’opérations.

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"
...
}

Interprétation des messages d’état

Pour chaque ensemble de documents, un état est attribué, soit succeeded, failedou skipped. Pour chaque document, il existe deux URL fournies pour valider les résultats : sourceUrl, qui est le conteneur source de Stockage Blob pour votre document d’entrée réussie, et resultUrl, qui est le fruit de l’association entre resultContainerUrl etcresultPrefixpour créer le chemin d’accès relatif pour le fichier source et .ocr.json.

État notStarted ou running. L’opération d’analyse par lots n’est pas lancée ou n’est pas terminée. Attendez que l’opération soit terminée pour tous les documents.
État completed. L’opération d’analyse par lots est terminée.
État failed. Échec de l’opération de traitement par lots. Cette réponse apparaît généralement si la demande génère des problèmes généraux. Les échecs sur les fichiers individuels sont signalés dans la réponse au rapport de traitement par lots, même si l’échec concerne tous les fichiers. Par exemple, les erreurs de stockage n’arrêtent pas l’opération de traitement par lots dans son ensemble, afin que vous puissiez accéder à des résultats partiels via la réponse au rapport de traitement par lots.

Seuls les fichiers dont l’état est succeeded présentent la propriété resultUrl dans la réponse. Cela permet à l’entraînement du modèle de détecter les noms de fichiers qui se terminent par .ocr.json et de les identifier comme seuls fichiers pouvant être utilisés pour l’entraînement.

Exemple de réponse d’état succeeded :

[
  "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}"
                   }
               }
          }
      ]
   }
]
...

Exemple de réponse d’état failed :

Cette erreur n’est signalée que s’il existe des erreurs dans la requête générale par lots.
Une fois l’opération d’analyse par lots lancée, l’état de l’opération d’un document individuel n’affecte pas l’état du traitement général par lots, même si tous les fichiers ont l’état 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}"
                }
            }
        ]
    }
]
...

Exemple de réponse d’état skipped :

[
    "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."
             }
        ]
    }
]
...

Les résultats d’analyse par lots vous aident à identifier les fichiers qui sont correctement analysés et à valider les résultats de l’analyse en comparant le fichier dans resultUrl avec le fichier de sortie dans le resultContainerUrl.

Remarque

Les résultats de l’analyse ne sont pas mentionnés pour les fichiers individuels tant que l’analyse par lots de l’ensemble de documents n’est pas terminée. Pour suivre la progression détaillée au-delà de percentCompleted, vous pouvez surveiller les fichiers *.ocr.json au fur et à mesure qu’ils sont écrits dans le resultContainerUrl.

Étapes suivantes

Voir des exemples d’échantillon sur GitHub.

Partager via