Lägga till telemetri i din QnA Maker-robot

Artikel
03/08/2023

GÄLLER FÖR: SDK v4

Anteckning

Azure AI QnA Maker dras tillbaka den 31 mars 2025. Från och med den 1 oktober 2022 kan du inte skapa nya QnA Maker-resurser eller kunskapsbaser. En nyare version av funktionen för frågor och svar är nu tillgänglig som en del av Azure AI Language.

Svar på anpassade frågor, en funktion i Azure AI Language, är den uppdaterade versionen av QnA Maker-tjänsten. Mer information om stöd för frågor och svar i Bot Framework SDK finns i Förstå naturligt språk.

Med telemetriloggning kan robotprogram skicka händelsedata till telemetritjänster som Application Insights. Telemetri ger insikter om din robot genom att visa vilka funktioner som används mest, identifierar oönskat beteende och ger insyn i tillgänglighet, prestanda och användning.

Klasserna TelemetryLoggerMiddleware och QnAMaker i Bot Framework SDK aktiverar telemetriloggning i QnA Maker-aktiverade robotar. TelemetryLoggerMiddleware är en mellanprogramskomponent som loggar telemetri varje gång meddelanden tas emot, skickas, uppdateras eller tas bort, och QnAMaker klassen tillhandahåller anpassad loggning som utökar telemetrifunktionerna.

I den här artikeln får du lära dig mer om:

Den kod som krävs för att koppla upp telemetri i roboten
Den kod som krävs för att aktivera den färdiga QnA Maker-loggning och rapporter som använder standardhändelseegenskaperna.
Ändra eller utöka SDK:ts standardhändelseegenskaper för att möjliggöra en mängd olika rapporteringsbehov.

Förutsättningar

QnA Maker-exempelkoden
En prenumeration på Microsoft Azure
En Application Insights-nyckel
Det är bra att känna till QnA Maker .
Ett QnA Maker-konto .
En befintlig och publicerad QnA Maker-kunskapsbas.

Anteckning

Den här artikeln bygger på QnA Maker-exempelkoden genom att stega dig igenom de steg som krävs för att införliva telemetri.

Lägga till telemetrikod i din QnA Maker-robot

Vi börjar med QnA Maker-exempelappen och lägger till den kod som krävs för att integrera telemetri i en robot som använder QnA Maker-tjänsten. Detta gör att Application Insights kan spåra begäranden.

Öppna QnA Maker-exempelappen i Visual Studio.
Lägg till Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet-paket. Mer information om hur du använder NuGet finns i Installera och hantera paket i Visual Studio:
Inkludera följande instruktioner i Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Anteckning

Om du följer med genom att uppdatera QnA Maker-exempelkoden ser du att using-instruktionen för Microsoft.Bot.Builder.Integration.AspNet.Core redan finns i QnA Maker-exemplet.

Lägg till följande kod i ConfigureServices() -metoden i Startup.cs. Detta gör telemetritjänster tillgängliga för din robot via beroendeinmatning (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>();
    ...
}

Anteckning

Om du följer med genom att uppdatera QnA Maker-exempelkoden ser du att den services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); redan finns.

Instruera adaptern att använda mellanprogramkoden som lades till i ConfigureServices() metoden . Öppna AdapterWithErrorHandler.cs och lägg till IMiddleware middleware i parameterlistan för konstruktorer. Lägg till -instruktionen Use(middleware); som den sista raden i konstruktorn:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Lägg till Application Insights-instrumentationsnyckeln i appsettings.json filen. Filen appsettings.json innehåller metadata om externa tjänster som roboten använder när den körs, till exempel anslutning och metadata för Cosmos DB, Application Insights och QnA Maker. Tillägget till appsettings.json filen måste ha följande format:
```
{
    "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"
    }
}
```
Anteckning
- Information om hur du hämtar Application Insights-instrumentationsnyckeln finns i artikeln Application Insights-nycklar.
- Du bör redan ha ett QnA Maker-konto. Information om hur du hämtar QnA Maker-kunskapsbas-ID, slutpunktsnyckel och värdvärden finns i avsnittet Publish to get GenerateAnswer endpoint (Publicera för att hämta GenerateAnswer-slutpunkt) i QnA Maker's Get an answer with the GenerateAnswer API (Hämta ett svar med Api:et för GenerateAnswer).

Nu är det preliminära arbetet med att aktivera telemetri med Application Insights gjort. Du kan köra din robot lokalt med hjälp av Bot Framework Emulator och sedan gå till Application Insights för att se vad som loggas, till exempel svarstid, övergripande apphälsa och allmän information om körning.

Tips

Information om personlig information finns i Aktivera eller inaktivera aktivitetshändelse och loggning av personlig information.

Nu ska vi se vad som behöver inkluderas för att lägga till telemetrifunktioner i QnA Maker-tjänsten.

Aktivera telemetri för att samla in användningsdata från QnA Maker-tjänsten

QnA Maker-tjänsten har inbyggd telemetriloggning tillgänglig, så det finns inte mycket du behöver göra för att börja hämta telemetridata från QnA Maker. Först ska vi se hur du införlivar telemetri i QnA Maker-koden för att aktivera den inbyggda telemetriloggningen. Sedan lär vi oss att ersätta eller lägga till egenskaper i befintliga händelsedata för att uppfylla en mängd olika rapporteringsbehov.

Aktivera QnA Maker-standardloggning

Skapa ett privat skrivskyddat fält av typen IBotTelemetryClient i klassen QnABot i QnABot.cs:

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

