Hinzufügen von Telemetriedaten zu Ihrem QnA Maker-Bot

Artikel
03/08/2023

GILT FÜR: SDK v4

Hinweis

Azure AI QnA Maker wird am 31. März 2025 eingestellt. Ab dem 1. Oktober 2022 können Sie keine neuen QnA Maker-Ressourcen oder Wissensdatenbanken mehr erstellen. Eine neuere Version der Frage- und Antwortfunktion ist jetzt als Teil von Azure AI Language verfügbar.

Benutzerdefinierte Fragebeantwortung, ein Feature von Azure AI Language, ist die aktualisierte Version des QnA Maker-Diensts. Weitere Informationen zur Unterstützung von Fragen und Antworten im Bot Framework SDK finden Sie unter Verstehen natürlicher Sprache.

Mit der Telemetrieprotokollierung können Botanwendungen Ereignisdaten an Telemetriedienste wie Application Insights senden. Anhand von Telemetriedaten können Sie sich Einblick in Ihren Bot verschaffen, indem Sie anzeigen, welche Features am meisten genutzt werden. Außerdem wird unerwünschtes Verhalten erkannt, und Sie erhalten Informationen zur Verfügbarkeit, Leistung und Nutzung.

Die TelemetryLoggerMiddleware Klassen und QnAMaker im Bot Framework SDK ermöglichen die Telemetrieprotokollierung in QnA Maker-fähigen Bots. TelemetryLoggerMiddleware ist eine Middlewarekomponente, die Telemetriedaten jedes Mal protokolliert, wenn Nachrichten empfangen, gesendet, aktualisiert oder gelöscht werden, und die QnAMaker -Klasse bietet benutzerdefinierte Protokollierung, die telemetriefunktionen erweitert.

In diesem Artikel lernen Sie Folgendes:

Erforderlicher Code zum Einrichten der Telemetrie in Ihrem Bot
Der Code, der erforderlich ist, um die sofort einsatzbereite QnA Maker-Protokollierung und Berichte zu aktivieren, die die Standardereigniseigenschaften verwenden.
Ändern oder Erweitern der Standardereigniseigenschaften des SDK zur Erfüllung vieler verschiedener Anforderungen an die Berichterstellung

Voraussetzungen

QnA Maker-Beispielcode
Microsoft Azure-Abonnement
Application Insights-Schlüssel
Es ist hilfreich, wenn Sie mit QnA Maker bereits vertraut sind.
QnA Maker-Konto
Eine vorhandene und veröffentlichte QnA Maker-Wissensdatenbank.

Hinweis

Dieser Artikel baut auf dem QnA Maker-Beispielcode auf, indem Er Sie durch die Schritte führt, die zum Integrieren von Telemetriedaten erforderlich sind.

Hinzufügen von Telemetriecode zu Ihrem QnA Maker-Bot

Wir beginnen mit der QnA Maker-Beispiel-App und fügen den Code hinzu, der zum Integrieren von Telemetriedaten in einen Bot erforderlich ist, der den QnA Maker-Dienst verwendet. Dadurch kann Application Insights Anforderungen nachverfolgen.

Öffnen Sie die QnA Maker-Beispiel-App in Visual Studio.
Fügen Sie das NuGet-Paket Microsoft.Bot.Builder.Integration.ApplicationInsights.Core hinzu. Weitere Informationen zur Verwendung von NuGet finden Sie unter Installieren und Verwalten von Paketen in Visual Studio mit dem NuGet-Paket-Manager.
Fügen Sie die folgenden Anweisungen in Startup.cs ein:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Hinweis

Wenn Sie den QnA Maker-Beispielcode aktualisieren, werden Sie feststellen, dass die using-Anweisung für Microsoft.Bot.Builder.Integration.AspNet.Core bereits im QnA Maker-Beispiel vorhanden ist.

Fügen Sie der ConfigureServices()-Methode in Startup.cs den unten angegebenen Code hinzu. So werden die Telemetriedienste per Abhängigkeitsinjektion für Ihren Bot verfügbar gemacht:

// 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>();
    ...
}

Hinweis

Wenn Sie den QnA Maker-Beispielcode aktualisieren, werden Sie feststellen, dass services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); bereits vorhanden ist.

