Soru-Cevap Oluşturma botunuza telemetri ekleme

Makale
03/08/2023

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Not

Azure AI Soru-Cevap Oluşturma 31 Mart 2025'te kullanımdan kaldırılacak. 1 Ekim 2022'de yeni Soru-Cevap Oluşturma kaynakları veya bilgi bankaları oluşturamayacaksınız. Soru ve yanıtlama özelliğinin daha yeni bir sürümü artık Azure AI Dili'nin bir parçası olarak kullanılabilir.

Azure Yapay Zeka Dilinin bir özelliği olan özel soru yanıtlama, Soru-Cevap Oluşturma hizmetinin güncelleştirilmiş sürümüdür. Bot Framework SDK'sında soru-cevap desteği hakkında daha fazla bilgi için bkz . Doğal dil anlama.

Telemetri günlüğü, bot uygulamalarının Application Insights gibi telemetri hizmetlerine olay verileri göndermesine olanak tanır. Telemetri en çok hangi özelliklerin kullanıldığını göstererek botunuzla ilgili içgörüler sunar, istenmeyen davranışları algılar ve kullanılabilirlik, performans ve kullanım hakkında görünürlük sağlar.

TelemetryLoggerMiddleware Bot Framework SDK'sı içindeki ve QnAMaker sınıfları, Soru-Cevap Oluşturma özellikli botlarda telemetri günlüğünü etkinleştirir. TelemetryLoggerMiddleware iletiler her alındığında, gönderildiğinde, güncelleştirildiğinde veya silindiğinde telemetriyi günlüğe kaydeden ve QnAMaker sınıfı telemetri özelliklerini genişleten özel günlükler sağlayan bir ara yazılım bileşenidir.

Bu makalede şunları öğreneceksiniz:

Botunuza telemetri göndermek için gereken kod
Hazır Soru-Cevap Oluşturma günlüğünü ve standart olay özelliklerini kullanan raporları etkinleştirmek için gereken kod.
Çok çeşitli raporlama gereksinimlerini etkinleştirmek için SDK'nın varsayılan olay özelliklerini değiştirme veya genişletme.

Önkoşullar

Soru-Cevap Oluşturma örnek kodu
Microsoft Azure aboneliği
Application Insights anahtarı
Soru-Cevap Oluşturma hakkında bilgi sahibi olması yararlı olacaktır.
Soru-Cevap Oluşturma hesabı.
Mevcut ve yayımlanmış bir Soru-Cevap Oluşturma bilgi bankası.

Not

Bu makalede, telemetriyi birleştirmek için gereken adımlarda size adım yol göstererek Soru-Cevap Oluşturma örnek kodu kullanılmaktadır.

Soru-Cevap Oluşturma botunuza telemetri kodu ekleme

Soru-Cevap Oluşturma örnek uygulamasıyla başlayacağız ve telemetriyi Soru-Cevap Oluşturma hizmetini kullanan bir botla tümleştirmek için gereken kodu ekleyeceğiz. Bu, Application Insights'ın istekleri izlemesini sağlar.

Visual Studio'da Soru-Cevap Oluşturma örnek uygulamasını açın.
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet paketini ekleyin. NuGet kullanma hakkında daha fazla bilgi için bkz. Visual Studio'da paketleri yükleme ve yönetme:
içinde aşağıdaki deyimleri Startup.csekleyin:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Not

Soru-Cevap Oluşturma örnek kodunu güncelleştirerek takip ediyorsanız, soru-cevap oluşturma örneğinde using Microsoft.Bot.Builder.Integration.AspNet.Core deyiminin zaten bulunduğunu fark edersiniz.

aşağıdaki kodu içindeki yöntemine ConfigureServices()Startup.csekleyin. Bu, telemetri hizmetlerini bağımlılık ekleme (DI) yoluyla botunuzun kullanımına sunar:

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

Not

Soru-Cevap Oluşturma örnek kodunu güncelleştirerek takip ediyorsanız zaten mevcut olduğunu services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); fark edeceksiniz.

