Déboguer un ensemble de compétences Recherche Azure AI dans le Portail Microsoft Azure

Article
01/12/2024

Démarrez une session de débogage basée sur le portail pour identifier et résoudre les erreurs, valider les modifications et transmettre les modifications à un ensemble de compétences publié dans votre service Recherche Azure AI.

Une session de débogage est une exécution de l’indexeur et de l’ensemble de compétences en mémoire cache, étendue à un seul document, que vous pouvez utiliser pour modifier et tester vos modifications de manière interactive. Une fois le débogage terminé, vous pouvez enregistrer vos modifications apportées à l'ensemble de compétences.

Pour obtenir des informations générales sur le fonctionnement d’une session de débogage, consultez Sessions de débogage dans Azure AI Search. Pour vous entraîner à utiliser un flux de travail de débogage avec un exemple de document, consultez Tutoriel : Sessions de débogage.

Prérequis

Un pipeline d’enrichissement existant, y compris une source de données, des compétences, un indexeur et un index.
Une attribution de rôle Contributeur dans le service de recherche.
Un compte Stockage Azure, utilisé pour sauvegarder l’état de la session.
Une attribution de rôle de contributeur de données Blob de stockage dans Stockage Microsoft Azure si vous utilisez une identité managée par le système. Sinon, prévoyez d'utiliser une chaîne de connexion à accès complet pour la connexion de la session de débogage au stockage Azure.
Si le compte Stockage Microsoft Azure se trouve derrière un pare-feu, configurez-le pour autoriser l'accès au service de recherche.

Limites

Les sessions de débogage fonctionnent avec toutes les sources de données d'indexeur généralement disponibles et la plupart des sources de données d'aperçu. La liste suivante souligne les exceptions :

Azure Cosmos DB for MongoDB n’est actuellement pas pris en charge.
Pour Azure Cosmos DB for NoSQL, si une ligne échoue pendant l’index et qu’il n’y a pas de métadonnées correspondantes, la session de débogage risque de ne pas choisir la ligne correcte.
Pour l’API SQL d’Azure Cosmos DB, si une collection partitionnée n’était pas partitionnée auparavant, la session de débogage ne trouvera pas le document.
Pour les compétences personnalisées, une identité managée attribuée par l’utilisateur n’est pas prise en charge pour une connexion de session de débogage au stockage Azure. Comme indiqué dans les conditions préalables, vous pouvez utiliser une identité gérée par le système ou spécifier une chaîne de connexion à accès complet qui inclut une clé. Pour plus d’informations, consultez Connecter un service de recherche à d’autres ressources Azure à l’aide d’une identité managée.

Le portail ne prend pas en charge le chiffrement à clé géré par le client (CMK), ce qui signifie que les expériences de portail telles que les sessions de débogage ne peuvent pas avoir de chaînes de connexion chiffrées par CMK ou d'autres métadonnées chiffrées. Si votre service de recherche est configuré pour l'application CMK, les sessions de débogage ne fonctionneront pas.

Créer une session de débogage

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
Dans la page de navigation de gauche, sélectionnez Sessions de débogage.
Dans la barre d'action en haut, sélectionnez Ajouter une session de débogage.
Dans Nom de la session de débogage, fournissez un nom qui vous rappellera les compétences, l’indexeur et la source de données auxquels se rapporte la session de débogage.
Dans Connexion de stockage, recherchez un compte de stockage à usage général pour la mise en cache de la session de débogage. Vous êtes invité à sélectionner et éventuellement à créer un conteneur d’objets blob dans Stockage Blob ou Azure Data Lake Storage Gen2. Vous pouvez réutiliser le même conteneur pour toutes les sessions de débogage suivantes que vous créez. Un nom de conteneur utile peut être « sessions-débogage-recherche-cognitive ».
Dans Authentification de l'identité managée, choisissez Aucune si la connexion à Stockage Microsoft Azure n'utilise pas d'identité managée. Sinon, choisissez l’identité managée à laquelle vous avez accordé les autorisations Storage Blob Data Contributor.
Dans Modèle d’indexeur, sélectionnez l’indexeur qui pilote l’ensemble de compétences que vous souhaitez déboguer. Des copies de l’indexeur et de l’ensemble de compétences sont utilisées pour initialiser la session.
Dans Document à déboguer, choisissez le premier document de l’index ou sélectionnez un document spécifique. Si vous sélectionnez un document spécifique, en fonction de la source de données, un URI ou un ID de ligne vous est demandé.

