Tutoriel : Indexer et enrichir des objets blob chiffrés pour la recherche en texte intégral dans Azure AI Recherche

Article
05/23/2024

Ce tutoriel vous montre comment utiliser Azure AI Recherche pour indexer des documents qui ont été précédemment chiffrés avec une clé gérée par le client dans Stockage Blob Azure.

Normalement, un indexeur ne peut pas extraire le contenu des objets blob qui ont été chiffrés à l’aide du chiffrement côté client de la bibliothèque cliente Stockage Blob Azure, car l’indexeur n’a pas accès à la clé de chiffrement gérée par le client dans Azure Key Vault. Cependant, en tirant parti de la compétence personnalisée DecryptBlobFile suivie de la compétence Document Extraction, vous pouvez fournir un accès contrôlé à la clé pour déchiffrer les fichiers, puis en extraire le contenu. Cela permet l’indexation et l’enrichissement de ces documents sans compromettre le statut de chiffrement de vos documents stockés.

En commençant avec des documents entiers précédemment chiffrés (du texte non structuré) à des formats tels que PDF, HTML, DOCX et PPTX dans Stockage Blob Azure, ce tutoriel utilise un client REST et les API REST de recherche pour effectuer les tâches suivantes :

Définissez un pipeline qui déchiffre les documents et en extrait le texte.
Définissez un index pour stocker la sortie.
Exécutez le pipeline pour créer et charger l’index.
Explorez les résultats à l’aide de la recherche en texte intégral et d’une syntaxe de requête enrichie.

Si vous n’avez pas d’abonnement Azure, ouvrez un compte gratuit avant de commencer.

Prérequis

Azure AI Recherche sur n’importe quel niveau ou région.
Stockage Azure, niveau de performance Standard (v2 universel)
Objets blob chiffrés avec une clé gérée par le client. Consultez Tutoriel : Chiffrer et déchiffrer des objets blob avec Azure Key Vault si vous avez besoin de créer des exemples de données.
Azure Key Vault dans le même abonnement qu’Azure AI Recherche. La suppression réversible et la protection contre le vidage doivent été activées pour le coffre de clés.

Le déploiement de compétences personnalisées crée une application de fonction Azure et un compte Stockage Azure. Étant donné que ces ressources sont créées pour vous, elles ne sont pas répertoriées comme condition préalable. Lorsque vous avez terminé ce didacticiel, n’oubliez pas de nettoyer les ressources afin de ne pas être facturé pour les services que vous n’utilisez pas.

Notes

Les ensembles de compétences nécessitent souvent l’attachement d’une ressource multiservice Azure AI. Comme indiqué, ces compétences n’ont aucune dépendance vis-à-vis d’Azure AI services et donc aucune clé n’est requise. Si, par la suite, vous ajoutez des enrichissements qui appellent des compétences intégrées, n’oubliez pas de mettre à jour vos compétences en conséquence.

1 - Créer des services et collecter les informations d'identification

Déployer la compétence personnalisée

Cet exemple utilise l'exemple de projet DecryptBlobFile du référentiel GitHub Super compétences de la Recherche Azure. Dans cette section, vous allez déployer la compétence sur une instance d'Azure Function afin qu'elle puisse être utilisée dans un ensemble de compétences. Un script de déploiement intégré crée une ressource Azure Function nommée avec le préfixe psdbf-function-app- et charge la compétence. Vous êtes ensuite invité à fournir un abonnement et un groupe de ressources. Veillez à choisir le même abonnement que celui auquel votre instance d'Azure Key Vault est associée.

De manière opérationnelle, la compétence DecryptBlobFile accepte l’URL et le jeton SAS pour chaque objet blob en tant qu’entrées, et génère le fichier téléchargé et déchiffré à l’aide du contrat de référence de fichier attendu par Azure AI Recherche. Pour rappel, DecryptBlobFile a besoin de la clé de chiffrement afin de procéder au déchiffrement. Dans le cadre de la configuration, vous allez également créer une stratégie d'accès qui accorde à la fonction DecryptBlobFile l'accès à la clé de chiffrement dans Azure Key Vault.

