Biblioteca cliente de conversaciones de Azure Cognitive Language Services para .NET: versión 1.1.0

  • Artículo

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.

Código | fuentePaquete (NuGet) | Documentación | de referencia de APIMuestras | Documentación | del productoDocumentación | de la API REST de análisisDocumentación de la API REST de creación

Introducción

Instalar el paquete

Instale la biblioteca cliente de Conversaciones de Azure Cognitive Language Services para .NET con NuGet:

dotnet add package Azure.AI.Language.Conversations

Requisitos previos

Aunque puede usar este SDK para crear e importar proyectos de conversación, Language Studio es el método preferido para crear proyectos.

Autenticar el cliente

Para interactuar con el servicio Conversations, deberá crear una instancia de la ConversationAnalysisClient clase . 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>

Espacios de nombres

Para empezar, importe el espacio de nombres para la ConversationAnalysisClient clase y relacionada:

using Azure.Core;
using Azure.AI.Language.Conversations;

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

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Creación de un objeto ConversationAuthoringClient

Para usar ConversationAuthoringClient, use el siguiente espacio de nombres además de los anteriores, si es necesario.

using Azure.AI.Language.Conversations.Authoring;

Con el punto de conexión y la clave de API, puede crear una instancia de :ConversationAuthoringClient

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

ConversationAuthoringClient client = new ConversationAuthoringClient(endpoint, credential);

Creación de un cliente mediante la autenticación de Azure Active Directory

También puede crear o ConversationAnalysisClientConversationAuthoringClient mediante la autenticación de Azure Active Directory (AAD). El usuario o la entidad de servicio deben tener asignado el rol "Lector de lenguaje de Cognitive Services". Con DefaultAzureCredential , puede autenticar un servicio mediante una identidad administrada o una entidad de servicio, autenticarse como desarrollador que trabaja en una aplicación y mucho más sin cambiar el código.

Para poder usar , DefaultAzureCredentialo cualquier tipo de credencial de Azure.Identity, primero deberá instalar el paquete Azure.Identity.

Para usarlo DefaultAzureCredential con un identificador de cliente y un secreto, deberá establecer las AZURE_TENANT_IDvariables de entorno , AZURE_CLIENT_IDy AZURE_CLIENT_SECRET ; como alternativa, puede pasar esos valores a ClientSecretCredential también en Azure.Identity.

Asegúrese de usar el espacio de nombres adecuado para DefaultAzureCredential en la parte superior del archivo de origen:

using Azure.Identity;

A continuación, puede crear una instancia de DefaultAzureCredential y pasarla a una nueva instancia del cliente:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. En su lugar, cree un nombre de dominio personalizado para que el recurso use la autenticación de AAD.

Conceptos clave

ConversationAnalysisClient

ConversationAnalysisClient es la interfaz principal para realizar predicciones mediante los modelos de conversaciones implementados. Proporciona API sincrónicas y asincrónicas para enviar consultas.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

La biblioteca cliente Azure.AI.Language.Conversations proporciona API sincrónicas y asincrónicas.

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

Análisis de una conversación

Para analizar una conversación, puede llamar al AnalyzeConversation() método :

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Send an email to Carol about tomorrow's demo",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(response.ContentStream);
JsonElement conversationalTaskResult = result.RootElement;
JsonElement conversationPrediction = conversationalTaskResult.GetProperty("result").GetProperty("prediction");

Console.WriteLine($"Top intent: {conversationPrediction.GetProperty("topIntent").GetString()}");

Console.WriteLine("Intents:");
foreach (JsonElement intent in conversationPrediction.GetProperty("intents").EnumerateArray())
{
    Console.WriteLine($"Category: {intent.GetProperty("category").GetString()}");
    Console.WriteLine($"Confidence: {intent.GetProperty("confidenceScore").GetSingle()}");
    Console.WriteLine();
}

Console.WriteLine("Entities:");
foreach (JsonElement entity in conversationPrediction.GetProperty("entities").EnumerateArray())
{
    Console.WriteLine($"Category: {entity.GetProperty("category").GetString()}");
    Console.WriteLine($"Text: {entity.GetProperty("text").GetString()}");
    Console.WriteLine($"Offset: {entity.GetProperty("offset").GetInt32()}");
    Console.WriteLine($"Length: {entity.GetProperty("length").GetInt32()}");
    Console.WriteLine($"Confidence: {entity.GetProperty("confidenceScore").GetSingle()}");
    Console.WriteLine();

    if (entity.TryGetProperty("resolutions", out JsonElement resolutions))
    {
        foreach (JsonElement resolution in resolutions.EnumerateArray())
        {
            if (resolution.GetProperty("resolutionKind").GetString() == "DateTimeResolution")
            {
                Console.WriteLine($"Datetime Sub Kind: {resolution.GetProperty("dateTimeSubKind").GetString()}");
                Console.WriteLine($"Timex: {resolution.GetProperty("timex").GetString()}");
                Console.WriteLine($"Value: {resolution.GetProperty("value").GetString()}");
                Console.WriteLine();
            }
        }
    }
}

Se pueden pasar opciones adicionales a AnalyzeConversation como habilitar una salida más detallada:

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Send an email to Carol about tomorrow's demo",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        verbose = true,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

Análisis de una conversación en un idioma diferente

La language propiedad se puede establecer para especificar el idioma de la conversación:

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Enviar un email a Carol acerca de la presentación de mañana",
            language = "es",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        verbose = true,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

