你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 认知语言服务问答客户端库 - 版本 1.1.0

项目
04/27/2023

问答服务是基于云的 API 服务，可用于基于现有数据创建对话问答层。使用它通过从半结构化内容（包括常见问题解答、手册和文档）中提取问题和答案来构建知识库。使用知识库中 QnA 的最佳答案自动回答用户的问题。你的知识库也会变得更聪明，因为它不断从用户行为中学习。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 认知语言服务问答客户端库：

dotnet add package Azure.AI.Language.QuestionAnswering

先决条件

Azure 订阅
现有的问答资源

尽管可以使用此 SDK 创建和导入对话项目，但 Language Studio 是创建项目的首选方法。

验证客户端

若要与问答服务交互，需要创建类的 QuestionAnsweringClient 实例来查询现有项目，或者创建用于管理资源中的项目的实例 QuestionAnsweringAuthoringClient 。需要一个 终结点和一个 API 密钥 来实例化客户端对象。有关使用认知服务进行身份验证的详细信息，请参阅对 Azure 认知服务的请求进行身份验证。

获取 API 密钥

可以从 Azure 门户中的认知服务资源或问答资源获取终结点和 API 密钥。

或者，使用如下所示的 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 身份验证创建客户端

还可以创建 QuestionAnsweringClient 或使用 QuestionAnsweringAuthoringClient Azure Active Directory (AAD) 身份验证。必须为用户或服务主体分配“认知服务语言读取者”角色。使用 DefaultAzureCredential ，可以使用托管标识或服务主体对服务进行身份验证，以处理应用程序的开发人员身份进行身份验证，等等，而无需更改代码。

在使用 DefaultAzureCredential、或 Azure.Identity 中的任何凭据类型之前，首先需要安装 Azure.Identity 包。

若要与客户端 ID 和机密一起使用 DefaultAzureCredential ，需要设置 AZURE_TENANT_ID、 AZURE_CLIENT_ID和 AZURE_CLIENT_SECRET 环境变量;或者，还可以将这些值传递给 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 来提问。

QuestionAnsweringAuthoringClient

QuestionAnsweringAuthoringClient提供用于管理问答项目的界面。可用操作的示例包括创建和部署项目、更新知识源以及更新问答对。它提供同步和异步 API。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

QuestionAnsweringClient

Azure.AI.Language.QuestionAnswering 客户端库提供同步和异步 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);
}

添加知识源

向项目添加内容的一种方法是添加知识源。以下示例演示如何设置 RequestContent 实例以添加类型为“url”的新知识源。

// 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 与认知语言服务问答客户端库交互时，服务返回的错误对应于为 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)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过

适用于 .NET 的 Azure 认知语言服务问答客户端库 - 版本 1.1.0

入门

安装包

先决条件

验证客户端

获取 API 密钥

创建 QuestionAnsweringClient

创建 QuestionAnsweringAuthoringClient

使用 Azure Active Directory 身份验证创建客户端

关键概念

QuestionAnsweringClient

QuestionAnsweringAuthoringClient

线程安全

其他概念

示例

QuestionAnsweringClient

提问

提出后续问题

QuestionAnsweringAuthoringClient

创建新项目

部署项目

添加知识源

疑难解答

常规

设置控制台日志记录

后续步骤

供稿

反馈

其他资源