Analyse par lots pour Intelligence documentaire (préversion)

Article
10/16/2024

Important

Les mises en production de préversion publique Document Intelligence fournissent un accès anticipé aux fonctionnalités en cours de développement actif. Les fonctionnalités, approches et processus peuvent changer, avant la disponibilité générale (GA), en fonction des commentaires des utilisateurs.
La préversion publique des bibliothèques de client Intelligence documentaire utilise par défaut la version 2024-07-31-preview de l’API REST.
La préversion publique 2024-07-31-preview est actuellement disponible uniquement dans les régions Azure suivantes. Notez que le modèle génératif personnalisé (extraction de champ de document) dans AI Studio est disponible uniquement dans la région USA Centre Nord :
- USA Est
- USA Ouest 2
- Europe Ouest
- USA Centre Nord

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 factures, une série de documents de prêt ou une multitude de documents d’entraînement de modèle personnalisé.

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.

Les modèles suivants prennent en charge l’analyse par lots :

Lecture : Extraction de lignes de texte, de mots, de langues détectées et du style manuscrit à partir de formulaires et de documents.
Disposition. Extraction du texte, de tables, de marques de sélection et d’informations structurelles à partir de formulaires et de documents.
Modèle personnalisé. Entraînement de modèles pour extraire des paires clé-valeur, des marques de sélection, des tables, des champs de signature et des régions à partir de formulaires structurés.
Neural personnalisé. Entraînement de modèles pour extraire des champs de données spécifiés à partir de documents structurés, semi-structurés et non structurés.
Générative personnalisée. Entraînement de modèles pour extraire des données spécifiées à partir d’objets complexes tels que des tables imbriquées, des champs abstractifs/génératifs et des formats réellement non structurés.

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.
Le paramètre azureBlobFileListSource peut être utilisé pour décomposer des requêtes plus volumineuses en requêtes plus petites.
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é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.
- Si vous utilisez le même conteneur, 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.

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

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.

Partage via