Schnellstart: QnA Maker-Clientbibliothek

Voraussetzungen

• Aktuelle Version von cURL. In den Schnellstartanleitungen werden mehrere Befehlszeilenschalter verwendet, die in der cURL-Dokumentation angegeben sind.

• Sie benötigen eine QnA Maker-Ressource, um den Schlüssel und Ressourcennamen verwenden zu können. Sie haben den Namen der Ressource während der Ressourcenerstellung eingegeben. Der Schlüssel wurde anschließend für Sie erstellt. Der Ressourcenname wird als Unterdomäne für Ihren Endpunkt verwendet. Wählen Sie für Ihre Ressource im Azure-Portal die Option Schnellstart aus, um den Schlüssel und den Ressourcennamen abzurufen. Der Ressourcenname ist die erste Unterdomäne der Endpunkt-URL:

  https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0

Erstellen einer Wissensdatenbank

Sie benötigen die folgenden Informationen, um mit den REST-APIs und mit cURL eine Wissensdatenbank zu erstellen:

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie für diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel sowie die JSON-Werte und die JSON-Größe ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://video2.skills-academy.com/azure/ai-services/qnamaker/faqs"]}'

Die cURL-Antwort aus QnA Maker enthält die operationId, die benötigt wird, um den Status des Vorgangs abzurufen.

{
  "operationState": "NotStarted",
  "createdTimestamp": "2020-02-27T04:11:22Z",
  "lastActionTimestamp": "2020-02-27T04:11:22Z",
  "userId": "9596077b3e0441eb93d5080d6a15c64b",
  "operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}

Abrufen des Status eines Vorgangs

Da der Vorgang beim Erstellen einer Wissensdatenbank asynchron ist, enthält die Antwort Informationen zum Ermitteln des Status.

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie in diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel sowie die Vorgangs-ID ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

Die cURL-Antwort enthält den Status. Wenn der Status des Vorgangs „Erfolgreich“ lautet, enthält resourceLocation die Wissensdatenbank-ID.

{
   "operationState": "Succeeded",
   "createdTimestamp": "2020-02-27T04:54:07Z",
   "lastActionTimestamp": "2020-02-27T04:54:19Z",
   "resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
   "userId": "f596077b3e0441eb93d5080d6a15c64b",
   "operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}

Veröffentlichen einer Wissensdatenbank

Sie benötigen Folgendes, bevor Sie die Wissensdatenbank abfragen können:

• Veröffentlichen einer Wissensdatenbank
• Abrufen des Laufzeitschlüssels für den Endpunkt

In diesem Schritt wird die Wissensdatenbank veröffentlicht. Das Abrufen des Laufzeitschlüssels für den Endpunkt ist eine separate Aufgabe.

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie in diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel sowie die Wissensdatenbank-ID ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''

Der Antwortstatus lautet 204 ohne Ergebnisse. Verwenden Sie den Befehlszeilenparameter -v, um die ausführliche Ausgabe für den cURL-Befehl anzuzeigen. Darin ist auch der HTTP-Status enthalten.

Abrufen des Laufzeitschlüssels für den Endpunkt für eine veröffentlichte Wissensdatenbank

Sie benötigen Folgendes, bevor Sie die Wissensdatenbank abfragen können:

• Veröffentlichen einer Wissensdatenbank
• Abrufen des Laufzeitschlüssels für den Endpunkt

In diesem Schritt wird der Laufzeitschlüssel für den Endpunkt abgerufen. Die Veröffentlichung der Wissensdatenbank ist eine separate Aufgabe.

Der Laufzeitschlüssel für den Endpunkt ist für alle Wissensdatenbanken gleich, die die QnA Maker-Ressource nutzen.

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie in diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

Die cURL-Antwort enthält die Laufzeitschlüssel für die Endpunkte. Verwenden Sie beim Abfragen nur einen der Schlüssel, um eine Antwort von der Wissensdatenbank zu erhalten.

{
  "primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
  "secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
  "installedVersion": "4.0.5",
  "lastStableVersion": "4.0.6"
}

Abfragen einer Antwort von der veröffentlichten Wissensdatenbank

Das Abrufen einer Antwort aus der Wissensdatenbank erfolgt über eine andere Laufzeit als beim Verwalten der Wissensdatenbank. Da es sich um eine separate Laufzeit handelt, müssen Sie für die Authentifizierung einen Laufzeitschlüssel verwenden.

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie in diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel sowie die Wissensdatenbank-ID ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true,  "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'

Eine erfolgreiche Antwort enthält die beste Antwort und die anderen Informationen, die von einer Clientanwendung, z. B. einem Chatbot, zum Anzeigen einer Antwort für den Benutzer benötigt werden.

Löschen einer Wissensdatenbank

Löschen Sie die Wissensdatenbank, wenn Sie die Nutzung beendet haben.

Der cURL-Befehl wird über eine Bash-Shell ausgeführt. Fügen Sie in diesen Befehl Ihren eigenen Ressourcennamen und Ressourcenschlüssel sowie die Wissensdatenbank-ID ein.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

Der Antwortstatus lautet 204 ohne Ergebnisse. Verwenden Sie den Befehlszeilenparameter -v, um die ausführliche Ausgabe für den cURL-Befehl anzuzeigen. Darin ist auch der HTTP-Status enthalten.

Zusätzliche Ressourcen

• Referenzdokumentation zur Erstellung
• Referenzdokumentation zur Laufzeit
• Bash-Beispielskripts mit cURL

Verwenden Sie die QnA Maker-Clientbibliothek für .NET für Folgendes:

• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Veröffentlichen einer Wissensdatenbank
• Abrufen von Endpunktschlüsseln der Vorhersage-Runtime
• Warten auf Aufgaben mit langer Ausführungsdauer
• Herunterladen einer Wissensdatenbank
• Abrufen einer Antwort aus einer Wissensdatenbank
• Löschen einer Wissensdatenbank

Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | C#-Beispiele

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Die Visual Studio-IDE oder die aktuelle Version von .NET Core.
• Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie im Azure-Portal eine QnA Maker-Ressource, um Ihren Erstellungsschlüssel und Ressourcennamen zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und Ressourcennamen aus der von Ihnen erstellten Ressource, um Ihre Anwendung mit der QnA Maker-API zu verbinden. Fügen Sie Ihren Schlüssel und Ressourcennamen weiter unten in der Schnellstartanleitung in den Code ein.
  • Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Befehlszeilenschnittstelle (CLI)

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen qna-maker-quickstart. Dieser Befehl erstellt ein einfaches C#-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei: program.cs.

dotnet new console -n qna-maker-quickstart

Wechseln Sie zum Ordner der neu erstellten App. Sie können die Anwendung mit folgendem Befehl erstellen:

dotnet build

Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installieren Sie im Anwendungsverzeichnis mit dem folgenden Befehl die QnA Maker-Clientbibliothek für .NET:

dotnet add package Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker --version 2.0.1

using-Direktiven

Öffnen Sie über das Projektverzeichnis die Datei program.cs, und fügen Sie die folgenden using-Direktiven hinzu:

using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker;
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

Abonnementschlüssel und Ressourcenendpunkte

Fügen Sie in der Main-Methode der Anwendung Variablen und Code hinzu, wie im folgenden Abschnitt gezeigt wird, um mit den allgemeinen Aufgaben in dieser Schnellstartanleitung arbeiten zu können.

• Die Begriffe „Abonnementschlüssel“ und Erstellungsschlüssel“ werden synonym verwendet. Ausführlichere Informationen zum Erstellungsschlüssel finden Sie unter Schlüssel in QnA Maker.

• Der Wert von „QNA_MAKER_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Ressourcenverwaltung die Seite Schlüssel und Endpunkt aus, um den Schlüssel für die Dokumenterstellung (Abonnement) und den QnA Maker-Endpunkt zu suchen.

• Der Wert von „QNA_MAKER_RUNTIME_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.azurewebsites.net. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Automation die Seite Vorlage exportieren aus, um den Laufzeitendpunkt zu suchen.

var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Objektmodelle

Von QnA Maker werden zwei unterschiedliche Objektmodelle verwendet:

• QnAMakerClient ist das Objekt zum Erstellen, Verwalten, Veröffentlichen und Herunterladen der Wissensdatenbank.
• QnAMakerRuntime ist das Objekt, das für Abfragen der Wissensdatenbank mit der GenerateAnswer-API und zum Senden neuer vorgeschlagener Fragen mithilfe der Train-API (im Rahmen des aktiven Lernens) verwendet wird.

Verwenden dieser Beispiel-Wissensdatenbank

Die Wissensdatenbank in diesem Schnellstart beginnt mit zwei QnA-Unterhaltungspaaren. Dies wurde absichtlich so implementiert, um das Beispiel zu vereinfachen und hochgradig vorhersagbare IDs für die Update-Methode zu erhalten, die Folgeaufforderungen mit Fragen zu neuen Paaren verknüpft. Dies wurde für diese Schnellstartanleitung in einer bestimmten Reihenfolge geplant und implementiert.

Wenn Sie beabsichtigen, Ihre Wissensdatenbank im Lauf der Zeit mit Folgeaufforderungen zu entwickeln, die von vorhandenen QnA-Paaren abhängen, bieten sich Ihnen die folgenden Möglichkeiten:

• Bei größeren Wissensdatenbanken Verwaltung der Wissensdatenbank in einem Text-Editor oder einem TSV-Tool, das Automatisierung unterstützt. Die Wissensdatenbank wird dann in einem Durchgang vollständig durch ein Update ersetzt.
• Bei kleineren Wissensdatenbanken ausschließliches Verwalten der Nachfolgeaufforderungen im QnA Maker-Portal.

Details zu den QnA-Paaren, die in dieser Schnellstartanleitung verwendet werden:

• Typen von QnA-Paaren: Nach dem Update gibt es zwei Typen von QnA-Paaren in dieser Wissensdatenbank: Geplauder und domänenspezifische Informationen. Dies ist typisch, wenn Ihre Wissensdatenbank an eine Unterhaltungsanwendung gebunden ist, wie etwa einen Chatbot.
• Die Antworten aus Ihrer Wissensdatenbank lassen sich zwar anhand von Metadaten oder Folgeaufforderungen filtern, dies wird in dieser Schnellstartanleitung aber nicht gezeigt. Suchen Sie hier nach diesen sprachunabhängigen generateAnswer-Beispielen.
• Der Antworttext ist Markdown und kann eine große Bandbreite von Markdown enthalten, z. B. Bilder (öffentlich verfügbare, internetbasierte Bilder), Links (zu öffentlich verfügbaren URLs) und Aufzählungspunkte. Diese Unterart spielt in diesem Schnellstart keine Rolle.

QnAMakerClient-Objektmodell

Der erstellende QnA Maker-Client ist ein QnAMakerClient-Objekt, das mithilfe der „Microsoft.Rest.ServiceClientCredentials“-Klasse, die Ihren Schlüssel enthält, bei Azure authentifiziert wird.

Nachdem der Client erstellt wurde, verwenden Sie die Knowledge Base-Eigenschaft, um Ihre Knowledge Base zu erstellen, zu verwalten und zu veröffentlichen.

Verwalten Sie Ihre Knowledge Base durch Senden eines JSON-Objekts. Bei sofortigen Vorgängen gibt eine Methode in der Regel ein JSON-Objekt zurück, das den Status angibt. Bei zeitintensiven Vorgängen ist die Antwort die Vorgangs-ID. Rufen Sie die client.Operations.GetDetailsAsync-Methode mit der Vorgangs-ID auf, um den Status der Anforderung zu bestimmen.

QnAMakerRuntimeClient-Objektmodell

Der QnA Maker-Vorhersageclient ist ein QnAMakerRuntimeClient-Objekt, das sich bei Azure mithilfe von Microsoft.Rest.ServiceClientCredentials authentifiziert, die Ihren Schlüssel für die Vorhersage-Runtime enthalten, der nach dem Veröffentlichen der Wissensdatenbank vom Aufruf client.EndpointKeys.GetKeys des erstellenden Clients zurückgegeben wurde.

Mithilfe der Methode GenerateAnswer können Sie eine Antwort aus der Abfragelaufzeit abrufen.

Codebeispiele

Mit den Codeausschnitten wird veranschaulicht, wie folgende Vorgänge mit der QnA Maker-Clientbibliothek für .NET durchgeführt werden:

• Authentifizieren des Erstellungsclients
• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Herunterladen einer Knowledge Base
• Veröffentlichen einer Wissensdatenbank
• Löschen einer Wissensdatenbank
• Abrufen des Abfrage-Runtimeschlüssels
• Abrufen des Status eines Vorgangs
• Authentifizieren des Abfrage-Runtimeclients
• Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Authentifizieren des Clients zum Erstellen der Wissensdatenbank

Instanziieren Sie ein Clientobjekt mit Ihrem Schlüssel, und verwenden Sie es zusammen mit Ihrer Ressource, um den Endpunkt zum Erstellen eines QnAMakerClient-Objekts mit Ihrem Endpunkt und Schlüssel zu erstellen. Erstellen Sie ein ServiceClientCredentials-Objekt.

var client = new QnAMakerClient(new ApiKeyServiceClientCredentials(authoringKey))
{ Endpoint = authoringURL };

Erstellen einer Wissensdatenbank

Eine Wissensdatenbank speichert Frage- und Antwortpaare für das CreateKbDTO-Objekt aus drei Quellen:

• Für redaktionellen Inhalt verwenden Sie das QnADTO-Objekt.
  • Verwenden Sie für Metadaten und Folgeaufforderungen den redaktionellen Kontext, da diese Daten auf der Ebene der einzelnen QnA-Paare hinzugefügt werden.
• Für Dateien verwenden Sie das FileDTO-Objekt. Das FileDTO-Objekt enthält den Dateinamen sowie die öffentliche URL für den Zugriff auf die Datei.
• Verwenden Sie für URLseine Liste von Zeichenfolgen zur Darstellung von öffentlich verfügbaren URLs.

Der Erstellungsschritt umfasst auch Eigenschaften für die Wissensdatenbank mit Folgendem:

• defaultAnswerUsedForExtraction: die Rückgabe, wenn keine Antwort gefunden wird
• enableHierarchicalExtraction: automatisches Erstellen von Aufforderungsbeziehungen zwischen extrahierten QnA-Paaren
• language– bei der Erstellung der ersten Wissensdatenbank für eine Ressource Festlegen der Sprache, die im Azure-Suchindex verwendet werden soll

Rufen Sie die CreateAsync-Methode auf, und übergeben Sie dann die zurückgegebene Vorgangs-ID an die MonitorOperation-Methode, um den Status abzurufen.

In der letzten Zeile des folgenden Codes wird die Knowledge Base-ID aus der Antwort von „MonitorOperation“ zurückgegeben.

private static async Task<string> CreateSampleKb(IQnAMakerClient client)
{
    var qna1 = new QnADTO
    {
        Answer = "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        Questions = new List<string> { "How do I manage my knowledgebase?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = "REST" }
        },

    };

    var qna2 = new QnADTO
    {
        Answer = "Yes, You can use our [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker) with the [.NET Reference Docs](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.knowledge.qnamaker?view=azure-dotnet) to manage your knowledge base.",
        Questions = new List<string> { "Can I program with C#?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = ".NET" }
        }
    };

    var file1 = new FileDTO
    {
        FileName = "myfile.tsv",
        FileUri = "https://mydomain/myfile.tsv"

    };

    var createKbDto = new CreateKbDTO
    {
        Name = "QnA Maker .NET SDK Quickstart",
        QnaList = new List<QnADTO> { qna1, qna2 },
        //Files = new List<FileDTO> { file1 }

    };

    var createOp = await client.Knowledgebase.CreateAsync(createKbDto);
    createOp = await MonitorOperation(client, createOp);

    return createOp.ResourceLocation.Replace("/knowledgebases/", string.Empty);
}