Si votre document spécifique est un blob, fournissez l’URI du blob. Vous pouvez trouver l’URI dans la page de propriétés du blob du portail.
Si vous le souhaitez, dans Paramètres de l’indexeur, spécifiez les paramètres d’exécution de l’indexeur à utiliser pour créer la session. Les paramètres doivent imiter les paramètres utilisés par l’indexeur réel. Les options d’indexeur que vous spécifiez dans une session de débogage n’ont aucun effet sur l’indexeur lui-même.
Votre configuration doit ressembler à cette capture d’écran. Sélectionnez Enregistrer la session pour commencer.

La session de débogage commence par exécuter l’indexeur et l’ensemble de compétences sur le document sélectionné. Le contenu et les métadonnées du document créés seront visibles et disponibles dans la session.

Une session de débogage peut être annulée durant son exécution avec le bouton Annuler. Si vous appuyez sur le bouton Annuler , vous devriez être en mesure d’analyser les résultats partiels.

On s'attend à ce qu'une session de débogage prenne plus de temps à s'exécuter que l'indexeur, car elle passe par un traitement supplémentaire.

Démarrer avec les erreurs et avertissements

L’historique d’exécution de l’indexeur dans le portail vous donne une liste complète des erreurs et avertissements pour tous les documents. Dans une session de débogage, les erreurs et avertissements sont limités à un seul document. Vous allez utiliser cette liste, apporter vos modifications, puis revenir à la liste pour vérifier si les problèmes sont résolus.

Pour afficher les messages, sélectionnez une compétence dans Enrichissement par IA et graphique des compétences puis sélectionnez Erreurs/avertissements dans le volet d’informations.

Il est recommandé de résoudre les problèmes liés aux entrées avant de passer aux sorties.

Pour vérifier qu’une modification résout une erreur, procédez comme suit :

Sélectionnez Enregistrer dans le volet d’informations de la compétence pour conserver vos modifications.
Sélectionnez Exécuter dans la fenêtre de session pour appeler l’exécution des compétences à l’aide de la définition modifiée.
Revenez aux Erreurs/avertissements pour voir si leur nombre est réduit. La liste ne sera pas actualisée tant que vous n’ouvrez pas l’onglet.

Afficher le contenu des nœuds d’enrichissement

Les pipelines d’enrichissement par IA extraient ou déduisent les informations et la structure des documents sources, créant ainsi un document enrichi au passage. Un document enrichi est d’abord créé lors du craquage de document et est rempli avec un nœud racine (/document), ainsi que des nœuds pour tout contenu directement porté à partir de la source de données, par exemple, des métadonnées et la clé de document. Des nœuds additionnels sont créés par des compétences lors de l’exécution des compétences, où chaque sortie de compétence ajoute un nouveau nœud à l’arborescence d’enrichissement.

Les documents enrichis sont internes, mais une session de débogage vous donne accès au contenu produit lors de l’exécution des compétences. Pour afficher le contenu ou la sortie de chaque compétence, procédez comme suit :

Commencez avec les vues par défaut : Enrichissement par IA et graphique des compétences, avec le type de graphique défini sur Graphique de dépendance.
Sélectionnez une compétence.
Dans le volet d’informations de droite, sélectionnez Exécutions, sélectionnez une SORTIE, puis ouvrez l’évaluateur d’expression (</>) pour afficher l’expression et son résultat.
Vous pouvez également ouvrir Enrichissement par IA et structure de données enrichie pour faire défiler la liste des nœuds. La liste comprend les nœuds potentiels et réels, avec une colonne pour la sortie, et une autre colonne qui indique l’objet en amont utilisé pour produire la sortie.

Modifier les définitions de compétences

Si les mappages de champs sont corrects, vérifiez les compétences individuelles relatives à la configuration et au contenu. Si une compétence ne génère pas de sortie, il se peut qu’il manque une propriété ou un paramètre, ce qui peut être déterminé par le biais des messages d’erreur et de validation.

D’autres problèmes, comme un contexte ou une expression d’entrée non valide, peuvent être plus difficiles à résoudre, car l’erreur indiquera ce qui ne va pas, mais pas comment corriger le problème. Pour obtenir de l’aide sur le contexte et la syntaxe d’entrée, consultez Enrichissements de référence dans un ensemble de compétences Azure AI Search. Pour obtenir de l’aide sur des messages individuels, consultez Dépannage des erreurs et avertissements courants de l’indexeur.

Les étapes suivantes vous montrent comment obtenir des informations sur une compétence.

