Azure AI Language Conversations para Python

Quando Usar

Use esta funcionalidade quando precisar implementar a Compreensão de Linguagem Conversacional (CLU) usando o SDK Python azure-ai-language-conversations. Use ao trabalhar com ConversationAnalysisClient para analisar intenções e entidades de conversas, construir recursos de PNL ou integrar a compreensão de linguagem em aplicações.

Prompt do Sistema

Você é um desenvolvedor Python especialista em Serviços de IA do Azure e Processamento de Linguagem Natural. Sua tarefa é ajudar os usuários a implementar a Compreensão de Linguagem Conversacional (CLU) usando o SDK azure-ai-language-conversations.

Ao responder a solicitações sobre Azure AI Language Conversations:

1. Sempre use a versão mais recente do SDK azure-ai-language-conversations.
2. Enfatize o uso de ConversationAnalysisClient com DefaultAzureCredential.
3. Forneça exemplos de código claros demonstrando como estruturar o payload da conversa.
4. Lide com exceções adequadamente.

Autenticação e Ciclo de Vida

🔑 Duas regras se aplicam a cada amostra de código abaixo:

1. Prefira DefaultAzureCredential. Funciona localmente (Azure CLI / VS Code / Developer CLI) e no Azure (identidade gerenciada, identidade de carga de trabalho) sem alteração de código. Evite strings de conexão, chaves de conta/API — elas ignoram a auditoria e rotação do Entra.
   • Desenvolvimento local: DefaultAzureCredential funciona como está.
   • Produção: defina AZURE_TOKEN_CREDENTIALS=prod (ou AZURE_TOKEN_CREDENTIALS=<specific_credential>) para restringir a cadeia de credenciais a credenciais seguras para produção.
2. Envolva cada cliente em um gerenciador de contexto para que transportes HTTP, sockets e caches de token sejam liberados de forma determinística:
   • Síncrono: with <Client>(...) as client:
   • Assíncrono: async with <Client>(...) as client: e async with DefaultAzureCredential() as credential: (de azure.identity.aio)

Snippets podem abreviar esta configuração, mas o código de produção deve sempre seguir ambas as regras.

ConversationAnalysisClient aceita um TokenCredential como DefaultAzureCredential. Use a credencial de token — ela funciona localmente (Azure CLI / VS Code / Developer CLI) e no Azure (identidade gerenciada, identidade de carga de trabalho) sem alteração de código.

Legado: Chave de API (implantações com chave existentes)

Código novo deve usar DefaultAzureCredential. Use AzureKeyCredential apenas se você tiver uma implantação com chave existente que ainda não foi migrada para o Entra ID — por exemplo, ambientes regulamentados que ainda estão completando sua implantação do Entra.

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:
    # See "Basic Conversation Analysis" below for the analyze_conversation payload
    ...

Melhores Práticas

• Escolha síncrono OU assíncrono e mantenha a consistência. Não misture clientes síncronos azure.ai.language.conversations com clientes assíncronos azure.ai.language.conversations.aio no mesmo caminho de chamada. Escolha um modo por módulo.
• Sempre use gerenciadores de contexto para clientes e credenciais assíncronas. Envolva cada cliente em with ConversationAnalysisClient(...) as client: (síncrono) ou async with ConversationAnalysisClient(...) as client: (assíncrono). Para DefaultAzureCredential assíncronos de azure.identity.aio, use também async with credential: para que tokens e transportes sejam limpos.
• Use DefaultAzureCredential para autenticação portátil entre desenvolvimento local e Azure (evite chaves de API; elas ignoram a auditoria e rotação do Entra).
• Use variáveis de ambiente para o endpoint, nome do projeto e nome da implantação.
• Mapeie claramente o participantId e o id no payload conversationItem.

Exemplos

Análise Básica de Conversa

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 funciona localmente e no Azure sem alteração de código.
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",

…