Menambahkan telemetri ke bot QnA Maker Anda

Artikel
03/08/2023

BERLAKU UNTUK: SDK v4

Catatan

Azure AI QnA Maker akan dihentikan pada 31 Maret 2025. Mulai 1 Oktober 2022, Anda tidak akan dapat membuat sumber daya atau pangkalan pengetahuan QnA Maker baru. Versi yang lebih baru dari kemampuan pertanyaan dan jawaban sekarang tersedia sebagai bagian dari Bahasa Azure AI.

Jawaban atas pertanyaan kustom, fitur Bahasa Azure AI, adalah versi terbaru dari layanan QnA Maker. Untuk informasi selengkapnya tentang dukungan tanya jawab di Bot Framework SDK, lihat Pemahaman bahasa alami.

Pengelogan telemetri memungkinkan aplikasi bot mengirim data peristiwa ke layanan telemetri seperti Application Insights. Telemetri menawarkan wawasan tentang bot Anda dengan menunjukkan fitur mana yang paling banyak digunakan, mendeteksi perilaku yang tidak diinginkan dan menawarkan visibilitas ke dalam ketersediaan, performa, dan penggunaan.

Kelas TelemetryLoggerMiddleware dan QnAMaker di Bot Framework SDK memungkinkan pengelogan telemetri di bot yang diaktifkan QnA Maker. TelemetryLoggerMiddleware adalah komponen middleware yang mencatat telemetri setiap kali pesan diterima, dikirim, diperbarui, atau dihapus, dan QnAMaker kelas menyediakan pengelogan kustom yang memperluas kemampuan telemetri.

Dalam artikel ini Anda akan mempelajari tentang:

Kode yang diperlukan untuk menyambungkan telemetri di bot Anda
Kode yang diperlukan untuk mengaktifkan pengelogan dan laporan QnA Maker di luar kotak yang menggunakan properti peristiwa standar.
Memodifikasi atau memperluas properti peristiwa default SDK untuk memungkinkan berbagai kebutuhan pelaporan.

Prasyarat

Kode sampel QnA Maker
Langganan Ke Microsoft Azure
Kunci Application Insights
Pemahaman tentang QnA Maker sangat membantu.
Akun QnA Maker .
Pangkalan Pengetahuan QnA Maker yang sudah ada dan diterbitkan.

Catatan

Artikel ini dibuat berdasarkan kode sampel QnA Maker dengan melangkah Anda melalui langkah-langkah yang diperlukan untuk menggabungkan telemetri.

Menambahkan kode telemetri ke bot QnA Maker Anda

Kita akan mulai dengan aplikasi sampel QnA Maker dan menambahkan kode yang diperlukan untuk mengintegrasikan telemetri ke dalam bot yang menggunakan layanan QnA Maker. Ini akan memungkinkan Application Insights untuk melacak permintaan.

Buka aplikasi sampel QnA Maker di Visual Studio.
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core Tambahkan paket NuGet. Untuk informasi selengkapnya tentang menggunakan NuGet, lihat Menginstal dan mengelola paket di Visual Studio:
Sertakan pernyataan berikut dalam Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Catatan

Jika Anda mengikuti dengan memperbarui kode sampel QnA Maker, Anda akan melihat bahwa pernyataan penggunaan untuk Microsoft.Bot.Builder.Integration.AspNet.Core sudah ada dalam sampel QnA Maker.

Tambahkan kode berikut ke ConfigureServices() metode di Startup.cs. Ini membuat layanan telemetri tersedia untuk bot Anda melalui injeksi dependensi (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>();
    ...
}

Catatan

Jika Anda mengikuti dengan memperbarui kode sampel QnA Maker, Anda akan melihat bahwa services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); sudah ada.

Instruksikan adaptor untuk menggunakan kode middleware yang ditambahkan ke ConfigureServices() metode . Buka AdapterWithErrorHandler.cs dan tambahkan IMiddleware middleware ke daftar parameter konstruktor. Use(middleware); Tambahkan pernyataan sebagai baris terakhir dalam konstruktor:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Tambahkan kunci instrumentasi Application Insights di file Anda appsettings.json . File appsettings.json berisi metadata tentang layanan eksternal yang digunakan bot saat berjalan, seperti koneksi dan metadata untuk Cosmos DB, Application Insights, dan QnA Maker. Penambahan ke file Anda appsettings.json harus dalam format ini:
```
{
    "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"
    }
}
```
Catatan
- Detail tentang mendapatkan kunci instrumentasi Application Insights dapat ditemukan dalam artikel kunci Application Insights.
- Anda harus sudah memiliki akun QnA Maker. Untuk informasi tentang mendapatkan ID Pangkalan Pengetahuan QnA Maker, kunci titik akhir, dan nilai host, lihat bagian Terbitkan untuk mendapatkan titik akhir GenerateAnswer dari QnA Maker's Dapatkan jawaban dengan artikel API GenerateAnswer.

Pada titik ini, pekerjaan awal untuk mengaktifkan telemetri menggunakan Application Insights dilakukan. Anda dapat menjalankan bot secara lokal menggunakan Emulator Kerangka Kerja Bot lalu masuk ke Application Insights untuk melihat apa yang sedang dicatat seperti waktu respons, kesehatan aplikasi secara keseluruhan, dan informasi yang berjalan secara umum.

Tip

Untuk informasi tentang informasi pribadi, lihat Mengaktifkan atau menonaktifkan peristiwa aktivitas dan pengelogan informasi pribadi.

Selanjutnya kita akan melihat apa yang perlu disertakan untuk menambahkan fungsionalitas telemetri ke layanan QnA Maker.

Mengaktifkan telemetri untuk mengambil data penggunaan dari layanan QnA Maker

Layanan QnA Maker memiliki pencatatan telemetri bawaan yang tersedia, jadi ada sedikit yang perlu Anda lakukan untuk mulai mendapatkan data telemetri dari QnA Maker. Pertama kita akan melihat cara menggabungkan telemetri ke dalam kode QnA Maker untuk mengaktifkan pengelogan telemetri bawaan, lalu kita akan mempelajari cara mengganti atau menambahkan properti ke data peristiwa yang ada untuk memenuhi berbagai kebutuhan pelaporan.

Aktifkan pengelogan QnA Maker default

Buat bidang jenis IBotTelemetryClient readonly privat di kelas Anda QnABot di QnABot.cs:

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

IBotTelemetryClient Tambahkan parameter ke konstruktor kelas Anda QnABot di QnABot.cs dan tetapkan nilainya ke bidang privat yang dibuat di langkah sebelumnya:

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

Parameter telemetryClient diperlukan saat membuat instans objek QnAMaker baru di QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Tip

Pastikan bahwa nama properti yang Anda gunakan dalam _configuration entri cocok dengan nama properti yang Anda gunakan di file AppSettings.json dan nilai untuk properti tersebut diperoleh dengan memilih tombol Tampilkan Kode pada halaman Pangkalan pengetahuan saya di portal QnA Maker:

Menampilkan data telemetri yang dicatat dari entri default QnA Maker

Anda dapat melihat hasil penggunaan bot QnA Maker anda di Application Insights setelah menjalankan bot Anda di Bot Framework Emulator dengan mengambil langkah-langkah berikut:

Di portal Azure, buka sumber daya Application Insights untuk bot Anda.
Di bawah Pemantauan, pilih Log.

Masukkan kueri Kusto berikut, lalu pilih Jalankan.

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

Biarkan halaman ini terbuka di browser Anda; kita akan kembali ke dalamnya setelah menambahkan properti kustom baru.

Tip

Jika Anda baru menggunakan bahasa kueri Kusto yang digunakan untuk menulis kueri log di Azure Monitor, tetapi terbiasa dengan bahasa kueri SQL, Anda mungkin menemukan referensi cepat kueri log SQL ke Azure Monitor berguna.

Mengubah atau memperluas properti peristiwa default

Jika Anda memerlukan properti yang tidak didefinisikan di QnAMaker kelas ada dua cara menangani ini, keduanya memerlukan pembuatan kelas Anda sendiri yang berasal dari QnAMaker kelas . Yang pertama dijelaskan di bagian di bawah ini berjudul Menambahkan properti tempat Anda menambahkan properti ke peristiwa yang ada QnAMessage . Metode kedua memungkinkan Anda membuat peristiwa baru tempat Anda dapat menambahkan properti seperti yang dijelaskan dalam Menambahkan peristiwa baru dengan properti kustom.