Bağdaştırıcıya yöntemine eklenen ConfigureServices() ara yazılım kodunu kullanmasını sağlayın. öğesini açın AdapterWithErrorHandler.cs ve oluşturucular parametre listesine ekleyin IMiddleware middleware . deyimini Use(middleware); oluşturucuya son satır olarak ekleyin:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Dosyanıza appsettings.json Application Insights izleme anahtarını ekleyin. Dosya, appsettings.json Cosmos DB, Application Insights ve Soru-Cevap Oluşturma için bağlantı ve meta veriler gibi bot tarafından çalıştırılan dış hizmetlerle ilgili meta verileri içerir. Dosyanıza appsettings.json ekleme şu biçimde olmalıdır:
```
{
    "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"
    }
}
```
Not
- Application Insights izleme anahtarını almayla ilgili ayrıntılar Application Insights anahtarları makalesinde bulunabilir.
- Zaten bir Soru-Cevap Oluşturma hesabınız olmalıdır. Soru-Cevap Oluşturma bilgi bankası kimliği, uç nokta anahtarı ve konak değerlerini alma hakkında bilgi için Soru-Cevap Oluşturma'nın GenerateAnswer API'si ile yanıt alma makalesinin GenerateAnswer uç noktasını almak için yayımlama bölümüne bakın.

Bu noktada, Application Insights kullanarak telemetriyi etkinleştirmeye yönelik ön çalışma yapılır. botunuzu Bot Framework Emulator kullanarak yerel olarak çalıştırabilir ve ardından Application Insights'a giderek yanıt süresi, genel uygulama durumu ve genel çalışan bilgiler gibi günlüğe kaydedilenleri görebilirsiniz.

İpucu

Kişisel bilgiler hakkında bilgi için bkz . Etkinlik olayını ve kişisel bilgi günlüğünü etkinleştirme veya devre dışı bırakma.

Şimdi Soru-Cevap Oluşturma hizmetine telemetri işlevselliği eklemek için nelerin eklenmesi gerektiğini göreceğiz.

Soru-Cevap Oluşturma hizmetinden kullanım verilerini yakalamak için telemetriyi etkinleştirme

Soru-Cevap Oluşturma hizmetinde yerleşik telemetri günlüğü mevcuttur, bu nedenle Soru-Cevap Oluşturma'dan telemetri verilerini almaya başlamak için yapmanız gereken çok az şey vardır. İlk olarak yerleşik telemetri günlüğünü etkinleştirmek için Soru-Cevap Oluşturma koduna telemetriyi nasıl ekleyeceğinizi göreceğiz, ardından çok çeşitli raporlama gereksinimlerini karşılamak için mevcut olay verilerini değiştirmeyi veya mevcut olay verilerine özellikleri eklemeyi öğreneceğiz.

Varsayılan Soru-Cevap Oluşturma günlüğünü etkinleştirme

içindeki sınıfınızda QnABotQnABot.cstüründe IBotTelemetryClient bir özel salt okunur alan oluşturun:

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

içindeki QnABot.cs sınıf oluşturucunuza QnABot bir IBotTelemetryClient parametre ekleyin ve değerini önceki adımda oluşturulan özel alana atayın:

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

parametresi telemetryClient , içinde QnABot.csyeni QnAMaker nesnesi örneği oluşturulurken gereklidir:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
İpucu

Girişlerde _configuration kullandığınız özellik adlarının AppSettings.json dosyasında kullandığınız özellik adlarıyla eşleştiğinden ve bu özelliklerin değerlerinin Soru-Cevap Oluşturma portalındaki Bilgi bankalarım sayfasındaki Kodu Görüntüle düğmesi seçilerek elde edildiklerinden emin olun:

Soru-Cevap Oluşturma varsayılan girişlerinden günlüğe kaydedilen telemetri verilerini görüntüleme

Aşağıdaki adımları uygulayarak botunuzu Bot Framework Emulator çalıştırdıktan sonra Application Insights'ta Soru-Cevap Oluşturma botu kullanımınızın sonuçlarını görüntüleyebilirsiniz:

Azure portal botunuzun Application Insights kaynağına gidin.
İzleme'nin altında Günlükler'i seçin.

Aşağıdaki Kusto sorgusunu girin ve Çalıştır'ı seçin.

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

Bu sayfayı tarayıcınızda açık bırakın; yeni bir özel özellik ekledikten sonra bu özelliğe geri döneceğiz.

İpucu

Azure İzleyici'de günlük sorguları yazmak için kullanılan Kusto sorgu dili konusunda yeniyseniz ancak SQL sorgu dili hakkında bilgi sahibiyseniz SQL'den Azure İzleyici'ye günlük sorgusu hızlı başvuru sayfasını yararlı bulabilirsiniz.

