QnA Maker 봇에 원격 분석 추가

적용 대상: SDK v4

참고

Azure AI QnA Maker는 2025년 3월 31일에 사용 중지됩니다. 2022년 10월 1일부터 새 QnA Maker 리소스 또는 기술 자료를 만들 수 없습니다. 이제 최신 버전의 질문 및 답변 기능을 Azure AI Language의 일부로 사용할 수 있습니다.

Azure AI Language의 기능인 사용자 지정 질문 답변은 QnA Maker 서비스의 업데이트된 버전입니다. Bot Framework SDK의 질문 및 답변 지원에 대한 자세한 내용은 자연어 이해를 참조하세요.

원격 분석 로깅을 사용하면 봇 애플리케이션이 Application Insights와 같은 원격 분석 서비스에 이벤트 데이터를 보낼 수 있습니다. 원격 분석은 가장 많이 사용되는 기능을 보여주고, 원치 않는 동작을 감지하고, 가용성, 성능 및 사용량 정보를 제공함으로써 봇에 대한 인사이트를 제공합니다.

Bot Framework SDK의 및 QnAMaker 클래스는 TelemetryLoggerMiddleware 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에서 요청을 추적할 수 있습니다.

1. Visual Studio에서 QnA Maker 샘플 앱을 엽니다.

2. Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet 패키지를 추가합니다. NuGet 사용에 대한 자세한 내용은 Visual Studio에서 패키지 설치 및 관리를 참조하세요.

3. 다음 명령문을 Startup.cs에 포함합니다.

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

   참고

   QnA Maker 샘플 코드를 업데이트하여 팔로우하는 경우 에 대한 Microsoft.Bot.Builder.Integration.AspNet.Core using 문이 이미 QnA Maker 샘플에 있다는 것을 알 수 있습니다.

4. 다음 코드를 Startup.cs의 ConfigureServices() 메서드에 추가합니다. 그러면 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>();
       ...
   }
   

   참고

   QnA Maker 샘플 코드를 업데이트하여 팔로우하는 경우 이미 존재하는 것을 services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); 알 수 있습니다.

5. ConfigureServices() 메서드에 추가된 미들웨어 코드를 사용하도록 어댑터에 지시합니다. AdapterWithErrorHandler.cs를 열고, IMiddleware middleware를 생성자 매개 변수 목록에 추가합니다. Use(middleware); 문을 생성자의 마지막 줄로 추가합니다.

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

6. 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 Insights 계측 키를 얻는 방법에 대한 자세한 내용은 Application Insights 키 문서를 참조하세요.
   • QnA Maker 계정이 이미 있어야 합니다. QnA Maker 기술 자료 ID, 엔드포인트 키 및 호스트 값을 가져오는 방법에 대한 자세한 내용은 GenerateAnswer API를 사용하여 QnA Maker의 답변 가져오기 문서의 GenerateAnswer 엔드포인트 가져오기 게시 섹션을 참조하세요.

이 시점에서 Application Insights를 사용하여 원격 분석을 사용하도록 설정하는 예비 작업이 완료됩니다. Bot Framework Emulator 사용하여 로컬로 봇을 실행한 다음 Application Insights로 이동하여 응답 시간, 전체 앱 상태 및 일반 실행 정보와 같이 기록되는 내용을 확인할 수 있습니다.

팁

개인 정보에 대한 자세한 내용은 활동 이벤트 및 개인 정보 로깅 사용 또는 사용 안 함을 참조하세요.

다음으로 QnA Maker 서비스에 원격 분석 기능을 추가하기 위해 포함해야 하는 사항을 살펴보겠습니다.

원격 분석을 사용하여 QnA Maker 서비스에서 사용량 현황 데이터 캡처

QnA Maker 서비스에는 기본 제공 원격 분석 로깅을 사용할 수 있으므로 QnA Maker에서 원격 분석 데이터를 가져오기 위해 수행할 필요가 거의 없습니다. 먼저 QnA Maker 코드에 원격 분석을 통합하여 기본 제공 원격 분석 로깅을 사용하도록 설정하는 방법을 알아봅니다. 그런 다음, 다양한 보고 요구 사항을 충족하기 위해 기존 이벤트 데이터를 대체하거나 속성을 추가하는 방법을 알아봅니다.

기본 QnA Maker 로깅 사용

1. IBotTelemetryClient 형식의 private readonly 필드를 QnABot.cs의 QnABot 클래스에 만듭니다.

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

2. IBotTelemetryClient 매개 변수를 QnABot.cs의 QnABot 클래스 생성자에 추가하고, 이전 단계에서 만든 private 필드에 해당 값을 할당합니다.

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

3. QnABot.cs에서 새 QnAMaker 개체를 인스턴스화하는 경우 telemetryClient 매개 변수가 필요합니다.

   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 기본 항목에서 기록된 원격 분석 데이터 보기

