Partager via

Prise en charge des documents natifs pour Azure AI Language (préversion)

  • Article

Important

  • La prise en charge des documents natifs est une préversion contrôlée. Pour demander un accès à la fonctionnalité de prise en charge des documents natifs, complétez et envoyez le formulaire Demande d’accès aux préversions du service Language.

  • Les publications de préversion publique d’Azure AI Language offrent un accès en avant-première aux fonctionnalités en cours de développement.

  • Les fonctionnalités, approches et processus peuvent changer, avant la disponibilité générale (GA), en fonction des commentaires des utilisateurs.

Azure AI Language est un service cloud qui applique des fonctionnalités de traitement du langage naturel (NLP, Natural Language Processing) aux données textuelles. La capacité de prise en charge des documents natifs vous permet d’envoyer des requêtes d’API de manière asynchrone en utilisant un corps de requête HTTP POST pour envoyer vos données et une chaîne de requête HTTP GET pour récupérer les résultats d’état. Vos documents traités se trouvent dans votre conteneur cible Stockage Blob Azure.

Un document natif fait référence au format de fichier utilisé pour créer le document d’origine tel que Microsoft Word (docx) ou un format de document portable (pdf). La prise en charge des documents natifs évite de prétraiter le texte avant d’utiliser les fonctionnalités des ressources Azure AI Language. Actuellement, la prise en charge des documents natifs est disponible pour les fonctionnalités suivantes :

  • Informations d’identification personnelle (PII). La fonctionnalité de détection des informations d’identification personnelle permet d’identifier, de catégoriser et de rédiger des informations sensibles dans du texte non structuré. L’API PiiEntityRecognition prend en charge le traitement des documents natifs.

  • Résumé des documents. Le résumé des documents utilise le traitement du langage naturel pour générer des résumés extractifs (extraction de phrases clés) ou abstractifs (extraction de mots contextuels) de documents. Les API AbstractiveSummarization et ExtractiveSummarization prennent en charge le traitement des documents natifs.

Formats de document pris en charge

Les applications utilisent des formats de fichiers natifs pour créer, enregistrer ou ouvrir des documents natifs. Actuellement, les fonctionnalités Informations d’identification personnelle et Résumé des documents prennent en charge les formats de document natifs suivants :

Type de fichier Extension de fichier Description
Texte .txt Document texte non mis en forme.
Adobe PDF .pdf Document au format de fichier de document portable.
Microsoft Word .docx Document Microsoft Word.

Recommandations concernant les entrées

Formats de fichiers pris en charge

Type prise en charge et limitations
Fichiers PDF Les fichiers PDF entièrement analysés ne sont pas pris en charge.
Texte dans les images Les images numériques avec du texte incorporé ne sont pas prises en charge.
Tableaux numériques Les tableaux dans les documents analysés ne sont pas pris en charge.

Taille des documents

Attribut Limite d’entrée
Nombre total de documents par requête ≤ 20
Taille totale du contenu par requête ≤ 1 Mo

Inclure des documents natifs avec une requête HTTP

