Добавление данных телеметрии в бот QnA Maker

Статья
03/08/2023

ПРИМЕНИМО К: Пакет SDK версии 4

Примечание

Поддержка Azure AI QnA Maker будет прекращена 31 марта 2025 г. Начиная с 1 октября 2022 г. вы не сможете создавать новые ресурсы или базы знаний QnA Maker. Новая версия возможности вопросов и ответов теперь доступна в составе языка ИИ Azure.

Настраиваемые ответы на вопросы , функция языка ИИ Azure, — это обновленная версия службы QnA Maker. Дополнительные сведения о поддержке вопросов и ответов в пакете SDK Bot Framework см. в разделе Распознавание естественной речи.

Ведение журнала телеметрии позволяет приложениям-ботам отправлять данные о событиях в службы телеметрии, такие как Application Insights. Данные телеметрии включают полезные сведения о боте (например о том, какие функции используются чаще всего), помогают обнаруживать нежелательное поведение и предоставляют сведения о доступности, производительности и использовании.

TelemetryLoggerMiddleware Классы и QnAMaker в пакете SDK Bot Framework включают ведение журнала телеметрии в ботах с поддержкой QnA Maker. TelemetryLoggerMiddleware — это компонент ПО промежуточного слоя, который регистрирует данные телеметрии каждый раз при получении, отправке, обновлении или удалении сообщений, а QnAMaker класс предоставляет пользовательское ведение журнала, расширяющее возможности телеметрии.

Из этой статьи вы узнаете следующее:

Код для подключения телеметрии к боту.
Код, необходимый для включения встроенного ведения журнала QnA Maker и отчетов, использующих стандартные свойства событий.
Процедуру изменения или расширения стандартных свойств событий, предоставляемых пакетом SDK, для широкого спектра задач отчетности.

Предварительные требования

Пример кода для QnA Maker.
Подписка на Microsoft Azure.
Ключ Application Insights.
Вам будет проще, если вы уже знакомы со службой QnA Maker.
Учетная запись QnA Maker.
Существующая и опубликованная база знаний QnA Maker.

Примечание

Эта статья основана на примере кода QnA Maker , выполнив пошаговые инструкции, необходимые для включения данных телеметрии.

Добавление кода телеметрии в бот QnA Maker

Начнем с примера приложения QnA Maker и добавим код, необходимый для интеграции данных телеметрии в бот, который использует службу QnA Maker. Это позволит Application Insights отслеживать запросы.

Откройте пример приложения QnA Maker в Visual Studio.
Добавьте пакет NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Подробные сведения об использовании NuGet см. в руководстве по установке пакетов и управлении ими в Visual Studio.
Добавьте следующие инструкции в Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Примечание

Если вы следите за этим путем обновления примера кода QnA Maker, вы заметите, что оператор using для Microsoft.Bot.Builder.Integration.AspNet.Core уже существует в примере QnA Maker.

Добавьте в метод ConfigureServices() файла Startup.cs следующий код. Теперь службы телеметрии станут доступными для бота через внедрение зависимостей:

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

Примечание

Если вы следите за этим путем обновления примера кода QnA Maker, вы заметите, что services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); он уже существует.

Настройте адаптер на использование кода ПО промежуточного слоя, который был добавлен в метод ConfigureServices(). Откройте AdapterWithErrorHandler.cs и добавьте IMiddleware middleware в список параметров конструктора. Use(middleware); Добавьте оператор в качестве последней строки в конструкторе:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Добавьте ключ инструментирования Application Insights в файл appsettings.json. Файл appsettings.json содержит метаданные о внешних службах, которые бот использует во время выполнения, например о подключении и метаданных для Cosmos DB, Application Insights и QnA Maker. Формат добавляемого в файл appsettings.json ключа должен быть таким:
```
{
    "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"
    }
}
```
Примечание
- Сведения о ключе инструментирования Application см. в статье о ключах Application Insights.
- У вас уже должна быть учетная запись QnA Maker. Сведения о получении идентификатора база знаний QnA Maker, ключа конечной точки и значений узла см. в разделе Публикация конечной точки GenerateAnswer статьи QnA Maker Получение ответа с помощью API GenerateAnswer.

На этом этапе выполняется предварительная работа по включению телеметрии с помощью Application Insights. Вы можете запустить бот локально с помощью Bot Framework Emulator, а затем перейти в Application Insights, чтобы просмотреть, что регистрируется в журнале, например время отклика, общую работоспособность приложения и общие сведения о выполнении.

Совет

Сведения о персональных данных см. в разделе Включение или отключение событий действий и ведение журнала личных сведений.

Далее мы посмотрим, что необходимо включить для добавления функций телеметрии в службу QnA Maker.

Включение телеметрии для сбора данных об использовании из службы QnA Maker

В службе QnA Maker доступно встроенное ведение журнала телеметрии, поэтому вам не нужно ничего делать, чтобы начать получать данные телеметрии из QnA Maker. Сначала мы рассмотрим, как включить данные телеметрии в код QnA Maker, чтобы включить встроенное ведение журнала телеметрии, а затем узнаем, как заменить или добавить свойства к существующим данным событий для удовлетворения широкого спектра потребностей в отчетах.

Включение ведения журнала QnA Maker по умолчанию