Cliquez sur le bouton Déployer sur Azure situé sur la page de destination de DecryptBlobFile pour ouvrir le modèle Resource Manager fourni sur le portail Azure.
Choisissez le même abonnement que celui où se trouve votre instance Azure Key Vault (ce didacticiel ne fonctionne pas si vous sélectionnez un autre abonnement).
Sélectionnez un groupe de ressources existant ou créez-en un. Un groupe de ressources dédié facilite le nettoyage ultérieurement.
Sélectionnez Vérifier + créer, acceptez les conditions, puis sélectionnez Créer pour déployer l'instance d'Azure Function.
Attendez que le déploiement se termine.

Vous devez disposer d’une application de fonction Azure qui contient la logique de déchiffrement et d’une ressource Stockage Azure qui stocke les données d’application. Dans les étapes suivantes, vous allez accorder à l’application des autorisations d’accès au coffre de clés et collecter les informations dont vous avez besoin pour les appels REST.

Accorder des autorisations dans Azure Key Vault

Accédez à votre service Azure Key Vault dans le portail. Dans Azure Key Vault, créez une stratégie d'accès qui accorde un accès à la clé de la compétence personnalisée.
Dans le volet de navigation gauche, sélectionnez Stratégies d’accès, puis sélectionnez + Créer pour démarrer l’Assistant Créer une stratégie d’accès.
Sur la page Autorisations, sous Configurer à partir du modèle, sélectionnez Azure Data Lake Storage ou Stockage Azure.
Sélectionnez Suivant.
Sur la page Principal, sélectionnez l’instance de fonction Azure que vous avez déployée. Vous pouvez la rechercher à l'aide du préfixe de ressource utilisé pour la créer à l'étape 2. La valeur par défaut du préfixe est psdbf-function-app.
Sélectionnez Suivant.
Dans Vérifier + créer, sélectionnez Créer.

Collecter les informations sur l’application

Sur le portail, accédez à la fonction psdbf-function-app et notez les propriétés suivantes dont vous avez besoin pour les appels REST :
Obtenez l’URL de la fonction, qui se trouve sous Essentials sur la page principale de la fonction.
Obtenez le code de la clé hôte, que vous pourrez vous procurer en accédant à Clés d'application, en cliquant pour afficher la clé par défaut et en copiant la valeur.

Obtenir une clé API d’administration et une URL pour Azure AI Recherche

Connectez-vous au Portail Azure, puis dans la page Vue d’ensemble du service de recherche, récupérez le nom de votre service de recherche. Vous pouvez confirmer le nom de votre service en passant en revue l’URL du point de terminaison. Si votre URL de point de terminaison est https://mydemo.search.windows.net, le nom du service doit être mydemo.
Dans Paramètres>Clés, obtenez une clé d’administration pour avoir des droits d’accès complets sur le service. Il existe deux clés d’administration interchangeables, fournies pour assurer la continuité de l’activité au cas où vous deviez en remplacer une. Vous pouvez utiliser la clé primaire ou secondaire sur les demandes d’ajout, de modification et de suppression d’objets.

Une clé API est nécessaire dans l’en-tête de chaque requête envoyée à votre service. Une clé valide permet d’établir, en fonction de chaque demande, une relation de confiance entre l’application qui envoie la demande et le service qui en assure le traitement.

Configurer un client REST

Créez des variables pour les points de terminaison et les clés :

Variable	Comment les obtenir
`admin-key`	Dans la page Clés du service Azure AI Recherche.
`search-service-name`	Nom du service Azure AI Recherche. L’URL est `https://{{search-service-name}}.search.windows.net`.
`storage-connection-string`	Dans le compte de stockage, sous l’onglet Clés d’accès, sélectionnez key1>Chaîne de connexion.
`storage-container-name`	Nom du conteneur d'objets blob qui contient les fichiers chiffrés à indexer.
`function-uri`	Dans Azure Function, sous Essentials sur la page principale.
`function-code`	Dans Azure Function, en accédant à Clés d'application, en cliquant pour afficher la clé par défaut et en copiant la valeur.
`api-version`	Laisser 2020-06-30.
`datasource-name`	Laisser encrypted-blobs-ds.
`index-name`	Laisser encrypted-blobs-idx.
`skillset-name`	Laisser encrypted-blobs-ss.
`indexer-name`	Laisser encrypted-blobs-ixr.

Examiner et exécuter chaque requête

Utilisez des requêtes HTTP pour créer les objets d’un pipeline d’enrichissement :

Demande PUT pour créer l’index : cet index de recherche contient les données qu’Azure AI Recherche utilise et retourne.
Une requête POST pour créer la source de données : cette source de données spécifie la connexion à votre compte de stockage contenant les fichiers d’objets blob chiffrés.
Une requête PUT pour créer l’ensemble de compétences : L'ensemble de compétences spécifie la définition de compétence personnalisée relative à l'instance d'Azure Function qui déchiffrera les données des fichiers blob, et une fonction DocumentExtractionSkill pour extraire le texte de chaque document une fois celui-ci déchiffré.
Une requête PUT pour créer l’indexeur : l’exécution de l’indexeur récupère les objets blob, applique les compétences et les index et stocke les résultats. Vous devez exécuter cette requête en dernier. La compétence personnalisée dans les compétences appelle la logique de déchiffrement.

Surveiller l’indexation

L’indexation et l’enrichissement commencent dès que vous envoyez la demande de création d’indexeur. Selon le nombre de documents présents sur votre compte de stockage, l'indexation peut prendre un certain temps. Pour savoir si l’indexeur est toujours en cours d’exécution, envoyez une requête Get Indexer Status, puis examinez la réponse pour savoir si l’indexeur est en cours d’exécution, ou pour voir les erreurs et les avertissements.

Si vous utilisez le niveau Gratuit, le message suivant doit s'afficher : "Could not extract content or metadata from your document. Truncated extracted text to '32768' characters". Ce message s'affiche car l'indexation d'objets blob au niveau Gratuit présente une limite d'extraction de caractères de 32 000. Vous ne verrez pas ce message pour ce jeu de données sur des niveaux supérieurs.

Rechercher dans votre contenu

Au terme de l'exécution de l'indexeur, vous pouvez lancer quelques requêtes pour vérifier que les données ont été correctement déchiffrées et indexées. Accédez à votre service Azure AI Recherche dans le portail et utilisez l’explorateur de recherche pour exécuter des requêtes sur les données indexées.

Nettoyer les ressources

Lorsque vous travaillez dans votre propre abonnement, il est judicieux à la fin d’un projet de supprimer les ressources dont vous n’avez plus besoin. Les ressources laissées en cours d’exécution peuvent vous coûter de l’argent. Vous pouvez supprimer les ressources une par une, ou choisir de supprimer le groupe de ressources afin de supprimer l’ensemble des ressources.

Vous pouvez rechercher et gérer les ressources dans le portail à l’aide des liens Toutes les ressources ou Groupes de ressources situés dans le volet de navigation de gauche.

Étapes suivantes

Maintenant que vous avez correctement indexé les fichiers chiffrés, vous pouvez effectuer une itération sur ce pipeline en ajoutant des compétences cognitives. Cela vous permettra d'enrichir vos données et de bénéficier d'insights supplémentaires sur celles-ci.

Si vous utilisez des données doublement chiffrées, vous souhaiterez peut-être examiner les fonctionnalités de chiffrement d’index disponibles dans Azure AI Recherche. Bien que l'indexeur ait besoin de données déchiffrées pour l'indexation, une fois que l'index existe, il peut être chiffré dans un index de recherche à l'aide d'une clé gérée par le client. Ainsi, vos données seront toujours chiffrées lorsqu'elles sont au repos. Pour plus d’informations, consultez Configurer des clés gérées par le client pour le chiffrement des données dans Azure AI Recherche.

Partager via