Incorporación de telemetría al bot de QnA Maker

  • Artículo

SE APLICA A: SDK v4

Nota

Azure AI QnA Maker se retirará el 31 de marzo de 2025. A partir del 1 de octubre de 2022, no podrá crear nuevos recursos ni bases de conocimiento de QnA Maker. Ya hay disponible una versión más reciente de la funcionalidad de preguntas y respuestas como parte de Lenguaje de Azure AI.

La respuesta a preguntas personalizada, una característica del lenguaje azure AI, es la versión actualizada del servicio QnA Maker. Para obtener más información sobre la compatibilidad con preguntas y respuestas en Bot Framework SDK, consulte Reconocimiento del lenguaje natural.

El registro de telemetría permite a las aplicaciones de bot enviar datos de eventos a servicios de telemetría, como Application Insights. La telemetría ofrece información al bot mostrando las características que se usan con mayor frecuencia, permite detectar comportamientos no deseados y ofrece visibilidad sobre la disponibilidad, el rendimiento y el uso.

Las TelemetryLoggerMiddleware clases y QnAMaker del SDK de Bot Framework habilitan el registro de telemetría en bots habilitados para QnA Maker. TelemetryLoggerMiddleware es un componente de middleware que registra la telemetría cada vez que se reciben, envían, actualizan o eliminan mensajes, y la QnAMaker clase proporciona un registro personalizado que amplía las funcionalidades de telemetría.

En este artículo, aprenderá sobre:

  • El código necesario para integrar la telemetría en el bot.
  • El código necesario para habilitar el registro y los informes de QnA Maker estándar que usan las propiedades de evento estándar.
  • Cómo modificar o extender las propiedades de evento predeterminadas del SDK para atender a una amplia variedad de necesidades de informes.

Prerrequisitos

Nota

Este artículo se basa en el código de ejemplo de QnA Maker siguiendo los pasos necesarios para incorporar telemetría.

Incorporación de código de telemetría al bot de QnA Maker

Comenzaremos con la aplicación de ejemplo QnA Maker y agregaremos el código necesario para integrar la telemetría en un bot que use el servicio QnA Maker. Esto permitirá a Application Insights realizar un seguimiento de las solicitudes.

  1. Abra la aplicación de ejemplo QnA Maker en Visual Studio.

  2. Agregue el paquete NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Para más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio:

  3. Incluya las siguientes instrucciones en Startup.cs:

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

    Nota

    Si va a seguir al actualizar el código de ejemplo de QnA Maker, observará que la instrucción using para Microsoft.Bot.Builder.Integration.AspNet.Core ya existe en el ejemplo de QnA Maker.

  4. Agregue el siguiente código al método ConfigureServices() en Startup.cs. Esto hará que los servicios de telemetría estén disponibles para el bot mediante la inserción de dependencias:

    // 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

    Si va a seguir con la actualización del código de ejemplo de QnA Maker, observará que services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); ya existe.

  5. Indique al adaptador que use el código de middleware que se agregó al método ConfigureServices(). Abra AdapterWithErrorHandler.cs y agregue IMiddleware middleware a la lista de parámetros de constructores. Agregue la Use(middleware); instrucción como la última línea del constructor:

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

    Use(middleware);
}

  6. Agregue la clave de instrumentación de Application Insights a su archivo appsettings.json. El appsettings.json archivo contiene metadatos sobre los servicios externos que usa el bot mientras se ejecuta, como la conexión y los metadatos de Cosmos DB, Application Insights y QnA Maker. La adición al archivo appsettings.json debe estar en este 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

En este momento, se realiza el trabajo preliminar para habilitar la telemetría mediante Application Insights. Puede ejecutar el bot localmente mediante el Bot Framework Emulator y, a continuación, ir a Application Insights para ver lo que se registra, como el tiempo de respuesta, el estado general de la aplicación y la información de ejecución general.

Sugerencia

Para obtener información sobre la información personal, vea Habilitar o deshabilitar el registro de eventos de actividad e información personal.

A continuación, veremos lo que debe incluirse para agregar la funcionalidad de telemetría al servicio QnA Maker.

Habilitación de la telemetría para capturar datos de uso del servicio QnA Maker

El servicio QnA Maker tiene disponible el registro de telemetría integrado, por lo que es poco necesario empezar a obtener datos de telemetría de QnA Maker. En primer lugar, veremos cómo incorporar telemetría en el código de QnA Maker para habilitar el registro de telemetría integrado y, a continuación, aprenderemos a reemplazar o agregar propiedades a los datos de eventos existentes para satisfacer una amplia gama de necesidades de informes.

Habilitación del registro predeterminado de QnA Maker

  1. Cree un campo de solo lectura privado de tipo IBotTelemetryClient en la clase QnABot en QnABot.cs:

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

  2. Agregue un parámetro IBotTelemetryClient al constructor de la clase QnABot en QnABot.cs y asigne su valor al campo privado creado en el paso anterior:

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

  3. Se requiere el parámetro telemetryClient al crear una instancia del nuevo objeto QnAMaker en QnABot.cs:

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

    Sugerencia

    Asegúrese de que los nombres de propiedad que use en las _configuration entradas coinciden con los nombres de propiedad que usó en el archivo AppSettings.json y los valores de esas propiedades se obtienen seleccionando el botón Ver código en la página Mis bases de conocimiento en el portal de QnA Maker:

    Ilustración de dónde se encuentra la configuración de la aplicación en el portal de LUIS.

Visualización de los datos de telemetría registrados desde las entradas predeterminadas de QnA Maker

Puede ver los resultados del uso del bot de QnA Maker en Application Insights después de ejecutar el bot en el Bot Framework Emulator siguiendo estos pasos:

  1. En el Azure Portal, vaya al recurso de Application Insights para el bot.

  2. En Supervisión, seleccione Registros.

  3. Escriba la siguiente consulta de Kusto y seleccione Ejecutar.

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

  4. Deje esta página abierta en el explorador; volveremos a ella después de agregar una nueva propiedad personalizada.

Sugerencia

Si no está familiarizado con el lenguaje de consulta kusto que se usa para escribir consultas de registro en Azure Monitor, pero está familiarizado con el lenguaje de consulta SQL, puede que le resulte útil la hoja de referencia rápida de consultas de registro de SQL a Azure Monitor .

Modificar o ampliar las propiedades de eventos predeterminadas

Si necesita propiedades que no estén definidas en la QnAMaker clase hay dos maneras de controlar esto, ambas requieren la creación de su propia clase derivada de la QnAMaker clase . La primera se explica en la sección siguiente titulada Adición de propiedades, en la que se agregan propiedades al evento QnAMessage existente. El segundo método le permite crear nuevos eventos a los que puede agregar propiedades, tal y como se describe en Adición de nuevos eventos con propiedades personalizadas.

Nota

El evento QnAMessage forma parte del SDK Bot Framework y proporciona todas las propiedades de evento predefinidas que se registran en Application Insights.

Adición de propiedades

En el siguiente ejemplo se muestra la derivación desde la clase QnAMaker. En el ejemplo se muestra cómo agregar la propiedad "MyImportantProperty" al evento QnAMessage. El evento QnAMessage se registra cada vez que se realiza una llamada a GetAnswers de QnA.

Después de aprender a agregar propiedades personalizadas, veremos cómo crear un nuevo evento personalizado y asociar propiedades con él, ejecutaremos el bot localmente mediante el Bot Framework Emulator y veremos lo que se registra en Application Insights mediante el lenguaje de consulta Kusto.

  1. Cree una nueva clase llamada MyQnAMaker en el espacio de nombres Microsoft.BotBuilderSamples que herede de la clase QnAMaker, y guárdela como MyQnAMaker.cs. Para heredar de la QnAMaker clase , deberá agregar la Microsoft.Bot.Builder.AI.QnA instrucción using. El código tendrá el siguiente aspecto:

    using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}

  2. Agregue un constructor de clase a MyQnAMaker. Necesitará dos instrucciones using más para los parámetros del constructor para System.Net.Http y 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. Agregue la nueva propiedad al evento QnAMessage después del constructor e incluya las instrucciones System.Collections.Generic, System.Threading y 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 el bot para usar la nueva clase, en lugar de crear un QnAMakerMyQnAMaker objeto en QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
Visualización de los datos de telemetría registrados desde la nueva propiedad MyImportantProperty

Después de ejecutar el bot en el emulador, puede ver los resultados en Application Insights haciendo lo siguiente:

  1. Vuelva al explorador que tiene activa la vista Registros (Analytics) .

  2. Escriba la siguiente consulta de Kusto y seleccione Ejecutar. Esto le dará el número de veces que se ejecutó la nueva propiedad:

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

  3. Para mostrar los detalles en lugar del recuento, quite la última línea y vuelva a ejecutar la consulta:

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

Adición de nuevos eventos con propiedades personalizadas

Si necesita registrar datos en un evento diferente al de QnaMessage, puede crear su propio evento personalizado con sus propiedades. Para ello, agregaremos código al final de la MyQnAMaker clase como se indica a continuación:

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

}

Panel de Application Insights

Cada vez que cree un recurso de Application Insights en Azure, Azure creará un nuevo panel asociado al recurso. Para mostrar el panel desde la hoja Application Insights, seleccione Panel de aplicaciones.

Como alternativa, para ver los datos, vaya al Azure Portal, expanda el menú del portal y seleccione Panel. A continuación, seleccione el panel que desee en el menú desplegable.

El panel muestra información predeterminada sobre el rendimiento del bot y cualquier otra consulta que haya anclado al panel.

Información adicional