Collecter les données de télémétrie pour l’analyse du trafic de recherche

L’analyse du trafic de recherche est un modèle pour la collecte des données de télémétrie concernant les interactions de l’utilisateur avec votre application de recherche Azure AI, comme les événements de clic initiés par l’utilisateur et les saisies au clavier. À l’aide de ces informations, vous pouvez déterminer l’efficacité de votre solution de recherche, en vous intéressant notamment aux termes de recherche populaires, aux taux de clics et aux entrées de requête qui ne produisent aucun résultat.

Ce modèle dépend d’Application Insights (fonctionnalité d’Azure Monitor) pour collecter les données utilisateur. Vous devrez également ajouter l’instrumentation à votre code client, comme le décrit cet article. Enfin, vous avez besoin d’un mécanisme de création de rapports pour analyser les données. Nous recommandons Power BI, mais vous pouvez utiliser n'importe quel outil de visualisation qui se connecte à Application Insights.

Remarque

Le modèle décrit dans cet article est destiné aux scénarios avancés et aux données parcours générées par le code que vous ajoutez à votre client. En revanche, les journaux de service sont faciles à configurer, fournissent une variété de métriques et peuvent être gérés dans le portail sans code requis. L’activation de la journalisation est recommandée pour tous les scénarios. Pour plus d’informations, consultez Collecter et analyser les données de journal.

Identifier les données de recherche pertinentes

Pour obtenir des mesures utiles pour l’analyse du trafic de recherche, il est nécessaire d’enregistrer certains signaux auprès des utilisateurs de votre application de recherche. Ces signaux indiquent le contenu qui intéresse les utilisateurs et qu’ils estiment pertinent. Pour l’analyse du trafic de recherche, il s’agit des éléments suivants :

• Événements de recherche générés par l’utilisateur : ce signal se concentre uniquement sur les requêtes de recherche lancées par un utilisateur. Les autres requêtes de recherche, comme celles utilisées pour renseigner des facettes ou récupérer des informations internes, ne sont pas importantes. Veillez à n'instrumenter que les événements initiés par l'utilisateur afin d'éviter que vos résultats ne soient faussés ou biaisés.

• Événements de clics générés par l’utilisateur :sur une page de résultats de recherche, un événement de clic signifie généralement qu’un document est un résultat pertinent pour une requête de recherche spécifique.

En associant les événements de recherche et de clic à un ID de corrélation, vous pouvez avoir une meilleure compréhension de la façon dont la fonctionnalité de recherche de votre application fonctionne.

Ajouter la fonctionnalité Analytique du trafic des recherches

Sur la page du portail de votre service Search Azure AI, ouvrez la page Traffic Analytics des recherches pour accéder à un aide-mémoire permettant de suivre ce modèle de télémétrie. À partir de cette page, vous pouvez sélectionner ou créer une ressource Application Insights, obtenir la clé d’instrumentation, copier des extraits de code que vous pouvez adapter à votre solution et télécharger un rapport Power BI qui est créé sur le schéma reflété dans le modèle.

Étape 1 : Configurer Application Insights

Sélectionnez une ressource Application Insights ou en créer une si vous n’en n’avez pas.

Un raccourci qui fonctionne pour certains types de projets Visual Studio est reflété dans les étapes suivantes.

Pour illustration, ces étapes utilisent le client de l’étape Ajouter la recherche à une application web statique.

1. Ouvrez votre solution dans Visual Studio.

2. Dans le menu Projet, sélectionnez Services connectés>Ajouter>Azure Application Insights.

3. Dans Se connecter à la dépendance, sélectionnez Azure Application Insights, puis Suivant.

4. Sélectionnez votre abonnement Azure, votre ressource Application Insights, puis Terminer.

À ce stade, votre application est configurée pour le monitoring d’application, ce qui signifie que tous les chargements de page dans votre application cliente sont suivis avec les métriques par défaut.

Si ce raccourci n’a pas fonctionné pour vous, consultez Activer la télémétrie côté serveur Application Insights.

Étape 2 : Ajouter l’instrumentation

Ajoutez le code d’instrumentation à votre application cliente. La page d’analyse de trafic de recherche dans le portail Azure propose des extraits de code que vous pouvez coller dans votre code d’application.

Créer un client de télémétrie

Créez un objet qui envoie des événements à Application Insights. Vous pouvez ajouter l’instrumentation à votre code d’application côté serveur ou au code côté client s’exécutant dans un navigateur, exprimé ici sous forme de variantes C# et JavaScript. Pour les autres langages, consultez Plateformes et infrastructures prises en charge.

La télémétrie côté serveur capture les métriques au niveau de la couche application, par exemple dans les applications s’exécutant en tant que service web sur Azure ou en tant qu’application locale sur un réseau d’entreprise. La télémétrie côté serveur capture les événements de recherche et de clic, la position d’un document dans les résultats et les informations sur les requêtes, mais votre collecte de données est limitée aux informations disponibles au niveau de cette couche.

Sur le client, il peut exister un autre code qui manipule les entrées de requête, ajoute la navigation ou inclut le contexte (par exemple, les requêtes lancées à partir d’une page d’accueil par rapport à celles lancées depuis une page de produit). Si cela décrit votre solution, vous pouvez opter pour l’instrumentation côté client de sorte que vos données de télémétrie reflètent ces détails supplémentaires. La façon dont ces détails supplémentaires sont collectés sort du cadre de ce modèle, mais vous pouvez consulter Application Insights pour les pages web pour vous aider à prendre une décision à ce propos.

