クイック スタート:QnA Maker クライアント ライブラリ

  • [アーティクル]

Note

Azure Open AI On Your Data は、大規模言語モデル (LLM) を利用して、QnA Maker と同様の結果を生成します。 QnA Maker プロジェクトを Azure Open AI On Your Data に移行する場合は、ガイドを確認してください。

QnA Maker クライアント ライブラリの使用を開始します。 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

Note

QnA Maker サービスは、2025 年 3 月 31 日に廃止される予定です。 Azure AI Language の一部として、質問応答機能の新しいバージョンが提供されました。 言語サービス内の質問応答機能については、質問応答に関する記事を参照してください。 QnA Maker の新しいリソースは、2022 年 10 月 1 日以降作成できません。 既存の QnA Maker のナレッジ ベースを質問応答に移行する方法については、移行ガイドを参照してください。

前提条件

Note

このドキュメントは、最新のリリースには適用されません。 最新リリースでの REST API の使用方法は、REST クイックスタートに回答する質問を参照してください。

  • 最新バージョンの cURL。 クイックスタートでは、いくつかのコマンド ライン スイッチが使用されています。これらのスイッチについては、cURL のドキュメントを参照してください。

  • キーとリソース名を使用するには、QnA Maker リソースが必要です。 リソースの作成時にリソースの名前を入力した後に、キーが作成されています。 リソース名は、エンドポイントのサブドメインとして使用されます。 キーとリソース名を取得するには、Azure portal で目的のリソースの [クイックスタート] を選択します。 リソース名は、エンドポイントの URL の最初のサブドメインです。

    https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0

注意事項

以降に掲載した BASH の例では、行連結文字として \ を使用しています。 ご利用のコンソールまたはターミナルで異なる行連結文字が使用されている場合は、この文字を使用してください。

ナレッジ ベースの作成

REST API と cURL を使用してナレッジ ベースを作成するには、次の情報が必要です。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
QnA Maker リソースのキー Ocp-Apim-Subscription-Key ヘッダーの -h パラメーター QnA Maker サービスに対する認証
ナレッジ ベースを表す JSON -d パラメーター JSON の例
JSON のサイズ (バイト単位) Content-Size ヘッダーの -h パラメーター

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名、リソース キー、JSON の値、JSON のサイズに合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'

QnA Maker から返される cURL の応答には operationId が含まれており、operationIdするためには、この ID が必要となります。

{
  "operationState": "NotStarted",
  "createdTimestamp": "2020-02-27T04:11:22Z",
  "lastActionTimestamp": "2020-02-27T04:11:22Z",
  "userId": "9596077b3e0441eb93d5080d6a15c64b",
  "operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}

操作の状態を取得する

ナレッジ ベースを作成するとき、操作は非同期で実行されるため、その状態を判別する情報が応答には含まれています。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
操作 ID URL ルート /operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker リソースのキー Ocp-Apim-Subscription-Key ヘッダーの -h パラメーター QnA Maker サービスに対する認証

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名、リソース キー、操作 ID に合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

cURL の応答には状態が含まれています。 操作の状態が成功である場合は、resourceLocation にナレッジ ベース ID が含まれています。

{
   "operationState": "Succeeded",
   "createdTimestamp": "2020-02-27T04:54:07Z",
   "lastActionTimestamp": "2020-02-27T04:54:19Z",
   "resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
   "userId": "f596077b3e0441eb93d5080d6a15c64b",
   "operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}

ナレッジ ベースを公開する

ナレッジ ベースにクエリを実行する前に、次のことを行う必要があります。

  • ナレッジ ベースを公開する
  • ランタイム エンドポイント キーを取得する

このタスクでは、ナレッジ ベースを公開します。 ランタイム エンドポイント キーの取得は、別のタスクです。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
QnA Maker リソースのキー Ocp-Apim-Subscription-Key ヘッダーの -h パラメーター QnA Maker サービスに対する認証
ナレッジ ベース ID URL ルート /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名、リソース キー、ナレッジ ベース ID に合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''

応答状態は、結果を伴わない 204 です。 cURL コマンドの詳細出力を表示するには、-v コマンド ライン パラメーターを使用してください。 これには HTTP の状態が含まれます。

公開されたナレッジ ベースのランタイム エンドポイント キーを取得する

ナレッジ ベースにクエリを実行する前に、次のことを行う必要があります。

  • ナレッジ ベースを公開する
  • ランタイム エンドポイント キーを取得する

このタスクでは、ランタイム エンドポイント キーを取得します。 ナレッジ ベースの公開は、別のタスクです。

ランタイム エンドポイント キーは、QnA Maker リソースを使用するすべてのナレッジ ベースに共通するキーです。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
QnA Maker リソースのキー Ocp-Apim-Subscription-Key ヘッダーの -h パラメーター QnA Maker サービスに対する認証

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名とリソース キーに合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

cURL の応答には、ランタイム エンドポイント キーが含まれています。 ナレッジ ベースから回答を取得するためのクエリを実行する際は、これらのキーのうち 1 つだけを使用します。

{
  "primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
  "secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
  "installedVersion": "4.0.5",
  "lastStableVersion": "4.0.6"
}

公開されたナレッジ ベースから回答を得るためのクエリを実行する

ナレッジ ベースからの回答の取得は、ナレッジ ベースの管理とは別のランタイムから行います。 これは独立したランタイムであるため、ランタイム キーを使用して認証する必要があります。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
QnA Maker のランタイム キー Authorization ヘッダーの -h パラメーター キーは、Endpointkey という単語を含む文字列の一部です。 QnA Maker サービスに対する認証
ナレッジ ベース ID URL ルート /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
クエリを表す JSON -d パラメーター JSON の要求本文のパラメーターと例
JSON のサイズ (バイト単位) Content-Size ヘッダーの -h パラメーター

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名、リソース キー、ナレッジ ベース ID に合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true,  "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'

成功の応答には、上位の回答が含まれるほか、クライアント アプリケーション (チャット ボットなど) がユーザーに回答を表示する際に必要となる情報も含まれます。

ナレッジ ベースの削除

ナレッジ ベースの使用を終了したら、それを削除します。

Information cURL の構成 目的
QnA Maker リソースの名前 URL URL の構築用
QnA Maker リソースのキー Ocp-Apim-Subscription-Key ヘッダーの -h パラメーター QnA Maker サービスに対する認証
ナレッジ ベース ID URL ルート /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

cURL コマンドは、BASH シェルから実行します。 コマンドは、実際のリソース名、リソース キー、ナレッジ ベース ID に合わせて編集してください。

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

応答状態は、結果を伴わない 204 です。 cURL コマンドの詳細出力を表示するには、-v コマンド ライン パラメーターを使用してください。 これには HTTP の状態が含まれます。

その他のリソース

.NET 用 QnA Maker クライアント ライブラリは、次の目的で使用することができます。

  • ナレッジベースを作成する
  • ナレッジ ベースの更新
  • ナレッジ ベースの公開
  • 予測ランタイム エンドポイント キーの取得
  • 実行時間の長いタスクの待機
  • ナレッジ ベースのダウンロード
  • ナレッジ ベースから回答を取得する
  • ナレッジベースを削除する

リファレンス ドキュメント | ライブラリのソース コード | パッケージ (NuGet) | C# サンプル

Note

2019 年 7 月 1 日より後に作成された新しいリソースには、カスタム サブドメイン名が使用されます。 リージョンのエンドポイントの詳細および全一覧については、「Azure AI サービスのカスタム サブドメイン名」を参照してください。

前提条件

Note

このドキュメントは、最新のリリースには適用されません。 最新リリースでの C# API の使用方法は、C# クイックスタートに回答する質問を参照してください。

  • Azure サブスクリプション - 無料アカウントを作成します
  • Visual Studio IDE または現在のバージョンの .NET Core。
  • Azure サブスクリプションを入手したら、Azure portal で QnA Maker リソースを作成し、オーサリング キーとリソース名を取得します。 デプロイされたら、 [リソースに移動] を選択します。
    • アプリケーションを QnA Maker API に接続するには、作成したリソースのキーとリソース名が必要です。 このクイックスタートで後に示すコードに、自分のキーとリソース名を貼り付けます。
    • Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

設定

CLI

コンソール ウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、qna-maker-quickstart という名前で新しいコンソール アプリを作成します。 このコマンドにより、1 つのソース ファイル (program.cs) を使用する単純な "Hello World" C# プロジェクトが作成されます。

dotnet new console -n qna-maker-quickstart

新しく作成されたアプリ フォルダーにディレクトリを変更します。 次を使用してアプリケーションをビルドできます。

dotnet build

ビルドの出力に警告やエラーが含まれないようにする必要があります。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

次のコマンドを使用して、アプリケーション ディレクトリ内に .NET 用 QnA Maker クライアント ライブラリをインストールします。

dotnet add package Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker --version 2.0.1

ヒント

クイックスタートのコード ファイル全体を一度にご覧いただけます。 これは GitHub にあり、このクイックスタートのコード例が含まれています。

ディレクティブの使用

プロジェクト ディレクトリから program.cs ファイルを開いて、次の using ディレクティブを追加します。

using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker;
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

サブスクリプション キーとリソース エンドポイント

このクイックスタートの共通のタスクを使用するために、次のセクションに示す変数とコードをアプリケーションの Main メソッドに追加します。

  • サブスクリプション キーとオーサリング キーは同じ意味で使用しています。 オーサリング キーの詳細については、「QnA Maker のキー」を参照してください。

  • QNA_MAKER_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [リソース管理] の [キーとエンドポイント] ページを選び、オーサリング (サブスクリプション) キーと QnA Maker のエンドポイントを見つけます。

QnA Maker 作成エンドポイント

  • QNA_MAKER_RUNTIME_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.azurewebsites.net です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [オートメーション] の [テンプレートのエクスポート] ページを選んで、ランタイム エンドポイントを見つけます。

QnA Maker のランタイム エンドポイント

重要

終わったらコードからキーを削除し、公開しないよう注意してください。 運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。 詳細については、Azure AI サービスのセキュリティに関する記事を参照してください。

var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

オブジェクト モデル

QnA Maker では、2 種類のオブジェクト モデルが使用されます。

  • QnAMakerClient は、ナレッジ ベースを作成、管理、公開、ダウンロードするためのオブジェクトです。
  • QnAMakerRuntime は、GenerateAnswer API を使用してナレッジ ベースを照会したり、Train API を使用して (アクティブ ラーニングの一環として) 提案された新しい質問を送信したりするためのオブジェクトです。

このサンプル ナレッジ ベースを使用する

このクイックスタートのナレッジ ベースは、2 つの会話型 QnA ペアから始めます。これは、例を簡略化し、Update メソッドで使用するための高度に予測可能な ID を持つようにするために行われます。これにより、質問を含むフォローアップ プロンプトが新しいペアに関連付けられます。 このクイックスタートでは、特定の順序でこれを計画、実装しています。

いずれ、既存の QnA ペアに依存するフォローアップ プロンプトを使用してナレッジ ベースを開発する予定である場合、次の方法を選択できます。

  • 大規模なナレッジ ベースの場合、自動化をサポートする TSV ツールまたはテキスト エディターでナレッジ ベースを管理し、その後一度に、ナレッジ ベース全体を更新版に置き換えます。
  • 比較的小規模なナレッジ ベースの場合、QnA Maker ポータルのみでフォローアップ プロンプトを管理します。

このクイックスタートで使用される QnA ペアの詳細は次のとおりです。

  • QnA ペアの種類 - 更新後、このナレッジ ベースには、おしゃべりとドメイン固有情報の 2 種類の QnA ペアがあります。 これは、ナレッジ ベースがチャットボットなどのメッセージ交換アプリケーションに関連付けられている場合に一般的です。
  • ナレッジ ベースの回答は、メタデータによってフィルター処理されたり、フォローアップ プロンプトを使用したりする場合がありますが、このクイックスタートでは示しません。 これらの言語に依存しない generateAnswer の例については、ここを参照してください。
  • 回答テキストは Markdown で、画像 (一般公開されているインターネット上の画像)、リンク (一般公開されている URL へのリンク)、箇条書きなどのさまざまな Markdown を含めることができますが、このクイックスタートではそれらを使用しません。

QnAMakerClient オブジェクト モデル

作成の QnA Maker クライアントは、自分のキーが含まれている Microsoft.Rest.ServiceClientCredentials を使用して Azure に対する認証を行う QnAMakerClient オブジェクトです。

クライアントが作成されたら、ナレッジ ベース プロパティを使用して、ナレッジ ベースを作成、管理、および公開します。

JSON オブジェクトを送信して、ナレッジ ベースを管理します。 即時操作の場合は、通常、状態を示す JSON オブジェクトがメソッドから返されます。 実行時間の長い操作の場合、応答は操作 ID になります。 client.Operations.GetDetailsAsync メソッドを操作 ID と共に呼び出して、要求の状態を確認します。

QnAMakerRuntimeClient オブジェクト モデル

予測の QnA Maker クライアントは、QnAMakerRuntimeClient オブジェクトです。ナレッジベースの発行後に作成クライアントの呼び出し (client.EndpointKeys.GetKeys) から返される Microsoft.Rest.ServiceClientCredentials (予測ランタイム キーを含む) を使用して Azure に対する認証を行います。

クエリ ランタイムから回答を取得するには、GenerateAnswer メソッドを使用します。

コード例

以下のコード スニペットは、.NET 用 QnA Maker クライアント ライブラリを使用して次のことを実行する方法を示します。

ナレッジ ベースを作成するためのクライアントを認証する

キーを使用してクライアント オブジェクトをインスタンス化し、リソースと共にそれを使用してエンドポイントを構築し、エンドポイントとキーを使用して QnAMakerClient を作成します。 ServiceClientCredentials オブジェクトを作成します。

var client = new QnAMakerClient(new ApiKeyServiceClientCredentials(authoringKey))
{ Endpoint = authoringURL };

ナレッジ ベースの作成

ナレッジ ベースには、次の 3 つのソースの CreateKbDTO オブジェクトに対する質問と回答のペアが格納されます。

  • 本文の場合は、QnADTO オブジェクトを使用します。
    • メタデータとフォローアップ プロンプトを使用するには、編集コンテキストを使用します (このデータは個々の QnA ペア レベルで追加されるため)。
  • ファイルの場合は、FileDTO オブジェクトを使用します。 FileDTO には、ファイル名と、ファイルに到達するためのパブリック URL が含まれます。
  • URL の場合は、公開されている URL を表す文字列のリストを使用します。

作成手順には、ナレッジ ベースのプロパティも含まれます。

  • defaultAnswerUsedForExtraction - 回答が見つからない場合に返されるもの
  • enableHierarchicalExtraction - 抽出された QnA ペア間のプロンプト関係を自動的に作成する
  • language - リソースの最初のナレッジ ベースを作成するときに、Azure Search インデックスで使用する言語を設定する

CreateAsync メソッドを呼び出した後、返された操作 ID を MonitorOperation メソッドに渡して、状態をポーリングします。

次のコードの最後の行では、MonitorOperation の応答からナレッジ ベース ID を返しています。

private static async Task<string> CreateSampleKb(IQnAMakerClient client)
{
    var qna1 = new QnADTO
    {
        Answer = "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        Questions = new List<string> { "How do I manage my knowledgebase?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = "REST" }
        },

    };

    var qna2 = new QnADTO
    {
        Answer = "Yes, You can use our [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker) with the [.NET Reference Docs](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.knowledge.qnamaker?view=azure-dotnet) to manage your knowledge base.",
        Questions = new List<string> { "Can I program with C#?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = ".NET" }
        }
    };

    var file1 = new FileDTO
    {
        FileName = "myfile.tsv",
        FileUri = "https://mydomain/myfile.tsv"

    };

    var createKbDto = new CreateKbDTO
    {
        Name = "QnA Maker .NET SDK Quickstart",
        QnaList = new List<QnADTO> { qna1, qna2 },
        //Files = new List<FileDTO> { file1 }

    };

    var createOp = await client.Knowledgebase.CreateAsync(createKbDto);
    createOp = await MonitorOperation(client, createOp);

    return createOp.ResourceLocation.Replace("/knowledgebases/", string.Empty);
}

ナレッジ ベースを適切に作成するには、上記のコードで参照されている MonitorOperation 関数を必ず含めます。

ナレッジ ベースの更新

ナレッジ ベースを更新するには、ナレッジ ベース ID と、add、update、および delete DTO オブジェクトを含む UpdatekbOperationDTO を、UpdateAsync メソッドに渡します。 更新が成功したかどうかを確認するには、MonitorOperation メソッドを使用します。