Zum erfolgreichen Erstellen einer Wissensdatenbank muss die Funktion MonitorOperation eingeschlossen werden, auf die im obigen Code verwiesen wird.

Aktualisieren einer Wissensdatenbank

Sie können eine Knowledge Base aktualisieren, indem Sie die Knowledge Base-ID und ein UpdatekbOperationDTO, das add-, update- und delete-DTO-Objekte enthält, als Eingabe an die UpdateAsync-Methode übergeben. Verwenden Sie die MonitorOperation -Methode, um zu bestimmen, ob das Update erfolgreich war.

private static async Task UpdateKB(IQnAMakerClient client, string kbId)
{

    var urls = new List<string> {
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    };

    var updateOp = await client.Knowledgebase.UpdateAsync(kbId, new UpdateKbOperationDTO
    {
        // Create JSON of changes
        Add = new UpdateKbOperationDTOAdd
        {
            QnaList = new List<QnADTO> {
                new QnADTO {
                    Questions = new List<string> {
                        "bye",
                        "end",
                        "stop",
                        "quit",
                        "done"
                    },
                    Answer = "goodbye",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "end" },
                    }
                },
                new QnADTO {
                    Questions = new List<string> {
                        "hello",
                        "hi",
                        "start"
                    },
                    Answer = "Hello, please select from the list of questions or enter a new question to continue.",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "begin" }
                    },
                    Context = new QnADTOContext
                    {
                        IsContextOnly = false,
                        Prompts = new List<PromptDTO>
                        {
                            new PromptDTO
                            {
                                DisplayOrder =1,
                                DisplayText= "Use REST",
                                QnaId=1

                            },
                            new PromptDTO
                            {
                                DisplayOrder =2,
                                DisplayText= "Use .NET NuGet package",
                                QnaId=2

                            },
                        }
                    }
                },
            },
            Urls = urls
        },
        Update = null,
        Delete = null
    }); ;

    // Loop while operation is success
    updateOp = await MonitorOperation(client, updateOp);
}

Nehmen Sie zum erfolgreichen Aktualisieren einer Wissensdatenbank unbedingt die Funktion MonitorOperation mit auf, auf die im Code oben verwiesen wird.

