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

适用于 Python 的 Azure 对话语言理解客户端库 - 版本 1.1.0

对话语言理解（也称为 CLU）是基于云的对话 AI 服务，可提供许多语言理解功能，例如：

• 对话应用：用于提取对话中的意向和实体
• 工作流应用：充当业务流程协调程序，选择最佳候选项来分析对话，以便从 Qna、Luis 和对话应用等应用获得最佳响应
• 对话式摘要：用于分析问题/解决方法、章节标题和叙述性摘要形式的对话

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

入门

先决条件

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

安装包

使用 pip 安装适用于 Python 的 Azure 对话客户端库：

pip install azure-ai-language-conversations

注意：此版本的客户端库默认为 2023-04-01 版本的服务

验证客户端

若要与 CLU 服务交互，需要创建 ConversationAnalysisClient 类或 ConversationAuthoringClient 类的实例。 需要一个 终结点和一个 API 密钥 来实例化客户端对象。 有关使用认知服务进行身份验证的详细信息，请参阅 对 Azure 认知服务的请求进行身份验证。

获取 API 密钥

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

或者，使用如下所示的 Azure CLI 命令从认知服务资源获取 API 密钥。

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

创建 ConversationAnalysisClient

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

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api-key>")
client = ConversationAnalysisClient(endpoint, credential)

创建 ConversationAuthoringClient

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

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations.authoring import ConversationAuthoringClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api-key>")
client = ConversationAuthoringClient(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.conversations import ConversationAnalysisClient
from azure.identity import DefaultAzureCredential

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

关键概念

ConversationAnalysisClient

ConversationAnalysisClient 是使用已部署的 Conversations 模型进行预测的主要接口。 对于异步操作，异步 ConversationAnalysisClient 位于 命名空间中 azure.ai.language.conversation.aio 。

ConversationAuthoringClient

可以使用 ConversationAuthoringClient 与 Azure 语言门户 进行交互，以便对语言资源/项目执行创作操作。 例如，可以使用它创建项目、填充训练数据、训练、测试和部署。 对于异步操作，异步 ConversationAuthoringClient 位于 命名空间中 azure.ai.language.conversation.authoring.aio 。

示例

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

以下示例演示使用 client上面创建的 的常见方案。

使用对话应用分析文本

如果要从用户话语中提取自定义意向和实体，可以使用对话的项目名称调用 client.analyze_conversation() 方法，如下所示：

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# get secrets
clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]
project_name = os.environ["AZURE_CONVERSATIONS_PROJECT_NAME"]
deployment_name = os.environ["AZURE_CONVERSATIONS_DEPLOYMENT_NAME"]

# analyze quey
client = ConversationAnalysisClient(clu_endpoint, AzureKeyCredential(clu_key))
with client:
    query = "Send an email to Carol about the tomorrow's demo"
    result = client.analyze_conversation(
        task={
            "kind": "Conversation",
            "analysisInput": {
                "conversationItem": {
                    "participantId": "1",
                    "id": "1",
                    "modality": "text",
                    "language": "en",
                    "text": query
                },
                "isLoggingEnabled": False
            },
            "parameters": {
                "projectName": project_name,
                "deploymentName": deployment_name,
                "verbose": True
            }
        }
    )

# view result
print("query: {}".format(result["result"]["query"]))
print("project kind: {}\n".format(result["result"]["prediction"]["projectKind"]))

print("top intent: {}".format(result["result"]["prediction"]["topIntent"]))
print("category: {}".format(result["result"]["prediction"]["intents"][0]["category"]))
print("confidence score: {}\n".format(result["result"]["prediction"]["intents"][0]["confidenceScore"]))

print("entities:")
for entity in result["result"]["prediction"]["entities"]:
    print("\ncategory: {}".format(entity["category"]))
    print("text: {}".format(entity["text"]))
    print("confidence score: {}".format(entity["confidenceScore"]))
    if "resolutions" in entity:
        print("resolutions")
        for resolution in entity["resolutions"]:
            print("kind: {}".format(resolution["resolutionKind"]))
            print("value: {}".format(resolution["value"]))
    if "extraInformation" in entity:
        print("extra info")
        for data in entity["extraInformation"]:
            print("kind: {}".format(data["extraInformationKind"]))
            if data["extraInformationKind"] == "ListKey":
                print("key: {}".format(data["key"]))
            if data["extraInformationKind"] == "EntitySubtype":
                print("value: {}".format(data["value"]))

使用业务流程应用分析文本

如果要将用户话语传递给业务流程协调程序 (worflow) 应用，可以使用业务流程的项目名称调用 client.analyze_conversation() 方法。 业务流程协调程序项目只是协调语言应用 (Luis、Conversation 和 Question Answering) 之间提交的用户话语，以便根据用户意图获得最佳响应。 请参阅下一个示例：

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# get secrets
clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]
project_name = os.environ["AZURE_CONVERSATIONS_WORKFLOW_PROJECT_NAME"]
deployment_name = os.environ["AZURE_CONVERSATIONS_WORKFLOW_DEPLOYMENT_NAME"]