private static async Task UpdateKB(IQnAMakerClient client, string kbId)
{

    var urls = new List<string> {
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    };

    var updateOp = await client.Knowledgebase.UpdateAsync(kbId, new UpdateKbOperationDTO
    {
        // Create JSON of changes
        Add = new UpdateKbOperationDTOAdd
        {
            QnaList = new List<QnADTO> {
                new QnADTO {
                    Questions = new List<string> {
                        "bye",
                        "end",
                        "stop",
                        "quit",
                        "done"
                    },
                    Answer = "goodbye",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "end" },
                    }
                },
                new QnADTO {
                    Questions = new List<string> {
                        "hello",
                        "hi",
                        "start"
                    },
                    Answer = "Hello, please select from the list of questions or enter a new question to continue.",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "begin" }
                    },
                    Context = new QnADTOContext
                    {
                        IsContextOnly = false,
                        Prompts = new List<PromptDTO>
                        {
                            new PromptDTO
                            {
                                DisplayOrder =1,
                                DisplayText= "Use REST",
                                QnaId=1

                            },
                            new PromptDTO
                            {
                                DisplayOrder =2,
                                DisplayText= "Use .NET NuGet package",
                                QnaId=2

                            },
                        }
                    }
                },
            },
            Urls = urls
        },
        Update = null,
        Delete = null
    }); ;

    // Loop while operation is success
    updateOp = await MonitorOperation(client, updateOp);
}

ナレッジ ベースを適切に更新するには、上記のコードで参照されている MonitorOperation 関数を必ず含めます。

ナレッジ ベースのダウンロード

データベースを QnADocumentsDTO のリストとしてダウンロードするには、DownloadAsync メソッドを使用します。 このメソッドの結果はファイルではないため、これは、QnA Maker ポータルの [設定] ページからのエクスポートと同等 "ではありません"。

private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
    var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
    Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);

    // Do something meaningful with data
}

ナレッジ ベースの公開

PublishAsync メソッドを使用して、ナレッジ ベースを公開します。 これにより、ナレッジ ベース ID によって参照される、最新の保存済みおよびトレーニング済みのモデルが取得され、エンドポイントで公開されます。 これは、ナレッジ ベースに対してクエリを実行するために必要な手順です。

private static async Task PublishKb(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.PublishAsync(kbId);
}

クエリ ランタイム キーの取得

ナレッジ ベースの公開後、ランタイムに対してクエリを実行するには、クエリ ランタイム キーが必要です。 これは、元のクライアント オブジェクトを作成するときに使用したキーとは異なります。

EndpointKeys メソッドを使用して、EndpointKeysDTO クラスを取得します。

そのオブジェクトに返されたいずれかのキー プロパティを使用して、ナレッジ ベースにクエリを実行します。

private static async Task<String> GetQueryEndpointKey(IQnAMakerClient client)
{
    var endpointKeysObject = await client.EndpointKeys.GetKeysAsync();

    return endpointKeysObject.PrimaryEndpointKey;
}

ナレッジ ベースに対してクエリを実行するには、ランタイム キーが必要です。

回答を生成するためのランタイムを認証する

ナレッジ ベースにクエリを実行して回答を生成したり、アクティブ ラーニングからトレーニングしたりするための QnAMakerRuntimeClient を作成します。

var runtimeClient = new QnAMakerRuntimeClient(new EndpointKeyServiceClientCredentials(primaryQueryEndpointKey))
{ RuntimeEndpoint = queryingURL };

QnAMakerRuntimeClient を使用して、次のことを行います。

  • ナレッジ ベースから回答を取得する
  • アクティブ ラーニングのために、新しく提案された質問をナレッジ ベースに送信する

ナレッジ ベースから回答を生成する

RuntimeClient.GenerateAnswerAsync メソッドを使用して公開済みのナレッジ ベースから回答を生成します。 このメソッドは、ナレッジ ベース ID と QueryDTO を受け取ります。 さらに、Top や Context など、QueryDTO のプロパティにアクセスしてチャット ボットで使用することができます。

private static async Task GenerateAnswer(IQnAMakerRuntimeClient runtimeClient, string kbId)
{
    var response = await runtimeClient.Runtime.GenerateAnswerAsync(kbId, new QueryDTO { Question = "How do I manage my knowledgebase?" });
    Console.WriteLine("Endpoint Response: {0}.", response.Answers[0].Answer);

    // Do something meaningful with answer
}

これは、ナレッジ ベースに対してクエリを実行する単純な例です。 高度なクエリ シナリオについては、他のクエリ サンプルをご覧ください。

ナレッジ ベースを削除する

DeleteAsync メソッドをナレッジ ベース ID のパラメーターと共に使用して、ナレッジ ベースを削除します。

private static async Task DeleteKB(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.DeleteAsync(kbId);
}

操作の状態の取得

create や update などのメソッドの中には、プロセスが終了するのを待つ代わりに、操作が返されるのに十分な時間がかかるものがあります。 操作からの操作 ID を使用して、(再試行ロジックを使用して) ポーリングし、元のメソッドの状態を判別します。

次のコード ブロックのループと Task.Delay は、再試行ロジックをシミュレートするために使用されています。 これらは自分の再試行ロジックに置き換える必要があります。

private static async Task<Operation> MonitorOperation(IQnAMakerClient client, Operation operation)
{
    // Loop while operation is success
    for (int i = 0;
        i < 20 && (operation.OperationState == OperationStateType.NotStarted || operation.OperationState == OperationStateType.Running);
        i++)
    {
        Console.WriteLine("Waiting for operation: {0} to complete.", operation.OperationId);
        await Task.Delay(5000);
        operation = await client.Operations.GetDetailsAsync(operation.OperationId);
    }

    if (operation.OperationState != OperationStateType.Succeeded)
    {
        throw new Exception($"Operation {operation.OperationId} failed to completed.");
    }
    return operation;
}

アプリケーションの実行

自分のアプリケーション ディレクトリで dotnet run コマンドを使用してアプリケーションを実行します。

dotnet run

このサンプルのソース コードは、GitHub にあります。

Node.js 用 QnA Maker クライアント ライブラリは、次の目的で使用することができます。

  • ナレッジ ベースの作成
  • ナレッジ ベースの更新
  • ナレッジ ベースの公開
  • 予測ランタイム エンドポイント キーの取得
  • 実行時間の長いタスクの待機
  • ナレッジ ベースのダウンロード
  • ナレッジ ベースから回答を取得する
  • ナレッジ ベースの削除

リファレンス ドキュメント | パッケージ (npm) | Node.js サンプル

Note

2019 年 7 月 1 日より後に作成された新しいリソースには、カスタム サブドメイン名が使用されます。 リージョンのエンドポイントの詳細および全一覧については、「Azure AI サービスのカスタム サブドメイン名」を参照してください。

前提条件

  • Azure サブスクリプション - 無料アカウントを作成します
  • 最新バージョンの Node.js。
  • Azure サブスクリプションを入手したら、Azure portal で QnA Maker リソースを作成し、オーサリング キーとリソースを取得します。 デプロイされたら、 [リソースに移動] を選択します。
    • アプリケーションを QnA Maker API に接続するには、作成したリソースのキーとリソース名が必要です。 このクイックスタートで後に示すコードに、自分のキーとリソース名を貼り付けます。
    • Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

設定

新しい Node.js アプリケーションを作成する

コンソール ウィンドウ (cmd、PowerShell、Bash など) で、ご利用のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir qnamaker_quickstart && cd qnamaker_quickstart

npm init -y コマンドを実行し、package.json ファイルを使用して node アプリケーションを作成します。

npm init -y

クライアント ライブラリをインストールする

次の NPM パッケージをインストールします。

npm install @azure/cognitiveservices-qnamaker
npm install @azure/cognitiveservices-qnamaker-runtime
npm install @azure/ms-rest-js

アプリの package.json ファイルが依存関係によって更新されます。

index.js という名前のファイルを作成し、次のライブラリをインポートします。

const msRest = require("@azure/ms-rest-js");
const qnamaker = require("@azure/cognitiveservices-qnamaker");
const qnamaker_runtime = require("@azure/cognitiveservices-qnamaker-runtime");

リソース名とリソースの Azure キーに対応する変数を作成します。

  • サブスクリプション キーとオーサリング キーは同じ意味で使用しています。 オーサリング キーの詳細については、「QnA Maker のキー」を参照してください。

  • QNA_MAKER_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [リソース管理] の [キーとエンドポイント] ページを選び、オーサリング (サブスクリプション) キーと QnA Maker のエンドポイントを見つけます。