Herunterladen einer Knowledge Base

Verwenden Sie die DownloadAsync-Methode, um die Datenbank als Liste von QnADocumentsDTO herunterzuladen. Dies entspricht nicht dem Export des QnA Maker-Portals von der Seite Einstellungen, weil das Ergebnis dieser Methode keine Datei ist.

private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
    var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
    Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);

    // Do something meaningful with data
}

Veröffentlichen einer Wissensdatenbank

Veröffentlichen Sie die Knowledge Base mithilfe der PublishAsync-Methode. Diese übernimmt das aktuell gespeicherte und trainierte Modell, auf das von der Knowledge Base-ID verwiesen wird, und veröffentlicht es an Ihrem Endpunkt. Dies ist ein erforderlicher Schritt zum Abfragen Ihrer Wissensdatenbank.

private static async Task PublishKb(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.PublishAsync(kbId);
}

Abrufen des Abfrage-Runtimeschlüssels

Nach dem Veröffentlichen einer Wissensdatenbank benötigen Sie den Abfrage-Runtimeschlüssel, um die Runtime abzufragen. Dabei handelt es sich nicht um den Schlüssel, der zum Erstellen des ursprünglichen Clientobjekts verwendet wurde.

Verwenden Sie die Methode EndpointKeys, um die Klasse EndpointKeysDTO abzurufen.

Verwenden Sie eine der im Objekt zurückgegeben Schlüsseleigenschaften, um die Wissensdatenbank abzufragen.

private static async Task<String> GetQueryEndpointKey(IQnAMakerClient client)
{
    var endpointKeysObject = await client.EndpointKeys.GetKeysAsync();

    return endpointKeysObject.PrimaryEndpointKey;
}

Ein Runtimeschlüssel ist zum Abfragen Ihrer Wissensdatenbank erforderlich.

Authentifizieren der Runtime zum Erstellen einer Antwort

Erstellen Sie ein QnAMakerRuntimeClient-Element, um die Wissensdatenbank abzufragen und eine Antwort zu generieren oder mit aktivem Lernen zu trainieren.

var runtimeClient = new QnAMakerRuntimeClient(new EndpointKeyServiceClientCredentials(primaryQueryEndpointKey))
{ RuntimeEndpoint = queryingURL };

Verwenden Sie das „QnAMakerRuntimeClient“-Element für folgende Aktionen:

• Abrufen einer Antwort aus der Wissensdatenbank
• Senden von neuen Fragevorschlägen an die Wissensdatenbank für aktives Lernen

Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Generieren Sie mithilfe der Methode RuntimeClient.GenerateAnswerAsync eine Antwort aus einer veröffentlichten Wissensdatenbank. Diese Methode akzeptiert die Wissensdatenbank-ID und die QueryDTO-Klasse. Greifen Sie auf weitere QueryDTO-Eigenschaften zu (etwa Top und Context), und verwenden Sie sie in Ihrem Chatbot.

private static async Task GenerateAnswer(IQnAMakerRuntimeClient runtimeClient, string kbId)
{
    var response = await runtimeClient.Runtime.GenerateAnswerAsync(kbId, new QueryDTO { Question = "How do I manage my knowledgebase?" });
    Console.WriteLine("Endpoint Response: {0}.", response.Answers[0].Answer);

    // Do something meaningful with answer
}

Dies ist ein einfaches Beispiel zum Abfragen der Wissensdatenbank. Informationen zu erweiterten Abfrageszenarien finden Sie in weiteren Abfragebeispielen.

Löschen einer Wissensdatenbank

Löschen Sie die Wissensdatenbank mithilfe der Methode DeleteAsync mit einem Parameter der Wissensdatenbank-ID.

private static async Task DeleteKB(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.DeleteAsync(kbId);
}

Abrufen des Status eines Vorgangs

Einige Methoden, wie „create“ und „update“, können so viel Zeit in Anspruch nehmen, dass ein Vorgang zurückgegeben wird, anstatt auf den Abschluss des Prozesses zu warten. Verwenden Sie die Vorgangs-ID des Vorgangs, um den Status der ursprünglichen Methode mittels Abrufen (mit Wiederholungslogik) zu bestimmen.

Die Schleife und Task.Delay im folgenden Codeblock werden verwendet, um die Wiederholungslogik zu simulieren. Diese sollten durch Ihre eigene Wiederholungslogik ersetzt werden.

private static async Task<Operation> MonitorOperation(IQnAMakerClient client, Operation operation)
{
    // Loop while operation is success
    for (int i = 0;
        i < 20 && (operation.OperationState == OperationStateType.NotStarted || operation.OperationState == OperationStateType.Running);
        i++)
    {
        Console.WriteLine("Waiting for operation: {0} to complete.", operation.OperationId);
        await Task.Delay(5000);
        operation = await client.Operations.GetDetailsAsync(operation.OperationId);
    }

    if (operation.OperationState != OperationStateType.Succeeded)
    {
        throw new Exception($"Operation {operation.OperationId} failed to completed.");
    }
    return operation;
}

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Den Quellcode für dieses Beispiel finden Sie auf GitHub.

Verwenden Sie die QnA Maker-Clientbibliothek für Node.js für folgende Zwecke:

• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Veröffentlichen einer Wissensdatenbank
• Abrufen von Endpunktschlüsseln der Vorhersage-Runtime
• Warten auf Aufgaben mit langer Ausführungsdauer
• Herunterladen einer Wissensdatenbank
• Abrufen einer Antwort aus einer Wissensdatenbank
• Löschen einer Wissensdatenbank

Referenzdokumentation | Paket (npm) | Node.js-Beispiele

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Die aktuelle Version von Node.js.
• Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie im Azure-Portal eine QnA Maker-Ressource, um Ihren Erstellungsschlüssel und die Ressource zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und Ressourcennamen aus der von Ihnen erstellten Ressource, um Ihre Anwendung mit der QnA Maker-API zu verbinden. Fügen Sie Ihren Schlüssel und Ressourcennamen weiter unten in der Schnellstartanleitung in den Code ein.
  • Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Erstellen einer neuen Node.js-Anwendung

Erstellen Sie in einem Konsolenfenster (etwa cmd, PowerShell oder Bash) ein neues Verzeichnis für Ihre App, und rufen Sie es auf.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Führen Sie den Befehl npm init -y aus, um eine Knotenanwendung mit der Datei package.json zu erstellen.

npm init -y

Installieren der Clientbibliothek

Installieren Sie die folgenden NPM-Pakete:

npm install @azure/cognitiveservices-qnamaker
npm install @azure/cognitiveservices-qnamaker-runtime
npm install @azure/ms-rest-js

Die Datei package.json Ihrer App wird mit den Abhängigkeiten aktualisiert.

Erstellen Sie eine Datei mit dem Namen „index.js“, öffnen Sie sie, und importieren Sie die folgenden Bibliotheken:

const msRest = require("@azure/ms-rest-js");
const qnamaker = require("@azure/cognitiveservices-qnamaker");
const qnamaker_runtime = require("@azure/cognitiveservices-qnamaker-runtime");

Erstellen Sie eine Variable für den Azure-Schlüssel Ihrer Ressource und den Ressourcennamen.

• Die Begriffe „Abonnementschlüssel“ und Erstellungsschlüssel“ werden synonym verwendet. Ausführlichere Informationen zum Erstellungsschlüssel finden Sie unter Schlüssel in QnA Maker.

• Der Wert von „QNA_MAKER_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Ressourcenverwaltung die Seite Schlüssel und Endpunkt aus, um den Schlüssel für die Dokumenterstellung (Abonnement) und den QnA Maker-Endpunkt zu suchen.

• Der Wert von „QNA_MAKER_RUNTIME_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.azurewebsites.net. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Automation die Seite Vorlage exportieren aus, um den Laufzeitendpunkt zu suchen.

const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Objektmodelle

Von QnA Maker werden zwei unterschiedliche Objektmodelle verwendet:

• QnAMakerClient ist das Objekt zum Erstellen, Verwalten, Veröffentlichen und Herunterladen der Wissensdatenbank.
• QnAMakerRuntime ist das Objekt, das für Abfragen der Wissensdatenbank mit der GenerateAnswer-API und zum Senden neuer vorgeschlagener Fragen mithilfe der Train-API (im Rahmen des aktiven Lernens) verwendet wird.

QnAMakerClient-Objektmodell

Der erstellende QnA Maker-Client ist ein QnAMakerClient-Objekt, das mithilfe Ihrer Anmeldeinformationen, in denen Ihr Schlüssel enthalten ist, bei Azure authentifiziert wird.

Verwenden Sie nach dem Erstellen des Clients die Wissensdatenbank, um Ihre Wissensdatenbank zu erstellen, zu verwalten und zu veröffentlichen.

Verwalten Sie Ihre Knowledge Base durch Senden eines JSON-Objekts. Bei sofortigen Vorgängen gibt eine Methode in der Regel ein JSON-Objekt zurück, das den Status angibt. Bei zeitintensiven Vorgängen ist die Antwort die Vorgangs-ID. Rufen Sie die client.Operations.getDetails-Methode mit der Vorgangs-ID auf, um den Status der Anforderung zu bestimmen.

