Partager via

Ajouter la télémétrie à votre bot QnA Maker

  • Article

S’APPLIQUE À : KIT de développement logiciel (SDK) v4

Notes

Azure AI QnA Maker sera mis hors service le 31 mars 2025. À compter du 1er octobre 2022, vous ne pourrez pas créer de ressources ou bases de connaissances QnA Maker. Une version plus récente de la fonctionnalité de questions et réponses est désormais disponible dans le cadre d’Azure AI Language.

Les réponses aux questions personnalisées, une fonctionnalité d’Azure AI Language, sont la version mise à jour du service QnA Maker. Pour plus d’informations sur la prise en charge des questions-réponses dans le Kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

La journalisation des données de télémétrie permet aux applications bots d’envoyer des données d’événement à des services de télémétrie tels qu’Application Insights. La télémétrie offre des aperçus de votre robot en indiquant les fonctionnalités qui sont utilisées le plus, détecte le comportement indésirable et offre une visibilité sur la disponibilité, les performances et l’utilisation.

Les TelemetryLoggerMiddleware classes et QnAMaker du Kit de développement logiciel (SDK) Bot Framework activent la journalisation des données de télémétrie dans les bots avec QnA Maker. TelemetryLoggerMiddleware est un composant middleware qui journalise les données de télémétrie chaque fois que des messages sont reçus, envoyés, mis à jour ou supprimés, et la QnAMaker classe fournit une journalisation personnalisée qui étend les fonctionnalités de télémétrie.

Cet article porte sur les points suivants :

  • Code nécessaire au raccordement de la télémétrie à votre bot
  • Code requis pour activer la journalisation et les rapports QnA Maker prêtes à l’emploi qui utilisent les propriétés d’événement standard.
  • Modification ou extension des propriétés d’événement par défaut du kit SDK pour répondre à un large éventail de besoins en matière de rapports.

Prérequis

Notes

Cet article s’appuie sur l’exemple de code QnA Maker en vous faisant suivre les étapes requises pour incorporer les données de télémétrie.

Ajouter du code de télémétrie à votre bot QnA Maker

