Share via

Azure Cognitive Language Services-Clientbibliothek für Fragen und Antworten für .NET– Version 1.1.0

  • Artikel

Der Fragebeantwortungsdienst ist ein cloudbasierter API-Dienst, mit dem Sie eine Konversations-Frage-Antwort-Ebene über Ihren vorhandenen Daten erstellen können. Verwenden Sie es, um eine Wissensdatenbank zu erstellen, indem Sie Fragen und Antworten aus Ihren teilweise strukturierten Inhalten extrahieren, einschließlich FAQ, Handbüchern und Dokumenten. Beantworten Sie die Fragen der Benutzer automatisch mit den besten Antworten der QnAs in Ihrem Wissensdatenbank. Auch Ihr Wissensdatenbank wird intelligenter, da sie ständig aus dem Benutzerverhalten lernt.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Produktdokumentation | Proben | Migrationshandbuch

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Cognitive Language Services-Clientbibliothek für Fragen und Antworten für .NET mit NuGet:

dotnet add package Azure.AI.Language.QuestionAnswering

Voraussetzungen

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 Frageantwortdienst zu interagieren, müssen Sie entweder eine instance der QuestionAnsweringClient -Klasse zum Abfragen vorhandener Projekte oder eine instance für die QuestionAnsweringAuthoringClient Verwaltung von Projekten in Ihrer Ressource 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 oder der Ressource "Fragen und Antworten" im Azure-Portal abrufen.

Alternativ können Sie den unten gezeigten Azure CLI-Befehl verwenden, um den API-Schlüssel aus der Ressource "Fragen und Antworten" abzurufen.

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

Erstellen eines QuestionAnsweringClient

Um zu QuestionAnsweringClientverwenden, stellen Sie sicher, dass Sie die richtigen Namespaces verwenden:

using Azure.Core;
using Azure.AI.Language.QuestionAnswering;

Mit Ihrem Endpunkt und API-Schlüssel können Sie eine QuestionAnsweringClientinstanziieren:

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

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Erstellen eines QuestionAnsweringAuthoringClient

Um den QuestionAnsweringAuthoringClientzu verwenden, verwenden Sie bei Bedarf zusätzlich zu den oben genannten Namespaces.

using Azure.AI.Language.QuestionAnswering.Authoring;

Mit Ihrem Endpunkt und API-Schlüssel können Sie eine QuestionAnsweringAuthoringClientinstanziieren:

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

QuestionAnsweringAuthoringClient client = new QuestionAnsweringAuthoringClient(endpoint, credential);

Erstellen eines Clients mithilfe der Azure Active Directory-Authentifizierung

Sie können auch eine oder QuestionAnsweringAuthoringClient eine QuestionAnsweringClient AAD-Authentifizierung (Azure Active Directory) erstellen. Ihrem Benutzer oder Dienstprinzipal muss die Rolle "Cognitive Services-Sprachleser" zugewiesen sein. Mit DefaultAzureCredential können Sie einen Dienst mithilfe einer verwalteten Identität oder eines Dienstprinzipals authentifizieren, sich als Entwickler authentifizieren, der an einer Anwendung arbeitet, und vieles mehr, ohne code zu ändern.

Bevor Sie oder DefaultAzureCredentialeinen beliebigen Anmeldeinformationstyp aus Azure.Identity verwenden können, müssen Sie zunächst das Azure.Identity-Paket installieren.

Um mit einer Client-ID und einem Geheimschlüssel zu verwenden DefaultAzureCredential , müssen Sie die AZURE_TENANT_IDUmgebungsvariablen , AZURE_CLIENT_IDund AZURE_CLIENT_SECRET festlegen. Alternativ können Sie diese Werte auch an azure.Identity ClientSecretCredential übergeben.

Stellen Sie sicher, dass Sie den richtigen Namespace für DefaultAzureCredential am Anfang ihrer 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();