QnAMakerRuntimeClient-Objektmodell

Der QnA Maker-Vorhersageclient ist ein QnAMakerRuntimeClient-Objekt, das sich bei Azure mithilfe von Microsoft.Rest.ServiceClientCredentials authentifiziert, die Ihren Schlüssel für die Vorhersage-Runtime enthalten, der nach dem Veröffentlichen der Wissensdatenbank vom Aufruf client.EndpointKeys.getKeys des erstellenden Clients zurückgegeben wurde.

Codebeispiele

Mit den Codeausschnitten wird veranschaulicht, wie folgende Vorgänge mit der QnA Maker-Clientbibliothek für .NET durchgeführt werden:

• Authentifizieren des Erstellungsclients
• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Herunterladen einer Knowledge Base
• Veröffentlichen einer Wissensdatenbank
• Löschen einer Wissensdatenbank
• Abrufen des Abfrage-Runtimeschlüssels
• Abrufen des Status eines Vorgangs
• Authentifizieren des Abfrage-Runtimeclients
• Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Authentifizieren des Clients zum Erstellen der Wissensdatenbank

Instanziieren Sie einen Client mit Ihrem Endpunkt und Schlüssel. Erstellen Sie ein ServiceClientCredentials-Objekt mit Ihrem Schlüssel, und verwenden Sie es mit Ihrem Endpunkt, um ein QnAMakerClient-Objekt zu erstellen.

const creds = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': subscription_key } });
const qnaMakerClient = new qnamaker.QnAMakerClient(creds, endpoint);
const knowledgeBaseClient = new qnamaker.Knowledgebase(qnaMakerClient);

Erstellen einer Wissensdatenbank

Eine Wissensdatenbank speichert Frage- und Antwortpaare für das CreateKbDTO-Objekt aus drei Quellen:

• Für redaktionellen Inhalt verwenden Sie das QnADTO-Objekt.
  • Verwenden Sie für Metadaten und Folgeaufforderungen den redaktionellen Kontext, da diese Daten auf der Ebene der einzelnen QnA-Paare hinzugefügt werden.
• Für Dateien verwenden Sie das FileDTO-Objekt. Das FileDTO-Objekt enthält den Dateinamen sowie die öffentliche URL für den Zugriff auf die Datei.
• Verwenden Sie für URLseine Liste von Zeichenfolgen zur Darstellung von öffentlich verfügbaren URLs.

Der Erstellungsschritt umfasst auch Eigenschaften für die Wissensdatenbank mit Folgendem:

• defaultAnswerUsedForExtraction: die Rückgabe, wenn keine Antwort gefunden wird
• enableHierarchicalExtraction: automatisches Erstellen von Aufforderungsbeziehungen zwischen extrahierten QnA-Paaren
• language: bei der Erstellung der ersten Wissensdatenbank für eine Ressource Festlegen der Sprache, die im Azure-Suchindex verwendet werden soll

Rufen Sie die create-Methode mit den Informationen der Wissensdatenbank auf. Bei den Informationen der Wissensdatenbank handelt es sich im Grunde um ein JSON-Objekt.

Übergeben Sie bei Rückgabe der create-Methode die zurückgegebene Vorgangs-ID an die wait_for_operation-Methode, um den Status abzurufen. Die Rückgabe der Methode „wait_for_operation“ erfolgt bei Abschluss des Vorgangs. Analysieren Sie den resourceLocation-Headerwert des zurückgegebenen Vorgangs, um die neue Wissensdatenbank-ID abzurufen.

const createKnowledgeBase = async (qnaClient, kbclient) => {

    console.log(`Creating knowledge base...`)

    const qna1 = {
        answer: "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "REST" }
        ]
    };

    const qna2 = {
        answer: "Yes, You can use our JS SDK on NPM for [authoring](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker), [query runtime](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker-runtime), and [the reference docs](https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-qnamaker/?view=azure-node-latest) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "JavaScript" }
        ]
    };

    const create_kb_payload = {
        name: 'QnA Maker JavaScript SDK Quickstart',
        qnaList: [
            qna1,
            qna2
        ],
        urls: [],
        files: [
            /*{
                fileName: "myfile.md",
                fileUri: "https://mydomain/myfile.md"
            }*/
        ],
        defaultAnswerUsedForExtraction: "No answer found.",
        enableHierarchicalExtraction: true,
        language: "English"
    };

    const results = await kbclient.create(create_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Create request failed - HTTP status ${results._response.status}`)
        return
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (!operationResult || !operationResult.operationState || !(operationResult.operationState = "Succeeded") || !operationResult.resourceLocation) {
        console.log(`Create operation state failed - HTTP status ${operationResult._response.status}`)
        return
    }

    // parse resourceLocation for KB ID
    const kbID = operationResult.resourceLocation.replace("/knowledgebases/", "");

    return kbID;
}

Zum erfolgreichen Erstellen einer Wissensdatenbank muss die Funktion wait_for_operation eingeschlossen werden, auf die im obigen Code verwiesen wird.

Aktualisieren einer Wissensdatenbank

Sie können eine Wissensdatenbank aktualisieren, indem Sie die Wissensdatenbank-ID und ein UpdateKbOperationDTO-Element, das add-, update- und delete-DTO-Objekte enthält, als Eingabe an die update-Methode übergeben. Die DTOs sind im Grunde ebenfalls JSON-Objekte. Verwenden Sie die wait_for_operation-Methode, um zu bestimmen, ob das Update erfolgreich war.

const updateKnowledgeBase = async (qnaClient, kbclient, kb_id) => {

    console.log(`Updating knowledge base...`)

    const urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]

    const qna3 = {
        answer: "goodbye",
        questions: [
            "bye",
            "end",
            "stop",
            "quit",
            "done"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "end" }
        ]
    };

    const qna4 = {
        answer: "Hello, please select from the list of questions or enter a new question to continue.",
        questions: [
            "hello",
            "hi",
            "start"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "begin" }
        ],
        context: {
            isContextOnly: false,
            prompts: [
                {
                    displayOrder: 1,
                    displayText: "Use REST",
                    qna: null,
                    qnaId: 1
                },
                {
                    displayOrder: 2,
                    displayText: "Use JS NPM package",
                    qna: null,
                    qnaId: 2
                },
            ]
        }
    };

    console.log(JSON.stringify(qna4))

    // Add new Q&A lists, URLs, and files to the KB.
    const kb_add_payload = {
        qnaList: [
            qna3,
            qna4
        ],
        urls: urls,
        files: []
    };

    // Bundle the add, update, and delete requests.
    const update_kb_payload = {
        add: kb_add_payload,
        update: null,
        delete: null,
        defaultAnswerUsedForExtraction: "No answer found. Please rephrase your question."
    };

    console.log(JSON.stringify(update_kb_payload))

    const results = await kbclient.update(kb_id, update_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Update request failed - HTTP status ${results._response.status}`)
        return false
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (operationResult.operationState != "Succeeded") {
        console.log(`Update operation state failed - HTTP status ${operationResult._response.status}`)
        return false
    }

    console.log(`Update operation state ${operationResult._response.status} - HTTP status ${operationResult._response.status}`)
    return true
}

Nehmen Sie zum erfolgreichen Aktualisieren einer Wissensdatenbank unbedingt die Funktion wait_for_operation mit auf, auf die im Code oben verwiesen wird.

Herunterladen einer Knowledge Base

Verwenden Sie die download-Methode, um die Datenbank als Liste von QnADocumentsDTO herunterzuladen. Dies entspricht nicht dem Export des QnA Maker-Portals von der Seite Einstellungen, da das Ergebnis dieser Methode keine TSV-Datei ist.

const downloadKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Downloading knowledge base...`)

    var kbData = await KBclient.download(kb_id, "Prod");
    console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);

    // Do something meaningful with data
}

Veröffentlichen einer Wissensdatenbank

Veröffentlichen Sie die Wissensdatenbank mit der publish-Methode. Diese übernimmt das aktuell gespeicherte und trainierte Modell, auf das von der Knowledge Base-ID verwiesen wird, und veröffentlicht dieses an einem Endpunkt. Überprüfen Sie den HTTP-Antwortcode, um sich zu vergewissern, dass die Veröffentlichung erfolgreich war.

const publishKnowledgeBase = async (kbclient, kb_id) => {

    console.log(`Publishing knowledge base...`)

    const results = await kbclient.publish(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Publish request failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Publish request succeeded - HTTP status ${results._response.status}`)

    return true
}

Abfragen einer Knowledge Base

Abrufen des Abfrage-Runtimeschlüssels

Nach dem Veröffentlichen einer Wissensdatenbank benötigen Sie den Abfrage-Runtimeschlüssel, um die Runtime abzufragen. Dabei handelt es sich nicht um den Schlüssel, der zum Erstellen des ursprünglichen Clientobjekts verwendet wurde.

Verwenden Sie die Methode EndpointKeys.getKeys, um die Klasse EndpointKeysDTO abzurufen.

