• Artigo

Build Status

Biblioteca de clientes de Reconhecimento vocal de Conversação do Azure para Python – versão 1.1.0

O Reconhecimento vocal de conversação - também conhecido como CLU para abreviar - é um serviço de IA de conversação baseado em nuvem que fornece muitos recursos de compreensão da linguagem, como:

  • Aplicativo de conversa: ele é usado na extração de intenções e entidades em conversas
  • Aplicativo de fluxo de trabalho: atua como um orquestrador para selecionar o melhor candidato para analisar conversas para obter a melhor resposta de aplicativos como Qna, Luis e Aplicativo de Conversa
  • Resumo de conversa: usado para analisar conversas na forma de problemas/resolução, título do capítulo e resumos narrativos

Código-fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIAmostras | Documentação do produto | Documentação da API REST

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes do Azure Conversations para Python com pip:

pip install azure-ai-language-conversations

Observação: esta versão da biblioteca de clientes usa como padrão a versão 2023-04-01 do serviço

Autenticar o cliente

Para interagir com o serviço CLU, você precisará criar uma instância da classe ConversationAnalysisClient ou da classe ConversationAuthoringClient . Você precisará de um ponto de extremidade e uma chave de API para instanciar um objeto cliente. Para obter mais informações sobre como autenticar com os Serviços Cognitivos, consulte Autenticar solicitações nos Serviços Cognitivos do Azure.

Obter uma chave de API

Você pode obter o ponto de extremidade e uma chave de API do recurso dos Serviços Cognitivos no Portal do Azure.

Como alternativa, use o comando da CLI do Azure mostrado abaixo para obter a chave de API do recurso serviço cognitivo.

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

Criar ConversationAnalysisClient

Depois de determinar o ponto de extremidade e a chave de API , você poderá instanciar um 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)

Criar ConversationAuthoringClient

Depois de determinar o ponto de extremidade e a chave de API , você poderá instanciar um 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)

Criar um cliente com uma Credencial do Azure Active Directory

Para usar uma credencial de token do AAD (Azure Active Directory), forneça uma instância do tipo de credencial desejado obtido da biblioteca azure-identity . Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para usar esse tipo de autenticação.

A autenticação com o AAD requer alguma configuração inicial:

Após a instalação, você pode escolher qual tipo de credencial do azure.identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente:

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Use a credencial de token retornada para autenticar o cliente:

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)

Principais conceitos

ConversationAnalysisClient

ConversationAnalysisClient é a interface principal para fazer previsões usando seus modelos de Conversas implantados. Para operações assíncronas, um assíncrono ConversationAnalysisClient está no azure.ai.language.conversation.aio namespace.

ConversationAuthoringClient

Você pode usar o ConversationAuthoringClient para fazer a interface com o Portal de Linguagem do Azure para realizar operações de criação em seu recurso/projeto de linguagem. Por exemplo, você pode usá-lo para criar um projeto, preencher com dados de treinamento, treinar, testar e implantar. Para operações assíncronas, um assíncrono ConversationAuthoringClient está no azure.ai.language.conversation.authoring.aio namespace.

Exemplos

A azure-ai-language-conversation biblioteca de clientes fornece APIs síncronas e assíncronas.

Os exemplos a seguir mostram cenários comuns usando o clientcriado acima.

Analisar texto com um aplicativo de conversa

Se você quiser extrair intenções e entidades personalizadas de um enunciado do usuário, poderá chamar o método com o client.analyze_conversation() nome do projeto da conversa da seguinte maneira:

# 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"]))

Analisar texto com um aplicativo de orquestração

Se você quiser passar o enunciado do usuário para seu aplicativo de orquestrador (worflow), poderá chamar o método com o client.analyze_conversation() nome do projeto da orquestração. O projeto do orquestrador simplesmente orquestra o enunciado do usuário enviado entre seus aplicativos de idioma (Luis, Conversation e Respostas às Perguntas) para obter a melhor resposta de acordo com a intenção do usuário. Confira o próximo exemplo:

# 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))

Resumo de conversa

Você pode usar este exemplo se precisar resumir uma conversa na forma de um problema e resolução final. Por exemplo, uma caixa de diálogo do suporte técnico:

# 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']}")

Importar um projeto de conversa

Este exemplo mostra um cenário comum para a parte de criação do 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)

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Solução de problemas

Geral

O cliente Conversas gerará exceções definidas no Azure Core.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o logging_enable argumento .

Confira a documentação completa de registro em log do SDK com exemplos aqui.

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(...)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

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

Próximas etapas

Mais códigos de exemplo

Consulte o README de exemplo para obter vários snippets de código que ilustram padrões comuns usados na API do Python CLU.

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões