Clientbibliothek für Azure Cognitive Language Services-Unterhaltungen für .NET– Version 1.1.0

Artikel
06/21/2023

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

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

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.