Verwenden Sie eine der im Objekt zurückgegeben Schlüsseleigenschaften, um die Wissensdatenbank abzufragen.

const getEndpointKeys = async (qnaClient) => {

    console.log(`Getting runtime endpoint keys...`)

    const runtimeKeysClient = await qnaClient.endpointKeys;
    const results = await runtimeKeysClient.getKeys()

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`GetEndpointKeys request failed - HTTP status ${results._response.status}`)
        return null
    }

    console.log(`GetEndpointKeys request succeeded - HTTP status ${results._response.status} - primary key ${results.primaryEndpointKey}`)

    return results.primaryEndpointKey
}

Authentifizieren der Runtime zum Erstellen einer Antwort

Erstellen Sie ein QnAMakerRuntimeClient-Element, um die Wissensdatenbank abzufragen und eine Antwort zu generieren oder mit aktivem Lernen zu trainieren.

const queryRuntimeCredentials = new msRest.ApiKeyCredentials({ inHeader: { 'Authorization': 'EndpointKey ' + primaryQueryRuntimeKey } });
const runtimeClient = new qnamaker_runtime.QnAMakerRuntimeClient(queryRuntimeCredentials, runtime_endpoint);

Verwenden Sie den QnAMakerRuntimeClient, um eine Antwort aus der Wissensdatenbank abzurufen oder ihr neue Fragenvorschläge für aktives Lernen zu senden.

Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Generieren Sie mithilfe der Methode „RuntimeClient.runtime.generateAnswer“ eine Antwort aus einer veröffentlichten Wissensdatenbank. Diese Methode akzeptiert die Wissensdatenbank-ID und die QueryDTO-Klasse. Greifen Sie auf weitere QueryDTO-Eigenschaften zu (etwa „Top“ und „Context“), und verwenden Sie sie in Ihrem Chatbot.

const generateAnswer = async (runtimeClient, runtimeKey, kb_id) => {

    console.log(`Querying knowledge base...`)

    const requestQuery = await runtimeClient.runtime.generateAnswer(
        kb_id,
        {
            question: "How do I manage my knowledgebase?",
            top: 1,
            strictFilters: [
                { name: "Category", value: "api" }
            ]
        }
    );
    console.log(JSON.stringify(requestQuery));

}

Dies ist ein einfaches Beispiel zum Abfragen der Wissensdatenbank. Informationen zu erweiterten Abfrageszenarien finden Sie in weiteren Abfragebeispielen.

Löschen einer Wissensdatenbank

Löschen Sie die Wissensdatenbank mit der delete-Methode mit einem Parameter der Wissensdatenbank-ID.

const deleteKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Deleting knowledge base...`)

    const results = await KBclient.deleteMethod(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Delete operation state failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Delete operation state succeeded - HTTP status ${results._response.status}`)
    return true
}

Abrufen des Status eines Vorgangs

Einige Methoden, wie „create“ und „update“, können so viel Zeit in Anspruch nehmen, dass ein Vorgang zurückgegeben wird, anstatt auf den Abschluss des Prozesses zu warten. Verwenden Sie die Vorgangs-ID des Vorgangs, um den Status der ursprünglichen Methode mittels Abrufen (mit Wiederholungslogik) zu bestimmen.

Der delayTimer-Aufruf im folgenden Codeblock wird verwendet, um die Wiederholungslogik zu simulieren. Ersetzen Sie ihn durch Ihre eigene Wiederholungslogik.

const wait_for_operation = async (qnaClient, operation_id) => {

    let state = "NotStarted"
    let operationResult = undefined

    while ("Running" === state || "NotStarted" === state) {

        operationResult = await qnaClient.operations.getDetails(operation_id)
        state = operationResult.operationState;

        console.log(`Operation state - ${state}`)

        await delayTimer(1000);
    }

    return operationResult;
}
const delayTimer = async (timeInMs) => {
    return await new Promise((resolve) => {
        setTimeout(resolve, timeInMs);
    });
}

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Befehl node index.js über das Anwendungsverzeichnis aus.

node index.js

Den Quellcode für dieses Beispiel finden Sie auf GitHub.

Verwenden Sie die QnA Maker-Clientbibliothek für Python für folgende Zwecke:

• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Veröffentlichen einer Wissensdatenbank
• Abrufen von Endpunktschlüsseln der Vorhersage-Runtime
• Warten auf Aufgaben mit langer Ausführungsdauer
• Herunterladen einer Wissensdatenbank
• Abrufen einer Antwort aus einer Wissensdatenbank
• Löschen einer Wissensdatenbank

Referenzdokumentation | Quellcode der Bibliothek | Paket (PyPi) | Python-Beispiele

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• Python 3.x
• Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie im Azure-Portal eine QnA Maker-Ressource, um Ihren Erstellungsschlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der QnA Maker-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt.
  • Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Installieren der Clientbibliothek

Nach der Installation von Python, können Sie die Clientbibliothek mit Folgendem installieren:

pip install azure-cognitiveservices-knowledge-qnamaker==0.2.0

Erstellen einer neuen Python-Anwendung

Erstellen Sie eine neue Python-Datei mit dem Namen quickstart-file.py, und importieren Sie die folgenden Bibliotheken:

import os
import time

from azure.cognitiveservices.knowledge.qnamaker.authoring import QnAMakerClient
from azure.cognitiveservices.knowledge.qnamaker.runtime import QnAMakerRuntimeClient
from azure.cognitiveservices.knowledge.qnamaker.authoring.models import QnADTO, MetadataDTO, CreateKbDTO, OperationStateType, UpdateKbOperationDTO, UpdateKbOperationDTOAdd, EndpointKeysDTO, QnADTOContext, PromptDTO
from azure.cognitiveservices.knowledge.qnamaker.runtime.models import QueryDTO
from msrest.authentication import CognitiveServicesCredentials

Erstellen Sie Variablen für den Azure-Endpunkt und -Schlüssel Ihrer Ressource.

• Die Begriffe „Abonnementschlüssel“ und Erstellungsschlüssel“ werden synonym verwendet. Ausführlichere Informationen zum Erstellungsschlüssel finden Sie unter Schlüssel in QnA Maker.

• Der Wert von „QNA_MAKER_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Ressourcenverwaltung die Seite Schlüssel und Endpunkt aus, um den Schlüssel für die Dokumenterstellung (Abonnement) und den QnA Maker-Endpunkt zu suchen.

• Der Wert von „QNA_MAKER_RUNTIME_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.azurewebsites.net. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Automation die Seite Vorlage exportieren aus, um den Laufzeitendpunkt zu suchen.

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'

authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'

runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

Objektmodelle

Von QnA Maker werden zwei unterschiedliche Objektmodelle verwendet:

• QnAMakerClient ist das Objekt zum Erstellen, Verwalten, Veröffentlichen und Herunterladen der Wissensdatenbank.
• QnAMakerRuntime ist das Objekt, das für Abfragen der Wissensdatenbank mit der GenerateAnswer-API und zum Senden neuer vorgeschlagener Fragen mithilfe der Train-API (im Rahmen des aktiven Lernens) verwendet wird.

Verwenden dieser Beispiel-Wissensdatenbank

Die Wissensdatenbank in diesem Schnellstart beginnt mit zwei QnA-Unterhaltungspaaren. Dies wurde absichtlich so implementiert, um das Beispiel zu vereinfachen und hochgradig vorhersagbare IDs für die Update-Methode zu erhalten, die Folgeaufforderungen mit Fragen zu neuen Paaren verknüpft. Dies wurde für diese Schnellstartanleitung in einer bestimmten Reihenfolge geplant und implementiert.

Wenn Sie beabsichtigen, Ihre Wissensdatenbank im Lauf der Zeit mit Folgeaufforderungen zu entwickeln, die von vorhandenen QnA-Paaren abhängen, bieten sich Ihnen die folgenden Möglichkeiten:

• Bei größeren Wissensdatenbanken Verwaltung der Wissensdatenbank in einem Text-Editor oder einem TSV-Tool, das Automatisierung unterstützt. Die Wissensdatenbank wird dann in einem Durchgang vollständig durch ein Update ersetzt.
• Bei kleineren Wissensdatenbanken ausschließliches Verwalten der Nachfolgeaufforderungen im QnA Maker-Portal.

Details zu den QnA-Paaren, die in dieser Schnellstartanleitung verwendet werden:

• Typen von QnA-Paaren: Nach dem Update gibt es zwei Typen von QnA-Paaren in dieser Wissensdatenbank: Geplauder und domänenspezifische Informationen. Dies ist typisch, wenn Ihre Wissensdatenbank an eine Unterhaltungsanwendung gebunden ist, wie etwa einen Chatbot.
• Die Antworten aus Ihrer Wissensdatenbank lassen sich zwar anhand von Metadaten oder Folgeaufforderungen filtern, dies wird in dieser Schnellstartanleitung aber nicht gezeigt. Suchen Sie hier nach diesen sprachunabhängigen generateAnswer-Beispielen.
• Der Antworttext ist Markdown und kann eine große Bandbreite von Markdown enthalten, z. B. Bilder (öffentlich verfügbare, internetbasierte Bilder), Links (zu öffentlich verfügbaren URLs) und Aufzählungspunkte. Diese Unterart spielt in diesem Schnellstart keine Rolle.