QnA Maker 作成エンドポイント

  • QNA_MAKER_RUNTIME_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.azurewebsites.net です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [オートメーション] の [テンプレートのエクスポート] ページを選んで、ランタイム エンドポイントを見つけます。

QnA Maker のランタイム エンドポイント

重要

終わったらコードからキーを削除し、公開しないよう注意してください。 運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。 詳細については、Azure AI サービスのセキュリティに関する記事を参照してください。

const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

オブジェクト モデル

QnA Maker では、2 種類のオブジェクト モデルが使用されます。

  • QnAMakerClient は、ナレッジ ベースを作成、管理、公開、ダウンロードするためのオブジェクトです。
  • QnAMakerRuntime は、GenerateAnswer API を使用してナレッジ ベースを照会したり、Train API を使用して (アクティブ ラーニングの一環として) 提案された新しい質問を送信したりするためのオブジェクトです。

QnAMakerClient オブジェクト モデル

作成 QnA Maker クライアントは、キーが含まれている資格情報を使用して Azure に対して認証する QnAMakerClient オブジェクトです。

クライアントが作成されたら、knowledgebase を使用して、ナレッジ ベースを作成、管理、公開します。

JSON オブジェクトを送信して、ナレッジ ベースを管理します。 即時操作の場合は、通常、状態を示す JSON オブジェクトがメソッドから返されます。 実行時間の長い操作の場合、応答は操作 ID になります。 client.operations.getDetails メソッドを操作 ID と共に呼び出して、要求の状態を確認します。

QnAMakerRuntimeClient オブジェクト モデル

予測の QnA Maker クライアントは、QnAMakerRuntimeClient オブジェクトです。ナレッジ ベースの公開後に作成クライアントの呼び出し (client.EndpointKeys.getKeys) から返される Microsoft.Rest.ServiceClientCredentials (予測ランタイム キーを含む) を使用して Azure に対する認証を行います。

コード例

以下のコード スニペットは、.NET 用 QnA Maker クライアント ライブラリを使用して次のことを実行する方法を示します。

ナレッジ ベースを作成するためのクライアントを認証する

ご利用のエンドポイントとキーを使用してクライアントをインスタンス化します。 自分のキーを使用して ServiceClientCredentials オブジェクトを作成し、それを自分のエンドポイントと共に使用して、QnAMakerClient オブジェクトを作成します。

const creds = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': subscription_key } });
const qnaMakerClient = new qnamaker.QnAMakerClient(creds, endpoint);
const knowledgeBaseClient = new qnamaker.Knowledgebase(qnaMakerClient);

ナレッジ ベースの作成

ナレッジ ベースには、次の 3 つのソースの CreateKbDTO オブジェクトに対する質問と回答のペアが格納されます。

  • 本文の場合は、QnADTO オブジェクトを使用します。
    • メタデータとフォローアップ プロンプトを使用するには、編集コンテキストを使用します (このデータは個々の QnA ペア レベルで追加されるため)。
  • ファイルの場合は、FileDTO オブジェクトを使用します。 FileDTO には、ファイル名と、ファイルに到達するためのパブリック URL が含まれます。
  • URL の場合は、公開されている URL を表す文字列のリストを使用します。

作成手順には、ナレッジ ベースのプロパティも含まれます。

  • defaultAnswerUsedForExtraction - 回答が見つからない場合に返されるもの
  • enableHierarchicalExtraction - 抽出された QnA ペア間のプロンプト関係を自動的に作成する
  • language - リソースの最初のナレッジ ベースを作成するときに、Azure Search インデックスで使用する言語を設定する

ナレッジ ベース情報を使用して、create メソッドを呼び出します。 ナレッジ ベース情報は、基本的に JSON オブジェクトです。

create メソッドから戻ったら、返された操作 ID を wait_for_operation メソッドに渡して、状態をポーリングします。 操作が完了すると、wait_for_operation メソッドから戻ってきます。 返された操作の resourceLocation ヘッダー値を解析して、新しいナレッジ ベース ID を取得します。

const createKnowledgeBase = async (qnaClient, kbclient) => {

    console.log(`Creating knowledge base...`)

    const qna1 = {
        answer: "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "REST" }
        ]
    };

    const qna2 = {
        answer: "Yes, You can use our JS SDK on NPM for [authoring](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker), [query runtime](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker-runtime), and [the reference docs](https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-qnamaker/?view=azure-node-latest) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "JavaScript" }
        ]
    };

    const create_kb_payload = {
        name: 'QnA Maker JavaScript SDK Quickstart',
        qnaList: [
            qna1,
            qna2
        ],
        urls: [],
        files: [
            /*{
                fileName: "myfile.md",
                fileUri: "https://mydomain/myfile.md"
            }*/
        ],
        defaultAnswerUsedForExtraction: "No answer found.",
        enableHierarchicalExtraction: true,
        language: "English"
    };

    const results = await kbclient.create(create_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Create request failed - HTTP status ${results._response.status}`)
        return
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (!operationResult || !operationResult.operationState || !(operationResult.operationState = "Succeeded") || !operationResult.resourceLocation) {
        console.log(`Create operation state failed - HTTP status ${operationResult._response.status}`)
        return
    }

    // parse resourceLocation for KB ID
    const kbID = operationResult.resourceLocation.replace("/knowledgebases/", "");

    return kbID;
}

ナレッジ ベースを適切に作成するには、上記のコードで参照されている wait_for_operation 関数を必ず含めます。

ナレッジ ベースの更新

ナレッジ ベースを更新するには、ナレッジ ベース ID と、add、update、delete DTO オブジェクトを含む UpdateKbOperationDTO を、update メソッドに渡します。 DTO も、基本的に JSON オブジェクトです。 更新が成功したかどうかを確認するには、wait_for_operation メソッドを使用します。

const updateKnowledgeBase = async (qnaClient, kbclient, kb_id) => {

    console.log(`Updating knowledge base...`)

    const urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]

    const qna3 = {
        answer: "goodbye",
        questions: [
            "bye",
            "end",
            "stop",
            "quit",
            "done"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "end" }
        ]
    };

    const qna4 = {
        answer: "Hello, please select from the list of questions or enter a new question to continue.",
        questions: [
            "hello",
            "hi",
            "start"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "begin" }
        ],
        context: {
            isContextOnly: false,
            prompts: [
                {
                    displayOrder: 1,
                    displayText: "Use REST",
                    qna: null,
                    qnaId: 1
                },
                {
                    displayOrder: 2,
                    displayText: "Use JS NPM package",
                    qna: null,
                    qnaId: 2
                },
            ]
        }
    };

    console.log(JSON.stringify(qna4))

    // Add new Q&A lists, URLs, and files to the KB.
    const kb_add_payload = {
        qnaList: [
            qna3,
            qna4
        ],
        urls: urls,
        files: []
    };

    // Bundle the add, update, and delete requests.
    const update_kb_payload = {
        add: kb_add_payload,
        update: null,
        delete: null,
        defaultAnswerUsedForExtraction: "No answer found. Please rephrase your question."
    };

    console.log(JSON.stringify(update_kb_payload))

    const results = await kbclient.update(kb_id, update_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Update request failed - HTTP status ${results._response.status}`)
        return false
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (operationResult.operationState != "Succeeded") {
        console.log(`Update operation state failed - HTTP status ${operationResult._response.status}`)
        return false
    }

    console.log(`Update operation state ${operationResult._response.status} - HTTP status ${operationResult._response.status}`)
    return true
}

ナレッジ ベースを適切に更新するには、上記のコードで参照されている wait_for_operation 関数を必ず含めます。

ナレッジ ベースのダウンロード

データベースを QnADocumentsDTO のリストとしてダウンロードするには、download メソッドを使用します。 このメソッドの結果は TSV ファイルではないため、これは、QnA Maker ポータルの [設定] ページからのエクスポートと同等 "ではありません"。

const downloadKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Downloading knowledge base...`)

    var kbData = await KBclient.download(kb_id, "Prod");
    console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);

    // Do something meaningful with data
}

ナレッジ ベースの公開

publish メソッドを使用して、ナレッジ ベースを公開します。 これにより、ナレッジ ベース ID によって参照される、最新の保存済みおよびトレーニング済みのモデルが取得され、エンドポイントで公開されます。 HTTP 応答コードを調べて、発行が成功したことを検証します。

const publishKnowledgeBase = async (kbclient, kb_id) => {

    console.log(`Publishing knowledge base...`)

    const results = await kbclient.publish(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Publish request failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Publish request succeeded - HTTP status ${results._response.status}`)

    return true
}