QuestionAnsweringClient client = new QuestionAnsweringClient(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

QuestionAnsweringClient

Die QuestionAnsweringClient ist die primäre Schnittstelle zum Stellen von Fragen mithilfe einer Wissensdatenbank mit Ihren eigenen Informationen oder texteingaben mit vortrainierten Modellen. Sie stellt sowohl synchrone als auch asynchrone APIs bereit, um Fragen zu stellen.

QuestionAnsweringAuthoringClient

stellt QuestionAnsweringAuthoringClient eine Schnittstelle zum Verwalten von Fragen-Antwort-Projekten bereit. Beispiele für die verfügbaren Vorgänge sind das Erstellen und Bereitstellen von Projekten, das Aktualisieren Ihrer Wissensquellen und das Aktualisieren von Frage-Antwort-Paaren. Es stellt sowohl synchrone als auch asynchrone APIs bereit.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und voneinander unabhängig 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

QuestionAnsweringClient

Die Azure.AI.Language.QuestionAnswering-Clientbibliothek stellt sowohl synchrone als auch asynchrone APIs bereit.

In den folgenden Beispielen werden häufige Szenarien mit dem clientoben erstellten veranschaulicht.

Fragen stellen

Die einzige Eingabe, die erforderlich ist, um eine Frage mithilfe eines vorhandenen Wissensdatenbank zu stellen, ist nur die Frage selbst:

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
Response<AnswersResult> response = client.GetAnswers("How long should my Surface battery last?", project);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

Sie können zusätzliche Eigenschaften für QuestionAnsweringClientOptions festlegen, um die Anzahl der Antworten zu begrenzen, eine minimale Konfidenzbewertung anzugeben und vieles mehr.

Stellen einer Folgefrage

Wenn Ihr Wissensdatenbank für "Chit-Chat" konfiguriert ist, können Sie eine Folgefrage stellen, sofern die vorherige Frage-Antwort-ID und optional die genaue Frage angegeben wird, die der Benutzer gestellt hat:

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
// Answers are ordered by their ConfidenceScore so assume the user choose the first answer below:
KnowledgeBaseAnswer previousAnswer = answers.Answers.First();
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions
{
    AnswerContext = new KnowledgeBaseAnswerContext(previousAnswer.QnaId.Value)
};

Response<AnswersResult> response = client.GetAnswers("How long should charging take?", project, options);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

QuestionAnsweringAuthoringClient

Die folgenden Beispiele zeigen häufige Szenarien mit der QuestionAnsweringAuthoringClientin diesem Abschnitt erstellten instance.

Erstellen eines neuen Projekts

Um ein neues Projekt zu erstellen, müssen Sie den Namen des Projekts angeben und eine RequestContent instance mit den Parametern erstellen, die zum Einrichten des Projekts erforderlich sind.

// Set project name and request content parameters
string newProjectName = "{ProjectName}";
RequestContent creationRequestContent = RequestContent.Create(
    new {
        description = "This is the description for a test project",
        language = "en",
        multilingualResource = false,
        settings = new {
            defaultAnswer = "No answer found for your question."
            }
        }
    );

Response creationResponse = client.CreateProject(newProjectName, creationRequestContent);

// Projects can be retrieved as follows
Pageable<BinaryData> projects = client.GetProjects();

Console.WriteLine("Projects: ");
foreach (BinaryData project in projects)
{
    Console.WriteLine(project);
}

Bereitstellen des Projekts

Ihre Projekte können mit oder DeployProjectAsync mit dem synchronen DeployProjectbereitgestellt werden. Sie müssen lediglich den Namen des Projekts und den Bereitstellungsnamen angeben, den Sie verwenden möchten. Beachten Sie, dass sie mit dem Dienst keine leeren Projekte bereitstellen können.

// Set deployment name and start operation
string newDeploymentName = "{DeploymentName}";

Operation<BinaryData> deploymentOperation = client.DeployProject(WaitUntil.Completed, newProjectName, newDeploymentName);

// Deployments can be retrieved as follows
Pageable<BinaryData> deployments = client.GetDeployments(newProjectName);
Console.WriteLine("Deployments: ");
foreach (BinaryData deployment in deployments)
{
    Console.WriteLine(deployment);
}

Hinzufügen einer Wissensquelle

Eine Möglichkeit zum Hinzufügen von Inhalten zu Ihrem Projekt besteht darin, eine Wissensquelle hinzuzufügen. Das folgende Beispiel zeigt, wie Sie eine RequestContent instance einrichten können, um eine neue Wissensquelle vom Typ "url" hinzuzufügen.

// Set request content parameters for updating our new project's sources
string sourceUri = "{KnowledgeSourceUri}";
RequestContent updateSourcesRequestContent = RequestContent.Create(
    new[] {
        new {
                op = "add",
                value = new
                {
                    displayName = "MicrosoftFAQ",
                    source = sourceUri,
                    sourceUri = sourceUri,
                    sourceKind = "url",
                    contentStructureKind = "unstructured",
                    refresh = false
                }
            }
    });

Operation<Pageable<BinaryData>> updateSourcesOperation = client.UpdateSources(WaitUntil.Completed, newProjectName, updateSourcesRequestContent);

// Knowledge Sources can be retrieved as follows
Pageable<BinaryData> sources = updateSourcesOperation.Value;

Console.WriteLine("Sources: ");
foreach (BinaryData source in sources)
{
    Console.WriteLine(source);
}

Problembehandlung

Allgemein

Wenn Sie mit der Cognitive Language Services-Clientbibliothek für Fragen und Antworten mithilfe des .NET SDK interagieren, entsprechen die vom Dienst zurückgegebenen Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise eine Frage an eine nicht vorhandene Wissensdatenbank übermitteln, wird ein 400 Fehler zurückgegeben, der "Ungültige Anforderung" angibt.

try
{
    QuestionAnsweringProject project = new QuestionAnsweringProject("invalid-knowledgebase", "test");
    Response<AnswersResult> response = client.GetAnswers("Does this knowledge base exist?", project);
}
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: Please verify azure search service is up, restart the WebApp and try again
Status: 400 (Bad Request)
ErrorCode: BadArgument

Content:
{
    "error": {
    "code": "BadArgument",
    "message": "Please verify azure search service is up, restart the WebApp and try again"
    }
}

Headers:
x-envoy-upstream-service-time: 23
apim-request-id: 76a83876-22d1-4977-a0b1-559a674f3605
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
Date: Wed, 30 Jun 2021 00:32:07 GMT
Content-Length: 139
Content-Type: application/json; charset=utf-8

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die -Methode, um einen Azure SDK-Protokolllistener zu erstellen, der AzureEventSourceListener.CreateConsoleLogger 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

Mitwirken

Ausführliche 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.

Aufrufe