Artículo
06/14/2023

Biblioteca cliente de Azure Conversational Language Understanding para Python: versión 1.1.0

Conversational Language Understanding ( también conocido como CLU para abreviar) es un servicio de inteligencia artificial conversacional basado en la nube que proporciona muchas funcionalidades de comprensión del lenguaje como:

Aplicación de conversación: se usa para extraer intenciones y entidades en conversaciones
Aplicación de flujo de trabajo: actúa como un orquestador para seleccionar el mejor candidato para analizar las conversaciones para obtener la mejor respuesta de aplicaciones como Qna, Luis y Conversation App.
Resumen conversacional: se usa para analizar conversaciones en forma de problemas o resolución, título del capítulo y resúmenes narrativos

Introducción

Requisitos previos

Se requiere Python 3.7 o posterior para usar este paquete.
Una suscripción de Azure
Un recurso de servicio de idioma

Instalar el paquete

Instale la biblioteca cliente de Azure Conversations para Python con pip:

pip install azure-ai-language-conversations

Nota: Esta versión de la biblioteca cliente tiene como valor predeterminado la versión 2023-04-01 del servicio.

Autenticar el cliente

Para interactuar con el servicio CLU, deberá crear una instancia de la clase ConversationAnalysisClient o conversationAuthoringClient . Necesitará un punto de conexión y una clave de API para crear instancias de un objeto de cliente. Para más información sobre la autenticación con Cognitive Services, consulte Autenticación de solicitudes en Azure Cognitive Services.

Obtención de una clave de API

Puede obtener el punto de conexión y una clave de API del recurso de Cognitive Services en Azure Portal.

Como alternativa, use el comando de la CLI de Azure que se muestra a continuación para obtener la clave de API del recurso de Cognitive Service.

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

Creación de ConversationAnalysisClient

Una vez que haya determinado el punto de conexión y la clave de API, puede crear una instancia de :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)

Creación de ConversationAuthoringClient

Una vez que haya determinado el punto de conexión y la clave de API, puede crear una instancia de :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)

Creación de un cliente con una credencial de Azure Active Directory

Para usar una credencial de token de Azure Active Directory (AAD), proporcione una instancia del tipo de credencial deseado obtenido de la biblioteca azure-identity . Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. Cree un nombre de subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

La autenticación con AAD requiere una configuración inicial:

Instalación de azure-identity
Registro de una nueva aplicación de AAD
Conceda acceso al servicio language mediante la asignación del rol "Lector de lenguaje de Cognitive Services" a la entidad de servicio.

Después de la instalación, puede elegir el tipo de credencial de azure.identity que se va a usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar al cliente:

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, , . AZURE_TENANT_IDAZURE_CLIENT_SECRET

Use la credencial de token devuelta para autenticar al 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)

Conceptos clave

ConversationAnalysisClient

ConversationAnalysisClient es la interfaz principal para realizar predicciones mediante los modelos de Conversaciones implementadas. En el caso de las operaciones asincrónicas, un asincrónico ConversationAnalysisClient se encuentra en el azure.ai.language.conversation.aio espacio de nombres .

ConversationAuthoringClient

Puede usar ConversationAuthoringClient para interactuar con Azure Language Portal para llevar a cabo operaciones de creación en el recurso o proyecto de lenguaje. Por ejemplo, puede usarlo para crear un proyecto, rellenar con datos de entrenamiento, entrenar, probar e implementar. En el caso de las operaciones asincrónicas, un asincrónico ConversationAuthoringClient se encuentra en el azure.ai.language.conversation.authoring.aio espacio de nombres .

Ejemplos

La azure-ai-language-conversation biblioteca cliente proporciona API sincrónicas y asincrónicas.

En los ejemplos siguientes se muestran escenarios comunes con el clientcreado anteriormente.

Análisis de texto con una aplicación de conversación

Si desea extraer intenciones y entidades personalizadas de una expresión de usuario, puede llamar al método con el client.analyze_conversation() nombre del proyecto de la conversación de la siguiente manera:

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

Análisis de texto con una aplicación de orquestación

Si desea pasar la expresión de usuario a la aplicación de orquestador (worflow), puede llamar al método con el client.analyze_conversation() nombre del proyecto de la orquestación. El proyecto de orquestador simplemente organiza la expresión de usuario enviada entre las aplicaciones de lenguaje (Luis, Conversación y Respuesta a preguntas) para obtener la mejor respuesta según la intención del usuario. Vea el ejemplo siguiente:

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

Resumen conversacional

Puede usar este ejemplo si necesita resumir una conversación en forma de problema y resolución final. Por ejemplo, un cuadro de diálogo de soporte 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']}")

Importación de un proyecto de conversación

En este ejemplo se muestra un escenario común para la parte de creación del 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)

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para reintentos, registro, protocolos de transporte, etc.

Solución de problemas

General

El cliente conversations generará excepciones definidas en Azure Core.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento .

Consulte la documentación completa del registro del SDK con ejemplos aquí.

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

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

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

Pasos siguientes

Más código de ejemplo

Consulte el archivo Léame de ejemplo para ver varios fragmentos de código que ilustran patrones comunes que se usan en la API de Python de CLU.

Contribuir

Consulte la CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de