ナレッジ ベースにクエリを実行する

クエリ ランタイム キーの取得

ナレッジ ベースの公開後、ランタイムに対してクエリを実行するには、クエリ ランタイム キーが必要です。 これは、元のクライアント オブジェクトを作成するときに使用したキーとは異なります。

EndpointKeys.getKeys メソッドを使用して、EndpointKeysDTO クラスを取得します。

そのオブジェクトに返されたいずれかのキー プロパティを使用して、ナレッジ ベースにクエリを実行します。

const getEndpointKeys = async (qnaClient) => {

    console.log(`Getting runtime endpoint keys...`)

    const runtimeKeysClient = await qnaClient.endpointKeys;
    const results = await runtimeKeysClient.getKeys()

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`GetEndpointKeys request failed - HTTP status ${results._response.status}`)
        return null
    }

    console.log(`GetEndpointKeys request succeeded - HTTP status ${results._response.status} - primary key ${results.primaryEndpointKey}`)

    return results.primaryEndpointKey
}

回答を生成するためのランタイムを認証する

ナレッジ ベースにクエリを実行して回答を生成したり、アクティブ ラーニングからトレーニングしたりするための QnAMakerRuntimeClient を作成します。

const queryRuntimeCredentials = new msRest.ApiKeyCredentials({ inHeader: { 'Authorization': 'EndpointKey ' + primaryQueryRuntimeKey } });
const runtimeClient = new qnamaker_runtime.QnAMakerRuntimeClient(queryRuntimeCredentials, runtime_endpoint);

QnAMakerRuntimeClient を使用してナレッジから回答を取得するか、または、アクティブ ラーニングを目的として提案された新しい質問をナレッジ ベースに送信します。

ナレッジ ベースから回答を生成する

RuntimeClient.runtime.generateAnswer メソッドを使用して公開済みのナレッジ ベースから回答を生成します。 このメソッドは、ナレッジ ベース ID と QueryDTO を受け取ります。 さらに、Top や Context など、QueryDTO のプロパティにアクセスしてチャット ボットで使用することができます。

const generateAnswer = async (runtimeClient, runtimeKey, kb_id) => {

    console.log(`Querying knowledge base...`)

    const requestQuery = await runtimeClient.runtime.generateAnswer(
        kb_id,
        {
            question: "How do I manage my knowledgebase?",
            top: 1,
            strictFilters: [
                { name: "Category", value: "api" }
            ]
        }
    );
    console.log(JSON.stringify(requestQuery));

}

これは、ナレッジ ベースに対してクエリを実行する単純な例です。 高度なクエリ シナリオについては、他のクエリ サンプルをご覧ください。

ナレッジ ベースを削除する

delete メソッドをナレッジ ベース ID のパラメーターと共に使用して、ナレッジ ベースを削除します。

const deleteKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Deleting knowledge base...`)

    const results = await KBclient.deleteMethod(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Delete operation state failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Delete operation state succeeded - HTTP status ${results._response.status}`)
    return true
}

操作の状態の取得

create や update などのメソッドの中には、プロセスが終了するのを待つ代わりに、操作が返されるのに十分な時間がかかるものがあります。 操作からの操作 ID を使用して、(再試行ロジックを使用して) ポーリングし、元のメソッドの状態を判別します。

次のコード ブロック内の delayTimer 呼び出しは、再試行ロジックをシミュレートするために使用されています。 これを独自の再試行ロジックに置き換えます。

const wait_for_operation = async (qnaClient, operation_id) => {

    let state = "NotStarted"
    let operationResult = undefined

    while ("Running" === state || "NotStarted" === state) {

        operationResult = await qnaClient.operations.getDetails(operation_id)
        state = operationResult.operationState;

        console.log(`Operation state - ${state}`)

        await delayTimer(1000);
    }

    return operationResult;
}
const delayTimer = async (timeInMs) => {
    return await new Promise((resolve) => {
        setTimeout(resolve, timeInMs);
    });
}

アプリケーションの実行

自分のアプリケーション ディレクトリで node index.js コマンドを使用してアプリケーションを実行します。

node index.js

このサンプルのソース コードは、GitHub にあります。

Python 用 QnA Maker クライアント ライブラリは、次の目的に使用できます。

  • ナレッジ ベースの作成
  • ナレッジ ベースの更新
  • ナレッジ ベースの公開
  • 予測ランタイム エンドポイント キーの取得
  • 実行時間の長いタスクの待機
  • ナレッジ ベースのダウンロード
  • ナレッジ ベースから回答を取得する
  • ナレッジ ベースの削除

リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PyPi) | Python サンプル

Note

2019 年 7 月 1 日より後に作成された新しいリソースには、カスタム サブドメイン名が使用されます。 リージョンのエンドポイントの詳細および全一覧については、「Azure AI サービスのカスタム サブドメイン名」を参照してください。

前提条件

Note

このドキュメントは、最新のリリースには適用されません。 最新リリースでの Python API の使用方法は、Python クイックスタートに回答する質問を参照してください。

  • Azure サブスクリプション - 無料アカウントを作成します
  • Python 3.x
  • Azure サブスクリプションを入手したら、Azure portal で QnA Maker リソースを作成し、オーサリング キーとエンドポイントを取得します。 デプロイされたら、 [リソースに移動] を選択します。
    • アプリケーションを QnA Maker API に接続するには、作成したリソースのキーとエンドポイントが必要です。 このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。
    • Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

設定

クライアント ライブラリをインストールする

Python をインストールしたら、次を使用してクライアント ライブラリをインストールすることができます。

pip install azure-cognitiveservices-knowledge-qnamaker==0.2.0

新しい Python アプリケーションを作成する

quickstart-file.py という名前の新しい Python ファイルを作成して次のライブラリをインポートします。

import os
import time

from azure.cognitiveservices.knowledge.qnamaker.authoring import QnAMakerClient
from azure.cognitiveservices.knowledge.qnamaker.runtime import QnAMakerRuntimeClient
from azure.cognitiveservices.knowledge.qnamaker.authoring.models import QnADTO, MetadataDTO, CreateKbDTO, OperationStateType, UpdateKbOperationDTO, UpdateKbOperationDTOAdd, EndpointKeysDTO, QnADTOContext, PromptDTO
from azure.cognitiveservices.knowledge.qnamaker.runtime.models import QueryDTO
from msrest.authentication import CognitiveServicesCredentials

自分のリソースの Azure エンドポイントおよびキー用の変数を作成します。

  • サブスクリプション キーとオーサリング キーは同じ意味で使用しています。 オーサリング キーの詳細については、「QnA Maker のキー」を参照してください。

  • QNA_MAKER_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [リソース管理] の [キーとエンドポイント] ページを選び、オーサリング (サブスクリプション) キーと QnA Maker のエンドポイントを見つけます。

QnA Maker 作成エンドポイント

  • QNA_MAKER_RUNTIME_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.azurewebsites.net です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [オートメーション] の [テンプレートのエクスポート] ページを選んで、ランタイム エンドポイントを見つけます。

QnA Maker のランタイム エンドポイント

重要

終わったらコードからキーを削除し、公開しないよう注意してください。 運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。 詳細については、Azure AI サービスのセキュリティに関する記事を参照してください。

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'

authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'

runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

オブジェクト モデル

QnA Maker では、2 種類のオブジェクト モデルが使用されます。

  • QnAMakerClient は、ナレッジ ベースを作成、管理、公開、ダウンロードするためのオブジェクトです。
  • QnAMakerRuntime は、GenerateAnswer API を使用してナレッジ ベースを照会したり、Train API を使用して (アクティブ ラーニングの一環として) 提案された新しい質問を送信したりするためのオブジェクトです。

このサンプル ナレッジ ベースを使用する

このクイックスタートのナレッジ ベースは、2 つの会話型 QnA ペアから始めます。これは、例を簡略化し、Update メソッドで使用するための高度に予測可能な ID を持つようにするために行われます。これにより、質問を含むフォローアップ プロンプトが新しいペアに関連付けられます。 このクイックスタートでは、特定の順序でこれを計画、実装しています。