# analyze query
client = ConversationAnalysisClient(clu_endpoint, AzureKeyCredential(clu_key))
with client:
    query = "Reserve a table for 2 at the Italian restaurant"
    result = client.analyze_conversation(
        task={
            "kind": "Conversation",
            "analysisInput": {
                "conversationItem": {
                    "participantId": "1",
                    "id": "1",
                    "modality": "text",
                    "language": "en",
                    "text": query
                },
                "isLoggingEnabled": False
            },
            "parameters": {
                "projectName": project_name,
                "deploymentName": deployment_name,
                "verbose": True
            }
        }
    )

# view result
print("query: {}".format(result["result"]["query"]))
print("project kind: {}\n".format(result["result"]["prediction"]["projectKind"]))

# top intent
top_intent = result["result"]["prediction"]["topIntent"]
print("top intent: {}".format(top_intent))
top_intent_object = result["result"]["prediction"]["intents"][top_intent]
print("confidence score: {}".format(top_intent_object["confidenceScore"]))
print("project kind: {}".format(top_intent_object["targetProjectKind"]))

if top_intent_object["targetProjectKind"] == "Luis":
    print("\nluis response:")
    luis_response = top_intent_object["result"]["prediction"]
    print("top intent: {}".format(luis_response["topIntent"]))
    print("\nentities:")
    for entity in luis_response["entities"]:
        print("\n{}".format(entity))

对话式摘要

如果需要以问题和最终解决方案的形式汇总对话，可以使用此示例。 例如，来自技术支持的对话框：

# import libraries
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient
# get secrets
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
key = os.environ["AZURE_CONVERSATIONS_KEY"]
# analyze query
client = ConversationAnalysisClient(endpoint, AzureKeyCredential(key))
with client:
    poller = client.begin_conversation_analysis(
        task={
            "displayName": "Analyze conversations from xxx",
            "analysisInput": {
                "conversations": [
                    {
                        "conversationItems": [
                            {
                                "text": "Hello, how can I help you?",
                                "modality": "text",
                                "id": "1",
                                "participantId": "Agent"
                            },
                            {
                                "text": "How to upgrade Office? I am getting error messages the whole day.",
                                "modality": "text",
                                "id": "2",
                                "participantId": "Customer"
                            },
                            {
                                "text": "Press the upgrade button please. Then sign in and follow the instructions.",
                                "modality": "text",
                                "id": "3",
                                "participantId": "Agent"
                            }
                        ],
                        "modality": "text",
                        "id": "conversation1",
                        "language": "en"
                    },
                ]
            },
            "tasks": [
                {
                    "taskName": "Issue task",
                    "kind": "ConversationalSummarizationTask",
                    "parameters": {
                        "summaryAspects": ["issue"]
                    }
                },
                {
                    "taskName": "Resolution task",
                    "kind": "ConversationalSummarizationTask",
                    "parameters": {
                        "summaryAspects": ["resolution"]
                    }
                },
            ]
        }
    )

    # view result
    result = poller.result()
    task_results = result["tasks"]["items"]
    for task in task_results:
        print(f"\n{task['taskName']} status: {task['status']}")
        task_result = task["results"]
        if task_result["errors"]:
            print("... errors occurred ...")
            for error in task_result["errors"]:
                print(error)
        else:
            conversation_result = task_result["conversations"][0]
            if conversation_result["warnings"]:
                print("... view warnings ...")
                for warning in conversation_result["warnings"]:
                    print(warning)
            else:
                summaries = conversation_result["summaries"]
                print("... view task result ...")
                for summary in summaries:
                    print(f"{summary['aspect']}: {summary['text']}")

导入对话项目

此示例演示 SDK 创作部分的常见方案

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations.authoring import ConversationAuthoringClient

clu_endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
clu_key = os.environ["AZURE_CONVERSATIONS_KEY"]

project_name = "test_project"

exported_project_assets = {
    "projectKind": "Conversation",
    "intents": [{"category": "Read"}, {"category": "Delete"}],
    "entities": [{"category": "Sender"}],
    "utterances": [
        {
            "text": "Open Blake's email",
            "dataset": "Train",
            "intent": "Read",
            "entities": [{"category": "Sender", "offset": 5, "length": 5}],
        },
        {
            "text": "Delete last email",
            "language": "en-gb",
            "dataset": "Test",
            "intent": "Delete",
            "entities": [],
        },
    ],
}

client = ConversationAuthoringClient(
    clu_endpoint, AzureKeyCredential(clu_key)
)
poller = client.begin_import_project(
    project_name=project_name,
    project={
        "assets": exported_project_assets,
        "metadata": {
            "projectKind": "Conversation",
            "settings": {"confidenceThreshold": 0.7},
            "projectName": "EmailApp",
            "multilingual": True,
            "description": "Trying out CLU",
            "language": "en-us",
        },
        "projectFileVersion": "2022-05-01",
    },
)
response = poller.result()
print(response)

可选配置

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

疑难解答

常规

对话客户端将引发 Azure Core 中定义的异常。

日志记录

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

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

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

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<my-api-key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = ConversationAnalysisClient(endpoint, credential, logging_enable=True)
result = client.analyze_conversation(...)

同样，即使没有为客户端启用详细日志记录，logging_enable 也可以为单个操作启用：

result = client.analyze_conversation(..., logging_enable=True)

后续步骤

更多示例代码

有关演示 CLU Python API 中使用的常见模式的多个代码片段 ，请参阅示例自述文件 。

供稿

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

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

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

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