.NET 用 Azure Cognitive Language Services 質問応答クライアントライブラリ - バージョン 1.1.0

[アーティクル]
04/27/2023

質問応答サービスは、既存のデータに対して会話型の質問と回答レイヤーを作成できるクラウドベースの API サービスです。これを使用して、FAQ、マニュアル、ドキュメントなど、半構造化コンテンツから質問と回答を抽出して、サポート情報を構築します。サポート情報の QnA からの最適な回答を使用して、ユーザーの質問に自動的に回答します。サポート情報は、ユーザーの行動から継続的に学習されるため、よりスマートになります。

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Azure Cognitive Language Services 質問応答クライアントライブラリをインストールします。

dotnet add package Azure.AI.Language.QuestionAnswering

前提条件

Azure サブスクリプション
既存の質問応答リソース

この SDK を使用して会話プロジェクトを作成およびインポートできますが、プロジェクトを作成するには Language Studio が推奨される方法です。

クライアントを認証する

質問応答サービスと対話するには、既存のプロジェクトに対してクエリを実行するためのクラスの QuestionAnsweringClient インスタンスを作成するか、リソース内のプロジェクトを管理するためのの QuestionAnsweringAuthoringClient インスタンスを作成する必要があります。クライアントオブジェクトをインスタンス化するには、 エンドポイントと API キー が必要です。 Cognitive Services を使用した認証の詳細については、「 Azure Cognitive Services への要求を認証する」を参照してください。

API キーを取得する

エンドポイントと API キーは、Azure Portal の Cognitive Services リソースまたは質問応答リソースから取得できます。

または、次に示す Azure CLI コマンドを使用して、質問応答リソースから API キーを取得します。

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

QuestionAnsweringClient を作成する

を使用するには、 QuestionAnsweringClient適切な名前空間を使用していることを確認します。

using Azure.Core;
using Azure.AI.Language.QuestionAnswering;

エンドポイントと API キーを使用すると、をQuestionAnsweringClientインスタンス化できます。

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com/");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

QuestionAnsweringAuthoringClient を作成する

を QuestionAnsweringAuthoringClient使用するには、必要に応じて、上記の名前空間に加えて次の名前空間を使用します。

using Azure.AI.Language.QuestionAnswering.Authoring;

エンドポイントと API キーを使用すると、をQuestionAnsweringAuthoringClientインスタンス化できます。

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com/");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

QuestionAnsweringAuthoringClient client = new QuestionAnsweringAuthoringClient(endpoint, credential);

Azure Active Directory 認証を使用してクライアントを作成する

または Azure Active Directory (AAD) 認証を使用してを作成QuestionAnsweringClientQuestionAnsweringAuthoringClientすることもできます。ユーザーまたはサービスプリンシパルには、"Cognitive Services 言語閲覧者" ロールが割り当てられている必要があります。 DefaultAzureCredential を使用すると、マネージド ID またはサービスプリンシパルを使用してサービスを認証したり、アプリケーションで作業する開発者として認証したり、コードを変更せずに認証したりすることができます。

または Azure.Identity から任意の資格情報のDefaultAzureCredential種類を使用する前に、まず Azure.Identity パッケージをインストールする必要があります。

クライアント ID とシークレットでを使用DefaultAzureCredentialするには、、AZURE_CLIENT_ID、および AZURE_CLIENT_SECRET 環境変数をAZURE_TENANT_ID設定する必要があります。または、それらの値を ClientSecretCredential Azure.Identity のにも渡すことができます。

ソースファイルの先頭にあるに適切な名前空間 DefaultAzureCredential を使用していることを確認します。

using Azure.Identity;

その後、の DefaultAzureCredential インスタンスを作成し、クライアントの新しいインスタンスに渡すことができます。

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

リージョンエンドポイントは AAD 認証をサポートしないことに注意してください。代わりに、AAD 認証を使用するリソースのカスタムドメイン名を作成します。

主要な概念

QuestionAnsweringClient

QuestionAnsweringClientは、独自の情報を含むサポート情報を使用して質問したり、事前トレーニング済みのモデルを使用してテキスト入力を行ったりするための主要なインターフェイスです。これには、質問をする同期 API と非同期 API の両方が用意されています。

QuestionAnsweringAuthoringClient

には QuestionAnsweringAuthoringClient 、質問応答プロジェクトを管理するためのインターフェイスが用意されています。使用可能な操作の例としては、プロジェクトの作成と展開、ナレッジソースの更新、質問と回答のペアの更新などがあります。同期 API と非同期 API の両方が提供されます。

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、スレッド間であっても、クライアントインスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

例

QuestionAnsweringClient

Azure.AI.Language.QuestionAnswering クライアントライブラリには、同期 API と非同期 API の両方が用意されています。

次の例は、上記で作成したを使用した一般的なシナリオをclient示しています。

質問をする

既存のサポート情報を使用して質問するために必要な唯一の入力は、質問自体です。

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
Response<AnswersResult> response = client.GetAnswers("How long should my Surface battery last?", project);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

に追加の QuestionAnsweringClientOptions プロパティを設定して、回答の数を制限したり、最小信頼度スコアを指定したりできます。

フォローアップの質問をする

サポート情報がおしゃべり用に構成されている場合は、前の質問応答 ID と、必要に応じてユーザーが尋ねた正確な質問を指定して、フォローアップの質問をすることができます。

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
// Answers are ordered by their ConfidenceScore so assume the user choose the first answer below:
KnowledgeBaseAnswer previousAnswer = answers.Answers.First();
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions
{
    AnswerContext = new KnowledgeBaseAnswerContext(previousAnswer.QnaId.Value)
};

Response<AnswersResult> response = client.GetAnswers("How long should charging take?", project, options);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

QuestionAnsweringAuthoringClient

次の例では、このセクションで作成したインスタンスを使用するQuestionAnsweringAuthoringClient一般的なシナリオを示します。

新しいプロジェクトを作成する

新しいプロジェクトを作成するには、プロジェクトの名前を指定し、プロジェクトの設定に必要な RequestContent パラメーターを含むインスタンスを作成する必要があります。

// Set project name and request content parameters
string newProjectName = "{ProjectName}";
RequestContent creationRequestContent = RequestContent.Create(
    new {
        description = "This is the description for a test project",
        language = "en",
        multilingualResource = false,
        settings = new {
            defaultAnswer = "No answer found for your question."
            }
        }
    );

Response creationResponse = client.CreateProject(newProjectName, creationRequestContent);

// Projects can be retrieved as follows
Pageable<BinaryData> projects = client.GetProjects();

Console.WriteLine("Projects: ");
foreach (BinaryData project in projects)
{
    Console.WriteLine(project);
}

プロジェクトのデプロイ

プロジェクトは、または同期 DeployProjectを使用してDeployProjectAsync配置できます。指定する必要があるのは、プロジェクトの名前と使用する配置名です。このサービスでは、空のプロジェクトをデプロイすることはできません。

// Set deployment name and start operation
string newDeploymentName = "{DeploymentName}";

Operation<BinaryData> deploymentOperation = client.DeployProject(WaitUntil.Completed, newProjectName, newDeploymentName);

// Deployments can be retrieved as follows
Pageable<BinaryData> deployments = client.GetDeployments(newProjectName);
Console.WriteLine("Deployments: ");
foreach (BinaryData deployment in deployments)
{
    Console.WriteLine(deployment);
}

ナレッジソースを追加する

プロジェクトにコンテンツを追加する方法の 1 つは、ナレッジソースを追加することです。次の例は、型 "url" の新しいナレッジソースを追加するようにインスタンスを設定 RequestContent する方法を示しています。