いずれ、既存の QnA ペアに依存するフォローアップ プロンプトを使用してナレッジ ベースを開発する予定である場合、次の方法を選択できます。

  • 大規模なナレッジ ベースの場合、自動化をサポートする TSV ツールまたはテキスト エディターでナレッジ ベースを管理し、その後一度に、ナレッジ ベース全体を更新版に置き換えます。
  • 比較的小規模なナレッジ ベースの場合、QnA Maker ポータルのみでフォローアップ プロンプトを管理します。

このクイックスタートで使用される QnA ペアの詳細は次のとおりです。

  • QnA ペアの種類 - 更新後、このナレッジ ベースには、おしゃべりとドメイン固有情報の 2 種類の QnA ペアがあります。 これは、ナレッジ ベースがチャットボットなどのメッセージ交換アプリケーションに関連付けられている場合に一般的です。
  • ナレッジ ベースの回答は、メタデータによってフィルター処理されたり、フォローアップ プロンプトを使用したりする場合がありますが、このクイックスタートでは示しません。 これらの言語に依存しない generateAnswer の例については、ここを参照してください。
  • 回答テキストは Markdown で、画像 (一般公開されているインターネット上の画像)、リンク (一般公開されている URL へのリンク)、箇条書きなどのさまざまな Markdown を含めることができますが、このクイックスタートではそれらを使用しません。

QnAMakerClient オブジェクト モデル

作成の QnA Maker クライアントは、自分のキーが含まれている Microsoft.Rest.ServiceClientCredentials を使用して Azure に対する認証を行う QnAMakerClient オブジェクトです。

クライアントが作成されたら、ナレッジ ベース プロパティを使用して、ナレッジ ベースを作成、管理、および公開します。

JSON オブジェクトを送信して、ナレッジ ベースを管理します。 即時操作の場合は、通常、状態を示す JSON オブジェクトがメソッドから返されます。 実行時間の長い操作の場合、応答は操作 ID になります。 operations.get_details メソッドを操作 ID と共に呼び出して、要求の状態を確認します。

QnAMakerRuntimeClient オブジェクト モデル

予測の QnA Maker クライアントは、QnAMakerRuntimeClient オブジェクトです。ナレッジ ベースの公開後に作成クライアントの呼び出し (QnAMakerRuntimeClient) から返される Microsoft.Rest.ServiceClientCredentials (予測ランタイム キーを含む) を使用して Azure に対する認証を行います。

クエリ ランタイムから回答を取得するには、generate_answer メソッドを使用します。

ナレッジ ベースを作成するためのクライアントを認証する

ご利用のエンドポイントとキーを使用してクライアントをインスタンス化します。 キーを使用して CognitiveServicesCredentials オブジェクトを作成し、それをエンドポイントと共に使用して、QnAMakerClient オブジェクトを作成します。

client = QnAMakerClient(endpoint=authoring_endpoint, credentials=CognitiveServicesCredentials(subscription_key))

ナレッジ ベースの作成

クライアント オブジェクトを使用してナレッジ ベース操作オブジェクトを取得します。

ナレッジ ベースには、次の 3 つのソースの CreateKbDTO オブジェクトに対する質問と回答のペアが格納されます。

  • 本文の場合は、QnADTO オブジェクトを使用します。
    • メタデータとフォローアップ プロンプトを使用するには、編集コンテキストを使用します (このデータは個々の QnA ペア レベルで追加されるため)。
  • ファイルの場合は、FileDTO オブジェクトを使用します。 FileDTO には、ファイル名と、ファイルに到達するためのパブリック URL が含まれます。
  • URL の場合は、公開されている URL を表す文字列のリストを使用します。

create メソッドを呼び出した後、返された操作 ID を Operations.getDetails メソッドに渡して、状態をポーリングします。

次のコードの最後の行では、MonitorOperation の応答からナレッジ ベース ID を返しています。

def create_kb(client):
    print ("Creating knowledge base...")

    qna1 = QnADTO(
        answer="Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions=["How do I manage my knowledgebase?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="REST"),
        ]
    )

    qna2 = QnADTO(
        answer="Yes, You can use our [Python SDK](https://pypi.org/project/azure-cognitiveservices-knowledge-qnamaker/) with the [Python Reference Docs](https://docs.microsoft.com/python/api/azure-cognitiveservices-knowledge-qnamaker/azure.cognitiveservices.knowledge.qnamaker?view=azure-python) to manage your knowledge base.",
        questions=["Can I program with Python?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="Python"),
        ]
    )

    urls = []
    files = [
        FileDTO(
            file_name = "structured.docx",
            file_uri = "https://github.com/Azure-Samples/cognitive-services-sample-data-files/raw/master/qna-maker/data-source-formats/structured.docx"
        )]

    create_kb_dto = CreateKbDTO(
        name="QnA Maker Python SDK Quickstart",
        qna_list=[
            qna1,
            qna2
        ],
        urls=urls,
        files=[],
        enable_hierarchical_extraction=True,
        default_answer_used_for_extraction="No answer found.",
        language="English"
    )
    create_op = client.knowledgebase.create(create_kb_payload=create_kb_dto)

    create_op_monitor = _monitor_operation(client=client, operation=create_op)

    # Get knowledge base ID from resourceLocation HTTP header
    knowledge_base_ID = create_op_monitor.resource_location.replace("/knowledgebases/", "")
    print("Created KB with ID: {}".format(knowledge_base_ID))

    return knowledge_base_ID

ナレッジ ベースを適切に作成するには、上記のコードで参照されている _monitor_operation 関数を必ず含めます。

ナレッジ ベースの更新

ナレッジ ベースを更新するには、ナレッジ ベース ID と、add、update、delete DTO オブジェクトを含む UpdateKbOperationDTO を、update メソッドに渡します。 更新が成功したかどうかを確認するには、Operation.getDetail メソッドを使用します。

def update_kb(client, kb_id):
    print ("Updating knowledge base...")

    qna3 = QnADTO(
        answer="goodbye",
        questions=[
            "bye",
            "end",
            "stop",
            "quit",
            "done"
            ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="end"),
        ]
    )

    qna4 = QnADTO(
        answer="Hello, please select from the list of questions or enter a new question to continue.",
        questions=[
            "hello",
            "hi",
            "start"
        ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="begin"),
        ],
        context = QnADTOContext(

            is_context_only = False,
            prompts = [

                PromptDTO(
                    display_order =1,
                    display_text= "Use REST",
                    qna_id=1

                ),
                PromptDTO(
                    display_order =2,
                    display_text= "Use .NET NuGet package",
                    qna_id=2
                ),
            ]
        )

    )

    urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]



    update_kb_operation_dto = UpdateKbOperationDTO(
        add=UpdateKbOperationDTOAdd(
            qna_list=[
                qna3,
                qna4
            ],
            urls = urls,
            files=[]
        ),
        delete=None,
        update=None
    )
    update_op = client.knowledgebase.update(kb_id=kb_id, update_kb=update_kb_operation_dto)
    _monitor_operation(client=client, operation=update_op)
    print("Updated knowledge base.")

ナレッジ ベースを適切に更新するには、上記のコードで参照されている _monitor_operation 関数を必ず含めます。

ナレッジ ベースのダウンロード

データベースを QnADocumentsDTO のリストとしてダウンロードするには、download メソッドを使用します。 このメソッドの結果は TSV ファイルではないため、これは、QnA Maker ポータルの [設定] ページからのエクスポートと同等 "ではありません"。

def download_kb(client, kb_id):
    print("Downloading knowledge base...")
    kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
    print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))

ナレッジ ベースの公開

publish メソッドを使用して、ナレッジ ベースを公開します。 これにより、ナレッジ ベース ID によって参照される、最新の保存済みおよびトレーニング済みのモデルが取得され、エンドポイントで公開されます。

def publish_kb(client, kb_id):
    print("Publishing knowledge base...")
    client.knowledgebase.publish(kb_id=kb_id)
    print("Published knowledge base.")

ナレッジ ベースにクエリを実行する

クエリ ランタイム キーの取得

ナレッジ ベースの公開後、ランタイムに対してクエリを実行するには、クエリ ランタイム キーが必要です。 これは、元のクライアント オブジェクトを作成するときに使用したキーとは異なります。

EndpointKeysOperations.get_keys メソッドを使用して、EndpointKeysDTO クラスを取得します。

そのオブジェクトに返されたいずれかのキー プロパティを使用して、ナレッジ ベースにクエリを実行します。

def getEndpointKeys_kb(client):
    print("Getting runtime endpoint keys...")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: {}.".format(keys.primary_endpoint_key))

    return keys.primary_endpoint_key

