Orchestrator で複数の LUIS および QnA モデルを使用するUse multiple LUIS and QnA models with Orchestrator

適用対象: SDK v4APPLIES TO: SDK v4

Bot が複数の LUIS モデルを使用してナレッジベース (ナレッジベース) を QnA Maker している場合は、Orchestrator を使用して、ユーザー入力と最も一致する LUIS モデルまたは QnA Maker ナレッジベースを特定できます。If a bot uses multiple LUIS models and QnA Maker knowledge bases (knowledge bases), you can use Orchestrator to determine which LUIS model or QnA Maker knowledge base best matches the user input. Bf ORCHESTRATOR CLI ツールは、実行時にユーザー入力を適切なモデルにルーティングするために使用される orchestrator スナップショットファイルを作成することによってこれを行います。The bf orchestrator CLI tool does this by creating a Orchestrator snapshot file that will be used to route user input to the correct model at run time. CLI コマンドを含む Orchestrator の詳細については、 ここをクリックしてください。For more information about Orchestrator, including the CLI commands, click here.

前提条件Prerequisites

このサンプルについてAbout this sample

このサンプルは、事前に定義された LUIS アプリと QnA Maker アプリのセットに基づいています。This sample is based on a predefined set of LUIS and QnA Maker apps.

コードサンプルロジックフロー cs

ユーザー入力を受け取るたびに、OnMessageActivityAsync が呼び出されます。OnMessageActivityAsync is called for each user input received. このモジュールでは、最上位スコアのユーザーの意図を検索し、その結果を DispatchToTopIntentAsync に渡します。This module finds the top scoring user intent and passes that result on to DispatchToTopIntentAsync. DispatchToTopIntentAsync は、適切なアプリハンドラーを呼び出します。DispatchToTopIntentAsync, in turn, calls the appropriate app handler.

  • ProcessSampleQnAAsync - ボットの FAQ の質問。ProcessSampleQnAAsync - for bot faq questions.
  • ProcessWeatherAsync -天気クエリ。ProcessWeatherAsync - for weather queries.
  • ProcessHomeAutomationAsync -家庭用照明コマンド。ProcessHomeAutomationAsync - for home lighting commands.

ハンドラーによって LUIS または QnA Maker サービスが呼び出され、生成された結果がユーザーに返されます。The handler calls the LUIS or QnA Maker service and returns the generated result back to the user.

LUIS アプリと QnA ナレッジ ベースを作成するCreate LUIS apps and QnA knowledge base

Orchestrator スナップショットファイルを作成する前に、LUIS apps と QnA のナレッジベースを作成して公開する必要があります。Before you can create Orchestrator snapshot file, you'll need to have your LUIS apps and QnA knowledge bases created and published. この記事では、 NLP With Orchestrator サンプルに含まれている次のモデルをフォルダーに公開し \CognitiveModels ます。In this article, we'll publish the following models that are included with the NLP With Orchestrator sample in the \CognitiveModels folder:

NameName 説明Description
HomeAutomationHomeAutomation 関連付けられているエンティティ データによってホーム オートメーションの意図を認識する LUIS アプリ。A LUIS app that recognizes a home automation intent with associated entity data.
WeatherWeather 場所データによって天気関連の意図を認識する LUIS アプリ。A LUIS app that recognizes weather-related intents with location data.
QnA MakerQnAMaker ボットに関するシンプルな質問への回答を提供する QnA Maker ナレッジ ベース。A QnA Maker knowledge base that provides answers to simple questions about the bot.

LUIS アプリの作成Create the LUIS apps

サンプルの 認知モデル ディレクトリにある ホームオートメーションWeather lu ファイルから LUIS アプリを作成します。Create LUIS apps from the HomeAutomation and Weather lu files in the cognitive models directory of the sample.

  1. 次のコマンドを実行して、アプリをインポートし、トレーニングして、運用環境に発行します。Run the following command to import, train and publish the app to the production environment.

    > bf luis:build --in CognitiveModels --authoringKey <YOUR-KEY> --botName <YOUR-BOT-NAME>
    
  2. アプリケーション ID、表示名、オーサリング キー、および場所を記録します。Record the application ID, display name, authoring key, and location.

詳細については 、「LUIS ポータルで LUIS アプリを作成する」および「ボットに自然言語の理解を追加する」の「LUIS アプリに接続するための値を取得する 」と 、アプリをトレーニングして実稼働環境に発行する方法に関する LUIS ドキュメントを参照してください。 For more information, see how to Create a LUIS app in the LUIS portal and Obtain values to connect to your LUIS app in Add natural language understanding to your bot and the LUIS documentation on how to train and publish an app to the production environment.

ナレッジ ベースQnA Maker作成するCreate the QnA Maker knowledge base

  1. ポータルまたは から QnAMaker サービスを qnamaker.ai、次の手順のリソース https://portal.azure.com キーを取得します。Create your QnAMaker service from qnamaker.ai portal or from https://portal.azure.com, get the resource key for the next step below.

  2. QnAMaker qna ファイルから QnAMaker kb を作成します。Create a QnAMaker kb from the QnAMaker qna file.

    1. 次のコマンドを実行して、アプリをインポート、トレーニング、および実稼働環境に発行します。Run the following command to import, train and publish the app to the production environment.

      > bf qnamaker:build --in CognitiveModels --subscriptionKey <YOUR-KEY> --botName <YOUR-BOT-NAME>
      
    2. 上記のコマンドQnA Maker kb、ホスト名、エンドポイント キーを記録します。Record the QnA Maker kb, hostname and endpoint key from the output of the command above.

Orchestrator スナップショット ファイルを作成するCreate the Orchestrator snapshot file

bf オーケストレーター ツールの CLI インターフェイスでは、実行時に適切な LUIS またはアプリにルーティングする Orchestrator スナップショット ファイルQnA Maker作成されます。The CLI interface for the bf orchestrator tool creates the Orchestrator snapshot file for routing to the correct LUIS or QnA Maker app at run time.

  1. コマンド プロンプトまたはターミナル ウィンドウを開き、ディレクトリをサンプル ディレクトリに変更しますOpen a command prompt or terminal window, and change directories to the sample directory

  2. npm の現在のバージョンと bf cli ツールがインストールされている必要があります。Make sure you have the current version of npm and the bf cli tool.

    npm i -g npm
    npm i -g @microsoft/botframework-cli
    
  3. Orchestrator の基本モデル ファイルをダウンロードするDownload Orchestrator base model file

    > mkdir model
    > bf orchestrator:basemodel:get --out ./model
    
  4. Orchestrator スナップショット ファイルを作成するCreate the Orchestrator snapshot file

    > mkdir generated
    > bf orchestrator:create --hierarchical --in ./CognitiveModels --out ./generated --model ./model
    

パッケージのインストールInstalling packages

このアプリを初めて実行する前に、いくつかの NuGet パッケージがインストールされていることを確認します。Prior to running this app for the first time ensure that several NuGet packages are installed:

  • Microsoft.Bot.BuilderMicrosoft.Bot.Builder
  • Microsoft.Bot.Builder.AI.LuisMicrosoft.Bot.Builder.AI.Luis
  • Microsoft.Bot.Builder.AI.QnAMicrosoft.Bot.Builder.AI.QnA
  • Microsoft.Bot.Builder.AI.OrchestratorMicrosoft.Bot.Builder.AI.Orchestrator

お使いの appsettings.json ファイルを手動で更新するManually update your appsettings.json file

すべてのサービス アプリが作成されたら、それぞれの情報を "appsettings.json" ファイルに追加する必要があります。Once all of your service apps are created, the information for each needs to be added into your 'appsettings.json' file. 初期 C# サンプル コードには、空の appsettings.json ファイルが含まれています。The initial C# Sample code contains an empty appsettings.json file:

appsettings.jsonappsettings.json


"LuisHomeAutomationAppId": "",
"LuisWeatherAppId": "",
"LuisAPIKey": "",
"LuisAPIHostName": "",

"AllowedHosts": "*",

