Megosztás a következőn keresztül:

Telemetria hozzáadása a QnA Maker-robothoz

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Megjegyzés

Az Azure AI QnA Maker 2025. március 31-én megszűnik. 2022. október 1-től nem hozhat létre új QnA Maker-erőforrásokat vagy tudásbázisokat. A kérdés- és válaszképesség újabb verziója már elérhető az Azure AI Language részeként.

Az Egyéni kérdések megválaszolása, az Azure AI Language egyik funkciója a QnA Maker szolgáltatás frissített verziója. A Bot Framework SDK kérdés-válasz támogatásával kapcsolatos további információkért lásd: Természetes nyelvfelismerés.

A telemetriai naplózás lehetővé teszi, hogy a robotalkalmazások eseményadatokat küldjenek a telemetriai szolgáltatásoknak, például az Application Insightsnak. A telemetriai adatok betekintést nyújtanak a robotba azáltal, hogy bemutatják, mely funkciókat használják a leggyakrabban, észleli a nemkívánatos viselkedést, és betekintést nyújt a rendelkezésre állásba, a teljesítménybe és a használatba.

A TelemetryLoggerMiddleware Bot Framework SDK és QnAMaker osztályai engedélyezik a telemetriai naplózást a QnA Maker-kompatibilis robotokban. TelemetryLoggerMiddleware köztes szoftver összetevő, amely minden alkalommal naplózza a telemetriát, amikor üzenetek érkeznek, küldenek, frissítenek vagy törölnek, és az QnAMaker osztály egyéni naplózást biztosít, amely kibővíti a telemetriai képességeket.

Ebben a cikkben az alábbiakat ismerheti meg:

  • A robot telemetriai adatainak beírásához szükséges kód
  • A beépített QnA Maker naplózásának és a standard eseménytulajdonságokat használó jelentések engedélyezéséhez szükséges kód.
  • Az SDK alapértelmezett eseménytulajdonságainak módosítása vagy kiterjesztése a jelentéskészítési igények széles körének lehetővé tétele érdekében.

Előfeltételek

Megjegyzés

Ez a cikk a QnA Maker mintakódjára épül, és végigvezeti a telemetriai adatok beépítéséhez szükséges lépéseken.

Telemetriakód hozzáadása a QnA Maker-robothoz

A QnA Maker mintaalkalmazással kezdjük, és hozzáadjuk a telemetriai adatok QnA Maker szolgáltatást használó robotba való integrálásához szükséges kódot. Ez lehetővé teszi az Application Insights számára a kérések nyomon követését.

  1. Nyissa meg a QnA Maker mintaalkalmazást a Visual Studióban.

  2. Adja hozzá a(z) Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet-csomagot. További információ a NuGet használatáról: Csomagok telepítése és kezelése a Visual Studióban:

  3. Adja meg a következő utasításokat a következőben Startup.cs:

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

    Megjegyzés

    Ha a QnA Maker mintakódjának frissítésével követi a műveletet, észreveheti, hogy a QnA Maker-mintában már létezik a using utasítás Microsoft.Bot.Builder.Integration.AspNet.Core .

  4. Adja hozzá a következő kódot a metódushoz a ConfigureServices() következőben: Startup.cs. Ez elérhetővé teszi a telemetriai szolgáltatásokat a robot számára függőséginjektáláson (DI) keresztül:

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

    Megjegyzés

    Ha a QnA Maker mintakódjának frissítésével követi a műveletet, észre fogja venni, hogy services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); már létezik.

  5. Utasítsa az adaptert, hogy használja a metódushoz ConfigureServices() hozzáadott köztes szoftverkódot. Nyissa meg AdapterWithErrorHandler.cs és adja hozzá IMiddleware middleware a konstruktorok paraméterlistájához. Adja hozzá az Use(middleware); utasítást a konstruktor utolsó soraként:

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

    Use(middleware);
}

  6. Adja hozzá az Application Insights eszközkulcsot a appsettings.json fájlhoz. A appsettings.json fájl metaadatokat tartalmaz a robot által a futtatás során használt külső szolgáltatásokról, például a Cosmos DB, az Application Insights és a QnA Maker kapcsolatáról és metaadatairól. A fájlnak appsettings.json a következő formátumban kell lennie:

    {
    "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"
    }
}

    Megjegyzés

