Bibliothèque de client Azure Cognitive Language Services Conversations pour .NET - version 1.1.0

Article
06/21/2023

L’Language Understanding conversationnelle( CLU) est un service d’IA conversationnelle basé sur le cloud qui fournit de nombreuses fonctionnalités de compréhension du langage, telles que :

Application de conversation : elle est utilisée pour extraire des intentions et des entités dans les conversations
Application de flux de travail : agit comme un orchestrateur pour sélectionner le meilleur candidat pour analyser les conversations afin d’obtenir la meilleure réponse à partir d’applications telles que Qna, Luis et Conversation App

Prise en main

Installer le package

Installez la bibliothèque cliente Azure Cognitive Language Services Conversations pour .NET avec NuGet :

dotnet add package Azure.AI.Language.Conversations

Prérequis

Un abonnement Azure
Une ressource Azure Language Service existante

Bien que vous puissiez utiliser ce Kit de développement logiciel (SDK) pour créer et importer des projets de conversation, Language Studio est la méthode préférée pour créer des projets.

Authentifier le client

Pour interagir avec le service Conversations, vous devez créer une instance de la ConversationAnalysisClient classe. Vous aurez besoin d’un point de terminaison et d’une clé API pour instancier un objet client. Pour plus d’informations sur l’authentification auprès de Cognitive Services, consultez Authentifier les demandes auprès d’Azure Cognitive Services.

Obtenir une clé API

Vous pouvez obtenir le point de terminaison et une clé d’API à partir de la ressource Cognitive Services dans le portail Azure.

Vous pouvez également utiliser la commande Azure CLI ci-dessous pour obtenir la clé API à partir de la ressource Cognitive Service.

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

Espaces de noms

Commencez par importer l’espace de noms pour la ConversationAnalysisClient classe et associée :

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

Créer un ConversationAnalysisClient

Une fois que vous avez déterminé votre point de terminaison et votre clé API , vous pouvez instancier un ConversationAnalysisClient:

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

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Créer un ConversationAuthoringClient

Pour utiliser , ConversationAuthoringClientutilisez l’espace de noms suivant en plus de ceux ci-dessus, si nécessaire.

using Azure.AI.Language.Conversations.Authoring;

Avec votre point de terminaison et votre clé API, vous pouvez instancier un ConversationAuthoringClient:

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

ConversationAuthoringClient client = new ConversationAuthoringClient(endpoint, credential);

Créer un client à l’aide de l’authentification Azure Active Directory

Vous pouvez également créer une ConversationAnalysisClientConversationAuthoringClient authentification Ou à l’aide d’Azure Active Directory (AAD). Le rôle « Lecteur de langue Cognitive Services » doit être attribué à votre utilisateur ou principal de service. À l’aide de DefaultAzureCredential , vous pouvez authentifier un service à l’aide d’une identité managée ou d’un principal de service, vous authentifier en tant que développeur travaillant sur une application, et bien plus encore, sans modifier le code.

Avant de pouvoir utiliser , DefaultAzureCredentialou tout type d’informations d’identification à partir d’Azure.Identity, vous devez d’abord installer le package Azure.Identity.

Pour utiliser DefaultAzureCredential avec un ID client et un secret, vous devez définir les AZURE_TENANT_IDvariables d’environnement , AZURE_CLIENT_IDet AZURE_CLIENT_SECRET ; vous pouvez également passer ces valeurs au ClientSecretCredential également dans Azure.Identity.

Veillez à utiliser l’espace de noms approprié pour DefaultAzureCredential en haut de votre fichier source :

using Azure.Identity;

Vous pouvez ensuite créer un instance de et le DefaultAzureCredential transmettre à un nouveau instance de votre client :

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

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Au lieu de cela, créez un nom de domaine personnalisé pour votre ressource afin d’utiliser l’authentification AAD.

Concepts clés

ConversationAnalysisClient

Est ConversationAnalysisClient l’interface principale pour effectuer des prédictions à l’aide de vos modèles Conversations déployés. Il fournit des API synchrones et asynchrones pour envoyer des requêtes.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Exemples

La bibliothèque cliente Azure.AI.Language.Conversations fournit des API synchrones et asynchrones.

Les exemples suivants illustrent les scénarios courants utilisant le clientcréé ci-dessus.

Analyser une conversation

Pour analyser une conversation, vous pouvez appeler la AnalyzeConversation() méthode :

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();
            }
        }
    }
}

D’autres options peuvent être passées à, comme l’activation AnalyzeConversation d’une sortie plus détaillée :

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

Analyser une conversation dans une autre langue

La language propriété peut être définie pour spécifier la langue de la conversation :

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

Analyser une conversation à l’aide d’un projet d’orchestration

Pour analyser une conversation à l’aide d’un projet d’orchestration, vous pouvez appeler la AnalyzeConversation() méthode comme le projet de conversation.

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");

Prédiction des réponses aux questions

Si votre conversation a été analysée par réponses aux questions, elle inclura une intention - peut-être même l’intention principale - à partir de laquelle vous pouvez récupérer des réponses :

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());
    }
}

Résumé conversationnel

Pour résumer une conversation, vous pouvez utiliser la surcharge de AnalyzeConversation méthode qui retourne 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();
    }
}

Exemples supplémentaires

Consultez nos exemples pour obtenir d’autres exemples d’analyse des conversations.

Dépannage

Général

Lorsque vous interagissez avec la bibliothèque cliente Cognitive Language Services Conversations à l’aide du Kit de développement logiciel (SDK) .NET, les erreurs retournées par le service correspondent aux mêmes codes status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous envoyez un énoncé à un projet non existant, une 400 erreur est retournée indiquant « Requête incorrecte ».

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());
}

Vous remarquerez que des informations supplémentaires sont enregistrées, telles que l’ID de demande client de l’opération.

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

Configuration de la journalisation de la console

Le moyen le plus simple d’afficher les journaux consiste à activer la journalisation de console. Pour créer un écouteur de journal du KIT de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez la AzureEventSourceListener.CreateConsoleLogger méthode .

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

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Consultez nos exemples.
Découvrez les différentes fonctionnalités du service Conversations.
Essayez nos démonstrations de service.

Contribution

Consultez le CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.