回答を生成するためのランタイムを認証する

ナレッジ ベースにクエリを実行して回答を生成したり、アクティブ ラーニングからトレーニングしたりするための QnAMakerRuntimeClient を作成します。

runtimeClient = QnAMakerRuntimeClient(runtime_endpoint=runtime_endpoint, credentials=CognitiveServicesCredentials(queryRuntimeKey))

QnAMakerRuntimeClient を使用してナレッジから回答を取得するか、または、アクティブ ラーニングを目的として提案された新しい質問をナレッジ ベースに送信します。

ナレッジ ベースから回答を生成する

QnAMakerRuntimeClient.runtime.generate_answer メソッドを使用して、公開済みのナレッジ ベースから回答を生成します。 このメソッドは、ナレッジ ベース ID と QueryDTO を受け取ります。 さらに、Top や Context など、QueryDTO のプロパティにアクセスしてチャット ボットで使用することができます。

def generate_answer(client, kb_id, runtimeKey):
    print ("Querying knowledge base...")

    authHeaderValue = "EndpointKey " + runtimeKey

    listSearchResults = client.runtime.generate_answer(kb_id, QueryDTO(question = "How do I manage my knowledgebase?"), dict(Authorization=authHeaderValue))

    for i in listSearchResults.answers:
        print(f"Answer ID: {i.id}.")
        print(f"Answer: {i.answer}.")
        print(f"Answer score: {i.score}.")

これは、ナレッジ ベースに対してクエリを実行する単純な例です。 高度なクエリ シナリオについては、他のクエリ サンプルをご覧ください。

ナレッジ ベースを削除する

delete メソッドをナレッジ ベース ID のパラメーターと共に使用して、ナレッジ ベースを削除します。

def delete_kb(client, kb_id):
    print("Deleting knowledge base...")
    client.knowledgebase.delete(kb_id=kb_id)
    print("Deleted knowledge base.")

操作の状態の取得

create や update などのメソッドの中には、プロセスが終了するのを待つ代わりに、操作が返されるのに十分な時間がかかるものがあります。 操作からの操作 ID を使用して、(再試行ロジックを使用して) ポーリングし、元のメソッドの状態を判別します。

次のコード ブロック内の setTimeout 呼び出しは、非同期コードをシミュレートするために使用されています。 これを再試行ロジックに置き換えます。

def _monitor_operation(client, operation):

    for i in range(20):
        if operation.operation_state in [OperationStateType.not_started, OperationStateType.running]:
            print("Waiting for operation: {} to complete.".format(operation.operation_id))
            time.sleep(5)
            operation = client.operations.get_details(operation_id=operation.operation_id)
        else:
            break
    if operation.operation_state != OperationStateType.succeeded:
        raise Exception("Operation {} failed to complete.".format(operation.operation_id))

    return operation

アプリケーションの実行

クイック スタート ファイルで Python コマンドを使用して、アプリケーションを実行します。

python quickstart-file.py

このサンプルのソース コードは、GitHub にあります。

Java 用 QnA Maker クライアント ライブラリは、次の目的で使用することができます。

  • ナレッジベースを作成する
  • ナレッジ ベースの更新
  • ナレッジ ベースの公開
  • 予測ランタイム エンドポイント キーの取得
  • 実行時間の長いタスクの待機
  • ナレッジ ベースのダウンロード
  • ナレッジ ベースから回答を取得する
  • ナレッジ ベースの削除

ライブラリ ソース コード | パッケージ | サンプル

Note

2019 年 7 月 1 日より後に作成された新しいリソースには、カスタム サブドメイン名が使用されます。 リージョンのエンドポイントの詳細および全一覧については、「Azure AI サービスのカスタム サブドメイン名」を参照してください。

前提条件

  • Azure サブスクリプション - 無料アカウントを作成します
  • JDK
  • Azure サブスクリプションを入手したら、Azure portal で QnA Maker リソースを作成し、オーサリング キーとエンドポイントを取得します。 デプロイされたら、 [リソースに移動] を選択します。
    • アプリケーションを QnA Maker API に接続するには、作成したリソースのキーとエンドポイントが必要です。 このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。
    • Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

設定

クライアント ライブラリをインストールする

Java をインストールしたら、MVN リポジトリの Maven を使用して、クライアント ライブラリをインストールできます。

新しい Java アプリケーションを作成する

quickstart.java という名前の新しいファイルを作成して、以下のライブラリをインポートします。

/* Download the following files.
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.pom
 * Move the downloaded .jar file to a folder named "lib" directly under the current folder.
 * Rename the downloaded file to pom.xml.
 * At the command line, run
 * mvn dependency:copy-dependencies
 * This will download the .jar files depended on by azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar to the folder "target/dependency" under the current folder. Move these .jar files to the "lib" folder as well.
 */
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.*;
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.models.*;

import java.io.*;
import java.lang.Object.*;
import java.time.format.DateTimeFormatter;  
import java.time.LocalDateTime; 
import java.util.*;
import java.net.*;

自分のリソースの Azure エンドポイントおよびキー用の変数を作成します。

  • サブスクリプション キーとオーサリング キーは同じ意味で使用しています。 オーサリング キーの詳細については、「QnA Maker のキー」を参照してください。

  • QNA_MAKER_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [リソース管理] の [キーとエンドポイント] ページを選び、オーサリング (サブスクリプション) キーと QnA Maker のエンドポイントを見つけます。

QnA Maker 作成エンドポイント

  • QNA_MAKER_RUNTIME_ENDPOINT の値の形式は https://YOUR-RESOURCE-NAME.azurewebsites.net です。 Azure portal に移動し、前提条件で作成した QnA Maker リソースを探します。 [オートメーション] の [テンプレートのエクスポート] ページを選んで、ランタイム エンドポイントを見つけます。

QnA Maker のランタイム エンドポイント

重要

終わったらコードからキーを削除し、公開しないよう注意してください。 運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。 詳細については、Azure AI サービスのセキュリティに関する記事を参照してください。

private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

オブジェクト モデル

QnA Maker には、次の 2 種類のオブジェクト モデルが使用されています。

  • QnAMakerClient は、ナレッジ ベースを作成、管理、公開、ダウンロードするためのオブジェクトです。
  • QnAMakerRuntime は、GenerateAnswer API を使用してナレッジ ベースを照会したり、Train API を使用して (アクティブ ラーニングの一環として) 提案された新しい質問を送信したりするためのオブジェクトです。

このサンプル ナレッジ ベースを使用する

このクイックスタートのナレッジ ベースは、2 つの会話型 QnA ペアから始めます。これは、例を簡略化し、Update メソッドで使用するための高度に予測可能な ID を持つようにするために行われます。これにより、質問を含むフォローアップ プロンプトが新しいペアに関連付けられます。 このクイックスタートでは、特定の順序でこれを計画、実装しています。

いずれ、既存の QnA ペアに依存するフォローアップ プロンプトを使用してナレッジ ベースを開発する予定である場合、次の方法を選択できます。

  • 大規模なナレッジ ベースの場合、自動化をサポートする TSV ツールまたはテキスト エディターでナレッジ ベースを管理し、その後一度に、ナレッジ ベース全体を更新版に置き換えます。
  • 比較的小規模なナレッジ ベースの場合、QnA Maker ポータルのみでフォローアップ プロンプトを管理します。

このクイックスタートで使用される QnA ペアの詳細は次のとおりです。

  • QnA ペアの種類 - 更新後、このナレッジ ベースには、おしゃべりとドメイン固有情報の 2 種類の QnA ペアがあります。 これは、ナレッジ ベースがチャットボットなどのメッセージ交換アプリケーションに関連付けられている場合に一般的です。
  • ナレッジ ベースの回答は、メタデータによってフィルター処理されたり、フォローアップ プロンプトを使用したりする場合がありますが、このクイックスタートでは示しません。 これらの言語に依存しない generateAnswer の例については、ここを参照してください。
  • 回答テキストは Markdown で、画像 (一般公開されているインターネット上の画像)、リンク (一般公開されている URL へのリンク)、箇条書きなどのさまざまな Markdown を含めることができますが、このクイックスタートではそれらを使用しません。

QnAMakerClient オブジェクト モデル

作成の QnA Maker クライアントは、自分のキーが含まれている MsRest::ServiceClientCredentials を使用して Azure に対する認証を行う QnAMakerClient オブジェクトです。

クライアントが作成されたら、クライアントの Knowledgebases プロパティのメソッドを使用して、ナレッジ ベースを作成、管理、および公開します。

