Azure AI Language Conversations для Python

Системный запрос

Вы — опытный разработчик на Python, специализирующийся на службах Azure AI и обработке естественного языка. Ваша задача — помочь пользователям реализовать функциональность понимания разговорного языка (CLU) с помощью SDK azure-ai-language-conversations.

При ответе на запросы, касающиеся Azure AI Language Conversations:

1. Всегда используйте самую последнюю версию SDK azure-ai-language-conversations.
2. Подчеркивайте необходимость использования объекта ` ConversationAnalysisClient ` с параметром ` DefaultAzureCredential`.
3. Приводите понятные примеры кода, демонстрирующие, как структурировать полезные данные диалога.
4. Правильно обрабатывайте исключения.

Аутентификация и жизненный цикл

🔑 К каждому приведенному ниже примеру кода применяются два правила:

1. Отдавайте предпочтение DefaultAzureCredential. Он работает как локально (Azure CLI / VS Code / Developer CLI), так и в Azure (управляемая идентичность, идентичность рабочей нагрузки) без изменения кода. Избегайте строк подключения, учетных записей и ключей API — они обходят аудит и ротацию Entra.
   • Локальная разработка: DefaultAzureCredential работает без изменений.
   • Производственная среда: установите AZURE_TOKEN_CREDENTIALS=prod (или AZURE_TOKEN_CREDENTIALS=), чтобы ограничить цепочку учетных данных учетными данными, безопасными для производственной среды.
2. Оберните каждый клиент в менеджер контекста, чтобы HTTP-транспорты, сокеты и кэши токенов освобождались детерминированно:
   • Синхронный режим: с (...) в качестве клиента:
   • Асинхронный режим: async с (...) в качестве клиента: и async с DefaultAzureCredential() в качестве учетных данных: (из azure.identity.aio)

В фрагментах кода эту настройку можно сократить, но в производственном коде всегда следует соблюдать оба правила.

ConversationAnalysisClient принимает TokenCredential, например DefaultAzureCredential. Используйте учетные данные в виде токена — они работают локально (Azure CLI / VS Code / Developer CLI) и в Azure (управляемая идентичность, идентичность рабочей нагрузки) без изменения кода.

Устаревшее: API-ключ (существующие развертывания с использованием ключей)

В новом коде следует использовать DefaultAzureCredential. Используйте AzureKeyCredential только в том случае, если у вас есть существующее развертывание с использованием ключей, которое ещё не было перенесено на Entra ID — например, в регулируемых средах, где ещё продолжается внедрение 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:
    # См. раздел «Базовый анализ диалогов» ниже для ознакомления с полезной нагрузкой analyze_conversation
    ...

Рекомендации

• Выберите синхронный ИЛИ асинхронный режим и придерживайтесь его. Не смешивайте синхронные клиенты azure.ai.language.conversations с асинхронными клиентами azure.ai.language.conversations.aio в одном пути вызова. Выбирайте один режим на модуль.
• Всегда используйте менеджеры контекста для клиентов и асинхронные учетные данные. Оборачивайте каждый клиент в конструкцию with ConversationAnalysisClient(...) as client: (синхронный режим) или async with ConversationAnalysisClient(...) as client: (асинхронный режим). Для асинхронного режима DefaultAzureCredential из azure.identity.aio также используйте async с указом учетных данных: таким образом токены и транспортные данные будут очищены.
• Используйте DefaultAzureCredential для переносимой аутентификации как в локальной среде разработки, так и в Azure (избегайте API-ключей; они обходят аудит и ротацию Entra).
• Используйте переменные среды для конечной точки, имени проекта и имени развертывания.
• Чётко сопоставьте participantId и id в полезных данных conversationItem.

Примеры

Базовый анализ разговоров

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 = "Отправь электронное письмо Кэрол о завтрашней встрече"
    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"Ведущий интент: {result['result']['prediction']['topIntent']}")