Ezen a ponton az Application Insights használatával végzett a telemetriai adatok engedélyezésére vonatkozó előzetes munka. A robotot helyileg futtathatja a Bot Framework Emulator, majd az Application Insightsban megtekintheti a naplózott adatokat, például a válaszidőt, az alkalmazás általános állapotát és az általános futtatási információkat.

Tipp

További információ a személyes adatokról: Tevékenységesemények és személyes adatok naplózásának engedélyezése vagy letiltása.

A következő lépésben látni fogjuk, hogy mit kell tartalmaznia ahhoz, hogy telemetriai funkciókat adjon hozzá a QnA Maker szolgáltatáshoz.

Telemetria engedélyezése a QnA Maker szolgáltatás használati adatainak rögzítéséhez

A QnA Maker szolgáltatás beépített telemetriai naplózással rendelkezik, ezért nem sok teendője van a telemetriai adatok QnA Makerből való lekéréséhez. Először látni fogjuk, hogyan építhet be telemetriát a QnA Maker-kódba a beépített telemetriai naplózás engedélyezéséhez, majd megtudhatja, hogyan cserélhet le vagy adhat hozzá tulajdonságokat a meglévő eseményadatokhoz a jelentéskészítési igények széles körének kielégítése érdekében.

Alapértelmezett QnA Maker-naplózás engedélyezése

  1. Hozzon létre egy privát írásvédett típusú IBotTelemetryClient mezőt az osztályban a QnABot következőben QnABot.cs:

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

  2. Adjon hozzá egy paramétert IBotTelemetryClient az QnABot osztálykonstruktorhoz, QnABot.cs és rendelje hozzá annak értékét az előző lépésben létrehozott privát mezőhöz:

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

  3. A telemetryClient paraméterre az új QnAMaker-objektum példányosításakor van szükség a következőben QnABot.cs:

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

    Tipp

    Győződjön meg arról, hogy a bejegyzésekben _configuration használt tulajdonságnevek megegyeznek az AppSettings.json fájlban használt tulajdonságnevekkel, és a tulajdonságok értékei a QnA Maker portálJának Saját tudásbázisok lapján található Kód megtekintése gombra kattintva érhetők el:

    Ábra arról, hogy hol találhatók az alkalmazásbeállítások a LUIS-portálon.

A QnA Maker alapértelmezett bejegyzéseiből naplózott telemetriai adatok megtekintése

A QnA Maker robothasználatának eredményeit az Application Insightsban tekintheti meg, miután futtatta a robotot a Bot Framework Emulator a következő lépésekkel:

  1. A Azure Portal lépjen a robot Application Insights-erőforrására.

  2. A Figyelés területen válassza a Naplók lehetőséget.

  3. Adja meg a következő Kusto-lekérdezést, majd válassza a Futtatás lehetőséget.

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

  4. Hagyja nyitva ezt a lapot a böngészőben; egy új egyéni tulajdonság hozzáadása után visszatérünk hozzá.

Tipp

Ha még nem ismeri a Kusto lekérdezési nyelvét, amely napló lekérdezések írására szolgál az Azure Monitorban, de ismeri az SQL lekérdezési nyelvét, hasznosnak találhatja az SQL-ről az Azure Monitor-napló lekérdezésére vonatkozó csalilapot .

Alapértelmezett eseménytulajdonságok módosítása vagy kiterjesztése

Ha olyan tulajdonságokra van szüksége, amelyek nincsenek definiálva az QnAMaker osztályban, kétféleképpen kezelhetők, mindkettőhöz létre kell hoznia az QnAMaker osztályból származtatott saját osztályt. Az elsőt a Tulajdonságok hozzáadása című szakaszban ismertetjük, amelyben tulajdonságokat ad hozzá a meglévő QnAMessage eseményhez. A második módszer lehetővé teszi új események létrehozását, amelyekhez tulajdonságokat adhat hozzá az Új események hozzáadása egyéni tulajdonságokkal című témakörben leírtak szerint.

Megjegyzés

Az QnAMessage esemény a Bot Framework SDK része, és biztosítja az Application Insightsba naplózott összes beépített eseménytulajdonságt.

Tulajdonságok hozzáadása

Az alábbiak bemutatják, hogyan származtatható az QnAMaker osztályból. A példában a "MyImportantProperty" tulajdonság hozzáadása az QnAMessage eseményhez. A QnAMessage rendszer minden alkalommal naplózza az eseményt, amikor QnA GetAnswers-hívást hajtanak végre.

Miután megtanultuk, hogyan adhatunk hozzá egyéni tulajdonságokat, megtudhatjuk, hogyan hozhatunk létre új egyéni eseményt, és társíthatunk hozzá tulajdonságokat, majd helyileg futtatjuk a robotot a Bot Framework Emulator használatával, és megvizsgáljuk, hogy mi van bejelentkezve az Application Insightsban a Kusto lekérdezési nyelv használatával.

  1. Hozzon létre egy új nevű osztályt MyQnAMaker a Microsoft.BotBuilderSamples névtérben, amely örökli az QnAMaker osztályt, és mentse a következő néven MyQnAMaker.cs: . Az osztálytól való QnAMaker öröklődéshez hozzá kell adnia a using utasítást Microsoft.Bot.Builder.AI.QnA . A kódnak a következőképpen kell megjelennie:

    using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}

  2. Adjon hozzá egy osztálykonstruktort a fájlhoz MyQnAMaker. A és Microsoft.Bot.Builderkonstruktorparamétereihez további két utasításra System.Net.Http lesz szüksége:

    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. Adja hozzá az új tulajdonságot a QnAMessage eseményhez a konstruktor után, és adja meg a következő utasításokat System.Collections.Generic: , System.Threading, és 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. Módosítsa a robotot úgy, hogy az új osztályt használja, ahelyett, hogy MyQnAMaker létrehoz egy QnAMaker objektumot a következőbenQnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
Az új MyImportantProperty tulajdonságból naplózott telemetriai adatok megtekintése

Miután futtatta a robotot az Emulatorban, az eredményeket az Application Insightsban az alábbi módon tekintheti meg:

  1. Váltson vissza arra a böngészőre, amely a Naplók (Elemzések) nézetet aktívként jeleníti meg.

  2. Adja meg a következő Kusto-lekérdezést, majd válassza a Futtatás lehetőséget. Ez megadja az új tulajdonság végrehajtásának számát:

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

  3. Ha a darabszám helyett a részleteket szeretné megjeleníteni, távolítsa el az utolsó sort, és futtassa újra a lekérdezést:

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

Új események hozzáadása egyéni tulajdonságokkal

Ha egy másik eseménybe QnaMessagekell naplóznia az adatokat, létrehozhatja saját egyéni eseményét a saját tulajdonságaival. Ehhez kódot adunk hozzá az osztály végéhez az MyQnAMaker alábbiak szerint:

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

}

Az Application Insights irányítópultja

Amikor létrehoz egy Application Insights-erőforrást az Azure-ban, az Azure létrehoz egy új irányítópultot az erőforráshoz társítva. Ha meg szeretné jeleníteni az irányítópultot az Application Insights panelen, válassza az Alkalmazás irányítópultja lehetőséget.

Másik lehetőségként az adatok megtekintéséhez lépjen a Azure Portal, bontsa ki a portál menüjét, majd válassza az Irányítópult lehetőséget. Ezután válassza ki a kívánt irányítópultot a legördülő menüből.

Az irányítópult megjeleníti a robot teljesítményével és az irányítópultra rögzített többi lekérdezésével kapcsolatos alapértelmezett információkat.

További információ