Commençons :

  • Pour ce projet, nous utilisons l’outil en ligne de commande cURL pour effectuer des appels d’API REST.

    Remarque

    Le package cURL est préinstallé sur la plupart des systèmes Windows 10 et Windows 11 et sur la plupart des distributions macOS et Linux. Vous pouvez vérifier la version du package avec les commandes suivantes : Windows : curl.exe -V macOS curl -V Linux : curl --version

  • Si cURL n’est pas installé, voici les liens d’installation pour votre plateforme :

  • Un compte Azure actif. Si vous n’en avez pas, vous pouvez créer un compte gratuit.

  • Un compte de stockage Blob Azure. Vous devez également créer des conteneurs dans votre compte de stockage Blob Azure pour vos fichiers sources et cibles :

    • Conteneur source. Ce conteneur est l’emplacement où vous chargez vos fichiers natifs pour l’analyse (obligatoire).
    • Conteneur cible. Ce conteneur est l’emplacement où vos fichiers analysés sont stockés (obligatoire).

  • Une ressource Language monoservice (pas une ressource Azure AI services multiservice) :

    Complétez les champs des détails du projet de ressource Language et de l’instance comme suit :

    1. Abonnement. Sélectionnez l’un de vos abonnements Azure disponibles.

    2. Groupe de ressources. Vous pouvez créer un groupe de ressources ou ajouter votre ressource à un groupe de ressources préexistant qui partage le même cycle de vie, les mêmes autorisations et les mêmes stratégies.

    3. Région de la ressource. Choisissez Globale, sauf si votre entreprise ou votre application nécessite une région spécifique. Si vous envisagez d’utiliser une identité managée affectée par le système (RBAC) pour l’authentification, choisissez une région géographique telle que USA Ouest.

    4. Nom. Entrez le nom choisi pour votre ressource. Le nom choisi doit être unique dans Azure.

    5. Niveau tarifaire. Vous pouvez utiliser le niveau tarifaire Gratuit (Free F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

    6. Sélectionnez Vérifier + créer.

    7. Passez en revue les conditions du service, puis sélectionnez Créer pour déployer votre ressource.

    8. Une fois votre ressource correctement déployée, sélectionnez Accéder à la ressource.

Récupérer votre clé et votre point de terminaison de service de langage

Les demandes adressées au service Language nécessitent une clé en lecture seule et un point de terminaison personnalisé pour authentifier l’accès.

  1. Si vous avez créé une ressource, après son déploiement, sélectionnez Accéder à la ressource. Si vous disposez déjà d’une ressource de service de langage, accédez directement à la page de votre ressource.

  2. Dans le rail de gauche, sous Gestion des ressources, sélectionnez Clés et point de terminaison.

  3. Vous pouvez copier et coller vos key et language service instance endpoint dans les exemples de code pour authentifier votre requête auprès du service Language. Une seule clé est nécessaire pour effectuer un appel d’API.

Créer des conteneurs de stockage d’objets blob Azure

Créez des conteneurs dans votre compte Stockage Blob Azure pour les fichiers sources et cibles.

  • Conteneur source. Ce conteneur est l’emplacement où vous chargez vos fichiers natifs pour l’analyse (obligatoire).
  • Conteneur cible. Ce conteneur est l’emplacement où vos fichiers analysés sont stockés (obligatoire).

Authentification

Votre ressource Language doit recevoir un accès à votre compte de stockage avant de pouvoir créer, lire ou supprimer des blobs. Il existe deux méthodes principales que vous pouvez utiliser pour accorder l’accès à vos données de stockage :

Pour ce projet, nous authentifions l’accès aux URL source location et target location avec des jetons SAS (Shared Access Signature) ajoutés en tant que chaînes de requête. Chaque jeton est affecté à un blob spécifique (fichier).

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

  • Votre blob ou conteneur source doit désigner un accès lecture et liste.
  • Votre blob ou conteneur cible doit désigner un accès écriture et liste.

Conseil

Étant donné que nous traitons un seul fichier (blob), nous vous recommandons de déléguer l’accès SAS au niveau du blob.

En-têtes et paramètres de requête

parameter Description
-X POST <endpoint> Spécifie le point de terminaison de votre ressource Language pour accéder à l’API.
--header Content-Type: application/json Type de contenu pour l’envoi de données JSON.
--header "Ocp-Apim-Subscription-Key:<key> Spécifie la clé de ressource Language pour accéder à l’API.
-data Fichier JSON contenant les données que vous souhaitez transmettre avec votre requête.

Les commandes cURL suivantes sont exécutées à partir d’un interpréteur de commandes bash. Modifiez ces commandes avec vos propres nom de ressource, clé de ressource et valeurs JSON. Essayez d’analyser des documents natifs en sélectionnant l’exemple de projet de code Personally Identifiable Information (PII) ou Document Summarization :

Exemple de document d’informations d’identification personnelle

Pour ce guide de démarrage rapide, vous avez besoin d’un document source chargé dans votre conteneur source. Vous pouvez télécharger notre exemple de document Microsoft Word ou Adobe PDF pour ce projet. La langue source est l’anglais.

Créer la requête POST

  1. À l’aide de votre éditeur ou IDE préféré, créez un répertoire nommé native-document pour votre application.

  2. Créez un fichier json appelé pii-detection.json dans votre répertoire native-document.

  3. Copiez et collez l’exemple de requête d’informations d’identification personnelle dans votre fichier pii-detection.json. Remplacez {your-source-container-SAS-URL} et {your-target-container-SAS-URL} par les valeurs de votre instance de conteneurs de compte de stockage du portail Azure :

Exemple de requête

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • La valeur location source est l’URL SAP du document source (blob), et non l’URL SAP du conteneur source.

  • Les valeurs redactionPolicy possibles sont UseRedactionCharacterWithRefId (valeur par défaut) ou UseEntityTypeName. Pour plus d’informations, consultez Paramètres PiiTask.

Exécuter la requête POST

  1. Voici la structure préliminaire de la requête POST :

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

  2. Avant d’exécuter la requête POST, remplacez {your-language-resource-endpoint} et {your-key} par les valeurs de votre instance de service Language du portail Azure.

    Important

    N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Si vous souhaitez en savoir plus, veuillez consulter la rubriqueSécurité Azure AI services.

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    invite de commandes/terminal

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. Voici un exemple de réponse :

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

Réponse POST (jobId)

Vous recevez une réponse 202 (Réussite) incluant un en-tête en lecture seule Operation-Location. La valeur de cet en-tête contient un jobId qui peut être interrogé pour obtenir l’état de l’opération asynchrone et récupérer les résultats à l’aide d’une requête GET :

Capture d’écran montrant la valeur d’emplacement de l’opération dans la réponse POST.

Obtenir les résultats d’analyse (requête GET)

  1. Une fois que votre requête POST a réussi, interrogez l’en-tête operation-location retourné dans la requête POST pour afficher les données traitées.

  2. Voici la structure préliminaire de la requête GET :

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

  3. Avant d’exécuter la commande, apportez les modifications suivantes :

    • Remplacez {jobId} par l’en-tête Operation-Location de la réponse POST.

    • Remplacez {your-language-resource-endpoint} et {your-key} par les valeurs de votre instance de service Language dans le portail Azure.

Requête GET

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Examiner la réponse

Vous recevez une réponse 200 (Réussite) avec une sortie JSON. Le champ status indique le résultat de l’opération. Si l’opération n’est pas terminée, la valeur de status est « running » ou « notStarted ». Vous devrez alors appeler l’API une nouvelle fois, manuellement ou via un script. Nous vous recommandons d’attendre une seconde ou plus entre chaque appel.

Exemple de réponse

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

Après la réussite de l’opération :

  • Vous trouverez les documents analysés dans votre conteneur cible.
  • La méthode POST réussie retourne un code de réponse 202 Accepted indiquant que la requête de lots a été créée par le service.
  • La requête POST a retourné également des en-têtes de réponse, notamment Operation-Location qui fournit une valeur utilisée dans les requêtes GET suivantes.

Nettoyer les ressources

Si vous souhaitez nettoyer et supprimer un abonnement Azure AI services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Étapes suivantes

Vue d’ensemble de la détection des informations d’identification personnelle Vue d’ensemble du résumé des documents