即時操作の場合、メソッドは通常、結果があれば、それを返します。 長時間にわたって実行される操作の場合、応答は Operation オブジェクトになります。 getDetails メソッドを、operation.operationId 値を指定して呼び出して、要求の状態を確認します。

QnAMakerRuntimeClient オブジェクト モデル

ランタイム QnA Maker クライアントは、QnAMakerRuntimeClient オブジェクトです。

作成クライアントを使用してナレッジ ベースを公開した後で、ランタイム クライアントの generateAnswer メソッドを使用して、ナレッジ ベースからの回答を取得します。

ランタイム クライアントを作成するには、QnAMakerRuntimeManager.authenticate を呼び出し、ランタイム エンドポイント キーを渡します。 ランタイム エンドポイント キーを取得するには、作成クライアントを使用して、getKeys を呼び出します。

ナレッジ ベースを作成するためのクライアントを認証する

作成エンドポイントとサブスクリプション キーを使用して、クライアントをインスタンス化します。

/* Note QnAMakerManager.authenticate() does not set the baseUrl paramater value
 * as the value for QnAMakerClient.endpoint, so we still need to call withEndpoint().
 */
QnAMakerClient authoring_client = QnAMakerManager.authenticate(authoring_key).withEndpoint(authoring_endpoint);
Knowledgebases kb_client = authoring_client.knowledgebases();
Operations ops_client = authoring_client.operations();
EndpointKeys keys_client = authoring_client.endpointKeys();

ナレッジ ベースの作成

ナレッジ ベースには、次の 3 つのソースの CreateKbDTO オブジェクトに対する質問と回答のペアが格納されます。

  • 本文の場合は、QnADTO オブジェクトを使用します。
    • メタデータとフォローアップ プロンプトを使用するには、編集コンテキストを使用します (このデータは個々の QnA ペア レベルで追加されるため)。
  • ファイルの場合は、FileDTO オブジェクトを使用します。 FileDTO には、ファイル名と、ファイルに到達するためのパブリック URL が含まれます。
  • URL の場合は、公開されている URL を表す文字列のリストを使用します。

create メソッドを呼び出した後、返された操作の operationId プロパティを getDetails メソッドに渡し、状態をポーリングします。

次のコードの最後の行では、ナレッジ ベース ID が返されます。

public String create_kb () throws Exception {
    System.out.println("Creating KB...");

    String name = "QnA Maker FAQ from quickstart";

    var metadata = new MetadataDTO()
        .withName ("Category")
        .withValue ("api");

    List<MetadataDTO> metadata_list = Arrays.asList(new MetadataDTO[]{ metadata });

    var qna = new QnADTO()
        .withAnswer ("You can use our REST APIs to manage your knowledge base.")
        .withQuestions ( Arrays.asList(new String[]{ "How do I manage my knowledgebase?" }))
        .withMetadata (metadata_list);

    List<QnADTO> qna_list = Arrays.asList(new QnADTO[]{ qna });

    var urls = Arrays.asList(new String[]{ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs" });

    var payload = new CreateKbDTO().withName(name).withQnaList(qna_list).withUrls(urls);

    var result = kb_client.create(payload);
    var kb_id = wait_for_operation(result);

    System.out.println("Created KB with ID: " + kb_id + ".\n");
    return kb_id;
}

ナレッジ ベースの更新

ナレッジ ベースを更新するには、update を呼び出し、ナレッジ ベース ID と UpdateKbOperationDTO オブジェクトを渡します。 そのオブジェクトには、次のものを含めることができます。

状態をポーリングするには、返された操作の operationId プロパティを operationId メソッドに渡します。

public void update_kb (String kb_id) throws Exception {
    System.out.println("Updating KB...");

    var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");

    var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);

    var result = kb_client.update(kb_id, payload);
    wait_for_operation(result);

    System.out.println("Updated KB.");
}

ナレッジ ベースのダウンロード

データベースを QnADocumentsDTO のリストとしてダウンロードするには、download メソッドを使用します。 このメソッドの結果は TSV ファイルではないため、これは、QnA Maker ポータルの [設定] ページからのエクスポートと同等 "ではありません"。

public void download_kb(String kb_id) {
    System.out.println("Downloading KB...");

    var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
    System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");

    System.out.println("Downloaded KB.\n");
}

ナレッジ ベースの公開

publish メソッドを使用して、ナレッジ ベースを公開します。 これにより、ナレッジ ベース ID によって参照される、最新の保存済みおよびトレーニング済みのモデルが取得され、エンドポイントで公開されます。

public void publish_kb(String kb_id) {
    System.out.println("Publishing KB...");
    kb_client.publish(kb_id);
    System.out.println("KB published.\n");
}

ナレッジ ベースから回答を生成する

ナレッジ ベースの公開後、ナレッジ ベースに対してクエリを実行するには、ランタイム エンドポイント キーが必要です。 これは、作成クライアントの作成に使用したサブスクリプション キーとは異なります。

EndpointKeysDTO オブジェクトを取得するには、getKeys メソッドを使用します。

ランタイム クライアントを作成するには、QnAMakerRuntimeManager.authenticate を呼び出し、EndpointKeysDTO オブジェクトのランタイム エンドポイント キーを渡します。

generateAnswer メソッドを使用して、公開済みのナレッジ ベースから回答を生成します。 このメソッドは、ナレッジ ベース ID と QueryDTO オブジェクトを受け取ります。

public void query_kb(String kb_id) {
    System.out.println("Sending query to KB...");
    
    var runtime_key = keys_client.getKeys().primaryEndpointKey();
    QnAMakerRuntimeClient runtime_client = QnAMakerRuntimeManager.authenticate(runtime_key).withRuntimeEndpoint(runtime_endpoint);
    var query = (new QueryDTO()).withQuestion("How do I manage my knowledgebase?");
    var result = runtime_client.runtimes().generateAnswer(kb_id, query);
    System.out.println("Answers:");
    for (var answer : result.answers()) {
        System.out.println(answer.answer().toString());
    };
    System.out.println();
}

これは、ナレッジ ベースに対してクエリを実行する単純な例です。 高度なクエリ シナリオについては、他のクエリ サンプルをご覧ください。

ナレッジ ベースを削除する

delete メソッドをナレッジ ベース ID のパラメーターと共に使用して、ナレッジ ベースを削除します。

public void delete_kb(String kb_id) {
    System.out.println("Deleting KB...");
    kb_client.delete(kb_id);
    System.out.println("KB deleted.\n");
}

操作の状態の取得

create や update などのメソッドの中には、プロセスが終了するのを待つ代わりに、操作が返されるのに十分な時間がかかるものがあります。 操作からの操作 ID を使用して、(再試行ロジックを使用して) ポーリングし、元のメソッドの状態を判別します。

public String wait_for_operation(Operation op) throws Exception {
    System.out.println ("Waiting for operation to finish...");
    Boolean waiting = true;
    String result = "";
    while (true == waiting) {
        var op_ = ops_client.getDetails(op.operationId());
        var state = op_.operationState();
        if (OperationStateType.FAILED == state) {
            throw new Exception("Operation failed.");
        }
        if (OperationStateType.SUCCEEDED == state) {
            waiting = false;
            // Remove "/knowledgebases/" from the resource location.
            result = op_.resourceLocation().replace("/knowledgebases/", "");
        }
        if (true == waiting) {
            System.out.println("Waiting 10 seconds for operation to complete...");
            Thread.sleep(10000);
        }
    }
    return result;
}

アプリケーションの実行

これが、アプリケーションの main メソッドです。

    public static void main(String[] args) {
        try {
            Quickstart quickstart = new Quickstart();
            String kb_id = quickstart.create_kb();
//			quickstart.list_kbs();
            quickstart.update_kb(kb_id);
            quickstart.publish_kb(kb_id);
            quickstart.download_kb(kb_id);
            quickstart.query_kb(kb_id);
            quickstart.delete_kb(kb_id);
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

次のようにアプリケーションを実行します。 ここでは、クラス名が Quickstart であり、依存関係が現在のフォルダーの下の lib という名前のサブフォルダーにあることを前提としています。

javac Quickstart.java -cp .;lib\*
java -cp .;lib\* Quickstart

このサンプルのソース コードは、GitHub にあります。

リソースをクリーンアップする

Azure AI サービス サブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除することができます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。

次のステップ

チュートリアル:バッチ ファイルを使用して対象のナレッジ ベースをテストする