"Orchestrator": {
  "ModelFolder": ".\\model",

次に示すエンティティごとに、前の手順で記録した値を追加します。For each of the entities shown below, add the values you recorded earlier in these instructions:

"MicrosoftAppId": "",
"MicrosoftAppPassword": "",

"QnAKnowledgebaseId": "<knowledge-base-id>",
"QnAEndpointKey": "<qna-maker-resource-key>",
"QnAEndpointHostName": "<your-hostname>",

"LuisAppId": "<app-id-for-dispatch-app>",
"LuisAPIKey": "<your-luis-endpoint-key>",
"LuisAPIHostName": "<your-dispatch-app-region>",

すべての変更が完了したら、このファイルを保存します。When all changes are complete, save this file.

ボットからサービスに接続するConnect to the services from your bot

LUIS に接続し、サービスQnA Maker、ボットは設定ファイルから情報を取得します。To connect to the LUIS, and QnA Maker services, your bot pulls information from the settings file.

BotServices.cs では、appsettings.js on の構成ファイルに含まれる情報を使用して、Orchestrator ボットを 、および サービス HomeAutomation Weather に接続 SampleQnA します。In BotServices.cs, the information contained within configuration file appsettings.json is used to connect your Orchestrator bot to the HomeAutomation, Weather and SampleQnA services. コンストラクターでは、ご自身で指定した値が、これらのサービスへの接続に使用されます。The constructors use the values you provided to connect to these services.

BotServices.csBotServices.cs

{
    public class BotServices : IBotServices
    {
        public BotServices(IConfiguration configuration, OrchestratorRecognizer dispatcher)
        {
            // Read the setting for cognitive services (LUIS, QnA) from the appsettings.json
            // If includeApiResults is set to true, the full response from the LUIS api (LuisResult)
            // will be made available in the properties collection of the RecognizerResult
            LuisHomeAutomationRecognizer = CreateLuisRecognizer(configuration, "LuisHomeAutomationAppId");
            LuisWeatherRecognizer = CreateLuisRecognizer(configuration, "LuisWeatherAppId");

            Dispatch = dispatcher;

            SampleQnA = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = configuration["QnAKnowledgebaseId"],
                EndpointKey = configuration["QnAEndpointKey"],
                Host = configuration["QnAEndpointHostName"]
            });
        }

        public OrchestratorRecognizer Dispatch { get; private set; }
        
        public QnAMaker SampleQnA { get; private set; }
        
        public LuisRecognizer LuisHomeAutomationRecognizer { get; private set; }

        public LuisRecognizer LuisWeatherRecognizer { get; private set; }

        private LuisRecognizer CreateLuisRecognizer(IConfiguration configuration, string appIdKey)
        {
            var luisApplication = new LuisApplication(
                configuration[appIdKey],
                configuration["LuisAPIKey"],
                configuration["LuisAPIHostName"]);

            // Set the recognizer options depending on which endpoint version you want to use.
            // More details can be found in https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3

ボットからのサービスを呼び出すCall the services from your bot

ユーザーからの入力ごとに、ボット ロジックはユーザー入力を Orchestrator Recognizer に渡し、返された上位の意図を検索し、その情報を使用して入力に適したサービスを呼び出します。For each input from your user, the bot logic passes in user input to Orchestrator Recognizer, finds the top returned intent, and uses that information to call the appropriate service for the input.

DispatchBot ファイルで、 OnMessageActivityAsync メソッドが呼び出されるたびに、受信ユーザーメッセージを確認し、Orchestrator レコグナイザーの最上位の目的を取得します。In the DispatchBot.cs file whenever the OnMessageActivityAsync method is called, we check the incoming user message and get the top intent from Orchestrator Recognizer. 次に、topIntent 認識 and izerresult ' を適切なメソッドに渡して、サービスを呼び出し、結果を返します。We then pass the topIntentand recognizerResult` on to the correct method to call the service and return the result.

bots\DispatchBot.csbots\DispatchBot.cs


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var dc = new DialogContext(new DialogSet(), turnContext, new DialogState());
    // Top intent tell us which cognitive service to use.
    var allScores = await _botServices.Dispatch.RecognizeAsync(dc, (Activity)turnContext.Activity, cancellationToken);
    var topIntent = allScores.Intents.First().Key;
    
    // Next, we call the dispatcher with the top intent.
    await DispatchToTopIntentAsync(turnContext, topIntent, cancellationToken);
}

認識結果を操作するWork with the recognition results

Orchestrator レコグナイザーによって結果が生成されると、(発話) を最も適切に処理できるサービスが示されます。When the Orchestrator recognizer produces a result, it indicates which service can most appropriately process the utterance. このボットのコードでは、要求を対応するサービスにルーティングし、呼び出されたサービスからの応答を要約します。The code in this bot routes the request to the corresponding service, and then summarizes the response from the called service. Orchestrator から返された インテント に応じて、このコードは返されたインテントを使用して正しい LUIS model または qna service にルーティングします。Depending on the intent returned from Orchestrator, this code uses the returned intent to route to the correct LUIS model or QnA service.

bots\DispatchBot.csbots\DispatchBot.cs

private async Task DispatchToTopIntentAsync(ITurnContext<IMessageActivity> turnContext, string intent, CancellationToken cancellationToken)
{
    switch (intent)
    {
        case "HomeAutomation":
            await ProcessHomeAutomationAsync(turnContext, cancellationToken);
            break;
        case "Weather":
            await ProcessWeatherAsync(turnContext, cancellationToken);
            break;
        case "QnAMaker":
            await ProcessSampleQnAAsync(turnContext, cancellationToken);
            break;
        default:
            _logger.LogInformation($"Dispatch unrecognized intent: {intent}.");
            await turnContext.SendActivityAsync(MessageFactory.Text($"Dispatch unrecognized intent: {intent}."), cancellationToken);
            break;
    }
}

ProcessHomeAutomationAsyncメソッドと ProcessWeatherAsync メソッドは、ターンコンテキストに含まれるユーザー入力を使用して、適切な LUIS モデルの最上位の目的とエンティティを取得します。The ProcessHomeAutomationAsync and ProcessWeatherAsync methods use the user input contained within the turn context to to get the top intent and entities from the correct LUIS model.

メソッドは、 ProcessSampleQnAAsync ターンコンテキスト内に含まれているユーザー入力を使用して、ナレッジベースから回答を生成し、その結果をユーザーに表示します。The ProcessSampleQnAAsync method uses the user input contained within the turn context to generate an answer from the knowledge base and display that result to the user.

注意

これが運用環境のアプリケーションの場合は、ここで、選択した LUIS メソッドが、指定されたサービスに接続されたうえで、そのメソッドによってユーザー入力が渡され、返された LUIS の意図とエンティティ データが処理されます。If this were a production application, this is where the selected LUIS methods would connect to their specified service, pass in the user input, and process the returned LUIS intent and entity data.

ボットをテストするTest your bot

  1. ご自身の開発環境を使用して、サンプル コードを開始します。Using your development environment, start the sample code. ご自身のアプリによって開かれたブラウザー ウィンドウのアドレス バーに表示されている次の localhost アドレスをメモしてください: "https://localhost:<Port_Number>"Note the localhost address shown in the address bar of the browser window opened by your App: "https://localhost:<Port_Number>".

  2. Bot Framework Emulator を開き、[ bot を開く ] ボタンをクリックします。Open Bot Framework Emulator, click on Open Bot button.

  3. [ ボットを開く ] ダイアログボックスで、bot エンドポイントの URL (など) を入力し http://localhost:3978/api/messages ます。In the Open a bot dialog box, enter your bot endpoint URL, such as http://localhost:3978/api/messages. [Connect] をクリックします。Click Connect.

  4. 参考のために、ご自身のボット用に作成されたサービスに含まれる質問とコマンドの一部を次に示します。For your reference, here are some of the questions and commands that are covered by the services built for your bot:

    • QnA MakerQnA Maker
      • hi, good morninghi, good morning
      • what are you, what do you dowhat are you, what do you do
    • LUIS (ホーム オートメーション)LUIS (home automation)
      • turn on bedroom light
      • turn off bedroom light
      • make some coffee
    • LUIS (天気)LUIS (weather)
      • whats the weather in redmond washington
      • what's the forecast for london
      • show me the forecast for nebraska

QnA Maker にユーザー (発話) をルーティングするRoute user utterance to QnA Maker

  1. Bot Emulator で、テキストを入力 hi し、(発話) を送信します。In the bot Emulator, enter the text hi and submit the utterance. Bot は、このクエリを Orchestrator に送信し、後続の処理のためにこの (発話) を取得する必要がある子アプリを示す応答を返します。The bot submits this query to Orchestrator and gets back a response indicating which child app should get this utterance for further processing.

  2. ログの行を選択すると、 Orchestrator Recognition Trace Bot Emulator で json 応答を確認できます。By selecting the Orchestrator Recognition Trace line in the log, you can see the json response in the bot Emulator . Orchestrator の結果がインスペクターに表示されます。The Orchestrator result is displayed in the Inspector.

    {
    "type": "trace",
    "timestamp": "2021-05-01T06:26:04.067Z",
    "serviceUrl": "http://localhost:58895",
    "channelId": "emulator",
    "from": {
      "id": "36b2a460-aa43-11eb-920f-7da472b36492",
      "name": "Bot",
      "role": "bot"
    },
    "conversation": {
      "id": "17ef3f40-aa46-11eb-920f-7da472b36492|livechat"
    },
    "recipient": {
      "id": "5f8c6123-2596-45df-928c-566d44426556",
      "role": "user"
    },
    "locale": "en-US",
    "replyToId": "1a3f70d0-aa46-11eb-8b97-2b2a779de581",
    "label": "Orchestrator Recognition",
    "valueType": "OrchestratorRecognizer",
    "value": {
      "text": "hi",
      "alteredText": null,
      "intents": {
        "QnAMaker": {
          "score": 0.9987310956576168
        },
        "HomeAutomation": {
          "score": 0.3402091165577196
        },
        "Weather": {
          "score": 0.24092200496795158
        }
      },
      "entities": {},
      "result": [
        {
          "Label": {
            "Type": 1,
            "Name": "QnAMaker",
            "Span": {
              "Offset": 0,
              "Length": 2
            }
          },
          "Score": 0.9987310956576168,
          "ClosestText": "hi"
        },
        {
          "Label": {
            "Type": 1,
            "Name": "HomeAutomation",
            "Span": {
              "Offset": 0,
              "Length": 2
            }
          },
          "Score": 0.3402091165577196,
          "ClosestText": "make some coffee"
        },
        {
          "Label": {
            "Type": 1,
            "Name": "Weather",
            "Span": {
              "Offset": 0,
              "Length": 2
            }
          },
          "Score": 0.24092200496795158,
          "ClosestText": "soliciting today's weather"
        }
      ]
    },
    "name": "OrchestratorRecognizerResult",
    "id": "1ae65f30-aa46-11eb-8b97-2b2a779de581",
    "localTimestamp": "2021-04-30T23:26:04-07:00"
    }
    

    発話 は Orchestrator の hi QnAMaker 意図の一部であり、 として選択されているので、ボットは 2 つ目の要求を行い、今回は同じ発話を持つ QnA Maker アプリに対して行います。 topScoringIntentBecause the utterance, hi, is part of the Orchestrator's QnAMaker intent, and is selected as the topScoringIntent, the bot will make a second request, this time to the QnA Maker app, with the same utterance.

  3. ボット エミュレーター QnAMaker Trace ログの行を選択します。Select the QnAMaker Trace line in the bot Emulator log. インスペクターに QnA Maker の結果が表示されます。The QnA Maker result displays in the Inspector.

    {
        "questions": [
            "hi",
            "greetings",
            "good morning",
            "good evening"
        ],
        "answer": "Hello!",
        "score": 1,
        "id": 96,
        "source": "QnAMaker.tsv",
        "metadata": [],
        "context": {
            "isContextOnly": false,
            "prompts": []
        }
    }