Přidání telemetrie do robota služby QnA Maker

Článek
07/20/2023

PLATÍ PRO: SDK v4

Poznámka

Služba Azure AI QnA Maker bude 31. března 2025 vyřazena. Od 1. října 2022 nebudete moct vytvářet nové prostředky nebo znalostní báze služby QnA Maker. Jako součást jazyka Azure AI je teď k dispozici novější verze funkce pro otázky a odpovědi.

Vlastní odpovídání na otázky, funkce jazyka Azure AI, je aktualizovaná verze služby QnA Maker. Další informace o podpoře otázek a odpovědí v sadě Sdk pro Bot Framework najdete v tématu Principy přirozeného jazyka.

Protokolování telemetrie umožňuje aplikacím robotů odesílat data událostí do telemetrických služeb, jako je Application Insights. Telemetrie nabízí přehled o robotovi tím, že ukazuje, které funkce se používají nejčastěji, detekuje nežádoucí chování a nabízí přehled o dostupnosti, výkonu a využití.

Třídy TelemetryLoggerMiddleware a QnAMaker v sadě Bot Framework SDK umožňují protokolování telemetrie v robotech s podporou služby QnA Maker. TelemetryLoggerMiddleware je komponenta middlewaru, která protokoluje telemetrii při každém přijetí, odesílání, aktualizaci nebo odstranění zpráv a třída QnAMaker poskytuje vlastní protokolování, které rozšiřuje možnosti telemetrie.

V tomto článku se dozvíte o:

Kód potřebný k připojení telemetrie v robotovi
Kód potřebný k povolení předpřijeného protokolování služby QnA Maker a sestav, které používají standardní vlastnosti událostí.
Úprava nebo rozšíření výchozích vlastností událostí sady SDK za účelem zajištění široké škály požadavků na vytváření sestav.

Požadavky

Ukázkový kód služby QnA Maker
Předplatné Microsoft Azure
Klíč Application Insights
Znalost služby QnA Maker je užitečná.
Účet služby QnA Maker .
Existující a publikovaná znalostní báze služby QnA Maker.

Poznámka

Tento článek vychází z ukázkového kódu služby QnA Maker tím, že vás provede kroky potřebnými k začlenění telemetrie.

Přidání kódu telemetrie do robota služby QnA Maker

Začneme ukázkovou aplikací QnA Maker a přidáme kód potřebný k integraci telemetrie do robota, který používá službu QnA Maker. To službě Application Insights umožní sledovat žádosti.

Otevřete ukázkovou aplikaci QnA Maker v sadě Visual Studio.
Přidejte balíček NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Další informace o používání NuGetu najdete v tématu Instalace a správa balíčků v sadě Visual Studio:
Do příkazu zahrňte následující příkazy Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Poznámka

Pokud postupujete aktualizací ukázkového kódu služby QnA Maker, všimněte si, že příkaz using pro Microsoft.Bot.Builder.Integration.AspNet.Core už v ukázce služby QnA Maker existuje.

Do metody v Startup.cssouboru přidejte následující kódConfigureServices(). Tím robotovi zpřístupníte telemetrické služby prostřednictvím injektáže závislostí (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>();
    ...
}

Poznámka

Pokud postupujete aktualizací ukázkového kódu služby QnA Maker, všimněte si, že services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); už existuje.

Požádejte adaptér, aby použil kód middlewaru ConfigureServices() , který byl přidán do metody. Otevřete AdapterWithErrorHandler.cs seznam parametrů konstruktorů a přidejte IMiddleware middleware ho do seznamu parametrů. Use(middleware); Přidejte příkaz jako poslední řádek v konstruktoru:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Přidejte do souboru instrumentační klíč appsettings.json Application Insights. Soubor appsettings.json obsahuje metadata o externích službách, které robot používá při spuštění, například připojení a metadata pro Cosmos DB, Application Insights a QnA Maker. Přidání souboru appsettings.json musí být v tomto formátu:
```
{
    "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"
    }
}
```
Poznámka
- Podrobnosti o získání instrumentačního klíče Application Insights najdete v článku Klíče Application Insights.
- Už byste měli mít účet služby QnA Maker. Informace o získání ID znalostní báze služby QnA Maker, klíče koncového bodu a hodnot hostitele najdete v části Publikování pro získání koncového bodu GenerateAnswer v článku Získání odpovědi pomocí rozhraní API GenerateAnswer ve službě QnA Maker.

V tomto okamžiku jsou hotové předběžné práce na povolení telemetrie pomocí Application Insights. Robota můžete spustit místně pomocí Bot Framework Emulator a pak přejít do Application Insights a zjistit, co se protokoluje, jako je doba odezvy, celkový stav aplikace a obecné informace o spuštění.

Tip

Informace o osobních údaji najdete v tématu Povolení nebo zakázání protokolování událostí aktivit a osobních údajů.

Dále uvidíme, co je potřeba zahrnout, aby bylo možné přidat telemetrické funkce do služby QnA Maker.

Povolení telemetrie pro zachycení dat o využití ze služby QnA Maker

Služba QnA Maker má k dispozici integrované protokolování telemetrie, takže je potřeba udělat jen málo, abyste mohli začít získávat telemetrická data z QnA Makeru. Nejprve se podíváme, jak začlenit telemetrii do kódu služby QnA Maker, aby se umožnilo integrované protokolování telemetrie, a pak se dozvíme, jak nahradit nebo přidat vlastnosti do existujících dat událostí, aby se splnila široká škála potřeb generování sestav.

Povolení výchozího protokolování služby QnA Maker

Vytvořte privátní pole typu IBotTelemetryClient jen pro čtení ve třídě QnABot v nástroji QnABot.cs:

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

IBotTelemetryClient Přidejte parametr do konstruktoru QnABot třídy v QnABot.cs a přiřaďte jeho hodnotu k privátnímu poli vytvořenému v předchozím kroku:

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

Parametr telemetryClient se vyžaduje při vytváření instance nového objektu QnAMaker v QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Tip

Ujistěte se, že názvy vlastností, které používáte v _configuration položkách, odpovídají názvům vlastností, které jste použili v souboru AppSettings.json, a že hodnoty těchto vlastností jsou získány výběrem tlačítka Zobrazit kód na stránce Moje znalostní báze na portálu služby QnA Maker:

Zobrazení telemetrických dat protokolovaných z výchozích položek služby QnA Maker

Výsledky využití robota služby QnA Maker můžete zobrazit v Application Insights po spuštění robota v Bot Framework Emulator provedením následujících kroků:

V Azure Portal přejděte k prostředku Application Insights pro vašeho robota.
V části Monitorování vyberte Protokoly.

Zadejte následující dotaz Kusto a pak vyberte Spustit.

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

Nechte tuto stránku otevřenou v prohlížeči; Po přidání nové vlastní vlastnosti se k němu vrátíme.

Tip

Pokud s dotazovacím jazykem Kusto, který se používá k zápisu dotazů na protokoly ve službě Azure Monitor, ale máte zkušenosti s dotazovacím jazykem SQL, může se vám pomoct tahák dotazu protokolu SQL na Azure Monitor .

Úprava nebo rozšíření výchozích vlastností událostí

Pokud potřebujete vlastnosti, které nejsou definovány ve QnAMaker třídě, existují dva způsoby, jak to zpracovat, oba vyžadují vytvoření vlastní třídy odvozené z QnAMaker třídy. První je vysvětlená v části níže s názvem Přidání vlastností , ve kterých přidáváte vlastnosti do existující QnAMessage události. Druhá metoda umožňuje vytvořit nové události, do kterých můžete přidat vlastnosti, jak je popsáno v tématu Přidání nových událostí s vlastními vlastnostmi.

Poznámka

Událost QnAMessage je součástí sady Bot Framework SDK a poskytuje všechny předefinované vlastnosti událostí, které se protokolují do Application Insights.

Přidání vlastností

Následující ukazuje, jak můžete odvodit z QnAMaker třídy. Příklad ukazuje přidání vlastnosti "MyImportantProperty" k QnAMessage události. Událost se QnAMessage protokoluje při každém volání QnA GetAnswers .

Až se naučíme přidávat vlastní vlastnosti, naučíme se vytvořit novou vlastní událost a přidružit k ní vlastnosti, pak robota spustíme místně pomocí Bot Framework Emulator a zjistíme, co se protokoluje v Application Insights pomocí dotazovacího jazyka Kusto.

Vytvořte novou třídu s názvem MyQnAMaker v Microsoft.BotBuilderSamples oboru názvů, který dědí z QnAMaker třídy, a uložte ji jako MyQnAMaker.cs. Pokud chcete dědit z QnAMaker třídy, budete muset přidat Microsoft.Bot.Builder.AI.QnA příkaz using. Váš kód by se měl zobrazit takto:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Přidejte konstruktor třídy do MyQnAMaker. Budete potřebovat další dva příkazy using pro parametry konstruktoru pro System.Net.Http a 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)
        {

        }
    }
}

Přidejte novou vlastnost do události QnAMessage za konstruktor a zahrňte příkazy System.Collections.Generic, System.Threadinga 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
                            );
        }

    }
}

Upravte robota tak, aby používal novou třídu. Místo vytvoření objektu QnAMakerMyQnAMaker vytvoříte objekt v QnABot.cs:

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

Zobrazení telemetrických dat protokolovaných z nové vlastnosti MyImportantProperty

Po spuštění robota v emulátoru můžete zobrazit výsledky v Application Insights takto:

Přepněte zpět do prohlížeče, který má aktivní zobrazení Protokoly (Analytics).

Zadejte následující dotaz Kusto a pak vyberte Spustit. Tím se zobrazí počet spuštění nové vlastnosti:

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

Pokud chcete místo počtu zobrazit podrobnosti, odeberte poslední řádek a spusťte dotaz znovu:

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

Přidání nových událostí s vlastními vlastnostmi

Pokud potřebujete protokolovat data k jiné události než QnaMessage, můžete vytvořit vlastní událost s vlastními vlastnostmi. Za tímto účelem přidáme kód na konec MyQnAMaker třídy následujícím způsobem:

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

}

Řídicí panel Application Insights

Kdykoli vytvoříte prostředek Application Insights v Azure, Azure vytvoří nový řídicí panel přidružený k vašemu prostředku. Pokud chcete zobrazit řídicí panel v okně Application Insights, vyberte Řídicí panel aplikace.

Případně můžete data zobrazit tak, že přejdete na Azure Portal, rozbalíte nabídku portálu a vyberete Řídicí panel. Potom v rozevírací nabídce vyberte požadovaný řídicí panel.

Na řídicím panelu se zobrazí některé výchozí informace o výkonu robota a všechny další dotazy, které jste na řídicí panel připnuli.

Přidání telemetrie do robota služby QnA Maker

Požadavky

Přidání kódu telemetrie do robota služby QnA Maker

Povolení telemetrie pro zachycení dat o využití ze služby QnA Maker

Povolení výchozího protokolování služby QnA Maker

Zobrazení telemetrických dat protokolovaných z výchozích položek služby QnA Maker

Úprava nebo rozšíření výchozích vlastností událostí

Přidání vlastností

Zobrazení telemetrických dat protokolovaných z nové vlastnosti MyImportantProperty

Přidání nových událostí s vlastními vlastnostmi

Řídicí panel Application Insights

Další informace

Další materiály