Статья
06/14/2023

Клиентская библиотека azure Conversational Распознавание речи для Python версии 1.1.0

Диалоговые Распознавание речи (сокращенно CLU) — это облачная служба ИИ для общения, которая предоставляет множество возможностей распознавания речи, таких как:

Приложение для бесед. Оно используется для извлечения намерений и сущностей в беседах.
Приложение рабочего процесса: действует как оркестратор, чтобы выбрать лучшего кандидата для анализа бесед, чтобы получить наилучший ответ от таких приложений, как Qna, Luis и Приложение для беседы
Сводные данные по беседам. Используется для анализа бесед в виде вопросов и решений, заголовка главы и сводных сведений о повествовании.

Начало работы

Предварительные требования

Для использования этого пакета требуется Python 3.7 или более поздней версии.
Подписка Azure
Ресурс языковой службы

Установка пакета

Установите клиентую библиотеку Azure Conversations для Python с помощью pip:

pip install azure-ai-language-conversations

Примечание. В этой версии клиентской библиотеки по умолчанию используется версия службы 2023-04-01.

Аутентификация клиента

Для взаимодействия со службой CLU необходимо создать экземпляр класса ConversationAnalysisClient или Класса ConversationAuthoringClient . Для создания экземпляра клиентского объекта потребуется конечная точка и ключ API . Дополнительные сведения о проверке подлинности с помощью Cognitive Services см. в статье Проверка подлинности запросов к Azure Cognitive Services.

Получение ключа API

Вы можете получить конечную точку и ключ API из ресурса Cognitive Services на портале Azure.

Кроме того, используйте приведенную ниже команду Azure CLI , чтобы получить ключ API из ресурса Cognitive Service.

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-identity . Обратите внимание, что региональные конечные точки не поддерживают проверку подлинности AAD. Создайте пользовательское имя поддомена для ресурса, чтобы использовать этот тип проверки подлинности.

Для проверки подлинности с помощью AAD требуется некоторая начальная настройка:

Установка azure-identity
Регистрация нового приложения AAD
Предоставьте доступ к языковой службе, назначив субъекту-службе роль "Читатель языка Cognitive Services".

После настройки можно выбрать тип учетных данных из azure.identity для использования. Например, для проверки подлинности клиента можно использовать DefaultAzureCredential :

Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: 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 — это основной интерфейс для прогнозирования с помощью развернутых моделей бесед. Для асинхронных операций асинхронный ConversationAnalysisClientazure.ai.language.conversation.aio объект находится в пространстве имен .

ConversationAuthoringClient

ConversationAuthoringClient можно использовать для взаимодействия с языковым порталом Azure для выполнения операций разработки в языковом ресурсе или проекте. Например, с его помощью можно создать проект, заполнить обучающие данные, обучить, протестировать и развернуть. Для асинхронных операций асинхронный ConversationAuthoringClientazure.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)

Дополнительная настройка

Необязательные аргументы ключевое слово можно передавать на уровне клиента и для каждой операции. В справочной документации по azure-core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Устранение неполадок

Общие сведения

Клиент Conversations будет вызывать исключения, определенные в 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)

Дальнейшие действия

Больше примеров кода

См . пример файла сведений для нескольких фрагментов кода, иллюстрирующих общие шаблоны, используемые в API CLU Python.

Участие

Дополнительные сведения о создании, тестировании и участии в этой библиотеке см. в CONTRIBUTING.md .

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Просмотры