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

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

项目
04/05/2023

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

源代码 | 包 (PyPI) | API 参考文档 | 产品文档 | 样品

免责声明

Azure SDK Python 包对 Python 2.7 的支持已于 2022 年 1 月 1 日结束。有关详细信息和问题，请参阅 https://github.com/Azure/azure-sdk-for-python/issues/20691

入门

先决条件

使用此包需要 Python 3.7 或更高版本。
Azure 订阅
语言服务资源

安装包

使用 pip 安装适用于 Python 的 Azure 问答客户端库：

pip install azure-ai-language-questionanswering

注意：此版本的客户端库默认为服务 API 版本 2021-10-01。

验证客户端

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

获取 API 密钥

可以从 Azure 门户中的语言资源获取终结点和 API 密钥。

或者，使用如下所示的 Azure CLI 命令从语言资源获取 API 密钥。

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

创建 QuestionAnsweringClient

确定 终结点 和 API 密钥 后，可以实例化 QuestionAnsweringClient：

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

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)

创建 AuthoringClient

使用终结点和 API 密钥，可以实例化 AuthoringClient：

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = AuthoringClient(endpoint, credential)

使用 Azure Active Directory 凭据创建客户端

若要使用 Azure Active Directory (AAD) 令牌凭据，请提供从 azure 标识库获取的所需凭据类型的实例。请注意，区域终结点不支持 AAD 身份验证。为资源创建自定义子域名称，以便使用此类型的身份验证。

使用 AAD 进行身份验证需要一些初始设置：

安装 azure-identity
注册新的 AAD 应用程序
通过将“认知服务语言读取者”角色分配给服务主体来授予对语言服务的访问权限。

设置后，可以从 azure.identity 中选择要使用的凭据类型。例如，可以使用 DefaultAzureCredential 对客户端进行身份验证：

将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量： AZURE_CLIENT_ID、 AZURE_TENANT_ID、 AZURE_CLIENT_SECRET

使用返回的令牌凭据对客户端进行身份验证：

from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = QuestionAnsweringClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

关键概念

QuestionAnsweringClient

QuestionAnsweringClient 是使用具有你自己的信息的知识库或使用预先训练的模型输入文本来提问的主要界面。对于异步操作，异步 QuestionAnsweringClient 位于命名空间中 azure.ai.language.questionanswering.aio 。

AuthoringClient

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

示例

QuestionAnsweringClient

客户端 azure-ai-language-questionanswering 库提供同步 API 和异步 API。

提出问题
提出后续问题
创建新项目
添加知识源
部署项目
异步操作

提问

使用知识库提问所需的唯一输入只是问题本身：

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="test"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

可以设置其他关键字选项来限制答案数、指定最低置信度分数等。

提出后续问题

如果知识库配置为聊天，则知识库的答案可能包含建议的提示，提示后续问题以启动对话。可以通过提供所选答案的 ID 作为继续对话的上下文来提出后续问题：

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should charging take?",
    answer_context=models.KnowledgeBaseAnswerContext(
        previous_qna_id=previous_answer.qna_id
    ),
    project_name="FAQ",
    deployment_name="live"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

创建新项目

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))
with client:

    # create project
    project_name = "IssacNewton"
    project = client.create_project(
        project_name=project_name,
        options={
            "description": "biography of Sir Issac Newton",
            "language": "en",
            "multilingualResource": True,
            "settings": {
                "defaultAnswer": "no answer"
            }
        })

    print("view created project info:")
    print("\tname: {}".format(project["projectName"]))
    print("\tlanguage: {}".format(project["language"]))
    print("\tdescription: {}".format(project["description"]))

添加知识源

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"
update_sources_poller = client.begin_update_sources(
    project_name=project_name,
    sources=[
        {
            "op": "add",
            "value": {
                "displayName": "Issac Newton Bio",
                "sourceUri": "https://wikipedia.org/wiki/Isaac_Newton",
                "sourceKind": "url"
            }
        }
    ]
)
update_sources_poller.result()

# list sources
print("list project sources")
sources = client.list_sources(
    project_name=project_name
)
for source in sources:
    print("project: {}".format(source["displayName"]))
    print("\tsource: {}".format(source["source"]))
    print("\tsource Uri: {}".format(source["sourceUri"]))
    print("\tsource kind: {}".format(source["sourceKind"]))

部署项目

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"

# deploy project
deployment_poller = client.begin_deploy_project(
    project_name=project_name,
    deployment_name="production"
)
deployment_poller.result()

# list all deployments
deployments = client.list_deployments(
    project_name=project_name
)

print("view project deployments")
for d in deployments:
    print(d)

异步操作

还可以使用命名空间中的 aio 客户端异步运行上述示例：

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

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = await client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="production"
)

可选配置

可选关键字参数可以在客户端和每个操作级别传入。 azure-core 参考文档介绍了重试、日志记录、传输协议等的可用配置。

疑难解答

常规

Azure 问答客户端会引发 Azure Core 中定义的异常。使用 Python SDK 与认知语言服务问答客户端库交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果向不存在知识库提交问题，则会返回一个400错误，指示“错误请求”。

from azure.core.exceptions import HttpResponseError

try:
    client.get_answers(
        question="Why?",
        project_name="invalid-knowledge-base",
        deployment_name="test"
    )
except HttpResponseError as error:
    print("Query failed: {}".format(error.message))

日志记录

此库使用标准日志记录库进行日志记录。有关 HTTP 会话 (URL、标头等) 的基本信息记录在信息级别。

可以使用参数在客户端 logging_enable 上启用详细的 DEBUG 级别日志记录，包括请求/响应正文和未执行的标头。

请参阅此处的示例的完整 SDK 日志记录文档。

后续步骤

查看示例。
了解问答服务的不同功能。
试用我们的服务演示。

供稿

有关构建、测试和参与此库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

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

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

曝光数

通过

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

免责声明

入门

先决条件

安装包

验证客户端

获取 API 密钥

创建 QuestionAnsweringClient

创建 AuthoringClient

使用 Azure Active Directory 凭据创建客户端

关键概念

QuestionAnsweringClient

AuthoringClient

示例

QuestionAnsweringClient

提问

提出后续问题

创建新项目

添加知识源

部署项目

异步操作

可选配置

疑难解答

常规

日志记录

后续步骤

供稿

其他资源