Varsayılan olay özelliklerini değiştirme veya genişletme

Sınıfında tanımlanmayan özelliklere ihtiyacınız varsa, bunu işlemenin QnAMaker iki yolu vardır; her ikisi de sınıftan QnAMaker türetilmiş kendi sınıfınızı oluşturmayı gerektirir. İlki, mevcut QnAMessage olaya özellik eklediğiniz özellikleri ekleme başlıklı aşağıdaki bölümde açıklanmıştır. İkinci yöntem, Özel özelliklerle yeni olaylar ekleme bölümünde açıklandığı gibi özellikler ekleyebileceğiniz yeni olaylar oluşturmanıza olanak tanır.

Not

Olay QnAMessage , Bot Framework SDK'sının bir parçasıdır ve Application Insights'ta günlüğe kaydedilen tüm kullanıma açık olay özelliklerini sağlar.

Özellik ekleme

Aşağıda sınıfından nasıl türetebileceğiniz gösterilmektedir QnAMaker . Örnekte olaya "MyImportantProperty" özelliğinin eklenmesi gösterilmektedir QnAMessage . Soru-Cevap QnAMessageGetAnswers çağrısı her gerçekleştirildiğinde olay günlüğe kaydedilir.

Özel özellikleri eklemeyi öğrendikkten sonra yeni bir özel olay oluşturmayı ve özellikleri bununla ilişkilendirmeyi öğrenecek, ardından botu Bot Framework Emulator kullanarak yerel olarak çalıştıracak ve Kusto sorgu dilini kullanarak Application Insights'ta nelerin günlüğe kaydedildiğini göreceğiz.

sınıfından Microsoft.BotBuilderSamples devralan QnAMaker ad alanında adlı MyQnAMaker yeni bir sınıf oluşturun ve olarak MyQnAMaker.cskaydedin. sınıfından devralmak QnAMaker için using deyimini Microsoft.Bot.Builder.AI.QnA eklemeniz gerekir. Kodunuz aşağıdaki gibi görünmelidir:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

öğesine MyQnAMakerbir sınıf oluşturucu ekleyin. ve Microsoft.Bot.Builderiçin oluşturucu parametreleri System.Net.Http için iki using deyimi daha gerekir:

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

        }
    }
}

Oluşturucudan sonra QnAMessage olayına yeni özelliği ekleyin ve , System.Threadingve System.Threading.Tasksdeyimlerini System.Collections.Genericekleyin:

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

    }
}

botunuzu yeni sınıfı kullanacak şekilde değiştirin; nesne QnAMaker oluşturmak yerine içinde QnABot.csbir MyQnAMaker nesne oluşturacaksınız:

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

MyImportantProperty yeni özelliğinden günlüğe kaydedilen telemetri verilerini görüntüleme

Botunuzu Öykünücüde çalıştırdıktan sonra, aşağıdakileri yaparak Sonuçları Application Insights'ta görüntüleyebilirsiniz:

Günlükler (Analiz) görünümünün etkin olduğu tarayıcınıza geri dönün.

Aşağıdaki Kusto sorgusunu girin ve Çalıştır'ı seçin. Bu, yeni özelliğin kaç kez yürütüleceğini sayar:

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

Sayım yerine ayrıntıları göstermek için son satırı kaldırın ve sorguyu yeniden çalıştırın:

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

Özel özelliklerle yeni olaylar ekleme

Verileri değerinden QnaMessagefarklı bir olaya kaydetmeniz gerekiyorsa, kendi özellikleriyle kendi özel olayınızı oluşturabilirsiniz. Bunu yapmak için sınıfın sonuna MyQnAMaker aşağıdaki gibi kod ekleyeceğiz:

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 panosu

Azure'da bir Application Insights kaynağı oluşturduğunuzda, Azure kaynağınızla ilişkili yeni bir pano oluşturur. Application Insights dikey penceresindeki panoyu görüntülemek için Uygulama Panosu'nu seçin.

Alternatif olarak, verileri görüntülemek için Azure portal gidin, portal menüsünü genişletin ve Pano'yu seçin. Ardından, açılan menüden istediğiniz panoyu seçin.

Pano, botunuzun performansı ve panonuza sabitlediğiniz diğer sorgular hakkında bazı varsayılan bilgileri görüntüler.

Aracılığıyla paylaş