Clientbibliothek für Azure Cognitive Language Services-Unterhaltungen für .NET– Version 1.1.0
Conversational Language Understanding – kurz CLU – ist ein cloudbasierter Konversations-KI-Dienst, der viele Sprachverständnisfunktionen bietet, z. B.:
- Konversations-App: Sie wird zum Extrahieren von Absichten und Entitäten in Unterhaltungen verwendet.
- Workflow-App: Fungiert wie ein Orchestrator, um den besten Kandidaten für die Analyse von Unterhaltungen auszuwählen, um die beste Antwort von Apps wie Qna, Luis und Conversation App zu erhalten
Quellcode | Paket (NuGet) | API-Referenzdokumentation | Proben | Produktdokumentation | Analyse-REST-API-Dokumentation | Erstellen der REST-API-Dokumentation
Erste Schritte
Installieren des Pakets
Installieren Sie die Azure Cognitive Language Services Conversations-Clientbibliothek für .NET mit NuGet:
dotnet add package Azure.AI.Language.Conversations
Voraussetzungen
- Ein Azure-Abonnement
- Eine vorhandene Azure Language Service-Ressource
Obwohl Sie dieses SDK zum Erstellen und Importieren von Unterhaltungsprojekten verwenden können, ist Language Studio die bevorzugte Methode zum Erstellen von Projekten.
Authentifizieren des Clients
Um mit dem Conversations-Dienst zu interagieren, müssen Sie eine instance der ConversationAnalysisClient -Klasse erstellen. Sie benötigen einen Endpunkt und einen API-Schlüssel , um ein Clientobjekt zu instanziieren. Weitere Informationen zur Authentifizierung mit Cognitive Services finden Sie unter Authentifizieren von Anforderungen an Azure Cognitive Services.
Abrufen eines API-Schlüssels
Sie können den Endpunkt und einen API-Schlüssel aus der Cognitive Services-Ressource im Azure-Portal abrufen.
Alternativ können Sie den unten gezeigten Azure CLI-Befehl verwenden, um den API-Schlüssel aus der Cognitive Service-Ressource abzurufen.
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Namespaces
Beginnen Sie mit dem Importieren des Namespaces für die und die ConversationAnalysisClient zugehörige Klasse:
using Azure.Core;
using Azure.AI.Language.Conversations;
Erstellen eines ConversationAnalysisClient
Nachdem Sie Ihren Endpunkt und API-Schlüssel ermittelt haben, können Sie einen ConversationAnalysisClientinstanziieren:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");
ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);
Erstellen eines ConversationAuthoringClient
Um den ConversationAuthoringClientzu verwenden, verwenden Sie ggf. zusätzlich zu den oben genannten Namespaces.
using Azure.AI.Language.Conversations.Authoring;
Mit Ihrem Endpunkt und API-Schlüssel können Sie eine ConversationAuthoringClientinstanziieren:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");
ConversationAuthoringClient client = new ConversationAuthoringClient(endpoint, credential);
Erstellen eines Clients mithilfe der Azure Active Directory-Authentifizierung
Sie können auch eine ConversationAnalysisClient Oder-Authentifizierung ConversationAuthoringClient mit Azure Active Directory (AAD) erstellen. Ihrem Benutzer oder Dienstprinzipal muss die Rolle "Cognitive Services Language Reader" zugewiesen sein.
Mithilfe von DefaultAzureCredential können Sie einen Dienst mit verwalteter Identität oder einem Dienstprinzipal authentifizieren, sich als Entwickler authentifizieren, der an einer Anwendung arbeitet, und vieles mehr, ohne Code zu ändern.
Bevor Sie den Anmeldeinformationstyp oder einen DefaultAzureCredentialbeliebigen Anmeldeinformationstyp aus Azure.Identity verwenden können, müssen Sie zuerst das Azure.Identity-Paket installieren.
Für die Verwendung DefaultAzureCredential mit einer Client-ID und einem Geheimnis müssen Sie die AZURE_TENANT_IDUmgebungsvariablen , AZURE_CLIENT_IDund AZURE_CLIENT_SECRET festlegen. Alternativ können Sie diese Werte auch an die ClientSecretCredential in Azure.Identity übergeben.
Stellen Sie sicher, dass Sie den richtigen Namespace für DefaultAzureCredential oben in Der Quelldatei verwenden:
using Azure.Identity;
Anschließend können Sie eine instance von DefaultAzureCredential erstellen und an eine neue instance Ihres Clients übergeben:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();
ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);
Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie stattdessen einen benutzerdefinierten Domänennamen für Ihre Ressource, um die AAD-Authentifizierung zu verwenden.
Wichtige Begriffe
ConversationAnalysisClient
Die ConversationAnalysisClient ist die primäre Schnittstelle zum Erstellen von Vorhersagen mithilfe Ihrer bereitgestellten Konversationsmodelle. Sie stellt sowohl synchrone als auch asynchrone APIs zum Übermitteln von Abfragen bereit.
Threadsicherheit
Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.
Zusätzliche Konzepte
Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer
Beispiele
Die Azure.AI.Language.Conversations-Clientbibliothek bietet sowohl synchrone als auch asynchrone APIs.
Die folgenden Beispiele zeigen häufige Szenarien mit dem clientoben erstellten.
Analysieren einer Unterhaltung
Um eine Unterhaltung zu analysieren, können Sie die AnalyzeConversation() -Methode aufrufen:
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();
}
}
}
}
Zusätzliche Optionen können übergeben werden, um z. B. eine ausführlichere Ausgabe zu AnalyzeConversation aktivieren:
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));
Analysieren einer Unterhaltung in einer anderen Sprache
Die language -Eigenschaft kann so festgelegt werden, dass die Sprache der Unterhaltung angegeben wird:
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));
Analysieren einer Unterhaltung mithilfe eines Orchestrierungsprojekts
Um eine Unterhaltung mithilfe eines Orchestrierungsprojekts zu analysieren, können Sie die AnalyzeConversation() -Methode genau wie das Konversationsprojekt aufrufen.
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");
Vorhersage der Fragebeantwortung
Wenn Ihre Unterhaltung durch Frageantwort analysiert wurde, enthält sie eine Absicht - vielleicht sogar die oberste Absicht -, aus der Sie Antworten abrufen können:
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());
}
}
Konversationszusammenfassung
Um eine Unterhaltung zusammenzufassen, können Sie die Methodenüberladung verwenden, die AnalyzeConversation einen Operation<BinaryData>zurückgibt:
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();
}
}
Weitere Beispiele
In unseren Beispielen finden Sie weitere Beispiele für die Analyse von Unterhaltungen.
Problembehandlung
Allgemein
Wenn Sie mit der Cognitive Language Services Conversations-Clientbibliothek mithilfe des .NET SDK interagieren, entsprechen vom Dienst zurückgegebene Fehler den gleichen HTTP-status-Codes, die für REST-API-Anforderungen zurückgegeben werden.
Wenn Sie beispielsweise eine Äußerung an ein nicht vorhandenes Projekt übermitteln, wird ein 400 Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist.
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());
}
Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.
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
Einrichten der Konsolenprotokollierung
Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die AzureEventSourceListener.CreateConsoleLogger -Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole ausgibt.
// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie hier.
Nächste Schritte
- Sehen Sie sich unsere Beispiele an.
- Erfahren Sie mehr über die verschiedenen Features des Conversations-Diensts.
- Probieren Sie unsere Servicedemos aus.
Mitwirken
Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .
Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.
Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.
Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.
Azure SDK for .NET