Analyse par lots pour Intelligence documentaire
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
,skipped
oufailed
. - 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.
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.
- 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
ouazureBlobFileListSource
.
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
etresultPrefix
pour qu’ils correspondent à votre entréeazureBlobSource
. - 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
, failed
ou 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
etcresultPrefix
pour créer le chemin d’accès relatif pour le fichier source et .ocr.json
.
État
notStarted
ourunning
. 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
.