Nous allons commencer par l’exemple d’application QnA Maker et ajouter le code requis pour intégrer la télémétrie à un bot qui utilise le service QnA Maker. Cela permet à Application Insights de suivre les demandes.

  1. Ouvrez l’exemple d’application QnA Maker dans Visual Studio.

  2. Ajoutez le package NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Pour plus d’informations sur l’utilisation de NuGet, consultez Installer et gérer des packages dans Visual Studio :

  3. Ajoutez les instructions suivantes dans Startup.cs :

    using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;

    Notes

    Si vous suivez en mettant à jour l’exemple de code QnA Maker, vous remarquerez que l’instruction using pour Microsoft.Bot.Builder.Integration.AspNet.Core existe déjà dans l’exemple QnA Maker.

  4. Ajoutez le code suivant à la méthode ConfigureServices() dans Startup.cs. Les services de télémétrie sont ainsi rendus disponibles pour votre bot via l’injection de dépendances (DI) :

    // This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    ...
    // Create the Bot Framework Adapter with error handling enabled.
    services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

    // Add Application Insights services into service collection
    services.AddApplicationInsightsTelemetry();

    // Add the standard telemetry client
    services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();

    // Create the telemetry middleware to track conversation events
    services.AddSingleton<TelemetryLoggerMiddleware>();

    // Add the telemetry initializer middleware
    services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();

    // Add telemetry initializer that will set the correlation context for all telemetry items
    services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>();

    // Add telemetry initializer that sets the user ID and session ID (in addition to other bot-specific properties, such as activity ID)
    services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>();
    ...
}

    Notes

    Si vous suivez en mettant à jour l’exemple de code QnA Maker, vous remarquerez qu’il services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); existe déjà.

  5. Demandez à l’adaptateur d’utiliser le code de l’intergiciel qui a été ajouté à la méthode ConfigureServices(). Ouvrez AdapterWithErrorHandler.cs et ajoutez IMiddleware middleware à la liste des paramètres des constructeurs. Ajoutez l’instruction Use(middleware); comme dernière ligne du constructeur :

    public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}

  6. Ajoutez la clé d’instrumentation Application Insights à votre fichier appsettings.json. Le appsettings.json fichier contient des métadonnées sur les services externes que le bot utilise lors de l’exécution, tels que la connexion et les métadonnées pour Cosmos DB, Application Insights et QnA Maker. L’ajout à votre fichier appsettings.json doit être au format suivant :

    {
    "MicrosoftAppId": "",
    "MicrosoftAppPassword": "",
    "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
    "ApplicationInsights": {
        "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

    Notes

    • Pour plus d’informations sur l’obtention de la clé d’instrumentation Application Insights, consultez l’article clés Application Insights.
    • Vous devez déjà disposer d’un compte QnA Maker. Pour plus d’informations sur l’obtention de l’ID de base de connaissances QnA Maker, de la clé de point de terminaison et des valeurs d’hôte, consultez la section Publier pour obtenir le point de terminaison GenerateAnswer de l’article Obtenir une réponse avec l’API GenerateAnswer de QnA Maker.

À ce stade, le travail préliminaire pour activer la télémétrie à l’aide d’Application Insights est effectué. Vous pouvez exécuter votre bot localement à l’aide de la Bot Framework Emulator, puis accéder à Application Insights pour voir ce qui est enregistré, comme le temps de réponse, l’intégrité globale de l’application et les informations générales d’exécution.

Conseil

Pour plus d’informations sur les informations personnelles, consultez Activer ou désactiver l’événement d’activité et la journalisation des informations personnelles.

Nous verrons ensuite ce qui doit être inclus pour ajouter la fonctionnalité de télémétrie au service QnA Maker.

Activer la télémétrie pour capturer les données d’utilisation à partir du service QnA Maker

Le service QnA Maker dispose d’une journalisation de télémétrie intégrée. Vous avez donc peu à faire pour commencer à obtenir des données de télémétrie à partir de QnA Maker. Tout d’abord, nous allons voir comment incorporer la télémétrie dans le code QnA Maker pour activer la journalisation de télémétrie intégrée, puis nous allons apprendre à remplacer ou ajouter des propriétés aux données d’événement existantes pour répondre à un large éventail de besoins de création de rapports.

Activer la journalisation QnA Maker par défaut

  1. Créez un champ readonly privé de type IBotTelemetryClient dans votre classe QnABot du fichier QnABot.cs :

    public class QnABot : ActivityHandler
    {
        private readonly IBotTelemetryClient _telemetryClient;
        ...
}

  2. Ajoutez un paramètre IBotTelemetryClient à votre constructeur de classe QnABot dans QnABot.cs et affectez sa valeur au champ privé créé à l’étape précédente :

    public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
{
    ...
    _telemetryClient = telemetryClient;
}

  3. Le paramètre telemetryClient est nécessaire lors de l’instanciation du nouvel objet QnAMaker dans QnABot.cs :

    var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);

    Conseil

    Assurez-vous que les noms de propriétés que vous utilisez dans les _configuration entrées correspondent aux noms de propriétés que vous avez utilisés dans le fichier AppSettings.json et que les valeurs de ces propriétés sont obtenues en sélectionnant le bouton Afficher le code dans la page Mes bases de connaissances dans le portail QnA Maker :

    Illustration de l’emplacement où les paramètres d’application se trouvent dans le portail LUIS.

Afficher les données de télémétrie enregistrées à partir des entrées par défaut de QnA Maker

Vous pouvez afficher les résultats de l’utilisation de votre bot QnA Maker dans Application Insights après avoir exécuté votre bot dans le Bot Framework Emulator en effectuant les étapes suivantes :

  1. Dans le Portail Azure, accédez à la ressource Application Insights pour votre bot.

  2. Sous Supervision, sélectionnez Journaux d’activité.

  3. Entrez la requête Kusto suivante, puis sélectionnez Exécuter.

    customEvents
| where name == 'QnaMessage'
| extend answer = tostring(customDimensions.answer)
| summarize count() by answer

  4. Laissez cette page ouverte dans votre navigateur ; nous y reviendrons après l’ajout d’une nouvelle propriété personnalisée.

Conseil

Si vous débutez avec le langage de requête Kusto qui est utilisé pour écrire des requêtes de journal dans Azure Monitor, mais que vous êtes familiarisé avec le langage de requête SQL, vous trouverez peut-être la aide-mémoire de la requête de journal SQL vers Azure Monitor .

Modifier ou étendre les propriétés d’événement par défaut

Si vous avez besoin de propriétés qui ne sont pas définies dans la QnAMaker classe, il existe deux façons de gérer cela, les deux nécessitent la création de votre propre classe dérivée de la QnAMaker classe . La première est expliquée dans la section ci-dessous intitulée Ajout de propriétés, et dans laquelle vous ajoutez des propriétés à l’événement QnAMessage existant. La seconde méthode vous permet de créer des événements auxquels vous pouvez ajouter des propriétés, comme décrit dans Ajout de nouveaux événements avec des propriétés personnalisées.

Notes

L’événement QnAMessage fait partie du kit SDK Bot Framework et fournit toutes les propriétés d’événement prêtes à l’emploi qui sont consignées dans Application Insights.

Ajouter des propriétés

La façon dont vous pouvez faire dériver la classe QnAMaker est illustrée ci-après. Cet exemple montre l’ajout de la propriété « MyImportantProperty » à l’événement QnAMessage. L’événement QnAMessage est enregistré chaque fois qu’un appel QnA GetAnswers est effectué.

Après avoir appris à ajouter des propriétés personnalisées, nous allons apprendre à créer un événement personnalisé et à y associer des propriétés, puis nous allons exécuter le bot localement à l’aide du Bot Framework Emulator et voir ce qui est connecté à Application Insights à l’aide du langage de requête Kusto.

  1. Créez une nouvelle classe nommée MyQnAMaker dans l’espace de noms Microsoft.BotBuilderSamples qui hérite de la classe QnAMaker et enregistrez-la sous MyQnAMaker.cs. Pour hériter de la QnAMaker classe, vous devez ajouter l’instruction Microsoft.Bot.Builder.AI.QnA using. Votre code doit s’afficher comme suit :

    using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}

  2. Ajoutez un constructeur de classe à MyQnAMaker. Vous aurez besoin de deux instructions using supplémentaires pour les paramètres du constructeur pour System.Net.Http et Microsoft.Bot.Builder:

    using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {
        public MyQnAMaker(
            QnAMakerEndpoint endpoint,
            QnAMakerOptions options = null,
            HttpClient httpClient = null,
            IBotTelemetryClient telemetryClient = null,
            bool logPersonalInformation = false)
            : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
        {

        }
    }
}

  3. Ajoutez la nouvelle propriété à l’événement QnAMessage après le constructeur, et incluez les instructions System.Collections.Generic, System.Threading et System.Threading.Tasks :

    using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.BotBuilderSamples
{
        public class MyQnAMaker : QnAMaker
        {
        ...

        protected override async Task OnQnaResultsAsync(
                            QueryResult[] queryResults,
                            Microsoft.Bot.Builder.ITurnContext turnContext,
                            Dictionary<string, string> telemetryProperties = null,
                            Dictionary<string, double> telemetryMetrics = null,
                            CancellationToken cancellationToken = default(CancellationToken))
        {
            var eventData = await FillQnAEventAsync(
                                    queryResults,
                                    turnContext,
                                    telemetryProperties,
                                    telemetryMetrics,
                                    cancellationToken)
                                .ConfigureAwait(false);

            // Add new property
            eventData.Properties.Add("MyImportantProperty", "myImportantValue");

            // Log QnAMessage event
            TelemetryClient.TrackEvent(
                            QnATelemetryConstants.QnaMsgEvent,
                            eventData.Properties,
                            eventData.Metrics
                            );
        }

    }
}

  4. Modifiez votre bot pour utiliser la nouvelle classe. Au lieu de créer un QnAMaker objet, vous allez créer un MyQnAMaker objet dans QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