다음 단계를 수행하여 Bot Framework Emulator 봇을 실행한 후 Application Insights에서 QnA Maker 봇 사용 결과를 볼 수 있습니다.

1. Azure Portal 봇에 대한 Application Insights 리소스로 이동합니다.

2. 모니터링에서 로그를 선택합니다.

3. 다음 Kusto 쿼리를 입력한 다음 실행을 선택합니다.

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

4. 브라우저에서 이 페이지를 열어 둡니다. 새 사용자 지정 속성을 추가한 후 다시 살펴보겠습니다.

팁

Azure Monitor에서 로그 쿼리를 작성하는 데 사용되는 Kusto 쿼리 언어를 익숙하지만 SQL 쿼리 언어에 익숙한 경우 SQL-Azure Monitor 로그 쿼리 참고 자료 가 유용할 수 있습니다.

기본 이벤트 속성 수정 또는 확장

클래스에 QnAMaker 정의되지 않은 속성이 필요한 경우 이를 처리하는 두 가지 방법이 있습니다. 둘 다 클래스에서 파생된 고유한 클래스를 QnAMaker 만들어야 합니다. 첫 번째 방법은 속성을 기존 QnAMessage 이벤트에 추가하는 아래의 속성 추가 섹션에 설명되어 있습니다. 두 번째 방법을 사용하면 사용자 지정 속성을 사용하여 새 이벤트 추가에서 설명한 대로 속성을 추가할 수 있는 새 이벤트를 만들 수 있습니다.

참고

QnAMessage 이벤트는 Bot Framework SDK의 일부이며, Application Insights에 로깅되는 기본 제공 이벤트 속성을 모두 제공합니다.

속성 추가

다음은 QnAMaker 클래스에서 파생되는 방법을 보여 줍니다. 이 예에서는 QnAMessage 이벤트에 "MyImportantProperty" 속성을 추가하는 방법을 보여줍니다. QnA GetAnswers 호출을 수행할 때마다 QnAMessage 이벤트가 기록됩니다.

사용자 지정 속성을 추가하는 방법을 학습한 후 새 사용자 지정 이벤트를 만들고 속성을 연결하는 방법을 알아봅니다. 그런 다음 Bot Framework Emulator 사용하여 로컬로 봇을 실행하고 Kusto 쿼리 언어를 사용하여 Application Insights에 기록되는 내용을 확인합니다.

1. MyQnAMaker라는 새 클래스를 QnAMaker 클래스에서 상속되는 Microsoft.BotBuilderSamples 네임스페이스에 만들고 MyQnAMaker.cs으로 저장합니다. 클래스에서 QnAMaker 상속하려면 using 문을 추가 Microsoft.Bot.Builder.AI.QnA 해야 합니다. 코드는 다음과 같이 표시됩니다.

   using Microsoft.Bot.Builder.AI.QnA;
   
   namespace Microsoft.BotBuilderSamples
   {
       public class MyQnAMaker : QnAMaker
       {
   
       }
   }
   

2. 클래스 생성자를 에 추가합니다 MyQnAMaker. 및 Microsoft.Bot.Builder에 대한 생성자 매개 변수 System.Net.Http 에 대해 두 개의 using 문이 더 필요합니다.

   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. 새 속성을 생성자 뒤의 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
                               );
           }
   
       }
   }
   

4. 에서 개체QnABot.cs를 만드는 대신 새 클래스를 QnAMaker 사용하도록 봇을 MyQnAMaker 수정합니다.

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

새 속성 MyImportantProperty에서 기록된 원격 분석 데이터 보기

에뮬레이터에서 봇을 실행한 후 다음을 수행하여 Application Insights에서 결과를 볼 수 있습니다.

1. 로그(분석) 보기가 활성 상태인 브라우저로 다시 전환합니다.

2. 다음 Kusto 쿼리를 입력한 다음, 실행을 선택합니다. 그러면 새 속성이 실행된 횟수가 제공됩니다.

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

3. 개수 대신 세부 정보를 표시하려면 마지막 줄을 제거하고 쿼리를 다시 실행합니다.

   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 대시보드

Azure에서 Application Insights 리소스를 만들 때마다 Azure는 리소스와 연결된 새 dashboard 만듭니다. Application Insights 블레이드에서 dashboard 표시하려면 애플리케이션 대시보드를 선택합니다.

또는 데이터를 보려면 Azure Portal 이동하여 포털 메뉴를 확장한 다음 대시보드를 선택합니다. 그런 다음 드롭다운 메뉴에서 원하는 dashboard 선택합니다.

dashboard 봇 성능 및 dashboard 고정한 다른 쿼리에 대한 몇 가지 기본 정보를 표시합니다.

추가 정보

• 봇에 원격 분석 추가
• Application Insights란?
• Application Insights에서 Search 사용
• Azure Application Insights를 사용하여 사용자 지정 KPI 대시보드 만들기