クイックスタート: カスタム質問応答

[アーティクル]
09/27/2024

Note

QnA Maker からワークロードを移行する必要がありますか。機能の比較と移行手順については、移行ガイドを参照してください。

カスタム質問応答クライアントライブラリを使用してみましょう。以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

FAQ や製品マニュアルなど、独自のコンテンツからカスタム質問応答プロジェクトを作成できます。この記事には、質問に回答するために、製品マニュアルからカスタム質問応答プロジェクトを作成する例が含まれています。

前提条件

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
カスタム質問と回答機能が有効になった言語リソース。リソースを作成したときに選んだ Microsoft Entra ID、サブスクリプション、Language リソース名を覚えておいてください。

最初のカスタム質問応答プロジェクトを作成する

Azure 資格情報を使用して Language Studio にサインインします。
[Answer questions](質問に回答する) セクションまで下にスクロールし、 [Open custom question answering](カスタム質問と回答を開く) を選択します。
リソースがまだ Azure Search に接続されていない場合は、 [Connect to Azure Search](Azure Search に接続する) を選択します。これにより、新しいブラウザータブが開き、Azure portal 内のリソースの [機能] ペインが表示されます。
[Enable custom question answering](カスタム質問と回答を有効にする) を選択し、リンク先の Azure Search リソースを選択して、 [適用] を選択します。
Language Studio タブに戻ります。リソースへの変更を登録するには、このページを最新の情報に更新する必要がある場合があります。 [新しいプロジェクトの作成] を選択します。
[I want to set the language for all projects created in this resource](このリソースで作成されたすべてのプロジェクトにこの言語を設定する)> オプションを選択し、[英語]> を選択し、[次へ] を選択します。
プロジェクト名には「Sample-project」、説明には「My first question answering project」(最初の質問と回答プロジェクト) と入力し、既定の回答は、 [No answer found](答えが見つかりません) のままにしておきます。
選択内容を確認し、 [Create project](プロジェクトの作成) を選択します。
[Manage sources](ソースの管理) ページから、 [Add source](ソースの追加)>[URL] を選択します。
[Add url](URL の追加) を選択し、次の値を入力し、 [Add all](すべて追加) を選択します。

URL の名前 URL の値

Surface Book ユーザーガイド https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf

抽出プロセスでは、ドキュメントを読み取って質問と回答を識別します。これにはしばらくかかります。

ソースを正常に追加したら、ソースコンテンツを編集して、カスタム質問と回答セットを追加できます。

URL の名前	URL の値
Surface Book ユーザーガイド	https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf

プロジェクトをテストする

ソースへのリンクを選ぶと、プロジェクトの編集ページが開きます。
メニューバーから [テスト] を選択 >「How do I setup my surface book?」 (Surface Book を設定するにはどうすればいいですか?) という質問を入力します。ソース URL から自動的に識別されて抽出された質問と回答のペアに基づいて、回答が生成されます。

[include short answer response](短い回答を含める) チェックボックスをオンにすると、質問をしたときにテストペインに回答パッセージと共に、正確な回答も表示されます (ある場合)。
[検査] を選択し、詳細に応答を確認します。 [テスト] ウィンドウは、プロジェクトをデプロイする前にプロジェクトに対する変更をテストするために使用されます。

[Inspect](検査) インターフェイスから、この応答が質問に回答する信頼レベルを確認し、特定の質問と回答の応答ペアを直接編集できます。

プロジェクトのデプロイ

[プロジェクトのデプロイ] アイコンを選択し、プロジェクトのデプロイのメニューに入ります。

プロジェクトをデプロイすると、プロジェクトのコンテンツが test インデックスから Azure Search の prod インデックスに移動します。
[デプロイ] を選択し、> プロンプトが表示されたら、もう一度 [デプロイ] を選択します。

これで、プロジェクトが正常にデプロイされました。エンドポイントを使用して、独自のカスタムアプリケーションで質問に回答したり、ボットで回答したりできます。

前提条件