Dans Enrichissement par IA et Graphique des compétences, sélectionnez une compétence. Le volet Détails de la compétence s’ouvre à droite.
Modifiez une définition de compétence à l’aide de l’une des approches suivantes :
- Paramètres de compétence si vous préférez un éditeur visuel
- Éditeur JSON de compétences pour modifier directement le document JSON
Vérifiez la syntaxe du chemin d’accès pour les nœuds de référence dans une arborescence d’enrichissement. Voici quelques-uns des chemins d’accès d’entrée les plus courants :
- /document/content pour les blocs de texte. Ce nœud est rempli à partir de la propriété content de l’objet blob.
- /document/merged_content pour les segments de texte dans des ensembles de compétences qui incluent une compétence de fusion de texte.
- /document/normalized_images/* pour le texte qui est reconnu ou inféré à partir d’images.

Vérifier les mappages de champs

Si les compétences génèrent une sortie, mais que l’index de recherche est vide, vérifiez les mappages de champs. Les mappages de champs spécifient comment le contenu sort du pipeline et entre dans un index de recherche.

Commencez avec les vues par défaut : Enrichissement par IA et graphique des compétences, avec le type de graphique défini sur Graphique de dépendance.
Sélectionnez Mappages de champs vers le haut. Vous devriez trouver au moins la clé de document qui identifie de façon unique chaque document de recherche dans l’index de recherche et l’associe à son document source dans la source de données.

Si vous importez du contenu brut directement à partir de la source de données, en ignorant l’enrichissement, vous devez rechercher ces champs dans les Mappages de champs.
Sélectionnez Mappages de champs de sortie en bas du graphique. Vous trouverez ici des mappages entre les sorties de compétences et les champs cibles de l’index de recherche. À moins que vous n’ayez utilisé l’assistant d’importation de données, les mappages de champs de sortie sont définis manuellement et peuvent être incomplets ou mal saisis.

Vérifiez que les champs des Mappages de champs de sortie existent dans l’index de recherche comme spécifié, en vérifiant l’orthographe et la syntaxe du chemin d’accès du nœud d’enrichissement.

Déboguer une compétence personnalisée localement

Les compétences personnalisées peuvent être plus difficiles à déboguer, car le code s’exécute en externe, de sorte que la session de débogage ne peut pas être utilisée pour les déboguer. Cette section décrit comment déboguer localement votre compétence API Web personnalisée, votre session de débogage, Visual Studio Code et ngrok ou Tunnelmole. Cette technique fonctionne avec les compétences personnalisées qui s’exécutent dans Azure Functions ou tout autre framework web qui s’exécute localement (par exemple, , FastAPI).

Obtenir une URL publique

Utiliser Tunnelmole

Tunnelmole est un outil de tunneling open source qui peut créer une URL publique qui transmet les requêtes à votre machine locale via un tunnel.

Installer Tunnelmole :
- npm : npm install -g tunnelmole
- Linux : curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
- Mac : curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
- Windows : installez à l'aide de npm. Ou si NodeJS n'est pas installé, téléchargez le fichier .exe précompilé pour Windows et placez-le quelque part dans votre PATH.
Exécutez cette commande pour créer un nouveau tunnel :
```
tmole 7071
```
Vous devriez voir une réponse qui ressemble à ceci :
```
http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
```
Dans l’exemple précédent, transfère https://m5hdpb-ip-49-183-170-144.tunnelmole.net vers le port 7071 de votre ordinateur local, qui est le port par défaut sur lequel les fonctions Azure sont exposées.

Utiliser ngrok

ngrok est une application multi-plateforme populaire, à code source fermé, qui peut créer une URL de tunneling ou de transfert, afin que les requêtes Internet atteignent votre ordinateur local. Utilisez ngrok pour transférer des requêtes à partir d’un pipeline d’enrichissement de votre service de recherche vers votre machine pour permettre un débogage local.

Installez ngrok.
Ouvrez un terminal et accédez au dossier contenant l’exécutable ngrok.
Exécutez ngrok avec la commande suivante pour créer un tunnel :
```
ngrok http 7071 
```
Remarque

Par défaut, les fonctions Azure sont exposées sur 7071. D’autres outils et configurations peuvent nécessiter que vous fournissiez un autre port.
Lorsque ngrok démarre, copiez et enregistrez l’URL de transfert public pour la prochaine étape. L’URL de transfert est générée de façon aléatoire.

Configurer dans le portail Azure

Au cours de la session de débogage, modifiez l’URI de votre compétence API Web personnalisée pour appeler l’URL de transfert Tunnelmole ou ngrok. Prenez soin d’ajouter « /api/FunctionName » lors de l’utilisation de fonction Azure pour exécuter le code de l’ensemble de compétences.

Vous pouvez modifier la définition de compétence dans le portail.

Test de votre code

À ce stade, les nouvelles demandes de votre session de débogage doivent maintenant être envoyées à votre fonction Azure locale. Vous pouvez utiliser des points d'arrêt dans votre Visual Studio Code pour déboguer votre code ou l'exécuter étape par étape.

Étapes suivantes

Maintenant que vous comprenez la disposition et les fonctionnalités de l’éditeur visuel de sessions de débogage, essayez le tutoriel pour obtenir une expérience pratique.

Tutoriel : Explorer les sessions de débogage

Partager via