Azure AI 语言服务对话 Python SDK

Azure AI Language Conversations for Python

使用场景

当你需要使用 azure-ai-language-conversations Python SDK 实现会话语言理解 (CLU) 时，请使用此技能。适用于使用 ConversationAnalysisClient 分析会话意图和实体、构建 NLP 功能或将语言理解集成到应用程序中。

系统提示词

在响应关于 Azure AI Language Conversations 的请求时：
1. 始终使用最新版本的 azure-ai-language-conversations SDK。
2. 强调使用 ConversationAnalysisClient 配合 DefaultAzureCredential。
3. 提供清晰的代码示例，演示如何构建会话负载 (payload)。
4. 正确处理异常。

身份验证与生命周期

> 🔑 以下每个代码示例均适用两条规则：
>
> 1. 优先使用 DefaultAzureCredential。 它在本地（Azure CLI / VS Code / Developer CLI）和 Azure（托管身份、工作负载身份）中均可工作，无需更改代码。避免使用连接字符串、账户/API 密钥，因为它们会绕过 Entra 审计和轮换。
> - 本地开发：DefaultAzureCredential 直接可用。
> - 生产环境：设置 AZURE_TOKEN_CREDENTIALS=prod（或 AZURE_TOKEN_CREDENTIALS=<specific_credential>）以将凭据链限制在生产安全的凭据中。
> 2. 将每个客户端封装在上下文管理器中，以便确定性地释放 HTTP 传输、套接字和令牌缓存：
> - 同步：with <Client>(...) as client:
> - 异步：async with <Client>(...) as client: 且 async with DefaultAzureCredential() as credential:（来自 azure.identity.aio）
>
> 代码片段可能会简化此设置，但生产代码应始终遵循这两条规则。

ConversationAnalysisClient 接受 TokenCredential（如 DefaultAzureCredential）。请使用令牌凭据 —— 它在本地（Azure CLI / VS Code / Developer CLI）和 Azure（托管身份、工作负载身份）中均可工作，无需更改代码。

遗留方案：API 密钥（现有密钥部署）

新代码应使用 DefaultAzureCredential。仅在现有密钥部署尚未迁移到 Entra ID 时（例如，仍在完成 Entra 部署的受监管环境）才使用 AzureKeyCredential。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.conversations import ConversationAnalysisClient
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
key = os.environ["AZURE_CONVERSATIONS_KEY"]
with ConversationAnalysisClient(endpoint, AzureKeyCredential(key)) as client:
    # 详见下文的“基础会话分析”部分

最佳实践

• 在同步（sync）或异步（async）之间做出选择并保持一致。 不要在同一个调用路径中混用 azure.ai.language.conversations 同步客户端和 azure.ai.language.conversations.aio 异步客户端。每个模块仅选择一种模式。

• 始终为客户端和异步凭据使用上下文管理器。 将每个客户端包装在 with ConversationAnalysisClient(...) as client:（同步）或 async with ConversationAnalysisClient(...) as client:（异步）中。对于来自 azure.identity.aio 的异步 DefaultAzureCredential，同样使用 async with credential: 以确保令牌和传输层被正确清理。

• 使用 DefaultAzureCredential 以实现本地开发和 Azure 环境之间的可移植认证（避免使用 API 密钥，因为它们会绕过 Entra 的审计和轮换机制）。

• 使用环境变量配置端点（endpoint）、项目名称（project name）和部署名称（deployment name）。

• 在 conversationItem 负载中清晰地映射 participantId 和 id。

示例

基础对话分析

import os
from azure.identity import DefaultAzureCredential
from azure.ai.language.conversations import ConversationAnalysisClient
endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
project_name = os.environ["AZURE_CONVERSATIONS_PROJECT"]
deployment_name = os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"]
DefaultAzureCredential 在本地和 Azure 环境中均可工作，无需修改代码。
credential = DefaultAzureCredential()
with ConversationAnalysisClient(endpoint, credential) as client:
    query = "Send an email to Carol about the tomorrow's meeting"
    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
            }
        }
    )
print(f"Top intent: {result['result']['prediction']['topIntent']}")

局限性

• 仅在任务明确符合其上游来源和本地项目上下文时才使用此技能。

• 在应用更改之前，请验证命令、生成的代码、依赖项、凭据以及外部服务的行为。

• 不要将示例视为环境特定测试、安全审查或破坏性/高成本操作用户确认的替代方案。