最新バージョンの cURL。クイックスタートでは、いくつかのコマンドラインスイッチが使用されています。これらのスイッチについては、cURL のドキュメントを参照してください。
Azure サブスクリプション - 無料アカウントを作成します
カスタム質問応答には、API キーとエンドポイントを生成するために、カスタム質問応答機能を有効にした言語リソースが必要です。
- 言語リソースがデプロイされたら、 [リソースに移動] を選びます。 API に接続するには、作成したリソースのキーとエンドポイントが必要です。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。
Azure CLI で言語リソースを作成するには、次のプロパティを追加します: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
クエリを実行する既存のプロジェクト。プロジェクトをまだ設定していない場合は、Language Studio のクイックスタートに関する記事の手順に従って行うことができます。または、この Surface ユーザーガイド URL をデータソースとして使用するプロジェクトを追加します。

設定

環境変数を作成する

API 要求を送信するには、アプリケーションを認証する必要があります。運用環境では、資格情報を安全に保存してアクセスできる方法を使用してください。この例では、アプリケーションを実行しているローカルコンピューター上の環境変数に資格情報を書き込みます。

言語リソースキーの環境変数を設定するには、コンソールウィンドウを開き、オペレーティングシステムと開発環境の指示に従います。

LANGUAGE_KEY 環境変数を設定するには、your-key をリソースのキーの 1 つに置き換えます。
LANGUAGE_ENDPOINT 環境変数を設定するには、your-endpoint をリソースのエンドポイントに置き換えます。

重要

API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Note

現在実行中のコンソールで環境変数のみにアクセスする必要がある場合は、環境変数を setx の代わりに set に設定できます。

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソールウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

環境変数を追加した後、変更を有効にするには、コンソールウィンドウから source ~/.bashrc を実行します。

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

環境変数を追加した後、変更を有効にするには、コンソールウィンドウから source ~/.bash_profile を実行します。

Xcode

iOS と macOS の開発では、Xcode で環境変数を設定します。たとえば、次の手順に従って、Xcode 13.4.1 で環境変数を設定します。

[Product]、[Scheme]、[スキームの編集] の順に選択する
[引数] を [実行] (デバッグ実行) ページで選択する
[環境変数] で、プラス記号 (+) を選択して、新しい環境変数を追加します。
[名前] に「LANGUAGE_KEY」と入力し、[値] に言語リソースキーを入力します。
リソースエンドポイントに対してこれらの手順を実行します。新しい環境変数 LANGUAGE_ENDPOINT に名前を付けます。

その他の構成オプションについては、Xcode のドキュメントを参照してください。

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

REST API と cURL を使ってカスタム質問応答プロジェクトのクエリを実行するには、次の情報が必要です。

変数名	値
`Endpoint`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。エンドポイントの例: `https://southcentralus.api.cognitive.microsoft.com/`
`API-Key`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。キー値は、サンプル要求の一部です。
`Project`	カスタム質問応答プロジェクトの名前。
`Deployment`	使用可能な値は `test` および `production` です。 `production` は、[Language Studio]>[質問応答]>[プロジェクトのデプロイ] からプロジェクトをデプロイしていることに依存します。

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

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?"
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-knowledgebases?projectName={YOUR_PROJECT_NAME}&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

上記のコードを実行すると、前提条件のデータソースを使用している場合は、次のような回答が表示されます。

{
"answers": [
    {
      "questions": [
        "Check battery level"
      ],
      "answer": "If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.",
      "confidenceScore": 0.9185,
      "id": 101,
      "source": "https://support.microsoft.com/en-us/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98",
      "metadata": {},
      "dialog": {
        "isContextOnly": false,
        "prompts": []
      }
    }
  ]
}

confidenceScore によって 0 から 1 の間の値が返されます。これはパーセンテージのように考えることができるため、100 を掛けます。つまり、信頼度スコアが 0.9185 の場合、カスタム質問応答では、これがプロジェクトに基づいた、質問に対する正しい答えであることを 91.85% 確信していることを意味します。

信頼度スコアが特定のしきい値を下回る回答を除外したい場合は、confidenceScoreThreshold パラメーターを追加します。

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
  "question": "How much battery life do I have left?",
  "confidenceScoreThreshold": "0.95",
  }'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com//language/:query-knowledgebases?projectName=Sample-project&api-version=2021-10-01&deploymentName={DEPLOYMENT_NAME}'

前回のコードの実行から、信頼度スコアが .9185 であることが分かっているため、しきい値を .95 に設定すると、既定の回答が返されます。

{
  "answers": [
    {
      "questions": [],
      "answer": "No good match found in KB",
      "confidenceScore": 0.0,
      "id": -1,
      "metadata": {}
    }
  ]
}

プロジェクトを使用せずにテキストのクエリを実行する

query-text 経由で呼び出される事前構築済みのカスタム質問応答 REST API を使って、プロジェクトなしでカスタム質問応答を使用することもできます。この場合、質問を送信する際に、質問と、回答の検索先となる関連テキストレコードの両方を質問応答に提供します。

この例の場合は、API KEY と ENDPOINT の変数だけを変更する必要があります。

curl -X POST -H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" -H "Content-Type: application/json" -d '{
"question":"How long does it takes to charge a surface?",
"records":[
{"id":"doc1","text":"Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you\u0027re using your Surface for power-intensive activities like gaming or video streaming while you\u0027re charging it"},
{"id":"doc2","text":"You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."}],
"language":"en",
"stringIndexType":"Utf16CodeUnit"
}'  '$LANGUAGE_ENDPOINT.api.cognitive.microsoft.com/language/:query-text?&api-version=2021-10-01'

この例では、次のような結果が返されます。

{  
"answers": [
    {
      "answer": "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.9118788838386536,
      "id": "doc1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0.9850527,
        "offset": 27,
        "length": 18
      },
      "offset": 0,
      "length": 243
    },
    {
      "answer": "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it",
      "confidenceScore": 0.052793052047491074,
      "id": "doc1",
      "answerSpan": {
        "text": "longer",
        "confidenceScore": 0.6694634,
        "offset": 11,
        "length": 7
      },
      "offset": 109,
      "length": 134
    },
    {
      "answer": "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
      "confidenceScore": 0.017600709572434425,
      "id": "doc2",
      "answerSpan": {
        "text": "USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging",
        "confidenceScore": 0.1544854,
        "offset": 15,
        "length": 165
      },
      "offset": 0,
      "length": 280
    }
  ]
}

このクイックスタートは、以下を行う .NET 用のカスタム質問応答クライアントライブラリに使用します。

プロジェクトから回答を取得します。
質問と共に送信したテキストの本文から回答を取得する。
質問に対する回答の信頼度スコアを取得する。

参考ドキュメント | パッケージ (NuGet) | 追加サンプル | ライブラリのソースコード

前提条件

Azure サブスクリプション - 無料アカウントを作成します
Visual Studio IDE または現在のバージョンの .NET Core。
カスタム質問応答には、API キーとエンドポイントを生成するために、カスタム質問応答機能を有効にした言語リソースが必要です。
- 言語リソースがデプロイされたら、 [リソースに移動] を選びます。 API に接続するには、作成したリソースのキーとエンドポイントが必要です。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。
Azure CLI で言語リソースを作成するには、次のプロパティを追加します: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
クエリを実行する既存のプロジェクト。プロジェクトをまだ設定していない場合は、Language Studio のクイックスタートに関する記事の手順に従って行うことができます。または、この Surface ユーザーガイド URL をデータソースとして使用するプロジェクトを追加します。

設定

環境変数を作成する

言語リソースキーの環境変数を設定するには、コンソールウィンドウを開き、オペレーティングシステムと開発環境の指示に従います。

LANGUAGE_KEY 環境変数を設定するには、your-key をリソースのキーの 1 つに置き換えます。
LANGUAGE_ENDPOINT 環境変数を設定するには、your-endpoint をリソースのエンドポイントに置き換えます。

重要

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Note

現在実行中のコンソールで環境変数のみにアクセスする必要がある場合は、環境変数を setx の代わりに set に設定できます。

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

環境変数を追加した後、変更を有効にするには、コンソールウィンドウから source ~/.bashrc を実行します。

Bash

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

環境変数を追加した後、変更を有効にするには、コンソールウィンドウから source ~/.bash_profile を実行します。

Xcode

