Bibliothèque de client Azure Cognitive Language Services Conversations pour .NET - version 1.1.0
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
| Code sourcePackage (NuGet) | Documentation de référence sur les | APIÉchantillons | | Documentation produitDocumentation | de l’API REST d’analyseCréation de la documentation de l’API REST
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
Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client
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.
Azure SDK for .NET