Vous pouvez vous procurer la clé d’instrumentation à partir du portail Azure, soit dans les pages pour Application Insights, soit dans la page d’analyse de trafic de recherche pour Recherche Azure AI.

// Application Insights SDK: https://www.nuget.org/packages/Microsoft.ApplicationInsights.Web 

var telemetryClient = new TelemetryClient();
telemetryClient.InstrumentationKey = "0000000000000000000000000000";

Demander un ID de recherche pour la corrélation

Important

Dans le portail Azure, les extraits de code pour les en-têtes de requête sont effectués à l’aide d’une version obsolète du SDK Azure. Des mises à jour sont en attente.

Pour mettre en corrélation les requêtes de recherche avec les clics, il est nécessaire de disposer d’un ID de corrélation qui lie ces deux événements distincts. La recherche Azure AI vous fournit un ID de recherche avec un en-tête HTTP.

Le fait de disposer de l’ID de recherche permet d’établir une corrélation entre les métriques émises par la Recherche Azure AI pour la requête elle-même et les métriques personnalisées que vous journalisez dans Application Insights.

var client = new SearchClient(<SEARCH SERVICE NAME>, <INDEX NAME>, new AzureDefaultCredentials())
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
IEnumerable<string> headerValues;
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out headerValues)){
	 searchId = headerValues.FirstOrDefault();
} 

Journaliser les événements de recherche

Chaque fois qu’une requête de recherche est émise par un utilisateur, vous devez la consigner en tant qu’événement de recherche en respectant le schéma suivant sur un événement personnalisé Application Insights. N’oubliez pas de consigner uniquement les requêtes de recherche générées par l’utilisateur.

• SearchServiceName : (string) nom du service de recherche
• SearchId : (guid) identificateur unique de la requête de recherche (fourni dans la réponse de recherche)
• IndexName : (string) index du service de recherche à interroger
• QueryTerms : (string) termes de recherche entrés par l’utilisateur
• ResultCount : (int) nombre de documents qui ont été retournés (dans la réponse de recherche)
• ScoringProfile : (string) nom du profil de scoring utilisé, le cas échéant

Remarque

Demandez le nombre de requêtes générées par l’utilisateur en ajoutant $count=true à votre requête de recherche. Pour en savoir plus, consultez la section relative à la recherche de documents (REST).

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"IndexName", <INDEX NAME>},
	{"QueryTerms", <SEARCH TERMS>},
	{"ResultCount", <RESULTS COUNT>},
	{"ScoringProfile", <SCORING PROFILE USED>}
};

telemetryClient.TrackEvent("Search", properties);

Journaliser les événements de clic

Chaque fois qu’un utilisateur clique sur un document, vous obtenez un signal qui doit être consigné afin d’analyser la recherche. Utilisez les événements personnalisés d’Application Insights pour consigner ces événements avec le schéma suivant :

• ServiceName : (string) nom du service de recherche
• SearchId : (guid) identificateur unique de la requête de recherche associée
• DocId : (string) identificateur du document
• Position : (int) rang du document dans la page des résultats de la recherche

Remarque

La position fait référence à la commande cardinale dans votre application. Vous êtes libre de définir ce nombre, tant qu’il reste toujours le même, pour faciliter la comparaison.

var properties = new Dictionary <string, string> {
	{"SearchServiceName", <SEARCH SERVICE NAME>},
	{"SearchId", <SEARCH ID>},
	{"ClickedDocId", <CLICKED DOCUMENT ID>},
	{"Rank", <CLICKED DOCUMENT POSITION>}
};

telemetryClient.TrackEvent("Click", properties);

Étape 3 : Analyser dans Power BI

Après avoir instrumenté votre application et vérifié qu’elle est correctement connectée à Application Insights, vous pouvez télécharger un modèle de rapport prédéfini pour analyser les données dans Power BI Desktop. Le rapport contient des graphiques et des tableaux prédéfinis utiles pour analyser les données supplémentaires capturées pour l’analyse de trafic de recherche.

1. Dans le portail Azure, sur les pages du service de recherche, sous Paramètres, sélectionnez Analyse de trafic de recherche.

2. Sélectionnez Obtenir Power BI Desktop pour installer Power BI.

3. Sélectionnez Télécharger le rapport Power BI pour obtenir le rapport.

4. Le rapport s’ouvre dans Power BI Desktop, et vous êtes invité à vous connecter à Application Insights et à fournir des informations d’identification. Des informations de connexion sont disponibles dans les pages du portail Azure relatives à votre ressource Application Insights. Pour les informations d’identification, indiquez les mêmes nom d’utilisateur et mot de passe que vous utilisez pour vous connecter au portail.

   

5. Sélectionnez Charger.

Ce rapport contient des graphiques et des tableaux qui vous aident à prendre des décisions plus éclairées pour améliorer les performances et la pertinence de vos recherches.

Les métriques incluaient les éléments suivants :

• Volume de recherche et paires terme-document les plus populaires : termes qui amènent l’utilisateur à cliquer sur le même document, classés par clics.
• Recherches sans clic : termes renvoyant aux principales requêtes qui n’enregistrent aucun clic

La capture d’écran suivante montre les éléments de données que votre rapport peut contenir.

Étapes suivantes

Instrumentez votre application de recherche pour obtenir des données puissantes et détaillées sur votre service de recherche.

Des informations supplémentaires sur Application Insights sont disponibles. Vous pouvez également visiter la page des tarifs pour en savoir plus sur les différents niveaux de service.

Apprenez-en davantage sur la création de rapports. Pour plus d’informations, consultez Bien démarrer avec Power BI Desktop.