iOS と macOS の開発では、Xcode で環境変数を設定します。たとえば、次の手順に従って、Xcode 13.4.1 で環境変数を設定します。

[Product]、[Scheme]、[スキームの編集] の順に選択する
[引数] を [実行] (デバッグ実行) ページで選択する
[環境変数] で、プラス記号 (+) を選択して、新しい環境変数を追加します。
[名前] に「LANGUAGE_KEY」と入力し、[値] に言語リソースキーを入力します。
リソースエンドポイントに対してこれらの手順を実行します。新しい環境変数 LANGUAGE_ENDPOINT に名前を付けます。

その他の構成オプションについては、Xcode のドキュメントを参照してください。

CLI

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

dotnet new console -n question-answering-quickstart

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

dotnet build

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

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

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

dotnet add package Azure.AI.Language.QuestionAnswering

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

以下の例では、GetAnswers を使ってプロジェクトのクエリを実行し、質問に対する回答を得ることができます。

以下の変数を実際の値に変更して、以下のコードを更新する必要があります。

変数名	値
`endpoint`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。エンドポイントの例: `https://southcentralus.api.cognitive.microsoft.com/`
`credential`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。キー値は、サンプル要求の一部です。
`projectName`	カスタム質問応答プロジェクトの名前。
`deploymentName`	使用可能な値は `test` および `production` です。 `production` は、[Language Studio]>[質問応答]>[プロジェクトのデプロイ] からプロジェクトをデプロイしていることに依存します。

重要

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

プロジェクトディレクトリから program.cs ファイルを開いて、以下のコードに置き換えます。

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;

namespace question_answering
{
    class Program
    {
        static void Main(string[] args)
        {

            // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
            Uri endpoint = new Uri("LANGUAGE_ENDPOINT");
            AzureKeyCredential credential = new AzureKeyCredential("LANGUAGE_KEY");
            string projectName = "{YOUR-PROJECT-NAME}";
            string deploymentName = "production";

            string question = "How long should my Surface battery last?";

            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
            QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);

            Response<AnswersResult> response = client.GetAnswers(question, project);

            foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
            {
                Console.WriteLine($"Q:{question}");
                Console.WriteLine($"A:{answer.Answer}");
            }
        }
    }
}

この例では変数をハードコーディングしています。運用環境では、資格情報を安全に格納して利用するための方法を用いることを検討してください。たとえば、Azure Key Vault で安全なキー記憶域を確保できます。

上記のコードを使用して Program.cs を更新し、正しい変数値で置き換えます。自分のアプリケーションディレクトリで dotnet run コマンドを使用してアプリケーションを実行します。

dotnet run

応答は次のようになります。

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

この回答の精度に関するカスタム質問応答による信頼度については、既存の print ステートメントの下に print ステートメントを追加します。

Console.WriteLine($"Q:{question}");
Console.WriteLine($"A:{answer.Answer}");
Console.WriteLine($"({answer.Confidence})"); // add this line

dotnet run を再度実行すると、信頼度スコアを含む結果が返されます。

Q:How much battery life do I have left?
A:If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
(0.9185)

信頼度スコアは、0 から 1 の値で返されます。これはパーセンテージのように考えることができるため、100 を掛けます。つまり、信頼度スコアが 0.9185 の場合、カスタム質問応答では、これがプロジェクトに基づいた、質問に対する正しい答えであることを 91.85% 確信していることを意味します。

信頼度スコアが特定のしきい値を下回る回答を除外したい場合は、AnswerOptions を使用して ConfidenceScoreThreshold プロパティを追加します。

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions(); //Add this line
options.ConfidenceThreshold = 0.95; //Add this line

Response<AnswersResult> response = client.GetAnswers(question, project, options); //Add the additional options parameter

前回のコードの実行から、信頼度スコアが .9185 であることが分かっているため、しきい値を .95 に設定すると、既定の回答が返されます。

Q:How much battery life do I have left?
A:No good match found in KB
(0)

プロジェクトを使用せずにテキストのクエリを実行する

GetAnswersFromText を使って、プロジェクトなしでカスタム質問応答を使用することもできます。この場合、要求を送信する際に、質問と、回答の検索先となる関連テキストレコードの両方をカスタム質問応答に提供します。

