Dodawanie telemetrii do bota usługi QnA Maker

Artykuł
07/20/2023

DOTYCZY: Zestaw SDK w wersji 4

Uwaga

Usługa Azure AI QnA Maker zostanie wycofana 31 marca 2025 r. Od 1 października 2022 r. nie będzie można tworzyć nowych zasobów usługi QnA Maker ani baz wiedzy. Nowsza wersja funkcji pytań i odpowiedzi jest teraz dostępna w ramach języka sztucznej inteligencji platformy Azure.

Niestandardowe odpowiadanie na pytania, funkcja języka sztucznej inteligencji platformy Azure, to zaktualizowana wersja usługi QnA Maker. Aby uzyskać więcej informacji na temat obsługi pytań i odpowiedzi w zestawie SDK platformy Bot Framework, zobacz Opis języka naturalnego.

Rejestrowanie danych telemetrycznych umożliwia aplikacjom botów wysyłanie danych zdarzeń do usług telemetrycznych, takich jak Application Insights. Telemetria oferuje wgląd w bota, pokazując, które funkcje są najczęściej używane, wykrywa niepożądane zachowanie i zapewnia wgląd w dostępność, wydajność i użycie.

Klasy TelemetryLoggerMiddleware i QnAMaker w zestawie SDK platformy Bot Framework umożliwiają rejestrowanie danych telemetrycznych w botach obsługujących usługę QnA Maker. TelemetryLoggerMiddleware to składnik oprogramowania pośredniczącego, który rejestruje dane telemetryczne za każdym razem, gdy komunikaty są odbierane, wysyłane, aktualizowane lub usuwane, a QnAMaker klasa zapewnia rejestrowanie niestandardowe, które rozszerza możliwości telemetrii.

W tym artykule znajdziesz informacje na temat:

Kod wymagany do połączenia telemetrii w bocie
Kod wymagany do włączenia gotowego rejestrowania usługi QnA Maker i raportów korzystających ze standardowych właściwości zdarzenia.
Modyfikowanie lub rozszerzanie domyślnych właściwości zdarzeń zestawu SDK w celu umożliwienia szerokiego zakresu potrzeb raportowania.

Wymagania wstępne

Przykładowy kod usługi QnA Maker
Subskrypcja platformy Microsoft Azure
Klucz usługi Application Insights
Znajomość usługi QnA Maker jest przydatna .
Konto usługi QnA Maker .
Istniejące i opublikowane baza wiedzy usługi QnA Maker.

Uwaga

Ten artykuł opiera się na przykładowym kodzie usługi QnA Maker , wykonując kroki wymagane do uwzględnienia danych telemetrycznych.

Dodawanie kodu telemetrii do bota usługi QnA Maker

Zaczniemy od przykładowej aplikacji usługi QnA Maker i dodamy kod wymagany do zintegrowania telemetrii z botem, który korzysta z usługi QnA Maker. Umożliwi to usłudze Application Insights śledzenie żądań.

Otwórz przykładową aplikację QnA Maker w programie Visual Studio.
Dodaj pakiet NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Aby uzyskać więcej informacji na temat korzystania z pakietu NuGet, zobacz Instalowanie pakietów i zarządzanie nimi w programie Visual Studio:
Uwzględnij następujące instrukcje w pliku Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Uwaga

Jeśli wykonasz poniższe czynności, aktualizując przykładowy kod usługi QnA Maker, zauważysz, że instrukcja using dla Microsoft.Bot.Builder.Integration.AspNet.Core już istnieje w przykładzie usługi QnA Maker.

Dodaj następujący kod do ConfigureServices() metody w Startup.cspliku . Dzięki temu usługi telemetryczne są dostępne dla bota za pośrednictwem wstrzykiwania zależności (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>();
    ...
}

Uwaga

Jeśli śledzisz, aktualizując przykładowy kod usługi QnA Maker, zauważysz, że services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); już istnieje.