Создайте закрытое поле только для чтения с типом IBotTelemetryClient в классе QnABot в QnABot.cs:
```
public class QnABot : ActivityHandler
    {
        private readonly IBotTelemetryClient _telemetryClient;
        ...
}
```
Добавьте параметр IBotTelemetryClient в конструктор класса QnABot в файле QnABot.cs и сохраните его значение в закрытое поле, созданное на предыдущем шаге:
```
public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
{
    ...
    _telemetryClient = telemetryClient;
}
```
Параметр telemetryClient является обязательным при создании экземпляра объекта QnAMaker в QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Совет

Убедитесь, что имена свойств, которые вы используете в _configuration записях, совпадают с именами свойств, которые использовались в файле AppSettings.json, и значения для этих свойств можно получить, нажав кнопку Просмотреть код на странице Мои базы знаний на портале QnA Maker:

Просмотр данных телеметрии, зарегистрированных в записях по умолчанию QnA Maker

Вы можете просмотреть результаты использования бота QnA Maker в Application Insights после запуска бота в Bot Framework Emulator, выполнив следующие действия.

В портал Azure перейдите к ресурсу Application Insights для бота.
В разделе Мониторинг выберите Журналы.

Введите следующий запрос Kusto, а затем выберите Выполнить.

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

Оставьте эту страницу открытой в браузере; Мы вернемся к нему после добавления нового настраиваемого свойства.

Совет

Если вы не знакомы с языком запросов Kusto, который используется для написания запросов к журналам в Azure Monitor, но знакомы с языком SQL-запросов, может оказаться полезным памятка по запросам журналов SQL в Azure Monitor .

Изменение или расширение свойств событий по умолчанию

Если вам нужны свойства, которые не определены в QnAMaker классе , существует два способа обработки этого метода. Оба из них требуют создания собственного QnAMaker класса, производного от класса . Первый способ описан в разделе Добавление свойств ниже, где свойства добавляются в существующее событие QnAMessage. Второй метод позволяет создавать новые события и добавлять в них свойства, как описано в разделе Добавление новых событий с пользовательскими свойствами.

Примечание

Событие QnAMessage входит в состав пакета SDK для Bot Framework и предоставляет все свойства событий, которые сохраняются в Application Insights.

Добавление свойств

Наследование от класса QnAMaker демонстрируется в примере ниже. Например, вы можете добавить свойство MyImportantProperty в событие QnAMessage. Событие QnAMessage записывается в журнал при каждом вызове GetAnswers службы в QnA.

Изучив, как добавить настраиваемые свойства, мы узнаем, как создать новое пользовательское событие и связать с ним свойства, а затем запустим бот локально с помощью Bot Framework Emulator и посмотрим, что регистрируется в Application Insights с помощью языка запросов Kusto.

Создайте новый класс с именем MyQnAMaker в пространстве имен Microsoft.BotBuilderSamples, унаследовав его от класса QnAMaker, и сохраните как MyQnAMaker.cs. Чтобы наследовать от QnAMaker класса , необходимо добавить Microsoft.Bot.Builder.AI.QnA оператор using. Теперь код должен выглядеть следующим образом:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Добавьте конструктор класса в MyQnAMaker. Вам потребуется еще две инструкции using для параметров конструктора для System.Net.Http и 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)
        {

        }
    }
}

Добавьте новое свойство в событие QnAMessage сразу после конструктора и включите инструкции System.Collections.Generic, System.Threading и 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
                            );
        }

    }
}

Измените бот для использования нового класса. Вместо создания QnAMaker объекта вы создадите MyQnAMaker объект в QnABot.cs:

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

Просмотр данных телеметрии, записанных в журнал из нового свойства MyImportantProperty

После запуска бота в эмуляторе можно просмотреть результаты в Application Insights, выполнив следующие действия.

Вернитесь в браузер, где открыто представление Журналы (аналитика) .
Введите следующий запрос Kusto и щелкните Запуск. Он возвращает количество выполнений для нового свойства:
```
customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
| summarize count() by MyImportantProperty
```
Чтобы отобразить сведения вместо счетчика, удалите последнюю строку и повторно выполните запрос:
```
customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
```

Добавление новых событий с пользовательскими свойствами

Если вам нужно сохранять данные в другое событие, отличное от QnaMessage, вы можете создать пользовательское событие с нужными свойствами. Для этого мы добавим код в конец MyQnAMaker класса следующим образом:

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

Каждый раз, когда вы создаете ресурс Application Insights в Azure, Azure создает новую панель мониторинга, связанную с вашим ресурсом. Чтобы отобразить панель мониторинга в колонке Application Insights, выберите Панель мониторинга приложений.

Кроме того, чтобы просмотреть данные, перейдите на портал Azure, разверните меню портала и выберите Панель мониторинга. Затем выберите нужную панель мониторинга в раскрывающемся меню.

На панели мониторинга отображаются некоторые сведения по умолчанию о производительности бота и другие запросы, закрепленные на панели мониторинга.

Поделиться через

Добавление данных телеметрии в бот QnA Maker

Предварительные требования

Добавление кода телеметрии в бот QnA Maker

Включение телеметрии для сбора данных об использовании из службы QnA Maker

Включение ведения журнала QnA Maker по умолчанию

Просмотр данных телеметрии, зарегистрированных в записях по умолчанию QnA Maker

Изменение или расширение свойств событий по умолчанию

Добавление свойств

Просмотр данных телеметрии, записанных в журнал из нового свойства MyImportantProperty

Добавление новых событий с пользовательскими свойствами

Панель мониторинга Application Insights

Дополнительные сведения

Дополнительные ресурсы