Aggiungere dati di telemetria al bot QnA Maker

Articolo
07/14/2024

SI APPLICA A: SDK v4

Nota

Azure AI QnA Maker verrà ritirato il 31 marzo 2025. A partire dal 1° ottobre 2022, non sarà possibile creare nuove risorse o knowledge base di QnA Maker. Una versione più recente della funzionalità di domanda e risposta è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure.

La risposta alle domande personalizzata, una funzionalità del linguaggio di intelligenza artificiale di Azure, è la versione aggiornata del servizio QnA Maker. Per altre informazioni sul supporto di domande e risposte in Bot Framework SDK, vedere Comprensione del linguaggio naturale.

La registrazione dei dati di telemetria consente alle applicazioni bot di inviare i dati degli eventi ai servizi di telemetria, ad esempio Application Insights. La telemetria offre informazioni dettagliate sul bot visualizzando le funzionalità più usate, rileva il comportamento indesiderato e offre visibilità su disponibilità, prestazioni e utilizzo.

Le TelemetryLoggerMiddleware classi e QnAMaker in Bot Framework SDK abilitano la registrazione dei dati di telemetria nei bot abilitati per QnA Maker. TelemetryLoggerMiddleware è un componente middleware che registra i dati di telemetria ogni volta che i messaggi vengono ricevuti, inviati, aggiornati o eliminati e la QnAMaker classe fornisce la registrazione personalizzata che estende le funzionalità di telemetria.

Questo articolo contiene informazioni relative agli argomenti seguenti:

Il codice necessario per collegare i dati di telemetria nel bot
Codice necessario per abilitare la registrazione e i report QnA Maker predefiniti che usano le proprietà degli eventi standard.
Come modifica o estendere le proprietà degli eventi predefinite dell'SDK per soddisfare una vasta gamma di esigenze di creazione di report.

Prerequisiti

Codice di esempio di QnA Maker
Sottoscrizione a Microsoft Azure
Chiave di Application Insights
È utile conoscere già QnA Maker.
Account QnA Maker.
Un knowledge base QnA Maker esistente e pubblicato.

Nota

Questo articolo si basa sul codice di esempio QnA Maker eseguendo i passaggi necessari per incorporare i dati di telemetria.

Aggiungere il codice di telemetria al bot QnA Maker

Si inizierà con l'app di esempio QnA Maker e si aggiungerà il codice necessario per integrare i dati di telemetria in un bot che usa il servizio QnA Maker. Ciò consentirà ad Application Insights di tenere traccia delle richieste.

Aprire l'app di esempio QnA Maker in Visual Studio.
Aggiungere il pacchetto NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Per altre informazioni sull'uso di NuGet, vedere Installare e gestire i pacchetti in Visual Studio:
Inserire le istruzioni seguenti in Startup.cs:
```
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
```
Nota

Se si esegue questa procedura aggiornando il codice di esempio di QnA Maker, si noterà che l'istruzione using per Microsoft.Bot.Builder.Integration.AspNet.Core esiste già nell'esempio di QnA Maker.

Aggiungere il codice seguente al metodo ConfigureServices() in Startup.cs. Ciò consentirà di rendere disponibili i servizi di telemetria nel bot tramite l'inserimento di dipendenze:

// 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 si sta seguendo la procedura aggiornando il codice di esempio di QnA Maker, si noterà che services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); esiste già.