Poinstruuj kartę, aby korzystała z kodu oprogramowania pośredniczącego ConfigureServices() , który został dodany do metody . Otwórz AdapterWithErrorHandler.cs plik i dodaj IMiddleware middleware go do listy parametrów konstruktorów. Dodaj instrukcję Use(middleware); jako ostatni wiersz w konstruktorze:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Dodaj klucz instrumentacji usługi Application Insights w pliku appsettings.json . Plik appsettings.json zawiera metadane dotyczące usług zewnętrznych używanych przez bota podczas działania, takich jak połączenie i metadane dla usług Cosmos DB, Application Insights i QnA Maker. Dodatek do appsettings.json pliku musi mieć następujący 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"
    }
}
```
Uwaga
- Szczegółowe informacje na temat uzyskiwania klucza instrumentacji usługi Application Insights można znaleźć w artykule Klucze usługi Application Insights.
- Powinno już istnieć konto usługi QnA Maker. Aby uzyskać informacje na temat uzyskiwania identyfikatora baza wiedzy usługi QnA Maker, klucza punktu końcowego i wartości hosta, zobacz sekcję Publikowanie w celu pobrania punktu końcowego GenerateAnswer w artykule Get an answer with the GenerateAnswer API (Uzyskiwanie odpowiedzi za pomocą interfejsu API GenerateAnswer).

W tym momencie wykonywana jest wstępna praca w celu włączenia telemetrii przy użyciu usługi Application Insights. Możesz uruchomić bota lokalnie przy użyciu Bot Framework Emulator, a następnie przejść do usługi Application Insights, aby zobaczyć, co jest rejestrowane, takie jak czas odpowiedzi, ogólna kondycja aplikacji i ogólne informacje o uruchomieniu.

Porada

Aby uzyskać informacje na temat informacji osobistych, zobacz Włączanie lub wyłączanie zdarzenia aktywności i rejestrowania informacji osobistych.

Następnie zobaczymy, co należy uwzględnić w celu dodania funkcji telemetrii do usługi QnA Maker.

Włączanie telemetrii w celu przechwytywania danych użycia z usługi QnA Maker

Usługa QnA Maker ma wbudowane rejestrowanie danych telemetrycznych, więc niewiele trzeba zrobić, aby rozpocząć pobieranie danych telemetrycznych z usługi QnA Maker. Najpierw zobaczymy, jak dołączyć dane telemetryczne do kodu usługi QnA Maker w celu włączenia wbudowanego rejestrowania telemetrii, a następnie dowiemy się, jak zastąpić lub dodać właściwości do istniejących danych zdarzenia w celu zaspokojenia szerokiego zakresu potrzeb raportowania.

Włączanie domyślnego rejestrowania usługi QnA Maker

Utwórz prywatne pole tylko do odczytu typu IBotTelemetryClient w QnABot klasie w pliku QnABot.cs:

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

Dodaj parametr do QnABot konstruktora IBotTelemetryClient klasy w QnABot.cs pliku i przypisz jego wartość do pola prywatnego utworzonego w poprzednim kroku:

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

Parametr telemetryClient jest wymagany podczas tworzenia wystąpienia nowego obiektu QnAMaker w pliku QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Porada

Upewnij się, że nazwy właściwości używane w _configuration wpisach są zgodne z nazwami właściwości użytymi w pliku AppSettings.json, a wartości tych właściwości są uzyskiwane, wybierając przycisk Wyświetl kod na stronie Moje bazy wiedzy w portalu usługi QnA Maker:

Wyświetlanie danych telemetrycznych zarejestrowanych w domyślnych wpisach usługi QnA Maker

Wyniki użycia bota usługi QnA Maker można wyświetlić w usłudze Application Insights po uruchomieniu bota w Bot Framework Emulator, wykonując następujące czynności:

W Azure Portal przejdź do zasobu usługi Application Insights dla bota.
W obszarze Monitorowanie wybierz pozycję Dzienniki.

Wprowadź następujące zapytanie Kusto, a następnie wybierz pozycję Uruchom.

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

Pozostaw tę stronę otwartą w przeglądarce; Wrócimy do niego po dodaniu nowej właściwości niestandardowej.

Porada

Jeśli jesteś nowym użytkownikiem języka zapytań Kusto używanego do pisania zapytań dzienników w usłudze Azure Monitor, ale znasz język zapytań SQL, przydatne może być ściągawka dotycząca zapytań dzienników w usłudze Azure Monitor.

Modyfikowanie lub rozszerzanie domyślnych właściwości zdarzenia

Jeśli potrzebujesz właściwości, które nie są zdefiniowane w QnAMaker klasie, istnieją dwa sposoby obsługi, oba wymagają utworzenia własnej klasy pochodzącej QnAMaker z klasy. Pierwszy wyjaśniono w sekcji poniżej zatytułowanej Dodawanie właściwości , w których dodajesz właściwości do istniejącego QnAMessage zdarzenia. Druga metoda umożliwia tworzenie nowych zdarzeń, do których można dodać właściwości zgodnie z opisem w temacie Dodawanie nowych zdarzeń z właściwościami niestandardowymi.

Uwaga

Zdarzenie QnAMessage jest częścią zestawu Bot Framework SDK i udostępnia wszystkie gotowe do użycia właściwości zdarzeń, które są rejestrowane w usłudze Application Insights.

Dodawanie właściwości

Poniżej pokazano, jak można pochodzić z QnAMaker klasy . W przykładzie pokazano dodanie właściwości "MyImportantProperty" do QnAMessage zdarzenia. Zdarzenie QnAMessage jest rejestrowane za każdym razem, gdy jest wykonywane wywołanie QnA GetAnswers .

Po dodaniu właściwości niestandardowych dowiesz się, jak utworzyć nowe zdarzenie niestandardowe i skojarzyć z nim właściwości, a następnie uruchomimy bota lokalnie przy użyciu Bot Framework Emulator i zobaczymy, co jest rejestrowane w usłudze Application Insights przy użyciu języka zapytań Kusto.

Utwórz nową klasę o nazwie MyQnAMaker w Microsoft.BotBuilderSamples przestrzeni nazw dziedziczonej QnAMaker po klasie i zapisz ją jako MyQnAMaker.cs. Aby dziedziczyć z QnAMaker klasy, należy dodać instrukcję Microsoft.Bot.Builder.AI.QnA using. Kod powinien wyglądać następująco:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Dodaj konstruktor klasy do MyQnAMakerklasy . Potrzebujesz jeszcze dwóch instrukcji using dla parametrów konstruktora dla System.Net.Http i 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)
        {

        }
    }
}

Dodaj nową właściwość do zdarzenia QnAMessage po konstruktorze i dołącz instrukcje System.Collections.Generic, System.Threadingi 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
                            );
        }

    }
}

Zmodyfikuj bota, aby używał nowej klasy, zamiast tworzyć QnAMaker obiekt, który MyQnAMaker utworzysz w programie QnABot.cs:

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

Wyświetlanie danych telemetrycznych zarejestrowanych z nowej właściwości MyImportantProperty

Po uruchomieniu bota w emulatorze możesz wyświetlić wyniki w usłudze Application Insights, wykonując następujące czynności:

Wróć do przeglądarki z aktywnym widokiem Dzienniki (Analiza).

Wprowadź następujące zapytanie Kusto, a następnie wybierz pozycję Uruchom. Spowoduje to podanie liczby przypadków wykonania nowej właściwości:

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

Aby wyświetlić szczegóły zamiast liczby, usuń ostatni wiersz i uruchom ponownie zapytanie:

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

Dodawanie nowych zdarzeń z właściwościami niestandardowymi

Jeśli musisz rejestrować dane w innym zdarzeniu niż QnaMessage, możesz utworzyć własne zdarzenie niestandardowe z własnymi właściwościami. W tym celu dodamy kod na końcu MyQnAMaker klasy w następujący sposób:

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

}

Pulpit nawigacyjny usługi Application Insights

Za każdym razem, gdy tworzysz zasób usługi Application Insights na platformie Azure, platforma Azure tworzy nowy pulpit nawigacyjny skojarzony z zasobem. Aby wyświetlić pulpit nawigacyjny w bloku Application Insights, wybierz pozycję Pulpit nawigacyjny aplikacji.

Alternatywnie, aby wyświetlić dane, przejdź do Azure Portal, rozwiń menu portalu, a następnie wybierz pozycję Pulpit nawigacyjny. Następnie wybierz odpowiedni pulpit nawigacyjny z menu rozwijanego.

Na pulpicie nawigacyjnym są wyświetlane domyślne informacje o wydajności bota i inne zapytania przypięte do pulpitu nawigacyjnego.

Udostępnij za pośrednictwem

Dodawanie telemetrii do bota usługi QnA Maker

Wymagania wstępne

Dodawanie kodu telemetrii do bota usługi QnA Maker

Włączanie telemetrii w celu przechwytywania danych użycia z usługi QnA Maker

Włączanie domyślnego rejestrowania usługi QnA Maker

Wyświetlanie danych telemetrycznych zarejestrowanych w domyślnych wpisach usługi QnA Maker

Modyfikowanie lub rozszerzanie domyślnych właściwości zdarzenia

Dodawanie właściwości

Wyświetlanie danych telemetrycznych zarejestrowanych z nowej właściwości MyImportantProperty

Dodawanie nowych zdarzeń z właściwościami niestandardowymi

Pulpit nawigacyjny usługi Application Insights

Dodatkowe informacje

Dodatkowe zasoby