QnAMakerClient-Objektmodell

Der erstellende QnA Maker-Client ist ein QnAMakerClient-Objekt, das mithilfe der „Microsoft.Rest.ServiceClientCredentials“-Klasse, die Ihren Schlüssel enthält, bei Azure authentifiziert wird.

Nachdem der Client erstellt wurde, verwenden Sie die Knowledge Base-Eigenschaft, um Ihre Knowledge Base zu erstellen, zu verwalten und zu veröffentlichen.

Verwalten Sie Ihre Knowledge Base durch Senden eines JSON-Objekts. Bei sofortigen Vorgängen gibt eine Methode in der Regel ein JSON-Objekt zurück, das den Status angibt. Bei zeitintensiven Vorgängen ist die Antwort die Vorgangs-ID. Rufen Sie die operations.get_details-Methode mit der Vorgangs-ID auf, um den Status der Anforderung zu bestimmen.

QnAMakerRuntimeClient-Objektmodell

Der QnA Maker-Vorhersageclient ist ein QnAMakerRuntimeClient-Objekt, das sich bei Azure mithilfe von Microsoft.Rest.ServiceClientCredentials authentifiziert, die Ihren Schlüssel für die Vorhersage-Runtime enthalten, der nach dem Veröffentlichen der Wissensdatenbank vom Aufruf client.EndpointKeysOperations.get_keys des erstellenden Clients zurückgegeben wurde.

Mithilfe der Methode generate_answer können Sie eine Antwort aus der Abfragelaufzeit abrufen.

Authentifizieren des Clients zum Erstellen der Wissensdatenbank

Instanziieren Sie einen Client mit Ihrem Endpunkt und Schlüssel. Erstellen Sie ein CognitiveServicesCredentials-Objekt mit Ihrem Schlüssel, und verwenden Sie es mit Ihrem Endpunkt, um ein QnAMakerClient-Objekt zu erstellen.

client = QnAMakerClient(endpoint=authoring_endpoint, credentials=CognitiveServicesCredentials(subscription_key))

Erstellen einer Wissensdatenbank

Verwenden Sie das Clientobjekt, um ein Objekt vom Typ KnowledgebaseOperations abzurufen.

Eine Wissensdatenbank speichert Frage- und Antwortpaare für das CreateKbDTO-Objekt aus drei Quellen:

• Für redaktionellen Inhalt verwenden Sie das QnADTO-Objekt.
  • Verwenden Sie für Metadaten und Folgeaufforderungen den redaktionellen Kontext, da diese Daten auf der Ebene der einzelnen QnA-Paare hinzugefügt werden.
• Für Dateien verwenden Sie das FileDTO-Objekt. Das FileDTO-Objekt enthält den Dateinamen sowie die öffentliche URL für den Zugriff auf die Datei.
• Verwenden Sie für URLs eine Liste von Zeichenfolgen zur Darstellung von öffentlich verfügbaren URLs.

Rufen Sie die create-Methode auf, und übergeben Sie dann die zurückgegebene Vorgangs-ID an die Operations.getDetails-Methode, um den Status abzurufen.

In der letzten Zeile des folgenden Codes wird die Knowledge Base-ID aus der Antwort von „MonitorOperation“ zurückgegeben.

def create_kb(client):
    print ("Creating knowledge base...")

    qna1 = QnADTO(
        answer="Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions=["How do I manage my knowledgebase?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="REST"),
        ]
    )

    qna2 = QnADTO(
        answer="Yes, You can use our [Python SDK](https://pypi.org/project/azure-cognitiveservices-knowledge-qnamaker/) with the [Python Reference Docs](https://docs.microsoft.com/python/api/azure-cognitiveservices-knowledge-qnamaker/azure.cognitiveservices.knowledge.qnamaker?view=azure-python) to manage your knowledge base.",
        questions=["Can I program with Python?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="Python"),
        ]
    )

    urls = []
    files = [
        FileDTO(
            file_name = "structured.docx",
            file_uri = "https://github.com/Azure-Samples/cognitive-services-sample-data-files/raw/master/qna-maker/data-source-formats/structured.docx"
        )]

    create_kb_dto = CreateKbDTO(
        name="QnA Maker Python SDK Quickstart",
        qna_list=[
            qna1,
            qna2
        ],
        urls=urls,
        files=[],
        enable_hierarchical_extraction=True,
        default_answer_used_for_extraction="No answer found.",
        language="English"
    )
    create_op = client.knowledgebase.create(create_kb_payload=create_kb_dto)

    create_op_monitor = _monitor_operation(client=client, operation=create_op)

    # Get knowledge base ID from resourceLocation HTTP header
    knowledge_base_ID = create_op_monitor.resource_location.replace("/knowledgebases/", "")
    print("Created KB with ID: {}".format(knowledge_base_ID))

    return knowledge_base_ID

Nehmen Sie zum erfolgreichen Erstellen einer Wissensdatenbank unbedingt die Funktion _monitor_operation mit auf, auf die im Code oben verwiesen wird.

Aktualisieren einer Wissensdatenbank

Sie können eine Wissensdatenbank aktualisieren, indem Sie die Wissensdatenbank-ID und ein UpdateKbOperationDTO-Element, das add-, update- und delete-DTO-Objekte enthält, als Eingabe an die update-Methode übergeben. Verwenden Sie die Operation.getDetail -Methode, um zu bestimmen, ob das Update erfolgreich war.

def update_kb(client, kb_id):
    print ("Updating knowledge base...")

    qna3 = QnADTO(
        answer="goodbye",
        questions=[
            "bye",
            "end",
            "stop",
            "quit",
            "done"
            ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="end"),
        ]
    )

    qna4 = QnADTO(
        answer="Hello, please select from the list of questions or enter a new question to continue.",
        questions=[
            "hello",
            "hi",
            "start"
        ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="begin"),
        ],
        context = QnADTOContext(

            is_context_only = False,
            prompts = [

                PromptDTO(
                    display_order =1,
                    display_text= "Use REST",
                    qna_id=1

                ),
                PromptDTO(
                    display_order =2,
                    display_text= "Use .NET NuGet package",
                    qna_id=2
                ),
            ]
        )

    )

    urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]



    update_kb_operation_dto = UpdateKbOperationDTO(
        add=UpdateKbOperationDTOAdd(
            qna_list=[
                qna3,
                qna4
            ],
            urls = urls,
            files=[]
        ),
        delete=None,
        update=None
    )
    update_op = client.knowledgebase.update(kb_id=kb_id, update_kb=update_kb_operation_dto)
    _monitor_operation(client=client, operation=update_op)
    print("Updated knowledge base.")

Nehmen Sie zum erfolgreichen Aktualisieren einer Wissensdatenbank unbedingt die Funktion _monitor_operation mit auf, auf die im Code oben verwiesen wird.

Herunterladen einer Knowledge Base

Verwenden Sie die download-Methode, um die Datenbank als Liste von QnADocumentsDTO herunterzuladen. Dies entspricht nicht dem Export des QnA Maker-Portals von der Seite Einstellungen, da das Ergebnis dieser Methode keine TSV-Datei ist.

def download_kb(client, kb_id):
    print("Downloading knowledge base...")
    kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
    print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))

Veröffentlichen einer Wissensdatenbank

Veröffentlichen Sie die Wissensdatenbank mit der publish-Methode. Diese übernimmt das aktuell gespeicherte und trainierte Modell, auf das von der Knowledge Base-ID verwiesen wird, und veröffentlicht dieses an einem Endpunkt.

def publish_kb(client, kb_id):
    print("Publishing knowledge base...")
    client.knowledgebase.publish(kb_id=kb_id)
    print("Published knowledge base.")

Abfragen einer Knowledge Base

Abrufen des Abfrage-Runtimeschlüssels

Nach dem Veröffentlichen einer Wissensdatenbank benötigen Sie den Abfrage-Runtimeschlüssel, um die Runtime abzufragen. Dabei handelt es sich nicht um den Schlüssel, der zum Erstellen des ursprünglichen Clientobjekts verwendet wurde.

Verwenden Sie die Methode EndpointKeysOperations.get_keys, um die Klasse EndpointKeysDTO abzurufen.

Verwenden Sie eine der im Objekt zurückgegeben Schlüsseleigenschaften, um die Wissensdatenbank abzufragen.

def getEndpointKeys_kb(client):
    print("Getting runtime endpoint keys...")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: {}.".format(keys.primary_endpoint_key))

    return keys.primary_endpoint_key

Authentifizieren der Runtime zum Erstellen einer Antwort

Erstellen Sie ein QnAMakerRuntimeClient-Element, um die Wissensdatenbank abzufragen und eine Antwort zu generieren oder mit aktivem Lernen zu trainieren.

runtimeClient = QnAMakerRuntimeClient(runtime_endpoint=runtime_endpoint, credentials=CognitiveServicesCredentials(queryRuntimeKey))