Afficher les données de télémétrie enregistrées à partir de la nouvelle propriété MyImportantProperty

Après avoir exécuté votre bot dans l’émulateur, vous pouvez afficher les résultats dans Application Insights en procédant comme suit :

  1. Revenez à votre navigateur sur lequel la vue Logs (Analytics) est active.

  2. Entrez la requête Kusto suivante et sélectionnez Exécuter. Le nombre de fois que la nouvelle propriété a été exécutée y est renseigné :

    customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
| summarize count() by MyImportantProperty

  3. Pour afficher les détails au lieu du nombre, supprimez la dernière ligne et réexécutez la requête :

    customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)

Ajouter de nouveaux événements avec des propriétés personnalisées

Si vous devez enregistrer des données dans un autre événement que QnaMessage, vous pouvez créer votre propre événement personnalisé doté de ses propriétés spécifiques. Pour ce faire, nous allons ajouter du code à la fin de la MyQnAMaker classe comme suit :

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

Le tableau de bord Application Insights

Chaque fois que vous créez une ressource Application Insights dans Azure, Azure crée un nouveau tableau de bord associé à votre ressource. Pour afficher le tableau de bord à partir du panneau Application Insights, sélectionnez Tableau de bord d’application.

Pour afficher les données, accédez à la Portail Azure, développez le menu du portail, puis sélectionnez Tableau de bord. Ensuite, sélectionnez le tableau de bord souhaité dans le menu déroulant.

Le tableau de bord affiche des informations par défaut sur les performances de votre bot et toutes les autres requêtes que vous avez épinglées à votre tableau de bord.

Informations supplémentaires