Partilhar via

Adicionar telemetria ao bot do Criador de FAQ

  • Artigo

APLICA-SE A: SDK v4

Nota

O Criador de FAQ do Azure AI será descontinuado a 31 de março de 2025. A partir de 1 de outubro de 2022, não poderá criar novos recursos ou bases de dados de conhecimento do Criador de FAQ. Uma versão mais recente da capacidade de perguntas e respostas está agora disponível como parte da Linguagem de IA do Azure.

A resposta a perguntas personalizadas, uma funcionalidade da Linguagem de IA do Azure, é a versão atualizada do serviço Criador de FAQ. Para obter mais informações sobre o suporte para perguntas e respostas no SDK do Bot Framework, veja Compreensão de linguagem natural.

O registo de telemetria permite que as aplicações de bot enviem dados de eventos para serviços de telemetria, como o Application Insights. A telemetria oferece informações sobre o bot ao mostrar que funcionalidades são mais utilizadas, deteta comportamentos indesejados e oferece visibilidade sobre disponibilidade, desempenho e utilização.

As TelemetryLoggerMiddleware classes e QnAMaker no SDK do Bot Framework ativam o registo de telemetria em bots preparados para o Criador de FAQ. TelemetryLoggerMiddleware é um componente middleware que regista a telemetria sempre que as mensagens são recebidas, enviadas, atualizadas ou eliminadas, e a QnAMaker classe fornece um registo personalizado que expande as capacidades de telemetria.

Neste artigo, irá saber mais sobre:

  • O código necessário para ligar a telemetria no bot
  • O código necessário para ativar o registo e os relatórios do Criador de FAQ que utilizam as propriedades padrão do evento.
  • Modificar ou expandir as propriedades de evento predefinidas do SDK para ativar uma vasta gama de necessidades de relatórios.

Pré-requisitos

Nota

Este artigo baseia-se no código de exemplo do Criador de FAQ ao percorrer os passos necessários para incorporar a telemetria.

Adicionar código de telemetria ao bot do Criador de FAQ

Vamos começar com a aplicação de exemplo Criador de FAQ e adicionar o código necessário para integrar a telemetria num bot que utiliza o serviço Criador de FAQ. Isto irá permitir que o Application Insights controle os pedidos.

  1. Abra a aplicação de exemplo Criador de FAQ no Visual Studio.

  2. Adicione o pacote NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Para obter mais informações sobre como utilizar o NuGet, veja Instalar e gerir pacotes no Visual Studio:

  3. Inclua as seguintes instruções em Startup.cs:

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

    Nota

    Se estiver a acompanhar ao atualizar o código de exemplo do Criador de FAQ, irá reparar que a instrução using para Microsoft.Bot.Builder.Integration.AspNet.Core já existe no exemplo do Criador de FAQ.

  4. Adicione o seguinte código ao ConfigureServices() método em Startup.cs. Isto disponibiliza serviços de telemetria ao bot através da injeção de dependência (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>();
    ...
}

    Nota

    Se estiver a acompanhar ao atualizar o código de exemplo do Criador de FAQ, irá reparar que services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); já existe.

  5. Instrua o adaptador para utilizar o código middleware que foi adicionado ao ConfigureServices() método . Abra AdapterWithErrorHandler.cs e adicione IMiddleware middleware à lista de parâmetros de construtores. Adicione a Use(middleware); instrução como a última linha no construtor:

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

    Use(middleware);
}

  6. Adicione a chave de instrumentação do Application Insights no seu appsettings.json ficheiro. O appsettings.json ficheiro contém metadados sobre serviços externos que o bot utiliza durante a execução, como ligação e metadados para o Cosmos DB, o Application Insights e o Criador de FAQ. A adição ao seu appsettings.json ficheiro tem de estar neste formato:

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

    Nota

    • Pode encontrar detalhes sobre como obter a chave de instrumentação do Application Insights no artigo Chaves do Application Insights.
    • Já deve ter uma conta do Criador de FAQ. Para obter informações sobre como obter o ID de base de dados de conhecimento do Criador de FAQ, a chave de ponto final e os valores do anfitrião, veja a secção Publish to get GenerateAnswer endpoint of QnA Maker's Get an answer with the GenerateAnswer API (Publicar para obter o ponto final GenerateAnswer do Criador de FAQ) Obter uma resposta com o artigo GenerateAnswer API (API GenerateAnswer).

Neste momento, é feito o trabalho preliminar para ativar a telemetria com o Application Insights. Pode executar o bot localmente com o Bot Framework Emulator e, em seguida, aceder ao Application Insights para ver o que está a ser registado, como o tempo de resposta, o estado de funcionamento geral da aplicação e as informações gerais de execução.

Dica

Para obter informações pessoais, consulte Ativar ou desativar o registo de informações pessoais e eventos de atividade.

Em seguida, veremos o que precisa de ser incluído para adicionar funcionalidades de telemetria ao serviço Criador de FAQ.

Ativar a telemetria para capturar dados de utilização do serviço Criador de FAQ

O serviço Criador de FAQ tem o registo de telemetria incorporado disponível, pelo que pouco precisa de fazer para começar a obter dados telemétricos do Criador de FAQ. Primeiro, vamos ver como incorporar telemetria no código do Criador de FAQ para ativar o registo de telemetria incorporado e, em seguida, aprenderemos a substituir ou adicionar propriedades aos dados de eventos existentes para satisfazer uma vasta gama de necessidades de relatórios.