Análisis de una conversación mediante un proyecto de orquestación

Para analizar una conversación mediante un proyecto de orquestación, puede llamar al AnalyzeConversation() método al igual que el proyecto de conversación.

string projectName = "DomainOrchestrator";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "How are you?",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(response.ContentStream);
JsonElement conversationalTaskResult = result.RootElement;
JsonElement orchestrationPrediction = conversationalTaskResult.GetProperty("result").GetProperty("prediction");

Predicción de respuesta a preguntas

Si la conversación fue analizada por Respuesta a preguntas, incluirá una intención , quizás incluso la intención principal, desde la que puede recuperar respuestas:

string respondingProjectName = orchestrationPrediction.GetProperty("topIntent").GetString();
JsonElement targetIntentResult = orchestrationPrediction.GetProperty("intents").GetProperty(respondingProjectName);

if (targetIntentResult.GetProperty("targetProjectKind").GetString() == "QuestionAnswering")
{
    Console.WriteLine($"Top intent: {respondingProjectName}");

    JsonElement questionAnsweringResponse = targetIntentResult.GetProperty("result");
    Console.WriteLine($"Question Answering Response:");
    foreach (JsonElement answer in questionAnsweringResponse.GetProperty("answers").EnumerateArray())
    {
        Console.WriteLine(answer.GetProperty("answer").GetString());
    }
}

Resumen conversacional

Para resumir una conversación, puede usar la sobrecarga del AnalyzeConversation método que devuelve un Operation<BinaryData>:

var data = new
{
    analysisInput = new
    {
        conversations = new[]
        {
            new
            {
                conversationItems = new[]
                {
                    new
                    {
                        text = "Hello, how can I help you?",
                        id = "1",
                        role = "Agent",
                        participantId = "Agent_1",
                    },
                    new
                    {
                        text = "How to upgrade Office? I am getting error messages the whole day.",
                        id = "2",
                        role = "Customer",
                        participantId = "Customer_1",
                    },
                    new
                    {
                        text = "Press the upgrade button please. Then sign in and follow the instructions.",
                        id = "3",
                        role = "Agent",
                        participantId = "Agent_1",
                    },
                },
                id = "1",
                language = "en",
                modality = "text",
            },
        }
    },
    tasks = new[]
    {
        new
        {
            taskName = "Issue task",
            kind = "ConversationalSummarizationTask",
            parameters = new
            {
                summaryAspects = new[]
                {
                    "issue",
                }
            },
        },
        new
        {
            taskName = "Resolution task",
            kind = "ConversationalSummarizationTask",
            parameters = new
            {
                summaryAspects = new[]
                {
                    "resolution",
                }
            },
        },
    },
};

Operation<BinaryData> analyzeConversationOperation = client.AnalyzeConversations(WaitUntil.Completed, RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(analyzeConversationOperation.Value.ToStream());
JsonElement jobResults = result.RootElement;
foreach (JsonElement task in jobResults.GetProperty("tasks").GetProperty("items").EnumerateArray())
{
    Console.WriteLine($"Task name: {task.GetProperty("taskName").GetString()}");
    JsonElement results = task.GetProperty("results");
    foreach (JsonElement conversation in results.GetProperty("conversations").EnumerateArray())
    {
        Console.WriteLine($"Conversation: #{conversation.GetProperty("id").GetString()}");
        Console.WriteLine("Summaries:");
        foreach (JsonElement summary in conversation.GetProperty("summaries").EnumerateArray())
        {
            Console.WriteLine($"Text: {summary.GetProperty("text").GetString()}");
            Console.WriteLine($"Aspect: {summary.GetProperty("aspect").GetString()}");
        }
        Console.WriteLine();
    }
}

Ejemplos adicionales

Explorador nuestros ejemplos para obtener más ejemplos de cómo analizar conversaciones.

Solución de problemas

General

Cuando interactúa con la biblioteca cliente de Conversaciones de Cognitive Language Services mediante el SDK de .NET, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de LA API REST.

Por ejemplo, si envía una expresión a un proyecto no existente, se devuelve un 400 error que indica "Solicitud incorrecta".

try
{
    var data = new
    {
        analysisInput = new
        {
            conversationItem = new
            {
                text = "Send an email to Carol about tomorrow's demo",
                id = "1",
                participantId = "1",
            }
        },
        parameters = new
        {
            projectName = "invalid-project",
            deploymentName = "production",

            // Use Utf16CodeUnit for strings in .NET.
            stringIndexType = "Utf16CodeUnit",
        },
        kind = "Conversation",
    };

    Response response = client.AnalyzeConversation(RequestContent.Create(data));
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

Azure.RequestFailedException: The input parameter is invalid.
Status: 400 (Bad Request)
ErrorCode: InvalidArgument

Content:
{
  "error": {
    "code": "InvalidArgument",
    "message": "The input parameter is invalid.",
    "innerError": {
      "code": "InvalidArgument",
      "message": "The input parameter \"payload\" cannot be null or empty."
    }
  }
}

Headers:
Transfer-Encoding: chunked
pragma: no-cache
request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
apim-request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
x-envoy-upstream-service-time: 15
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Cache-Control: no-store, proxy-revalidate, no-cache, max-age=0, private
Content-Type: application/json

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que envía mensajes a la consola, use el AzureEventSourceListener.CreateConsoleLogger método .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para más información sobre otros mecanismos de registro, consulte aquí.

Pasos siguientes

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.