Catatan

Peristiwa ini QnAMessage adalah bagian dari Bot Framework SDK dan menyediakan semua properti peristiwa siap pakai yang dicatat ke Application Insights.

Menambahkan properti

Berikut ini menunjukkan bagaimana Anda dapat memperoleh dari QnAMaker kelas . Contoh menunjukkan penambahan properti "MyImportantProperty" ke QnAMessage acara. Peristiwa QnAMessage dicatat setiap kali panggilan QnA GetAnswers dilakukan.

Setelah mempelajari cara menambahkan properti kustom, kita akan mempelajari cara membuat peristiwa kustom baru dan mengaitkan properti dengannya, maka kita akan menjalankan bot secara lokal menggunakan Emulator Kerangka Kerja Bot dan melihat apa yang sedang dicatat di Application Insights menggunakan bahasa kueri Kusto.

Buat kelas baru bernama MyQnAMaker di Microsoft.BotBuilderSamples namespace layanan yang mewarisi dari QnAMaker kelas dan simpan sebagai MyQnAMaker.cs. Untuk mewarisi dari QnAMaker kelas , Anda harus menambahkan Microsoft.Bot.Builder.AI.QnA pernyataan penggunaan. Kode Anda akan muncul sebagai berikut:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Tambahkan konstruktor kelas ke MyQnAMaker. Anda akan memerlukan dua pernyataan penggunaan lagi untuk parameter konstruktor untuk System.Net.Http dan 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)
        {

        }
    }
}

Tambahkan properti baru ke peristiwa QnAMessage setelah konstruktor dan sertakan pernyataan System.Collections.Generic, , System.Threadingdan 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
                            );
        }

    }
}

Ubah bot Anda untuk menggunakan kelas baru, alih-alih membuat objek, QnAMaker Anda akan membuat MyQnAMaker objek di QnABot.cs:

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

Menampilkan data telemetri yang dicatat dari properti baru MyImportantProperty

Setelah menjalankan bot di Emulator, Anda dapat melihat hasilnya di Application Insights dengan melakukan hal berikut:

Beralih kembali ke browser Anda yang memiliki tampilan Log (Analitik) aktif.

Masukkan kueri Kusto berikut lalu pilih Jalankan. Ini akan memberikan hitungan berapa kali properti baru dijalankan:

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

Untuk memperlihatkan detail alih-alih hitungan, hapus baris terakhir dan jalankan ulang kueri:

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

Menambahkan peristiwa baru dengan properti kustom

Jika Anda perlu mencatat data ke peristiwa yang berbeda dari QnaMessage, Anda dapat membuat peristiwa kustom Anda sendiri dengan propertinya sendiri. Untuk melakukan ini, kita akan menambahkan kode ke akhir MyQnAMaker kelas sebagai berikut:

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

}

Dasbor Application Insights

Setiap kali Anda membuat sumber daya Application Insights di Azure, Azure membuat dasbor baru yang terkait dengan sumber daya Anda. Untuk menampilkan dasbor dari bilah Application Insights, pilih Dasbor Aplikasi.

Atau, untuk melihat data, buka portal Azure, perluas menu portal, lalu pilih Dasbor. Kemudian, pilih dasbor yang Anda inginkan dari menu drop-down.

Dasbor menampilkan beberapa informasi default tentang performa bot Anda dan kueri lain yang telah Anda sematkan ke dasbor Anda.

Bagikan melalui

Menambahkan telemetri ke bot QnA Maker Anda

Prasyarat

Menambahkan kode telemetri ke bot QnA Maker Anda

Mengaktifkan telemetri untuk mengambil data penggunaan dari layanan QnA Maker

Aktifkan pengelogan QnA Maker default

Menampilkan data telemetri yang dicatat dari entri default QnA Maker

Mengubah atau memperluas properti peristiwa default

Menambahkan properti

Menampilkan data telemetri yang dicatat dari properti baru MyImportantProperty

Menambahkan peristiwa baru dengan properti kustom

Dasbor Application Insights

Informasi Tambahan

Sumber Daya Tambahan: