Azure.AI.Language.QuestionAnswering 1.1.0

Azure 认知语言服务问答客户端库 for .NET

问答服务是一种基于云的 API 服务，允许您在现有数据上创建一个会话式问答层。通过使用它从您的半结构化内容（包括常见问题、手册和文档）中提取问题和答案来构建知识库。使用知识库中最佳的问答来回答用户的问题—自动。随着知识库持续从用户行为中学习，它也会变得越智能。

源代码 | 包（NuGet） | API 参考文档 | 产品文档 | 示例 | 迁移指南

入门

安装包

使用 NuGet 安装 Azure 认知语言服务问题回答客户端库

dotnet add package Azure.AI.Language.QuestionAnswering

先决条件

• Azure 订阅
• 现有的问题回答资源

虽然您可以使用此 SDK 创建和导入对话项目，但首选方法是通过 语言工作室 创建项目。

客户端认证

要与服务交互，您需要创建一个 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 认证创建客户端

您还可以使用 Azure Active Directory（Azure AD）认证创建 QuestionAnsweringClient 或 QuestionAnsweringAuthoringClient。您的用户或服务主体必须分配 "认知服务语言读取器" 角色。使用DefaultAzureCredential，您可以通过托管身份或服务主体验证服务，以开发人员的身份进行认证，以及更多，而不需要更改代码。

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

要使用包含客户端ID和密码的 DefaultAzureCredential，您需要设置环境变量 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET；或者，您也可以将这些值传递给 Azure.Identity 中的 ClientSecretCredential。

请确保您在源文件顶部使用了正确的命名空间用于 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);
}

部署项目

您可以使用 DeployProjectAsync 或同步的 DeployProject 来部署您的项目。您需要指定的只有项目的名称和您希望使用的部署名称。请注意，该服务不允许您部署空项目。

// 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-bot 将自动确定您是否需要提供 CLA，并且会相应地装饰 PR（例如，标记、注释）。只需遵循机器人提供的说明即可。您只需在所有使用我们 CLA 的存储库中做一次此事。

该项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 [email protected] 讨论任何其他问题或评论。