.NET 用 Azure Cognitive Language Services 質問応答クライアント ライブラリ - バージョン 1.1.0
質問応答サービスは、既存のデータに対して会話型の質問と回答レイヤーを作成できるクラウドベースの API サービスです。 これを使用して、FAQ、マニュアル、ドキュメントなど、半構造化コンテンツから質問と回答を抽出して、サポート情報を構築します。 サポート情報の QnA からの最適な回答を使用して、ユーザーの質問に自動的に回答します。 サポート情報は、ユーザーの行動から継続的に学習されるため、よりスマートになります。
ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | 製品ドキュメント | サンプル | 移行ガイド
作業の開始
パッケージをインストールする
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 宛てに質問またはコメントをお送りください。
Azure SDK for .NET