Biblioteca de cliente Language Understanding conversacional do Azure para Python – versão 1.1.0
O Language Understanding conversacional , também conhecido como CLU para abreviar, é um serviço de IA de conversação baseado na cloud que fornece muitas capacidades de compreensão de linguagem, como:
- Aplicação de Conversação: é utilizada na extração de intenções e entidades em conversações
- Aplicação de fluxo de trabalho: age como um orquestrador para selecionar o melhor candidato para analisar conversações para obter a melhor resposta de aplicações como Qna, Luis e Aplicação de Conversação
- Resumo conversacional: utilizado para analisar conversações sob a 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 APIExemplos | Documentação do | produto Documentação da API REST
Introdução
Pré-requisitos
- O Python 3.7 ou posterior é necessário para utilizar este pacote.
- Uma subscrição do Azure
- Um recurso do Serviço de idiomas
Instalar o pacote
Instale a biblioteca de cliente do Azure Conversations para Python com pip:
pip install azure-ai-language-conversations
Nota: esta versão da biblioteca de cliente é predefinida para a versão 2023-04-01 do serviço
Autenticar o cliente
Para interagir com o serviço CLU, terá de criar uma instância da classe ConversationAnalysisClient ou ConversationAuthoringClient . Precisará de um ponto final e de uma chave de API para instanciar um objeto de cliente. Para obter mais informações sobre a autenticação com os Serviços Cognitivos, veja Authenticate requests to Azure Cognitive Services (Autenticar pedidos nos Serviços Cognitivos do Azure).
Obter uma chave de API
Pode obter o ponto final e uma chave de API a partir do recurso dos Serviços Cognitivos no Portal do Azure.
Em alternativa, utilize o comando da CLI do Azure mostrado abaixo para obter a chave de API do recurso do Serviço Cognitivo.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Criar ConversationAnalysisClient
Depois de determinar o ponto final e a chave de API , pode 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 final e a chave de API , pode 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 utilizar uma credencial de token do Azure Active Directory (AAD), forneça uma instância do tipo de credencial pretendido obtido a partir da biblioteca de identidades do azure . Tenha em atenção que os pontos finais regionais não suportam a autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para utilizar este tipo de autenticação.
A autenticação com o AAD requer alguma configuração inicial:
- Instalar azure-identity
- Registar uma nova aplicação do AAD
- Conceda acesso ao serviço Idioma ao atribuir a função "Leitor de Idiomas dos Serviços Cognitivos" ao principal de serviço.
Após a configuração, pode escolher o tipo de credencial a partir de azure.identity a utilizar. Por exemplo, DefaultAzureCredential pode ser utilizado para autenticar o cliente:
Defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET
Utilize a credencial do token devolvido 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)
Conceitos-chave
ConversationAnalysisClient
O ConversationAnalysisClient é a interface principal para fazer predições com os modelos de Conversações implementados. Para operações assíncronas, está um assíncrono ConversationAnalysisClient no azure.ai.language.conversation.aio espaço de nomes.
ConversationAuthoringClient
Pode utilizar o ConversationAuthoringClient para interagir com o Portal de Idiomas do Azure para realizar operações de criação no recurso/projeto de linguagem. Por exemplo, pode utilizá-lo para criar um projeto, preencher com dados de preparação, preparar, testar e implementar. Para operações assíncronas, está um assíncrono ConversationAuthoringClient no azure.ai.language.conversation.authoring.aio espaço de nomes.
Exemplos
A azure-ai-language-conversation biblioteca de cliente fornece APIs síncronas e assíncronas.
Os exemplos seguintes mostram cenários comuns com o clientcriado acima.
Analisar Texto com uma Aplicação de Conversação
Se quiser extrair intenções e entidades personalizadas de uma expressão de utilizador, pode chamar o método com o client.analyze_conversation() nome do projeto da conversação da seguinte forma:
# 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 uma Aplicação de Orquestração
Se quiser transmitir a expressão de utilizador para a sua aplicação orchestrator (worflow), pode chamar o método com o client.analyze_conversation() nome do projeto da orquestração. O projeto do orquestrador orquestra simplesmente a expressão de utilizador submetida entre as suas aplicações de idioma (Luis, Conversação e Resposta a Perguntas) para obter a melhor resposta de acordo com a intenção do utilizador. Veja o exemplo seguinte:
# 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ção
Pode utilizar este exemplo se precisar de resumir uma conversação sob a forma de um problema e a 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ção
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
Os argumentos de palavra-chave opcionais podem ser transmitidos ao nível do cliente e por operação. A documentação de referência azure-core descreve as configurações disponíveis para repetições, registo, protocolos de transporte e muito mais.
Resolução de problemas
Geral
O cliente conversações irá gerar exceções definidas no Azure Core.
Registo
Esta biblioteca utiliza a biblioteca de registos padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.
O registo de nível de DEBUG detalhado, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento .
Veja a documentação completa do registo 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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:
result = client.analyze_conversation(..., logging_enable=True)
Passos seguintes
Mais código de exemplo
Veja README de exemplo para obter vários fragmentos de código que ilustram padrões comuns utilizados na CLU Python API.
Contribuir
Veja o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para esta biblioteca.
Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.
Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.
Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.
Azure SDK for Python