Indicare all'adapter di usare il codice middleware aggiunto al metodo ConfigureServices(). Aprire AdapterWithErrorHandler.cs e aggiungere IMiddleware middleware all'elenco di parametri dei costruttori. Aggiungere l'istruzione Use(middleware); come ultima riga nel costruttore:
```
public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}
```
Aggiungere la chiave di strumentazione di Application Insights nel file appsettings.json. Il appsettings.json file contiene i metadati relativi ai servizi esterni usati dal bot durante l'esecuzione, ad esempio connessioni e metadati per Cosmos DB, Application Insights e QnA Maker. L'aggiunta al file appsettings.json deve avere il formato seguente:
```
{
    "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
- informazioni dettagliate su come ottenere la chiave di strumentazione di Application Insights sono disponibili nell'articolo Chiavi di Application Insights.
- È necessario avere già un account QnA Maker. Per informazioni su come ottenere i valori di QnA Maker knowledge base ID, chiave dell'endpoint e host, vedere la sezione Pubblicare per ottenere l'endpoint GenerateAnswer dell'articolo Ottenere una risposta con l'API GenerateAnswer di QnA Maker.

A questo punto, viene eseguito il lavoro preliminare per abilitare la telemetria con Application Insights. È possibile eseguire il bot in locale usando il Bot Framework Emulator e quindi passare ad Application Insights per vedere cosa viene registrato, ad esempio il tempo di risposta, l'integrità complessiva delle app e le informazioni generali sull'esecuzione.

Suggerimento

Per informazioni personali, vedere Abilitare o disabilitare l'evento di attività e la registrazione delle informazioni personali.

Si vedrà ora cosa deve essere incluso per aggiungere funzionalità di telemetria al servizio QnA Maker.

Abilitare la telemetria per acquisire i dati di utilizzo dal servizio QnA Maker

Il servizio QnA Maker include la registrazione dei dati di telemetria incorporata disponibile, quindi non è necessario eseguire alcuna operazione per iniziare a ottenere i dati di telemetria da QnA Maker. Prima di tutto si vedrà come incorporare i dati di telemetria nel codice di QnA Maker per abilitare la registrazione dei dati di telemetria predefinita, quindi si apprenderà come sostituire o aggiungere proprietà ai dati degli eventi esistenti per soddisfare un'ampia gamma di esigenze di creazione di report.

Abilitare la registrazione predefinita di QnA Maker

Creare un campo di sola lettura privato di tipo IBotTelemetryClient nella classe QnABot in QnABot.cs:

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

Aggiungere un parametro IBotTelemetryClient al costruttore della classe QnABot in QnABot.cs e assegnare il relativo valore al campo privato creato nel passaggio precedente:

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

Il parametro telemetryClient è obbligatorio quando si crea un'istanza del nuovo oggetto QnAMaker in QnABot.cs:
```
var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
```
Suggerimento

Assicurarsi che i nomi delle proprietà usati nelle _configuration voci corrispondano ai nomi delle proprietà usati nel file AppSettings.json e che i valori per tali proprietà siano ottenuti selezionando il pulsante Visualizza codice nella pagina Knowledge Base del portale di QnA Maker:

Visualizzare i dati di telemetria registrati dalle voci predefinite di QnA Maker

È possibile visualizzare i risultati dell'utilizzo del bot QnA Maker in Application Insights dopo aver eseguito il bot nel Bot Framework Emulator seguendo questa procedura:

Nella portale di Azure passare alla risorsa di Application Insights per il bot.
In Monitoraggio selezionare Log.

Immettere la query Kusto seguente e quindi selezionare Esegui.

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

Lasciare aperta questa pagina nel browser; verrà restituito dopo l'aggiunta di una nuova proprietà personalizzata.

Suggerimento

Se non si ha familiarità con il linguaggio di query Kusto usato per scrivere query di log in Monitoraggio di Azure, ma si ha familiarità con il linguaggio di query SQL, è possibile trovare il foglio informativo sulle query di log da SQL a Monitoraggio di Azure .

Modificare o estendere le proprietà degli eventi predefinite

Se sono necessarie proprietà non definite nella QnAMaker classe esistono due modi per gestirle, entrambe richiedono la creazione di una classe personalizzata derivata dalla QnAMaker classe . Il primo è illustrato nella sezione seguente intitolata Aggiunta delle proprietà in cui si aggiungono proprietà all'evento QnAMessage esistente. Il secondo metodo consente di creare nuovi eventi a cui è possibile aggiungere proprietà, come descritto in Aggiunta di nuovi eventi con proprietà personalizzate.

Nota

L'evento QnAMessage fa parte di Bot Framework SDK e fornisce tutte le proprietà degli eventi predefinite registrate in Application Insights.

Aggiungere le proprietà

Di seguito viene illustrato come eseguire la derivazione dalla classe QnAMaker. L'esempio mostra l'aggiunta della proprietà "MyImportantProperty" all'evento QnAMessage. L'evento QnAMessage viene registrato ogni volta che viene eseguita una chiamata GetAnswers a QnA.

Dopo aver appreso come aggiungere proprietà personalizzate, si apprenderà come creare un nuovo evento personalizzato e associarvi le proprietà, quindi si eseguirà il bot in locale usando il Bot Framework Emulator e si vedrà cosa viene registrato in Application Insights usando il linguaggio di query Kusto.

Creare una nuova classe denominata MyQnAMaker nello spazio dei nomi Microsoft.BotBuilderSamples che eredita dalla classe QnAMaker e salvarla come MyQnAMaker.cs. Per ereditare dalla QnAMaker classe , è necessario aggiungere l'istruzione Microsoft.Bot.Builder.AI.QnA using. Il codice dovrebbe essere simile al seguente:
```
using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}
```

Aggiungere un costruttore di classe a MyQnAMaker. Sono necessarie altre due istruzioni using per i parametri del costruttore per 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)
        {

        }
    }
}

Aggiungere la nuova proprietà all'evento QnAMessage dopo il costruttore e includere le istruzioni System.Collections.Generic, System.Threading e 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
                            );
        }

    }
}

Modificare il bot per usare la nuova classe, anziché creare un QnAMaker oggetto MyQnAMaker in QnABot.cs:

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

Visualizzare i dati di telemetria registrati dalla nuova proprietà MyImportantProperty

Dopo aver eseguito il bot nell'emulatore, è possibile visualizzare i risultati in Application Insights eseguendo le operazioni seguenti:

Tornare al browser con la visualizzazione Log (Analisi) attiva.

Immettere la query Kusto seguente e quindi selezionare Esegui. Verrà restituito un conteggio del numero di volte in cui è stata eseguita la nuova proprietà:

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

Per visualizzare i dettagli anziché il conteggio, rimuovere l'ultima riga ed eseguire di nuovo la query:

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

Aggiungere nuovi eventi con proprietà personalizzate

Se è necessario registrare i dati in un evento diverso da QnaMessage, è possibile creare un evento personalizzato con le relative proprietà. A tale scopo, si aggiungerà il codice alla fine della MyQnAMaker classe come indicato di seguito:

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

}

Dashboard di Application Insights

Ogni volta che si crea una risorsa di Application Insights in Azure, Azure crea un nuovo dashboard associato alla risorsa. Per visualizzare il dashboard dal pannello Application Insights, selezionare Dashboard applicazioni.

In alternativa, per visualizzare i dati, passare alla portale di Azure, espandere il menu del portale e quindi selezionare Dashboard. Selezionare quindi il dashboard desiderato dal menu a discesa.

Il dashboard visualizza alcune informazioni predefinite sulle prestazioni del bot e sulle altre query aggiunte al dashboard.

Condividi tramite

Aggiungere dati di telemetria al bot QnA Maker

Prerequisiti

Aggiungere il codice di telemetria al bot QnA Maker

Abilitare la telemetria per acquisire i dati di utilizzo dal servizio QnA Maker

Abilitare la registrazione predefinita di QnA Maker

Visualizzare i dati di telemetria registrati dalle voci predefinite di QnA Maker

Modificare o estendere le proprietà degli eventi predefinite

Aggiungere le proprietà

Visualizzare i dati di telemetria registrati dalla nuova proprietà MyImportantProperty

Aggiungere nuovi eventi con proprietà personalizzate

Dashboard di Application Insights

Informazioni aggiuntive

Risorse aggiuntive