Verwenden Sie den QnAMakerRuntimeClient, um eine Antwort aus der Wissensdatenbank abzurufen oder ihr neue Fragenvorschläge für aktives Lernen zu senden.

Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Generieren Sie mithilfe der Methode „QnAMakerRuntimeClient.runtime.generate_answer“ eine Antwort auf der Grundlage einer veröffentlichten Wissensdatenbank. Diese Methode akzeptiert die Wissensdatenbank-ID und die QueryDTO-Klasse. Greifen Sie auf weitere QueryDTO-Eigenschaften zu (etwa „Top“ und „Context“), und verwenden Sie sie in Ihrem Chatbot.

def generate_answer(client, kb_id, runtimeKey):
    print ("Querying knowledge base...")

    authHeaderValue = "EndpointKey " + runtimeKey

    listSearchResults = client.runtime.generate_answer(kb_id, QueryDTO(question = "How do I manage my knowledgebase?"), dict(Authorization=authHeaderValue))

    for i in listSearchResults.answers:
        print(f"Answer ID: {i.id}.")
        print(f"Answer: {i.answer}.")
        print(f"Answer score: {i.score}.")

Dies ist ein einfaches Beispiel zum Abfragen der Wissensdatenbank. Informationen zu erweiterten Abfrageszenarien finden Sie in weiteren Abfragebeispielen.

Löschen einer Wissensdatenbank

Löschen Sie die Wissensdatenbank mit der delete-Methode mit einem Parameter der Wissensdatenbank-ID.

def delete_kb(client, kb_id):
    print("Deleting knowledge base...")
    client.knowledgebase.delete(kb_id=kb_id)
    print("Deleted knowledge base.")

Abrufen des Status eines Vorgangs

Einige Methoden, wie „create“ und „update“, können so viel Zeit in Anspruch nehmen, dass ein Vorgang zurückgegeben wird, anstatt auf den Abschluss des Prozesses zu warten. Verwenden Sie die Vorgangs-ID des Vorgangs, um den Status der ursprünglichen Methode per Abruf (mit Wiederholungslogik) zu bestimmen.

Der setTimeout-Aufruf im folgenden Codeblock wird verwendet, um asynchronen Code zu simulieren. Ersetzen Sie dies durch Wiederholungslogik.

def _monitor_operation(client, operation):

    for i in range(20):
        if operation.operation_state in [OperationStateType.not_started, OperationStateType.running]:
            print("Waiting for operation: {} to complete.".format(operation.operation_id))
            time.sleep(5)
            operation = client.operations.get_details(operation_id=operation.operation_id)
        else:
            break
    if operation.operation_state != OperationStateType.succeeded:
        raise Exception("Operation {} failed to complete.".format(operation.operation_id))

    return operation

Ausführen der Anwendung

Führen Sie die Anwendung mit dem Python-Befehl für die Schnellstartdatei aus.

python quickstart-file.py

Den Quellcode für dieses Beispiel finden Sie auf GitHub.

Verwenden Sie die QnA Maker-Clientbibliothek für Java für Folgendes:

• Erstellen einer Wissensdatenbank
• Aktualisieren einer Wissensdatenbank
• Veröffentlichen einer Wissensdatenbank
• Abrufen von Endpunktschlüsseln der Vorhersage-Runtime
• Warten auf Aufgaben mit langer Ausführungsdauer
• Herunterladen einer Wissensdatenbank
• Abrufen einer Antwort aus einer Wissensdatenbank
• Löschen einer Wissensdatenbank

Quellcode der Bibliothek | Paket | Beispiele

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos
• JDK
• Sobald Sie über Ihr Azure-Abonnement verfügen, erstellen Sie im Azure-Portal eine QnA Maker-Ressource, um Ihren Erstellungsschlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der QnA Maker-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt.
  • Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.

Einrichten

Installieren der Clientbibliotheken

Nach der Installation von Java können Sie die Clientbibliotheken mithilfe von Maven aus dem MVN-Repository installieren.

Erstellen einer neuen Java-Anwendung

Erstellen Sie eine neue Datei namens quickstart.java, und importieren Sie die folgenden Bibliotheken:

/* Download the following files.
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.pom
 * Move the downloaded .jar file to a folder named "lib" directly under the current folder.
 * Rename the downloaded file to pom.xml.
 * At the command line, run
 * mvn dependency:copy-dependencies
 * This will download the .jar files depended on by azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar to the folder "target/dependency" under the current folder. Move these .jar files to the "lib" folder as well.
 */
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.*;
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.models.*;

import java.io.*;
import java.lang.Object.*;
import java.time.format.DateTimeFormatter;  
import java.time.LocalDateTime; 
import java.util.*;
import java.net.*;

Erstellen Sie Variablen für den Azure-Endpunkt und -Schlüssel Ihrer Ressource.

• Die Begriffe „Abonnementschlüssel“ und Erstellungsschlüssel“ werden synonym verwendet. Ausführlichere Informationen zum Erstellungsschlüssel finden Sie unter Schlüssel in QnA Maker.

• Der Wert von „QNA_MAKER_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Ressourcenverwaltung die Seite Schlüssel und Endpunkt aus, um den Schlüssel für die Dokumenterstellung (Abonnement) und den QnA Maker-Endpunkt zu suchen.

• Der Wert von „QNA_MAKER_RUNTIME_ENDPOINT“ hat das Format https://YOUR-RESOURCE-NAME.azurewebsites.net. Navigieren Sie zum Azure-Portal, und suchen Sie die unter „Voraussetzungen“ erstellte QnA Maker-Ressource. Wählen Sie unter Automation die Seite Vorlage exportieren aus, um den Laufzeitendpunkt zu suchen.

private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Objektmodelle

QnA Maker verwendet zwei unterschiedliche Objektmodelle:

• QnAMakerClient ist das Objekt zum Erstellen, Verwalten, Veröffentlichen und Herunterladen der Wissensdatenbank.
• QnAMakerRuntime ist das Objekt, das für Abfragen der Wissensdatenbank mit der GenerateAnswer-API und zum Senden neuer vorgeschlagener Fragen mithilfe der Train-API (im Rahmen des aktiven Lernens) verwendet wird.

Verwenden dieser Beispiel-Wissensdatenbank

Die Wissensdatenbank in diesem Schnellstart beginnt mit zwei QnA-Unterhaltungspaaren. Dies wurde absichtlich so implementiert, um das Beispiel zu vereinfachen und hochgradig vorhersagbare IDs für die Update-Methode zu erhalten, die Folgeaufforderungen mit Fragen zu neuen Paaren verknüpft. Dies wurde für diese Schnellstartanleitung in einer bestimmten Reihenfolge geplant und implementiert.

Wenn Sie beabsichtigen, Ihre Wissensdatenbank im Lauf der Zeit mit Folgeaufforderungen zu entwickeln, die von vorhandenen QnA-Paaren abhängen, bieten sich Ihnen die folgenden Möglichkeiten:

• Bei größeren Wissensdatenbanken Verwaltung der Wissensdatenbank in einem Text-Editor oder einem TSV-Tool, das Automatisierung unterstützt. Die Wissensdatenbank wird dann in einem Durchgang vollständig durch ein Update ersetzt.
• Bei kleineren Wissensdatenbanken ausschließliches Verwalten der Nachfolgeaufforderungen im QnA Maker-Portal.

Details zu den QnA-Paaren, die in dieser Schnellstartanleitung verwendet werden:

• Typen von QnA-Paaren: Nach dem Update gibt es zwei Typen von QnA-Paaren in dieser Wissensdatenbank: Geplauder und domänenspezifische Informationen. Dies ist typisch, wenn Ihre Wissensdatenbank an eine Unterhaltungsanwendung gebunden ist, wie etwa einen Chatbot.
• Die Antworten aus Ihrer Wissensdatenbank lassen sich zwar anhand von Metadaten oder Folgeaufforderungen filtern, dies wird in dieser Schnellstartanleitung aber nicht gezeigt. Suchen Sie hier nach diesen sprachunabhängigen generateAnswer-Beispielen.
• Der Antworttext ist Markdown und kann eine große Bandbreite von Markdown enthalten, z. B. Bilder (öffentlich verfügbare, internetbasierte Bilder), Links (zu öffentlich verfügbaren URLs) und Aufzählungspunkte. Diese Unterart spielt in diesem Schnellstart keine Rolle.

QnAMakerClient-Objektmodell

Der erstellende QnA Maker-Client ist ein QnAMakerClient-Objekt, das mithilfe der Klasse „MsRest::ServiceClientCredentials“, die Ihren Schlüssel enthält, bei Azure authentifiziert wird.

Nachdem der Client erstellt wurde, verwenden Sie die Methoden der Knowledgebases-Eigenschaft des Clients, um Ihre Wissensdatenbank zu erstellen, zu verwalten und zu veröffentlichen.

Bei sofortigen Vorgängen gibt eine Methode in der Regel das Ergebnis zurück, falls vorhanden. Bei zeitintensiven Vorgängen ist die Antwort ein Objekt vom Typ Operation. Rufen Sie die getDetails-Methode mit dem Wert operation.operationId auf, um den Status der Anforderung zu bestimmen.