// Set request content parameters for updating our new project's sources
string sourceUri = "{KnowledgeSourceUri}";
RequestContent updateSourcesRequestContent = RequestContent.Create(
    new[] {
        new {
                op = "add",
                value = new
                {
                    displayName = "MicrosoftFAQ",
                    source = sourceUri,
                    sourceUri = sourceUri,
                    sourceKind = "url",
                    contentStructureKind = "unstructured",
                    refresh = false
                }
            }
    });

Operation<Pageable<BinaryData>> updateSourcesOperation = client.UpdateSources(WaitUntil.Completed, newProjectName, updateSourcesRequestContent);

// Knowledge Sources can be retrieved as follows
Pageable<BinaryData> sources = updateSourcesOperation.Value;

Console.WriteLine("Sources: ");
foreach (BinaryData source in sources)
{
    Console.WriteLine(source);
}

トラブルシューティング

全般

.NET SDK を使用して Cognitive Language Services 質問応答クライアントライブラリを操作する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。

たとえば、存在しないサポート情報に質問を送信すると、"無効な400要求" を示すエラーが返されます。

try
{
    QuestionAnsweringProject project = new QuestionAnsweringProject("invalid-knowledgebase", "test");
    Response<AnswersResult> response = client.GetAnswers("Does this knowledge base exist?", project);
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

操作のクライアント要求 ID など、追加情報がログに記録されていることがわかります。

Azure.RequestFailedException: Please verify azure search service is up, restart the WebApp and try again
Status: 400 (Bad Request)
ErrorCode: BadArgument

Content:
{
    "error": {
    "code": "BadArgument",
    "message": "Please verify azure search service is up, restart the WebApp and try again"
    }
}

Headers:
x-envoy-upstream-service-time: 23
apim-request-id: 76a83876-22d1-4977-a0b1-559a674f3605
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
Date: Wed, 30 Jun 2021 00:32:07 GMT
Content-Length: 139
Content-Type: application/json; charset=utf-8

コンソールログの設定

ログを表示する最も簡単な方法は、コンソールログを有効にすることです。コンソールにメッセージを出力する Azure SDK ログリスナーを作成するには、メソッドを AzureEventSourceListener.CreateConsoleLogger 使用します。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

その他のログメカニズムの詳細については、こちらを参照してください。

次のステップ

サンプルを表示します。
質問応答サービスのさまざまな機能について確認します。
サービスのデモをお試しください。

共同作成

このライブラリのビルド、テスト、および投稿の詳細については、 CONTRIBUTING.md を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

.NET 用 Azure Cognitive Language Services 質問応答クライアントライブラリ - バージョン 1.1.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

API キーを取得する

QuestionAnsweringClient を作成する

QuestionAnsweringAuthoringClient を作成する

Azure Active Directory 認証を使用してクライアントを作成する

主要な概念

QuestionAnsweringClient

QuestionAnsweringAuthoringClient

スレッドセーフ

その他の概念

例

QuestionAnsweringClient

質問をする

フォローアップの質問をする

QuestionAnsweringAuthoringClient

新しいプロジェクトを作成する

プロジェクトのデプロイ

ナレッジソースを追加する

トラブルシューティング

全般

コンソールログの設定

次のステップ

共同作成

フィードバック

その他のリソース

.NET 用 Azure Cognitive Language Services 質問応答クライアント ライブラリ - バージョン 1.1.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

API キーを取得する

QuestionAnsweringClient を作成する

QuestionAnsweringAuthoringClient を作成する

Azure Active Directory 認証を使用してクライアントを作成する

主要な概念

QuestionAnsweringClient

QuestionAnsweringAuthoringClient

スレッド セーフ

その他の概念

例

QuestionAnsweringClient

質問をする

フォローアップの質問をする

QuestionAnsweringAuthoringClient

新しいプロジェクトを作成する

プロジェクトのデプロイ

ナレッジ ソースを追加する

トラブルシューティング

全般

コンソール ログの設定

次のステップ

共同作成

フィードバック

その他のリソース

.NET 用 Azure Cognitive Language Services 質問応答クライアントライブラリ - バージョン 1.1.0

スレッドセーフ

ナレッジソースを追加する

コンソールログの設定