Weisen Sie den Adapter an, den Middleware-Code zu verwenden, der der ConfigureServices()-Methode hinzugefügt wurde. Öffnen Sie AdapterWithErrorHandler.cs, und fügen Sie IMiddleware middleware der Liste mit den Konstruktorparametern hinzu. Fügen Sie die Use(middleware); -Anweisung als letzte Zeile im Konstruktor hinzu:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Fügen Sie den Application Insights-Instrumentierungsschlüssel in Ihrer Datei appsettings.json hinzu. Die appsettings.json Datei enthält Metadaten zu externen Diensten, die der Bot während der Ausführung verwendet, z. B. Verbindungen und Metadaten für Cosmos DB, Application Insights und QnA Maker. Verwenden Sie zum Hinzufügen zur Datei appsettings.json das folgende 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"
    }
}
```
Hinweis
- Ausführliche Informationen zum Abrufen des Application Insights-Instrumentierungsschlüssels finden Sie im Artikel zum Thema Application Insights-Schlüssel.
- Sie sollten bereits über ein QnA Maker-Konto verfügen. Informationen zum Abrufen der QnA Maker-Wissensdatenbank-ID, des Endpunktschlüssels und der Hostwerte finden Sie im Artikel Zum Abrufen von GenerateAnswer-Endpunkten veröffentlichen im Artikel Zum Abrufen einer Antwort mit der GenerateAnswer-API von QnA Maker.

An diesem Punkt sind die Vorarbeiten zum Aktivieren von Telemetriedaten mithilfe von Application Insights abgeschlossen. Sie können Ihren Bot lokal mit dem Bot Framework Emulator ausführen und dann in Application Insights nachsehen, was protokolliert wird, z. B. Antwortzeit, allgemeine App-Integrität und allgemeine Ausführungsinformationen.

Tipp

Informationen zu persönlichen Informationen finden Sie unter Aktivieren oder Deaktivieren der Protokollierung von Aktivitätsereignissen und persönlichen Informationen.

Als Nächstes sehen wir, was enthalten sein muss, um Telemetriefunktionen zum QnA Maker-Dienst hinzuzufügen.

Aktivieren von Telemetriedaten zum Erfassen von Nutzungsdaten aus dem QnA Maker-Dienst

Der QnA Maker-Dienst verfügt über integrierte Telemetrieprotokollierung, sodass Sie nur wenig tun müssen, um Telemetriedaten von QnA Maker zu erhalten. Zunächst erfahren Sie, wie Sie Telemetriedaten in den QnA Maker-Code integrieren, um die integrierte Telemetrieprotokollierung zu aktivieren. Anschließend erfahren Sie, wie Sie vorhandene Ereignisdaten ersetzen oder Eigenschaften hinzufügen, um eine Vielzahl von Berichtsanforderungen zu erfüllen.

Aktivieren der QnA Maker-Standardprotokollierung

Erstellen Sie in QnABot.cs in Ihrer QnABot-Klasse das private Feld „readonly“ mit dem Typ IBotTelemetryClient:

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

Fügen Sie Ihrem QnABot-Klassenkonstruktor in QnABot.cs einen IBotTelemetryClient-Parameter hinzu, und weisen Sie dessen Wert dem privaten Feld zu, das Sie im vorherigen Schritt erstellt haben:

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

Der Parameter telemetryClient ist erforderlich, wenn Sie in QnABot.cs das neue QnAMaker-Objekt instanziieren:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Tipp

Stellen Sie sicher, dass die Eigenschaftennamen, die Sie in den _configuration Einträgen verwenden, mit den Eigenschaftennamen übereinstimmen, die Sie in der Datei AppSettings.json verwendet haben, und die Werte für diese Eigenschaften abgerufen werden, indem Sie auf der Seite Meine Wissensdatenbanken im QnA Maker-Portal die Schaltfläche Code anzeigen auswählen:

Anzeigen von Telemetriedaten, die von den QnA Maker-Standardeinträgen protokolliert wurden

Sie können die Ergebnisse der Verwendung Ihres QnA Maker-Bots in Application Insights anzeigen, nachdem Sie Ihren Bot im Bot Framework Emulator ausgeführt haben, indem Sie die folgenden Schritte ausführen:

Navigieren Sie im Azure-Portal zur Application Insights-Ressource für Ihren Bot.
Wählen Sie unter Überwachung die Option Protokolle aus.

Geben Sie die folgende Kusto-Abfrage ein, und wählen Sie dann Ausführen aus.

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

Lassen Sie diese Seite in Ihrem Browser geöffnet. Nach dem Hinzufügen einer neuen benutzerdefinierten Eigenschaft kehren wir darauf zurück.

Tipp

Wenn Sie noch nicht mit der Kusto-Abfragesprache vertraut sind, die zum Schreiben von Protokollabfragen in Azure Monitor verwendet wird, aber mit der SQL-Abfragesprache vertraut sind, finden Sie möglicherweise das Protokollabfragesspickzettel sql to Azure Monitor nützlich.

Ändern oder Erweitern von Standardereigniseigenschaften

Wenn Sie Eigenschaften benötigen, die nicht in der QnAMaker -Klasse definiert sind, gibt es zwei Möglichkeiten, dies zu behandeln, müssen beide eine eigene Klasse erstellen, die von der QnAMaker -Klasse abgeleitet ist. Die erste Option ist unten im Abschnitt Hinzufügen von Eigenschaften beschrieben, in dem Sie dem vorhandenen QnAMessage-Ereignis Eigenschaften hinzufügen. Die zweite Option ermöglicht Ihnen die Erstellung neuer Ereignisse, denen Sie Eigenschaften hinzufügen können. Dies ist unter Hinzufügen von neuen Ereignissen mit benutzerdefinierten Eigenschaften beschrieben.

Hinweis

Das Ereignis QnAMessage ist Teil des Bot Framework SDK und stellt alle vorkonfigurierten Ereigniseigenschaften bereit, die unter Application Insights protokolliert werden.

Hinzufügen von Eigenschaften

Im folgenden Beispiel wird veranschaulicht, wie Sie eine Ableitung von der QnAMaker-Klasse durchführen können. Im Beispiel wird die Eigenschaft „MyImportantProperty“ dem QnAMessage-Ereignis hinzugefügt. Das Ereignis QnAMessage wird jedes Mal protokolliert, wenn der QnA-Aufruf GetAnswers durchgeführt wird.

Nachdem wir erfahren haben, wie Sie benutzerdefinierte Eigenschaften hinzufügen, erfahren Sie, wie Sie ein neues benutzerdefiniertes Ereignis erstellen und diesem Eigenschaften zuordnen. Anschließend führen wir den Bot lokal mithilfe des Bot Framework Emulator aus und sehen, was in Application Insights mit der Kusto-Abfragesprache protokolliert wird.

Erstellen Sie eine neue Klasse mit dem Namen MyQnAMaker im Namespace Microsoft.BotBuilderSamples, die von der QnAMaker-Klasse erbt, und speichern Sie sie als MyQnAMaker.cs. Um von der QnAMaker -Klasse zu erben, müssen Sie die using-Anweisung Microsoft.Bot.Builder.AI.QnA hinzufügen. Ihr Code sollte wie folgt aussehen:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Fügen Sie einen Klassenkonstruktor hinzu MyQnAMaker. Sie benötigen zwei weitere using-Anweisungen für die Konstruktorparameter für System.Net.Http und 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)
        {

        }
    }
}

Fügen Sie die neue Eigenschaft dem QnAMessage-Ereignis nach dem Konstruktor hinzu, und fügen Sie die Anweisungen System.Collections.Generic, System.Threading und System.Threading.Tasks ein:

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

    }
}

Ändern Sie Ihren Bot so, dass er die neue Klasse verwendet. Anstatt ein QnAMaker Objekt zu erstellen, erstellen Sie ein MyQnAMaker Objekt in QnABot.cs:

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

Anzeigen von Telemetriedaten, die über die neue Eigenschaft MyImportantProperty protokolliert wurden

Nachdem Sie Ihren Bot im Emulator ausgeführt haben, können Sie die Ergebnisse in Application Insights wie folgt anzeigen:

Wechseln Sie zurück zu Ihrem Browser, in dem die Ansicht Protokolle (Analytics) aktiv ist.
Geben Sie die folgende Kusto-Abfrage ein, und wählen Sie anschließend die Option Ausführen aus. Sie erhalten einen Wert, der angibt, wie oft die neue Eigenschaft ausgeführt wurde:
```
customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
| summarize count() by MyImportantProperty
```

Um Details anstelle der Anzahl anzuzeigen, entfernen Sie die letzte Zeile, und führen Sie die Abfrage erneut aus:

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

Hinzufügen neuer Ereignisse mit benutzerdefinierten Eigenschaften

Falls Sie Daten unter einem anderen Ereignis als QnaMessage protokollieren müssen, können Sie ein eigenes benutzerdefiniertes Ereignis mit eigenen Eigenschaften erstellen. Zu diesem Zweck fügen wir wie folgt Code am Ende der MyQnAMaker Klasse hinzu:

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-Dashboard

Wenn Sie eine Application Insights-Ressource in Azure erstellen, erstellt Azure eine neue Dashboard, die Ihrer Ressource zugeordnet ist. Um die Dashboard auf dem Blatt Application Insights anzuzeigen, wählen Sie Anwendungsdashboard aus.

Wechseln Sie alternativ zum Anzeigen der Daten zum Azure-Portal, erweitern Sie das Portalmenü, und wählen Sie dann Dashboard aus. Wählen Sie dann im Dropdownmenü die gewünschte Dashboard aus.

Die Dashboard zeigt einige Standardinformationen zur Botleistung und alle anderen Abfragen an, die Sie an Ihre Dashboard angeheftet haben.

Hinzufügen von Telemetriedaten zu Ihrem QnA Maker-Bot

Voraussetzungen

Hinzufügen von Telemetriecode zu Ihrem QnA Maker-Bot

Aktivieren von Telemetriedaten zum Erfassen von Nutzungsdaten aus dem QnA Maker-Dienst

Aktivieren der QnA Maker-Standardprotokollierung

Anzeigen von Telemetriedaten, die von den QnA Maker-Standardeinträgen protokolliert wurden

Ändern oder Erweitern von Standardereigniseigenschaften

Hinzufügen von Eigenschaften

Anzeigen von Telemetriedaten, die über die neue Eigenschaft MyImportantProperty protokolliert wurden

Hinzufügen neuer Ereignisse mit benutzerdefinierten Eigenschaften

Application Insights-Dashboard

Zusätzliche Informationen

Zusätzliche Ressourcen