Azure认知语言服务问答Python客户端库

问答是一种基于云的API服务，允许您在现有数据上创建一个会话式问答层。使用它从您的半结构化内容中提取问题和答案来构建知识库，包括FAQ、手册和文档。使用知识库中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 安装 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-identity 库获取的所需凭证类型的实例。请注意，区域端点不支持 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。

示例

QuestionAnsweringClient

《azure-ai-language-questionanswering》客户端库提供了同步和异步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))

日志记录

此库使用标准的logging库进行日志记录。HTTP会话的基本信息（URL、头等）以INFO级别记录。

启用详细DEBUG级别日志记录，包括请求数据/响应正文和未编辑的头信息，可以使用客户端的logging_enable参数。

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

下一步

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

贡献

有关构建、测试和为此库做出贡献的详细信息，请参阅CONTRIBUTING.md。

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权，实际上确实授予我们使用您的贡献的权利。有关详细信息，请访问cla.microsoft.com。

提交拉取请求时，CLA-bot会自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循bot提供的说明即可。您只需在整个使用我们的CLA的仓库中这样做一次。

本项目已采用微软开源行为准则。如需更多信息，请参阅行为准则常见问题解答，或通过opencode@microsoft.com联系以提出任何额外问题或评论。