この例の場合は、endpoint と credential の変数だけを変更する必要があります。

using Azure;
using Azure.AI.Language.QuestionAnswering;
using System;
using System.Collections.Generic;


namespace questionansweringcsharp
{
    class Program
    {
        static void Main(string[] args)
        {

            Uri endpoint = new Uri("https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/");
            AzureKeyCredential credential = new AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY");
            QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

            IEnumerable<TextDocument> records = new[]
            {
                new TextDocument("doc1", "Power and charging.It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                         "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it"),
                new TextDocument("doc2", "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                         "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."),
            };

            AnswersFromTextOptions options = new AnswersFromTextOptions("How long does it takes to charge a surface?", records);
            Response<AnswersFromTextResult> response = client.GetAnswersFromText(options);

           foreach (TextAnswer answer in response.Value.Answers)
            {
                if (answer.Confidence > .9)
                {
                    string BestAnswer = response.Value.Answers[0].Answer;

                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine($"A:{BestAnswer}");
                    Console.WriteLine($"Confidence Score: ({response.Value.Answers[0].Confidence:P2})"); //:P2 converts the result to a percentage with 2 decimals of accuracy. 
                    break;
                }
                else
                {
                    Console.WriteLine($"Q:{options.Question}");
                    Console.WriteLine("No answers met the requested confidence score.");
                    break;
                }
            }

        }
    }
}

上記のコードを実行するには、Program.cs を上記のスクリプトブロックの内容で置き換え、endpoint と credential の変数を、前提条件の一部として作成した言語リソースに対応するように変更します。

今回は、すべての回答を繰り返し処理し、最大の信頼性スコアが 0.9 より大きい回答のみを返します。 GetAnswersFromText で使用できるオプションの詳細について理解する。

このクイックスタートは、以下を行う Python 用のカスタム質問応答クライアントライブラリに使用します。

プロジェクトから回答を取得します。
質問と共に送信したテキストの本文から回答を取得する。
質問に対する回答の信頼度スコアを取得する。

参考ドキュメント | パッケージ (PyPI) | 追加サンプル | ライブラリのソースコード

前提条件

Azure サブスクリプション - 無料アカウントを作成します
Python 3.x
カスタム質問応答には、API キーとエンドポイントを生成するために、カスタム質問応答機能を有効にした言語リソースが必要です。
- 言語リソースがデプロイされたら、 [リソースに移動] を選びます。 API に接続するには、作成したリソースのキーとエンドポイントが必要になります。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。
Azure CLI で言語リソースを作成するには、次のその他のプロパティを追加します: --api-properties qnaAzureSearchEndpointId=/subscriptions/<azure-subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Search/searchServices/<azure-search-service-name> qnaAzureSearchEndpointKey=<azure-search-service-auth-key>
クエリを実行する既存のプロジェクト。プロジェクトをまだ設定していない場合は、Language Studio のクイックスタートに関する記事の手順に従って行うことができます。または、この Surface ユーザーガイド URL をデータソースとして使用するプロジェクトを追加します。

設定

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

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

pip install azure-ai-language-questionanswering

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

以下の例では、get_answers を使ってプロジェクトのクエリを実行し、質問に対する回答を得ることができます。このコードは、専用の .py ファイルや Jupyter Notebook または Lab のセルにコピーすることができます。

以下の変数を実際の値に変更して、以下のコードを更新する必要があります。

変数名	値
`endpoint`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。エンドポイントの例: `https://southcentralus.api.cognitive.microsoft.com/`
`credential`	この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。キー値は、サンプル要求の一部です。
`knowledge_base_project`	質問応答プロジェクトの名前。
`deployment`	使用可能な値は `test` および `production` です。 `production` は、[Language Studio]>[質問応答]>[プロジェクトのデプロイ] からプロジェクトをデプロイしていることに依存します。

重要

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("{YOUR-LANGUAGE-RESOURCE-KEY}")
knowledge_base_project = "{YOUR-PROJECT-NAME}"
deployment = "production"

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How much battery life do I have left?"
        output = client.get_answers(
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )
    print("Q: {}".format(question))
    print("A: {}".format(output.answers[0].answer))

if __name__ == '__main__':
    main()

上記のコードを実行すると、前提条件のデータソースを使用している場合は、次のような回答が表示されます。

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.

この回答の精度に関するカスタム質問応答による信頼度については、既存の print ステートメントの下に別の print ステートメントを追加します。

print("Q: {}".format(question))
print("A: {}".format(output.answers[0].answer))
print("Confidence Score: {}".format(output.answers[0].confidence)) # add this line

これで、信頼度スコアを含む結果が返されます。

Q: How much battery life do I have left?
A: If you want to see how much battery you have left, go to **Start  **> **Settings  **> **Devices  **> **Bluetooth & other devices  **, then find your pen. The current battery level will appear under the battery icon.
Confidence Score: 0.9185

信頼度スコアが特定のしきい値を下回る回答を除外したい場合は、AnswerOptions を変更して confidence_threshold パラメーターを追加します。