QnAMakerRuntimeClient-Objektmodell

Der QnA Maker-Runtimeclient ist ein QnAMakerRuntimeClient-Objekt.

Verwenden Sie nach dem Veröffentlichen der Wissensdatenbank mithilfe des Erstellungsclients die Methode generateAnswer des Runtimeclients, um eine Antwort aus der Wissensdatenbank abzurufen.

Sie erstellen einen Runtimeclient durch Aufrufen von QnAMakerRuntimeManager.authenticate und Übergeben eines Runtimeendpunktschlüssels. Verwenden Sie zum Abrufen des Runtimeendpunktschlüssels den Erstellungsclient, um getKeys aufzurufen.

Authentifizieren des Clients zum Erstellen der Wissensdatenbank

Instanziieren Sie einen Client mit dem Erstellungsendpunkt und dem Abonnementschlüssel.

/* Note QnAMakerManager.authenticate() does not set the baseUrl paramater value
 * as the value for QnAMakerClient.endpoint, so we still need to call withEndpoint().
 */
QnAMakerClient authoring_client = QnAMakerManager.authenticate(authoring_key).withEndpoint(authoring_endpoint);
Knowledgebases kb_client = authoring_client.knowledgebases();
Operations ops_client = authoring_client.operations();
EndpointKeys keys_client = authoring_client.endpointKeys();

Erstellen einer Wissensdatenbank

Eine Wissensdatenbank speichert Frage- und Antwortpaare für das CreateKbDTO-Objekt aus drei Quellen:

• Für redaktionellen Inhalt verwenden Sie das QnADTO-Objekt.
  • Verwenden Sie für Metadaten und Folgeaufforderungen den redaktionellen Kontext, da diese Daten auf der Ebene der einzelnen QnA-Paare hinzugefügt werden.
• Für Dateien verwenden Sie das FileDTO-Objekt. Das FileDTO-Objekt enthält den Dateinamen sowie die öffentliche URL für den Zugriff auf die Datei.
• Verwenden Sie für URLs eine Liste von Zeichenfolgen zur Darstellung von öffentlich verfügbaren URLs.

Rufen Sie die create-Methode auf, und übergeben Sie dann die Eigenschaft operationIddes zurückgegebenen Vorgangs an die getDetails-Methode, um den Status abzurufen.

In der letzten Zeile des folgenden Codes wird die Wissensdatenbank-ID zurückgegeben:

public String create_kb () throws Exception {
    System.out.println("Creating KB...");

    String name = "QnA Maker FAQ from quickstart";

    var metadata = new MetadataDTO()
        .withName ("Category")
        .withValue ("api");

    List<MetadataDTO> metadata_list = Arrays.asList(new MetadataDTO[]{ metadata });

    var qna = new QnADTO()
        .withAnswer ("You can use our REST APIs to manage your knowledge base.")
        .withQuestions ( Arrays.asList(new String[]{ "How do I manage my knowledgebase?" }))
        .withMetadata (metadata_list);

    List<QnADTO> qna_list = Arrays.asList(new QnADTO[]{ qna });

    var urls = Arrays.asList(new String[]{ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs" });

    var payload = new CreateKbDTO().withName(name).withQnaList(qna_list).withUrls(urls);

    var result = kb_client.create(payload);
    var kb_id = wait_for_operation(result);

    System.out.println("Created KB with ID: " + kb_id + ".\n");
    return kb_id;
}

Aktualisieren einer Wissensdatenbank

Sie können eine Wissensdatenbank aktualisieren, indem Sie update aufrufen und die Wissensdatenbank-ID sowie ein UpdateKbOperationDTO-Objekt übergeben. Dieses Objekt kann wiederum Folgendes enthalten:

• add
• update
• delete

Übergeben Sie die Eigenschaft operationId des zurückgegebenen Vorgangs an die getDetails-Methode, um den Status abzurufen.

public void update_kb (String kb_id) throws Exception {
    System.out.println("Updating KB...");

    var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");

    var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);

    var result = kb_client.update(kb_id, payload);
    wait_for_operation(result);

    System.out.println("Updated KB.");
}

Herunterladen einer Knowledge Base

Verwenden Sie die download-Methode, um die Datenbank als Liste von QnADocumentsDTO herunterzuladen. Dies entspricht nicht dem Export des QnA Maker-Portals von der Seite Einstellungen, da das Ergebnis dieser Methode keine TSV-Datei ist.

public void download_kb(String kb_id) {
    System.out.println("Downloading KB...");

    var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
    System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");

    System.out.println("Downloaded KB.\n");
}

Veröffentlichen einer Wissensdatenbank

Veröffentlichen Sie die Wissensdatenbank mit der publish-Methode. Diese übernimmt das aktuell gespeicherte und trainierte Modell, auf das von der Knowledge Base-ID verwiesen wird, und veröffentlicht dieses an einem Endpunkt.

public void publish_kb(String kb_id) {
    System.out.println("Publishing KB...");
    kb_client.publish(kb_id);
    System.out.println("KB published.\n");
}

Generieren einer Antwort auf der Grundlage der Wissensdatenbank

Nach dem Veröffentlichen einer Wissensdatenbank benötigen Sie den Runtimeendpunktschlüssel, um die Wissensdatenbank abzufragen. Dieser ist nicht mit dem Abonnementschlüssel identisch, der zum Erstellen des Erstellungsclients verwendet wurde.

Verwenden Sie die Methode getKeys, um das Objekt EndpointKeysDTO abzurufen.

Erstellen Sie einen Runtimeclient durch Aufrufen von QnAMakerRuntimeManager.authenticate und Übergeben eines Runtimeendpunktschlüssels aus dem EndpointKeysDTO-Objekt.

Generieren Sie mithilfe der Methode generateAnswer eine Antwort aus einer veröffentlichten Wissensdatenbank. Diese Methode akzeptiert die Wissensdatenbank-ID und das QueryDTO-Objekt.

public void query_kb(String kb_id) {
    System.out.println("Sending query to KB...");
    
    var runtime_key = keys_client.getKeys().primaryEndpointKey();
    QnAMakerRuntimeClient runtime_client = QnAMakerRuntimeManager.authenticate(runtime_key).withRuntimeEndpoint(runtime_endpoint);
    var query = (new QueryDTO()).withQuestion("How do I manage my knowledgebase?");
    var result = runtime_client.runtimes().generateAnswer(kb_id, query);
    System.out.println("Answers:");
    for (var answer : result.answers()) {
        System.out.println(answer.answer().toString());
    };
    System.out.println();
}

Dies ist ein einfaches Beispiel zum Abfragen einer Wissensdatenbank. Informationen zu erweiterten Abfrageszenarien finden Sie in weiteren Abfragebeispielen.

Löschen einer Wissensdatenbank

Löschen Sie die Wissensdatenbank mit der delete-Methode mit einem Parameter der Wissensdatenbank-ID.

public void delete_kb(String kb_id) {
    System.out.println("Deleting KB...");
    kb_client.delete(kb_id);
    System.out.println("KB deleted.\n");
}

Abrufen des Status eines Vorgangs

Einige Methoden, wie „create“ und „update“, können so viel Zeit in Anspruch nehmen, dass ein Vorgang zurückgegeben wird, anstatt auf den Abschluss des Prozesses zu warten. Verwenden Sie die Vorgangs-ID des Vorgangs, um den Status der ursprünglichen Methode per Abruf (mit Wiederholungslogik) zu bestimmen.

public String wait_for_operation(Operation op) throws Exception {
    System.out.println ("Waiting for operation to finish...");
    Boolean waiting = true;
    String result = "";
    while (true == waiting) {
        var op_ = ops_client.getDetails(op.operationId());
        var state = op_.operationState();
        if (OperationStateType.FAILED == state) {
            throw new Exception("Operation failed.");
        }
        if (OperationStateType.SUCCEEDED == state) {
            waiting = false;
            // Remove "/knowledgebases/" from the resource location.
            result = op_.resourceLocation().replace("/knowledgebases/", "");
        }
        if (true == waiting) {
            System.out.println("Waiting 10 seconds for operation to complete...");
            Thread.sleep(10000);
        }
    }
    return result;
}

Ausführen der Anwendung

Hier sehen Sie die Main-Methode für die Anwendung:

    public static void main(String[] args) {
        try {
            Quickstart quickstart = new Quickstart();
            String kb_id = quickstart.create_kb();
//			quickstart.list_kbs();
            quickstart.update_kb(kb_id);
            quickstart.publish_kb(kb_id);
            quickstart.download_kb(kb_id);
            quickstart.query_kb(kb_id);
            quickstart.delete_kb(kb_id);
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

Führen Sie die Anwendung wie folgt aus: Dies setzt voraus, dass der Klassenname Quickstart lautet und sich die Abhängigkeiten in einem Unterordner mit dem Namen lib unterhalb des aktuellen Ordners befinden.

javac Quickstart.java -cp .;lib\*
java -cp .;lib\* Quickstart

Den Quellcode für dieses Beispiel finden Sie auf GitHub.