Lägg till en IBotTelemetryClient parameter i QnABot klasskonstruktorn i QnABot.cs och tilldela dess värde till det privata fält som skapades i föregående steg:

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

Parametern telemetryClient krävs när du instansierar det nya QnAMaker-objektet i QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Tips

Kontrollera att egenskapsnamnen _configuration som du använder i posterna matchar de egenskapsnamn som du använde i filen AppSettings.json och att värdena för dessa egenskaper hämtas genom att välja knappen Visa kod på sidan Mina kunskapsbaser i QnA Maker-portalen:

Visa telemetridata som loggats från QnA Maker-standardposterna

Du kan visa resultatet av din QnA Maker-robotanvändning i Application Insights när du har kört roboten i Bot Framework Emulator genom att utföra följande steg:

I Azure Portal går du till Application Insights-resursen för din robot.
Under Övervakning väljer du Loggar.

Ange följande Kusto-fråga och välj sedan Kör.

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

Låt den här sidan vara öppen i webbläsaren. Vi kommer tillbaka till den när vi har lagt till en ny anpassad egenskap.

Tips

Om du är nybörjare på kusto-frågespråket som används för att skriva loggfrågor i Azure Monitor, men är bekant med SQL-frågespråket, kan det vara användbart att använda lathunden för SQL till Azure Monitor-loggfrågor .

Ändra eller utöka standardhändelseegenskaper

Om du behöver egenskaper som inte har definierats i QnAMaker klassen finns det två sätt att hantera detta. Båda kräver att du skapar en egen klass som härletts från QnAMaker klassen . Den första förklaras i avsnittet nedan med titeln Lägga till egenskaper där du lägger till egenskaper i den befintliga QnAMessage händelsen. Med den andra metoden kan du skapa nya händelser där du kan lägga till egenskaper enligt beskrivningen i Lägga till nya händelser med anpassade egenskaper.

Anteckning

Händelsen QnAMessage är en del av Bot Framework SDK och innehåller alla färdiga händelseegenskaper som loggas i Application Insights.

Lägg till egenskaper

Följande visar hur du kan härleda från QnAMaker klassen . Exemplet visar hur du lägger till egenskapen "MyImportantProperty" i QnAMessage händelsen. Händelsen QnAMessage loggas varje gång ett QnA GetAnswers-anrop utförs.

När du har lärt dig hur du lägger till anpassade egenskaper får du lära dig hur du skapar en ny anpassad händelse och associerar egenskaper med den. Sedan kör vi roboten lokalt med hjälp av Bot Framework Emulator och ser vad som loggas i Application Insights med hjälp av Kusto-frågespråket.

Skapa en ny klass med namnet MyQnAMaker i Microsoft.BotBuilderSamples namnområdet som ärver från QnAMaker klassen och spara den som MyQnAMaker.cs. Om du vill ärva från QnAMaker klassen måste du lägga till using-instruktionen Microsoft.Bot.Builder.AI.QnA . Koden bör visas på följande sätt:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Lägg till en klasskonstruktor i MyQnAMaker. Du behöver ytterligare två using-instruktioner för konstruktorparametrarna för System.Net.Http och 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)
        {

        }
    }
}

Lägg till den nya egenskapen i QnAMessage-händelsen efter konstruktorn och inkludera instruktionerna System.Collections.Generic, System.Threadingoch 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
                            );
        }

    }
}

Ändra roboten så att den använder den nya klassen, i stället för att skapa ett QnAMaker objekt skapar du ett MyQnAMaker -objekt i QnABot.cs:

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

Visa telemetridata som loggats från den nya egenskapen MyImportantProperty

När du har kört roboten i emulatorn kan du visa resultatet i Application Insights genom att göra följande:

Växla tillbaka till webbläsaren där loggvyn (Analytics) är aktiv.

Ange följande Kusto-fråga och välj sedan Kör. Detta ger ett antal gånger som den nya egenskapen kördes:

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

Om du vill visa information i stället för antalet tar du bort den sista raden och kör frågan igen:

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

Lägga till nya händelser med anpassade egenskaper

Om du behöver logga data till en annan händelse än QnaMessagekan du skapa en egen anpassad händelse med egna egenskaper. För att göra detta lägger vi till kod i slutet av MyQnAMaker klassen på följande sätt:

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);

}

Application Insights-instrumentpanelen

När du skapar en Application Insights-resurs i Azure skapar Azure en ny instrumentpanel som är associerad med resursen. Om du vill visa instrumentpanelen från Application Insights-bladet väljer du Programinstrumentpanel.

Du kan också visa data genom att gå till Azure Portal, expandera portalmenyn och sedan välja Instrumentpanel. Välj sedan den instrumentpanel som du vill använda i den nedrullningsbara menyn.

Instrumentpanelen visar viss standardinformation om robotens prestanda och andra frågor som du har fäst på instrumentpanelen.

Dela via

Lägga till telemetri i din QnA Maker-robot

Förutsättningar

Lägga till telemetrikod i din QnA Maker-robot

Aktivera telemetri för att samla in användningsdata från QnA Maker-tjänsten

Aktivera QnA Maker-standardloggning

Visa telemetridata som loggats från QnA Maker-standardposterna

Ändra eller utöka standardhändelseegenskaper

Lägg till egenskaper

Visa telemetridata som loggats från den nya egenskapen MyImportantProperty

Lägga till nya händelser med anpassade egenskaper

Application Insights-instrumentpanelen

Ytterligare information

Ytterligare resurser