Ativar o registo predefinido do Criador de FAQ

  1. Crie um campo privado só de leitura do tipo IBotTelemetryClient na sua QnABot turma em QnABot.cs:

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

  2. Adicione um IBotTelemetryClient parâmetro ao construtor QnABot de classes no QnABot.cs e atribua o respetivo valor ao campo privado criado no passo anterior:

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

  3. O telemetryClient parâmetro é necessário ao instanciar o novo objeto QnAMaker no QnABot.cs:

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

    Dica

    Certifique-se de que os nomes de propriedade que utiliza nas _configuration entradas correspondem aos nomes de propriedade que utilizou no ficheiro AppSettings.json e que os valores dessas propriedades são obtidos ao selecionar o botão Ver Código na página As minhas bases de dados de conhecimento no portal do Criador de FAQ:

    Ilustração de onde as definições da aplicação são encontradas no portal do LUIS.

Ver dados telemétricos registados a partir das entradas predefinidas do Criador de FAQ

Pode ver os resultados da utilização do bot do Criador de FAQ no Application Insights depois de executar o bot no Bot Framework Emulator ao seguir os seguintes passos:

  1. Na portal do Azure, aceda ao recurso do Application Insights do bot.

  2. Em Monitorização, selecione Registos.

  3. Introduza a seguinte consulta Kusto e, em seguida, selecione Executar.

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

  4. Deixe esta página aberta no seu browser; Voltaremos ao mesmo depois de adicionarmos uma nova propriedade personalizada.

Dica

Se não estiver familiarizado com a linguagem de consulta Kusto utilizada para escrever consultas de registo no Azure Monitor, mas estiver familiarizado com a linguagem de consulta SQL, poderá considerar útil a folha de truques e dicas da consulta de registo do SQL para o Azure Monitor .

Modificar ou expandir propriedades de eventos predefinidas

Se precisar de propriedades que não estão definidas na QnAMaker classe, existem duas formas de lidar com isto, ambas requerem a criação da sua própria classe derivada da QnAMaker classe . A primeira é explicada na secção abaixo intitulada Adicionar propriedades nas quais adiciona propriedades ao evento existente QnAMessage . O segundo método permite-lhe criar novos eventos aos quais pode adicionar propriedades, conforme descrito em Adicionar novos eventos com propriedades personalizadas.

Nota

O QnAMessage evento faz parte do SDK do Bot Framework e fornece todas as propriedades de eventos que são registadas no Application Insights.

Adicionar propriedades

O seguinte demonstra como pode derivar da QnAMaker classe . O exemplo mostra a adição da propriedade "MyImportantProperty" ao QnAMessage evento. O QnAMessage evento é registado sempre que é efetuada uma chamada GetAnswers de FAQ.

Depois de aprendermos a adicionar propriedades personalizadas, vamos aprender a criar um novo evento personalizado e a associar propriedades ao mesmo. Em seguida, iremos executar o bot localmente com o Bot Framework Emulator e ver o que está a ser registado no Application Insights com a linguagem de consulta Kusto.

  1. Crie uma nova classe com o nome MyQnAMaker no Microsoft.BotBuilderSamples espaço de nomes que herda da classe e guarde-a QnAMaker como MyQnAMaker.cs. Para herdar da QnAMaker classe, terá de adicionar a Microsoft.Bot.Builder.AI.QnA instrução using. O código deverá aparecer da seguinte forma:

    using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}

  2. Adicione um construtor de classes a MyQnAMaker. Precisará de mais duas instruções de utilização para os parâmetros do construtor para System.Net.Http e 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)
        {

        }
    }
}

  3. Adicione a nova propriedade ao evento QnAMessage após o construtor e inclua as instruções System.Collections.Generic, System.Threadinge 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. Modifique o bot para utilizar a nova classe, em vez de criar um QnAMaker objeto MyQnAMaker no QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
Ver dados telemétricos registados a partir da nova propriedade MyImportantProperty

Depois de executar o bot no Emulador, pode ver os resultados no Application Insights ao fazer o seguinte:

  1. Mude novamente para o browser que tem a vista Registos (Análise) ativa.

  2. Introduza a seguinte consulta Kusto e, em seguida, selecione Executar. Isto dará uma contagem do número de vezes que a nova propriedade foi executada:

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

  3. Para mostrar os detalhes em vez da contagem, remova a última linha e volte a executar a consulta:

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

Adicionar novos eventos com propriedades personalizadas

Se precisar de registar dados num evento diferente do QnaMessage, pode criar o seu próprio evento personalizado com as suas próprias propriedades. Para tal, vamos adicionar código ao fim da classe da MyQnAMaker seguinte forma:

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

}

O dashboard do Application Insights

Sempre que cria um recurso do Application Insights no Azure, o Azure cria um novo dashboard associado ao recurso. Para apresentar o dashboard no painel Application Insights, selecione Dashboard da Aplicação.

Em alternativa, para ver os dados, aceda ao portal do Azure, expanda o menu do portal e, em seguida, selecione Dashboard. Em seguida, selecione o dashboard que pretende no menu pendente.

O dashboard apresenta algumas informações predefinidas sobre o desempenho do bot e quaisquer outras consultas que tenha afixado ao dashboard.

Informações adicionais