        output = client.get_answers(
            confidence_threshold = 0.95, #add this line
            question = question,
            project_name=knowledge_base_project,
            deployment_name=deployment
        )

前回のコードの実行から、信頼度スコアが .9185 であることが分かっているため、しきい値を .95 に設定すると、既定の回答が返されます。

Q: How much battery life do I have left?
A: No good match found in KB
Confidence Score: 0.0

プロジェクトを使用せずにテキストのクエリを実行する

get_answers_from_text を使って、プロジェクトなしでカスタム質問応答を使用することもできます。この場合、要求を送信する際に、質問と、回答の検索先となる関連テキストレコードの両方をカスタム質問応答に提供します。

この例の場合は、endpoint と credential の変数だけを変更する必要があります。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models as qna

endpoint = "https://{YOUR-ENDPOINT}.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("YOUR-LANGUAGE-RESOURCE-KEY")

def main():
    client = QuestionAnsweringClient(endpoint, credential)
    with client:
        question="How long does it takes to charge a surface?"
        input = qna.AnswersFromTextOptions(
            question=question,
            text_documents=[
                "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. " +
                "It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.",
                "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. " +
                "The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
            ]
        )


        output = client.get_answers_from_text(input)

    best_answer = [a for a in output.answers if a.confidence > 0.9][0]
    print(u"Q: {}".format(input.question))
    print(u"A: {}".format(best_answer.answer))
    print("Confidence Score: {}".format(output.answers[0].confidence))

if __name__ == '__main__':
    main()

このコードは、専用の .py ファイルや Jupyter Notebook または Lab の新しいセルにコピーすることができます。この例では、次の結果が返されます。

Q: How long does it takes to charge surface?
A: Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you're using your Surface for power-intensive activities like gaming or video streaming while you're charging it.
Confidence Score: 0.9254655838012695

今回は、すべての回答を繰り返し処理し、最大の信頼性スコアが 0.9 より大きい回答のみを返します。 get_answers_from_text で使用できるオプションについて詳しく理解するには、AnswersFromTextOptions パラメーターに関するページを参照してください。

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

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

REST API の確認

カスタム質問応答パイプラインの自動化については、REST API のドキュメントを参照してください。現在、オーサリング機能は REST API 経由でのみ使用できます。

次のステップ

チュートリアル: FAQ ボットを作成する

次の方法で共有

クイックスタート: カスタム質問応答

前提条件

最初のカスタム質問応答プロジェクトを作成する

プロジェクトをテストする

プロジェクトのデプロイ

前提条件

設定

環境変数を作成する

Bash

Xcode

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

前提条件

設定

環境変数を作成する

Bash

Xcode

CLI

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

前提条件

設定

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

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

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

REST API の確認

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイック スタート: カスタム質問応答

前提条件

最初のカスタム質問応答プロジェクトを作成する

プロジェクトをテストする

プロジェクトのデプロイ

前提条件

設定

環境変数を作成する

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

前提条件

設定

環境変数を作成する

CLI

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

前提条件

設定

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

プロジェクトのクエリを実行する

プロジェクトから回答を生成する

プロジェクトを使用せずにテキストのクエリを実行する

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

REST API の確認

次のステップ

フィードバック

その他のリソース

クイックスタート: カスタム質問応答

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