Share via

Quickstart: QnA Maker-clientbibliotheek

  • Artikel

Aan de slag met de QnA Maker-clientbibliotheek. Volg deze stappen om het pakket te installeren en de voorbeeldcode voor basistaken uit te proberen.

Notitie

De QnA Maker-service wordt op 31 maart 2025 buiten gebruik gesteld. Een nieuwere versie van de vraag- en antwoordmogelijkheid is nu beschikbaar als onderdeel van Azure AI Language. Zie vraagantwoording voor vragen in de Language Service voor het beantwoorden van vragen. Vanaf 1 oktober 2022 kunt u geen nieuwe QnA Maker-resources maken. Raadpleeg de migratiehandleiding voor informatie over het migreren van bestaande QnA Maker-knowledge bases om vragen te beantwoorden.

Vereisten

Notitie

Deze documentatie is niet van toepassing op de nieuwste versie. Raadpleeg de snelstart voor het beantwoorden van de vraag over het beantwoorden van rest API's voor meer informatie over het gebruik van de REST API met de nieuwste versie

  • De huidige versie van cURL. In deze quickstarts worden verschillende opdrachtregelopties gebruikt, die worden vermeld in de cURL-documentatie.

  • U moet een QnA Maker-resource hebben om de sleutel en resourcenaam te gebruiken. U hebt de resourcenaam ingevoerd tijdens het maken van de resource, daarna is de sleutel voor u gemaakt. De resourcenaam is gebruikt als het subdomein voor uw eindpunt. Als u uw sleutel en resourcenaam wilt ophalen, selecteert u Quickstart voor uw resource in Azure Portal. De resourcenaam is het eerste subdomein van de eindpunt-URL:

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

Let op

In de volgende BASH-voorbeelden wordt het regelvoortzettingsteken \ gebruikt. Als in uw console of terminal een ander regelvoortzettingsteken wordt gebruikt, gebruikt u dit teken.

Een kennisdatabase maken

Als u een Knowledge Base wilt maken met de REST API's en cURL, hebt u de volgende informatie nodig:

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
QnA Maker-resourcesleutel Param -h voor de header Ocp-Apim-Subscription-Key Verifiëren bij QnA Maker-service
JSON met een beschrijving van de Knowledge Base Param -d Voorbeelden van JSON
Grootte van de JSON in bytes Param -h voor de header Content-Size

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam, resourcesleutel, JSON-waarden en JSON-grootte.

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://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'

De cURL-reactie van QnA Maker omvat de operationId, die vereist is om de status van de bewerking op te halen.

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

De status van de bewerking ophalen

Wanneer u een Knowledge Base maakt, omvat de reactie informatie om de status te bepalen, omdat de bewerking asynchroon is.

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
Bewerkings-id URL-route /operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker-resourcesleutel Param -h voor de header Ocp-Apim-Subscription-Key Verifiëren bij QnA Maker-service

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam, resourcesleutel en bewerkings-id.

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"

De cURL-reactie omvat de status. Als de bewerkingsstatus is geslaagd, dan bevat resourceLocation de Knowledge Base-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"
}

Knowledge base publiceren

Voordat u een query uitvoert op de Knowledge Base, moet u het volgende doen:

  • Knowledge base publiceren
  • De runtime-eindpuntsleutel ophalen

Met deze taak wordt de Knowledge Base gepubliceerd. De runtime-eindpuntsleutel ophalen is een afzonderlijke taak.

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
QnA Maker-resourcesleutel Param -h voor de header Ocp-Apim-Subscription-Key Verifiëren bij QnA Maker-service
Knowledge Base-id URL-route /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam, resourcesleutel en Knowledge Base-id.

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 ''

De antwoordstatus is 204 zonder resultaten. Gebruik de opdrachtregelparameter -v om de uitgebreide uitvoer van de cURL-opdracht te bekijken. Deze omvat ook de HTTP-status.

De runtime-eindpuntsleutel van de gepubliceerde Knowledge Base ophalen

Voordat u een query uitvoert op de Knowledge Base, moet u het volgende doen:

  • Knowledge base publiceren
  • De runtime-eindpuntsleutel ophalen

Met deze taak wordt de runtime-eindpuntsleutel opgehaald. Het publiceren van de Knowledge Base is een afzonderlijke taak.

De runtime-eindpuntsleutel is dezelfde sleutel voor alle Knowledge Base die gebruikmaken van de QnA Maker-resource.

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
QnA Maker-resourcesleutel Param -h voor de header Ocp-Apim-Subscription-Key Verifiëren bij QnA Maker-service

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam en resourcesleutel.

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"

De cURL-reactie omvat de runtime-eindpuntsleutels. Gebruik één van de sleutels wanneer u een query uitvoert om een antwoord van de Knowledge Base te krijgen.

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

Query uitvoeren voor een antwoord van de gepubliceerde Knowledge Base

Een antwoord krijgen van de Knowledge Base wordt vanuit een afzonderlijke runtime gedaan dan het beheer van de Knowledge Base. Omdat het een afzonderlijke runtime is, moet u verifiëren met een runtime-sleutel.

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
QnA Maker-runtimesleutel Param -h voor de header Authorization De sleutel maakt deel uit van een tekenreeks die het woord Endpointkey bevat. Verifiëren bij QnA Maker-service
Knowledge Base-id URL-route /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON die query beschrijft Param -d Parameters voor aanvraagbody en voorbeelden van JSON
Grootte van de JSON in bytes Param -h voor de header Content-Size

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam, resourcesleutel en Knowledge Base-id.

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="}'

Een geslaagde reactie omvat het beste antwoord samen met andere informatie die een clienttoepassing, zoals een chatbot, moet weergeven om de gebruiker te beantwoorden.

Een Knowledge Base verwijderen

Wanneer u klaar bent met de Knowledge Base, kunt u die verwijderen.

Gegevens cURL-configuratie Doel
QnA Maker-resourcenaam URL gebruikt voor het maken van een URL
QnA Maker-resourcesleutel Param -h voor de header Ocp-Apim-Subscription-Key Verifiëren bij QnA Maker-service
Knowledge Base-id URL-route /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

De cURL-opdracht wordt uitgevoerd vanuit een BASH-shell. Bewerk deze opdracht met uw eigen resourcenaam, resourcesleutel en Knowledge Base-id.

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"

De antwoordstatus is 204 zonder resultaten. Gebruik de opdrachtregelparameter -v om de uitgebreide uitvoer van de cURL-opdracht te bekijken. Deze omvat ook de HTTP-status.

Aanvullende bronnen

Gebruik de QnA Maker-clientbibliotheek voor .NET voor het volgende:

  • Een Knowledge Base maken
  • Een Knowledge Base bijwerken
  • Een Knowledge Base publiceren
  • Een eindpuntsleutel voor de voorspellingsruntime ophalen
  • Wachten op een langlopende taak
  • Een Knowledge Base downloaden
  • Antwoord krijgen in een Knowledge Base
  • Een Knowledge Base verwijderen

Referentiedocumentatie | Broncode van bibliotheek | Pakket (NuGet) | C#-voorbeelden

Notitie

Nieuwe resources die zijn gemaakt na 1 juli 2019, hebben aangepaste subdomeinnamen. Zie Aangepaste subdomeinnamen voor Azure AI-services voor meer informatie en een volledige lijst met regionale eindpunten.

Vereisten

Notitie

Deze documentatie is niet van toepassing op de nieuwste versie. Raadpleeg de quickstart voor het beantwoorden van C# voor meer informatie over het gebruik van de C#-API met de nieuwste release.

  • Azure-abonnement: Krijg een gratis abonnement
  • De Visual Studio IDE of de huidige versie van .NET Core.
  • Zodra u een Azure-abonnement hebt, maakt u een QnA Maker-resource in Azure Portal om uw auteurssleutel en resourcenaam op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
    • U hebt de sleutel en de resourcenaam nodig van de resource die u maakt, om de toepassing te verbinden met de QnA Maker-API. Plak uw sleutel en resourcenaam verderop in de onderstaande code in de quickstart.
    • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

Instellen

CLI

Gebruik in een consolevenster (zoals cmd, PowerShell of Bash) de opdracht dotnet new om een nieuwe console-app te maken met de naam qna-maker-quickstart. Met deze opdracht maakt u een eenvoudig Hallo wereld-C#-project met één bronbestand: program.cs.

dotnet new console -n qna-maker-quickstart

Wijzig uw map in de zojuist gemaakte app-map. U kunt de toepassing maken met:

dotnet build

De build-uitvoer mag geen waarschuwingen of fouten bevatten.

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

Installeer in de toepassingsmap de QnA Maker-clientbibliotheek voor .NET met de volgende opdracht:

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

Tip

Wilt u het volledige quickstartcodebestand ineens weergeven? Die is te vinden op GitHub, waar de codevoorbeelden uit deze quickstart zich bevinden.

Instructies gebruiken

Open vanuit de projectmap het bestand program.cs en voeg de volgende using-instructies toe:

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

Abonnementssleutel en resource-eindpunten

Voeg in de methode Main van de toepassing variabelen en code toe, zoals wordt weergegeven in de volgende sectie, zodat u de algemene taken in deze quickstart kunt gebruiken.

  • We gebruiken abonnementssleutel en creatiesleutel door elkaar. Volg Sleutels in QnA Maker voor meer informatie over het ontwerpen van sleutels.

  • De waarde van QNA_MAKER_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sleutels en eindpunt , onder Resourcebeheer om de ontwerpsleutel (abonnement) en het QnA Maker-eindpunt te zoeken.

QnA Maker-ontwerpeindpunt

  • De waarde van QNA_MAKER_RUNTIME_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.azurewebsites.net. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sjabloon exporteren onder Automation om het runtime-eindpunt te vinden.

QnA Maker Runtime-eindpunt

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie het beveiligingsartikel over Azure AI-services voor meer informatie.

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";

Objectmodellen

In QnA Maker worden twee verschillende objectmodellen gebruikt:

  • QnAMakerClient is het object voor het maken, beheren, publiceren en downloaden van de Knowledge Base.
  • QnAMakerRuntime is het object waarmee u een query op de Knowledge Base gaat uitvoeren met behulp van de GenerateAnswer-API en nieuwe voorgestelde vragen verzendt met behulp van de Train-API (als onderdeel van actief leren).

Deze voorbeeld-Knowledge Base gebruiken

De Knowledge Base in deze quickstart begint met twee vraag-en-antwoordparen. Dit is met opzet gedaan om het voorbeeld te vereenvoudigen en om zeer voorspelbare id's te gebruiken in de bijwerkmethode, waarmee u vervolgprompts met vragen kunt koppelen aan nieuwe paren. Dit is gepland en geïmplementeerd in een specifieke volgorde voor deze quickstart.

Als u van plan bent om uw Knowledge Base in de loop der tijd te ontwikkelen met vervolgprompts die afhankelijk zijn van bestaande vraag-en-antwoordparen, kunt u kiezen uit de volgende mogelijkheden:

  • Voor grotere Knowledge Bases beheert u de Knowledge Base in een teksteditor of een hulpprogramma met door tabs gescheiden waarden dat automatisering ondersteunt, en vervangt u de KB vervolgens volledig door een update.
  • Voor kleinere Knowledge Bases beheert u de vervolgprompts volledig in de QnA Maker-portal.

Details over de vraag-en-antwoordparen die worden gebruikt in deze quickstart:

  • Typen vraag-en-antwoordparen: na de update zijn er twee typen vraag-en-antwoordparen in deze Knowledge Base: chitchat en domein-specifieke informatie. Dit is gebruikelijk als uw Knowledge Base is gekoppeld aan een conversatietoepassing zoals een chatbot.
  • Hoewel de antwoorden in de Knowledge Base kunnen worden gefilterd op metagegevens of er vervolgprompts kunnen worden gebruikt, komt dat niet terug in deze quickstart. Klik hier als u taalagnostische voorbeelden van het genereren van antwoorden wilt bekijken.
  • Antwoordtekst is markdown en kan allerlei soorten markdown bevatten, zoals afbeeldingen (openbaar beschikbare afbeeldingen op internet), koppelingen (naar openbaar beschikbare URL's) en opsommingstekens, maar de variëteit in deze quickstart is beperkt.

QnAMakerClient-objectmodel

De QnA Maker-ontwerpclient is een QnAMakerClient-object dat bij Azure wordt geverifieerd met behulp van Microsoft.Rest.ServiceClientCredentials, dat uw sleutel bevat.

Zodra de client is gemaakt, gebruikt u de eigenschap Knowledge Base om uw Knowledge Base te maken, te beheren en te publiceren.

Beheer uw Knowledge Base door een JSON-object te verzenden. Voor directe bewerkingen wordt via een methode doorgaans een JSON-object geretourneerd waarmee de status wordt aangegeven. Voor langlopende bewerkingen bestaat het antwoord uit de bewerkings-id. Roep de client.Operations.GetDetailsAsync-methode aan met de bewerkings-id om de status van de aanvraag te bepalen.

QnAMakerRuntimeClient-objectmodel

De QnA Maker-voorspellingsclient voor voorspellingen is een QnAMakerRuntimeClient-object dat bij Azure wordt geverifieerd met behulp van Microsoft.Rest.ServiceClientCredentials, die uw voorspellingsruntimesleutel bevat die wordt geretourneerd van de ontwerpclientaanroep, client.EndpointKeys.GetKeys nadat de Knowledge Base is gepubliceerd.

Gebruik de methode GenerateAnswer om een antwoord te krijgen van de runtime van de query.

Codevoorbeelden

Deze codefragmenten laten zien hoe u de volgende taken kunt uitvoeren met de QnA Maker-clientbibliotheek voor .NET:

De client voor het ontwerpen van de Knowledge Base verifiëren

Instantieer een clientobject met uw sleutel en gebruik dit samen met uw resource om het eindpunt te maken waarmee u een QnAMakerClient kunt maken met uw eindpunt en sleutel. Maak een ServiceClientCredentials-object.

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

Een kennisdatabase maken

In een Knowledge Base worden vraag-en-antwoordparen voor het CreateKbDTO-object opgeslagen die afkomstig zijn uit drie bronnen:

  • Gebruik voor redactionele inhoud het QnADTO-object.
    • Als u metagegevens en vervolgprompts wilt gebruiken, kiest u de redactionele context, aangezien deze gegevens op het niveau van een afzonderlijk vraag-en-antwoordpaar wordt toegevoegd.
  • Gebruik voor Bestanden het FileDTO-object. De FileDTO bevat de bestandsnaam en de openbare URL om het bestand te bereiken.
  • Gebruik voor URL's een lijst met tekenreeksen die openbaar beschikbare URL's vertegenwoordigen.

De maakstap bevat ook eigenschappen voor de Knowledge Base:

  • defaultAnswerUsedForExtraction: dit wordt geretourneerd als er geen antwoord wordt gevonden
  • enableHierarchicalExtraction: hiermee worden automatisch promptrelaties tussen geëxtraheerde vraag-en-antwoordparen gemaakt
  • language: wanneer u de eerste Knowledge Base van een resource maakt, stelt u de taal in die in de Azure Search-index moet worden gebruikt.

Roep de methode CreateAsync aan en geef de geretourneerde bewerkings-id door aan de methode MonitorOperation om de status op te vragen.

Met de laatste regel van de volgende code wordt de Knowledge Base-id uit het antwoord van MonitorOperation geretourneerd.

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);
}

Vergeet niet de MonitorOperation-functie op te nemen waarnaar in de bovenstaande code wordt verwezen om een Knowledge Base te maken.

Een kennisdatabase bijwerken

U kunt een Knowledge Base bijwerken door de Knowledge Base-id en een UpdatekbOperationDTO met de DTO-objecten add, update en delete door te geven aan de UpdateAsync-methode. Gebruik de MonitorOperation-methode om te bepalen of de update is geslaagd.

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);
}

Zorg ervoor dat u de MonitorOperation functie, waarnaar in de bovenstaande code wordt verwezen, opneemt om een knowledge base te kunnen bijwerken.

Een Knowledge Base downloaden

Gebruik de DownloadAsync-methode om de database als een lijst van QnADocumentsDTO te downloaden. Dit is geen equivalent voor de exportbewerking vanuit de pagina Instellingen van de QnA Maker-portal omdat het resultaat van deze methode geen bestand is.

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
}

Een kennisdatabase publiceren

Publiceer de Knowledge Base met behulp van de PublishAsync-methode. Hiervoor wordt het momenteel opgeslagen en getrainde model gebruikt waarnaar door de Knowledge Base-id wordt verwezen en wordt dat model naar uw eindpunt gepubliceerd. Dit is een noodzakelijke stap om een query op uw Knowledge Base te kunnen uitvoeren.

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

Een queryruntimesleutel ophalen

Zodra een Knowledge Base is gepubliceerd, hebt u de queryruntimesleutel nodig om een query uit te voeren op de runtime. Dit is niet dezelfde sleutel als de sleutel die u hebt gebruikt om het oorspronkelijke clientobject te maken.

Gebruik de EndpointKeys-methode om de EndpointKeysDTO-klasse op te halen.

Gebruik een van de sleuteleigenschappen die in het object zijn geretourneerd om een query uit te voeren op de Knowledge Base.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Er is een runtimesleutel nodig om een query op uw Knowledge Base te kunnen uitvoeren.

De runtime voor het genereren van een antwoord verifiëren

Maak een QnAMakerRuntimeClient om een query uit te voeren op de Knowledge Base om een antwoord te genereren of een training uit te voeren via actief leren.

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

Gebruik QnAMakerRuntimeClient om het volgende te doen:

  • een antwoord ophalen uit de Knowledge Base
  • nieuwe suggesties voor vragen sturen naar de Knowledge Base voor actief leren.

Een antwoord genereren uit de Knowledge Base

Genereer een antwoord uit een gepubliceerde Knowledge Base met behulp van de RuntimeClient.GenerateAnswerAsync-methode. Deze methode accepteert de Knowledge Base-id en de QueryDTO. Krijg toegang tot aanvullende eigenschappen van de QueryDTO, zoals een Top en Context die u in uw chatbot kunt gebruiken.

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
}

Dit is een eenvoudig voorbeeld waarbij een query wordt uitgevoerd op de Knowledge Base. Bekijk Andere queryvoorbeelden voor meer informatie over geavanceerde queryscenario's.

Een knowledge base verwijderen

Verwijder de Knowledge Base met behulp van de DeleteAsync-methode met een parameter van de Knowledge Base-id.

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

De status van een bewerking ophalen

Sommige methoden, zoals maken en bijwerken, duren zo lang dat er niet wordt gewacht tot het proces is beëindigd maar een bewerking wordt geretourneerd. Gebruik de bewerkings-id uit de bewerking om een poll uit te voeren (met logica voor opnieuw proberen) om de status van de oorspronkelijke methode te bepalen.

De lus en Task.Delay in het volgende codeblok worden gebruikt om logica voor opnieuw proberen te simuleren. Deze moeten worden vervangen door uw eigen logica voor nieuwe pogingen.

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;
}

De toepassing uitvoeren

Voer de toepassing uit vanuit uw toepassingsmap met de opdracht dotnet run.

dotnet run

De broncode voor dit voorbeeld is te vinden op GitHub.

Gebruik de QnA Maker-clientbibliotheek voor Node.js voor het volgende:

  • Een Knowledge Base maken
  • Een Knowledge Base bijwerken
  • Een Knowledge Base publiceren
  • Een eindpuntsleutel voor de voorspellingsruntime ophalen
  • Wachten op een langlopende taak
  • Een Knowledge Base downloaden
  • Antwoord krijgen in een Knowledge Base
  • Een Knowledge Base verwijderen

Referentiedocumentatiepakket (npm) | Node.js Voorbeelden |

Notitie

Nieuwe resources die zijn gemaakt na 1 juli 2019, hebben aangepaste subdomeinnamen. Zie Aangepaste subdomeinnamen voor Azure AI-services voor meer informatie en een volledige lijst met regionale eindpunten.

Vereisten

  • Azure-abonnement: Krijg een gratis abonnement
  • De huidige versie van Node.js.
  • Zodra u een Azure-abonnement hebt, maakt u een QnA Maker-resource in Azure Portal om uw auteurssleutel en resource op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
    • U hebt de sleutel en de resourcenaam nodig van de resource die u maakt, om de toepassing te verbinden met de QnA Maker-API. Plak uw sleutel en resourcenaam verderop in de onderstaande code in de quickstart.
    • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

Instellen

Een nieuwe Node.js-toepassing maken

Maak in een consolevenster (zoals cmd, PowerShell of Bash) een nieuwe map voor de app, en navigeer naar deze map.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Voer de opdracht npm init -y uit om een knooppunttoepassing te maken met een package.json-bestand.

npm init -y

De clientbibliotheek installeren

Installeer de volgende NPM-pakketten:

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

Het package.json-bestand van uw app wordt bijgewerkt met de afhankelijkheden.

Maak een bestand met de naam index.js en importeer de volgende bibliotheken:

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

Maak een variabele voor de Azure-sleutel en resourcenaam van uw resource.

  • We gebruiken abonnementssleutel en creatiesleutel door elkaar. Volg Sleutels in QnA Maker voor meer informatie over het ontwerpen van sleutels.

  • De waarde van QNA_MAKER_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sleutels en eindpunt , onder Resourcebeheer om de ontwerpsleutel (abonnement) en het QnA Maker-eindpunt te zoeken.

QnA Maker-ontwerpeindpunt

  • De waarde van QNA_MAKER_RUNTIME_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.azurewebsites.net. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sjabloon exporteren onder Automation om het runtime-eindpunt te vinden.

QnA Maker Runtime-eindpunt

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie het beveiligingsartikel over Azure AI-services voor meer informatie.

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";

Objectmodellen

In QnA Maker worden twee verschillende objectmodellen gebruikt:

  • QnAMakerClient is het object voor het maken, beheren, publiceren en downloaden van de Knowledge Base.
  • QnAMakerRuntime is het object waarmee u een query op de Knowledge Base gaat uitvoeren met behulp van de GenerateAnswer-API en nieuwe voorgestelde vragen verzendt met behulp van de Train-API (als onderdeel van actief leren).

QnAMakerClient-objectmodel

De QnA Maker-ontwerpclient is een QnAMakerClient-object dat bij Azure wordt geverifieerd met behulp van uw referenties, die uw sleutel bevatten.

Zodra de client is gemaakt, gebruikt u de Knowledge Base om uw Knowledge Base te maken, beheren en publiceren.

Beheer uw Knowledge Base door een JSON-object te verzenden. Voor directe bewerkingen wordt via een methode doorgaans een JSON-object geretourneerd waarmee de status wordt aangegeven. Voor langlopende bewerkingen bestaat het antwoord uit de bewerkings-id. Roep de client.operations.getDetails-methode aan met de bewerkings-id om de status van de aanvraag te bepalen.

QnAMakerRuntimeClient-objectmodel

De QnA Maker-client is een QnAMakerRuntimeClient-object dat bij Azure wordt geverifieerd met behulp van Microsoft.Rest.ServiceClientCredentials, die uw voorspellingsruntimesleutel bevat die wordt geretourneerd van de ontwerpclientaanroep, client.EndpointKeys.getKeys nadat de Knowledge Base is gepubliceerd.

Codevoorbeelden

Deze codefragmenten laten zien hoe u de volgende taken kunt uitvoeren met de QnA Maker-clientbibliotheek voor .NET:

De client voor het ontwerpen van de Knowledge Base verifiëren

Instantieer een client met uw eindpunt en sleutel. Maak een ServiceClientCredentials-object met uw sleutel en gebruik het met uw eindpunt om een QnAMakerClient-object te maken.

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);

Een kennisdatabase maken

In een Knowledge Base worden vraag-en-antwoordparen voor het CreateKbDTO-object opgeslagen die afkomstig zijn uit drie bronnen:

  • Gebruik voor redactionele inhoud het QnADTO-object.
    • Als u metagegevens en vervolgprompts wilt gebruiken, kiest u de redactionele context, aangezien deze gegevens op het niveau van een afzonderlijk vraag-en-antwoordpaar wordt toegevoegd.
  • Gebruik voor Bestanden het FileDTO-object. De FileDTO bevat de bestandsnaam en de openbare URL om het bestand te bereiken.
  • Gebruik voor URL's een lijst met tekenreeksen die openbaar beschikbare URL's vertegenwoordigen.

De maakstap bevat ook eigenschappen voor de Knowledge Base:

  • defaultAnswerUsedForExtraction: dit wordt geretourneerd als er geen antwoord wordt gevonden
  • enableHierarchicalExtraction: hiermee worden automatisch promptrelaties tussen geëxtraheerde vraag-en-antwoordparen gemaakt
  • language: wanneer u de eerste Knowledge Base van een resource maakt, stelt u de taal in die in de Azure Search-index moet worden gebruikt.

Roep de create-methode aan met de Knowledge Base-informatie. De Knowledge Base-informatie is in feite een JSON-object.

Wanneer een antwoord door de create-methode wordt geretourneerd, geeft u de geretourneerde bewerkings-id door aan de wait_for_operation-methode om de status te controleren. De wait_for_operation-methode retourneert een antwoord wanneer de bewerking is voltooid. Parseer de resourceLocation-headerwaarde van de geretourneerde bewerking om de nieuwe Knowledge Base-id op te halen.

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;
}

Vergeet niet de wait_for_operation-functie op te nemen waarnaar in de bovenstaande code wordt verwezen om een Knowledge Base te maken.

Een kennisdatabase bijwerken

U kunt een Knowledge Base bijwerken door de Knowledge Base-id en een UpdateKbOperationDTO met de DTO-objecten add, update en delete door te geven aan de update-methode. De DTO's zijn in feite ook JSON-objecten. Gebruik de wait_for_operation-methode om te bepalen of de update is geslaagd.

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
}

Vergeet niet de wait_for_operation-functie op te nemen waarnaar in de bovenstaande code wordt verwezen om een Knowledge Base bij te werken.

Een Knowledge Base downloaden

Gebruik de download-methode om de database als een lijst van QnADocumentsDTO te downloaden. Dit is geen equivalent voor de exportbewerking vanuit de pagina Instellingen van de QnA Maker-portal omdat het resultaat van deze methode geen TSV-bestand is.

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
}

Een kennisdatabase publiceren

Publiceer de Knowledge Base met behulp van de publish-methode. Hiervoor wordt het momenteel opgeslagen en getrainde model gebruikt waarnaar door de Knowledge Base-id wordt verwezen, en wordt dat model naar een eindpunt gepubliceerd. Controleer of de HTTP-antwoordcode om te controleren of de publicatie is geslaagd.

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
}

Een query uitvoeren op een Knowledge Base

Een queryruntimesleutel ophalen

Zodra een Knowledge Base is gepubliceerd, hebt u de queryruntimesleutel nodig om een query uit te voeren op de runtime. Dit is niet dezelfde sleutel als de sleutel die u hebt gebruikt om het oorspronkelijke clientobject te maken.

Gebruik de EndpointKeys.getKeys-methode om de EndpointKeysDTO-klasse op te halen.

Gebruik een van de sleuteleigenschappen die in het object zijn geretourneerd om een query uit te voeren op de Knowledge Base.

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
}

De runtime voor het genereren van een antwoord verifiëren

Maak een QnAMakerRuntimeClient om een query uit te voeren op de Knowledge Base om een antwoord te genereren of een training uit te voeren via actief leren.

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

Gebruik de QnAMakerRuntimeClient om een antwoord uit de Knowledge Base op te halen of om nieuwe vraagvoorstellen naar de Knowledge Base te verzenden voor actief leren.

Een antwoord genereren uit de Knowledge Base

Genereer een antwoord uit een gepubliceerde Knowledge Base met behulp van de RuntimeClient.runtime.generateAnswer-method. Deze methode accepteert de Knowledge Base-id en de QueryDTO. Krijg toegang tot aanvullende eigenschappen van de QueryDTO, zoals een Top en Context die u in uw chatbot kunt gebruiken.

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));

}

Dit is een eenvoudig voorbeeld waarbij een query wordt uitgevoerd op de Knowledge Base. Bekijk Andere queryvoorbeelden voor meer informatie over geavanceerde queryscenario's.

Een knowledge base verwijderen

Verwijder de Knowledge Base met behulp van de delete-methode met een parameter van de Knowledge Base-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
}

De status van een bewerking ophalen

Sommige methoden, zoals maken en bijwerken, duren zo lang dat er niet wordt gewacht tot het proces is beëindigd maar een bewerking wordt geretourneerd. Gebruik de bewerkings-id uit de bewerking om een poll uit te voeren (met logica voor opnieuw proberen) om de status van de oorspronkelijke methode te bepalen.

De delayTimer-aanroep in het volgende codeblok wordt gebruikt om de logica voor opnieuw proberen te simuleren. Vervang deze door uw eigen logica voor opnieuw proberen.

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);
    });
}

De toepassing uitvoeren

Voer de toepassing uit vanuit uw toepassingsmap met de opdracht node index.js.

node index.js

De broncode voor dit voorbeeld is te vinden op GitHub.

Gebruik de QnA Maker-clientbibliotheek voor Python om het volgende te doen:

  • Een Knowledge Base maken
  • Een Knowledge Base bijwerken
  • Een Knowledge Base publiceren
  • Een eindpuntsleutel voor de voorspellingsruntime ophalen
  • Wachten op een langlopende taak
  • Een Knowledge Base downloaden
  • Antwoord krijgen in een Knowledge Base
  • Een Knowledge Base verwijderen

Referentiedocumentatie | Broncode van bibliotheek | Package (PyPi) | Python-voorbeelden

Notitie

Nieuwe resources die zijn gemaakt na 1 juli 2019, hebben aangepaste subdomeinnamen. Zie Aangepaste subdomeinnamen voor Azure AI-services voor meer informatie en een volledige lijst met regionale eindpunten.

Vereisten

Notitie

Deze documentatie is niet van toepassing op de nieuwste versie. Raadpleeg de vraag over het beantwoorden van python-quickstart voor meer informatie over het gebruik van de Python-API met de nieuwste release.

  • Azure-abonnement: Krijg een gratis abonnement
  • Python 3.x
  • Zodra u een Azure-abonnement hebt, maakt u een QnA Maker-resource in Azure Portal om uw ontwerpsleutel en eindpunt op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
    • U hebt de sleutel en het eindpunt nodig van de resource die u maakt, om de toepassing te verbinden met de QnA Maker-API. Later in de quickstart plakt u uw sleutel en eindpunt in de onderstaande code.
    • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

Instellen

De clientbibliotheek installeren

Na de installatie van Python kunt u de clientbibliotheek installeren met:

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

Een nieuwe Python-toepassing maken

Maak een nieuw Python-bestand met de naam quickstart-file.py en importeer de volgende 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

Maak variabelen voor het Azure-eindpunt en de Azure-sleutel voor uw resource.

  • We gebruiken abonnementssleutel en creatiesleutel door elkaar. Volg Sleutels in QnA Maker voor meer informatie over het ontwerpen van sleutels.

  • De waarde van QNA_MAKER_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sleutels en eindpunt , onder Resourcebeheer om de ontwerpsleutel (abonnement) en het QnA Maker-eindpunt te zoeken.

QnA Maker-ontwerpeindpunt

  • De waarde van QNA_MAKER_RUNTIME_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.azurewebsites.net. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sjabloon exporteren onder Automation om het runtime-eindpunt te vinden.

QnA Maker Runtime-eindpunt

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie het beveiligingsartikel over Azure AI-services voor meer informatie.

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'

Objectmodellen

In QnA Maker worden twee verschillende objectmodellen gebruikt:

  • QnAMakerClient is het object voor het maken, beheren, publiceren en downloaden van de Knowledge Base.
  • QnAMakerRuntime is het object waarmee u een query op de Knowledge Base gaat uitvoeren met behulp van de GenerateAnswer-API en nieuwe voorgestelde vragen verzendt met behulp van de Train-API (als onderdeel van actief leren).

Deze voorbeeld-Knowledge Base gebruiken

De Knowledge Base in deze quickstart begint met twee vraag-en-antwoordparen. Dit is met opzet gedaan om het voorbeeld te vereenvoudigen en om zeer voorspelbare id's te gebruiken in de bijwerkmethode, waarmee u vervolgprompts met vragen kunt koppelen aan nieuwe paren. Dit is gepland en geïmplementeerd in een specifieke volgorde voor deze quickstart.

Als u van plan bent om uw Knowledge Base in de loop der tijd te ontwikkelen met vervolgprompts die afhankelijk zijn van bestaande vraag-en-antwoordparen, kunt u kiezen uit de volgende mogelijkheden:

  • Voor grotere Knowledge Bases beheert u de Knowledge Base in een teksteditor of een hulpprogramma met door tabs gescheiden waarden dat automatisering ondersteunt, en vervangt u de KB vervolgens volledig door een update.
  • Voor kleinere Knowledge Bases beheert u de vervolgprompts volledig in de QnA Maker-portal.

Details over de vraag-en-antwoordparen die worden gebruikt in deze quickstart:

  • Typen vraag-en-antwoordparen: na de update zijn er twee typen vraag-en-antwoordparen in deze Knowledge Base: chitchat en domein-specifieke informatie. Dit is gebruikelijk als uw Knowledge Base is gekoppeld aan een conversatietoepassing zoals een chatbot.
  • Hoewel de antwoorden in de Knowledge Base kunnen worden gefilterd op metagegevens of er vervolgprompts kunnen worden gebruikt, komt dat niet terug in deze quickstart. Klik hier als u taalagnostische voorbeelden van het genereren van antwoorden wilt bekijken.
  • Antwoordtekst is markdown en kan allerlei soorten markdown bevatten, zoals afbeeldingen (openbaar beschikbare afbeeldingen op internet), koppelingen (naar openbaar beschikbare URL's) en opsommingstekens, maar de variëteit in deze quickstart is beperkt.

QnAMakerClient-objectmodel

De QnA Maker-ontwerpclient is een QnAMakerClient-object dat bij Azure wordt geverifieerd met behulp van Microsoft.Rest.ServiceClientCredentials, dat uw sleutel bevat.

Zodra de client is gemaakt, gebruikt u de eigenschap Knowledge Base om uw Knowledge Base te maken, te beheren en te publiceren.

Beheer uw Knowledge Base door een JSON-object te verzenden. Voor directe bewerkingen wordt via een methode doorgaans een JSON-object geretourneerd waarmee de status wordt aangegeven. Voor langlopende bewerkingen bestaat het antwoord uit de bewerkings-id. Roep de methode operations.get_details aan met de bewerkings-id om de status van de aanvraag te bepalen.

QnAMakerRuntimeClient-objectmodel

De QnA Maker-voorspellingsclient is een QnAMakerRuntimeClient object dat wordt geverifieerd bij Azure met behulp van Microsoft.Rest.ServiceClientCredentials, die uw voorspellingsruntimesleutel bevat, die wordt geretourneerd door de creatieclientaanroep, de client. EndpointKeysOperations.get_keys nadat de Knowledge Base is gepubliceerd.

Gebruik de generate_answer methode om een antwoord op te halen uit de queryruntime.

De client voor het ontwerpen van de Knowledge Base verifiëren

Instantieer een client met uw eindpunt en sleutel. Maak een CognitiveServicesCredentials-object met uw sleutel en gebruik het met uw eindpunt om een QnAMakerClient-object te maken.

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

Een kennisdatabase maken

Gebruik het clientobject om een knowledge base operations-object op te halen.

In een Knowledge Base worden vraag-en-antwoordparen voor het CreateKbDTO-object opgeslagen die afkomstig zijn uit drie bronnen:

  • Gebruik voor redactionele inhoud het QnADTO-object.
    • Als u metagegevens en vervolgprompts wilt gebruiken, kiest u de redactionele context, aangezien deze gegevens op het niveau van een afzonderlijk vraag-en-antwoordpaar wordt toegevoegd.
  • Gebruik voor Bestanden het FileDTO-object. De FileDTO bevat de bestandsnaam en de openbare URL om het bestand te bereiken.
  • Gebruik voor URL's een lijst met tekenreeksen die openbaar beschikbare URL's vertegenwoordigen.

Roep de methode create aan en geef de geretourneerde bewerkings-id door aan de methode Operations.getDetails om de status op te vragen.

Met de laatste regel van de volgende code wordt de Knowledge Base-id uit het antwoord van MonitorOperation geretourneerd.

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

Vergeet niet de _monitor_operation-functie op te nemen waarnaar in de bovenstaande code wordt verwezen om een Knowledge Base te maken.

Een kennisdatabase bijwerken

U kunt een Knowledge Base bijwerken door de Knowledge Base-id en een UpdateKbOperationDTO met de DTO-objecten add, update en delete door te geven aan de update-methode. Gebruik de methode Operation.getDetail om te bepalen of de update is geslaagd.

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.")

Vergeet niet de _monitor_operation-functie op te nemen waarnaar in de bovenstaande code wordt verwezen om een Knowledge Base bij te werken.

Een Knowledge Base downloaden

Gebruik de download-methode om de database als een lijst van QnADocumentsDTO te downloaden. Dit is geen equivalent voor de exportbewerking vanuit de pagina Instellingen van de QnA Maker-portal omdat het resultaat van deze methode geen TSV-bestand is.

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)))

Een kennisdatabase publiceren

Publiceer de Knowledge Base met behulp van de publish-methode. Hiervoor wordt het momenteel opgeslagen en getrainde model gebruikt waarnaar door de Knowledge Base-id wordt verwezen, en wordt dat model naar een eindpunt gepubliceerd.

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

Een query uitvoeren op een Knowledge Base

Een queryruntimesleutel ophalen

Zodra een Knowledge Base is gepubliceerd, hebt u de queryruntimesleutel nodig om een query uit te voeren op de runtime. Dit is niet dezelfde sleutel als de sleutel die u hebt gebruikt om het oorspronkelijke clientobject te maken.

Gebruik de methode EndpointKeysOperations.get_keys om de EndpointKeysDTO-klasse op te halen.

Gebruik een van de sleuteleigenschappen die in het object zijn geretourneerd om een query uit te voeren op de Knowledge Base.

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

De runtime voor het genereren van een antwoord verifiëren

Maak een QnAMakerRuntimeClient om een query uit te voeren op de Knowledge Base om een antwoord te genereren of een training uit te voeren via actief leren.

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

Gebruik de QnAMakerRuntimeClient om een antwoord uit de Knowledge Base op te halen of om nieuwe vraagvoorstellen naar de Knowledge Base te verzenden voor actief leren.

Een antwoord genereren uit de Knowledge Base

Genereer een antwoord uit een gepubliceerde Knowledge Base met behulp van de methode QnAMakerRuntimeClient.runtime.generateAnswer. Deze methode accepteert de Knowledge Base-id en de QueryDTO. Krijg toegang tot aanvullende eigenschappen van de QueryDTO, zoals een Top en Context die u in uw chatbot kunt gebruiken.

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}.")

Dit is een eenvoudig voorbeeld waarin een query wordt uitgevoerd op de Knowledge Base. Bekijk Andere queryvoorbeelden voor meer informatie over geavanceerde queryscenario's.

Een knowledge base verwijderen

Verwijder de Knowledge Base met behulp van de delete-methode met een parameter van de Knowledge Base-id.

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

De status van een bewerking ophalen

Sommige methoden, zoals maken en bijwerken, duren zo lang dat er niet wordt gewacht tot het proces is beëindigd maar een bewerking wordt geretourneerd. Gebruik de bewerkings-id uit de bewerking om een poll uit te voeren (met logica voor opnieuw proberen) om de status van de oorspronkelijke methode te bepalen.

De setTimeout-aanroep in het volgende codeblok wordt gebruikt om asynchrone code te simuleren. Vervang deze door logica voor opnieuw proberen.

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

De toepassing uitvoeren

Voer de toepassing uit met de Python-opdracht in uw quickstart-bestand.

python quickstart-file.py

De broncode voor dit voorbeeld is te vinden op GitHub.

Gebruik de QnA Maker-clientbibliotheek voor Java voor het volgende:

  • Een Knowledge Base maken
  • Een Knowledge Base bijwerken
  • Een Knowledge Base publiceren
  • Een eindpuntsleutel voor de voorspellingsruntime ophalen
  • Wachten op een langlopende taak
  • Een Knowledge Base downloaden
  • Antwoord krijgen in een Knowledge Base
  • Een Knowledge Base verwijderen

Broncode van de bibliotheek | Pakket | Voorbeelden

Notitie

Nieuwe resources die zijn gemaakt na 1 juli 2019, hebben aangepaste subdomeinnamen. Zie Aangepaste subdomeinnamen voor Azure AI-services voor meer informatie en een volledige lijst met regionale eindpunten.

Vereisten

  • Azure-abonnement: Krijg een gratis abonnement
  • JDK
  • Zodra u een Azure-abonnement hebt, maakt u een QnA Maker-resource in Azure Portal om uw ontwerpsleutel en eindpunt op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
    • U hebt de sleutel en het eindpunt nodig van de resource die u maakt, om de toepassing te verbinden met de QnA Maker-API. Plak uw sleutel en eindpunt verderop in de onderstaande code in de quickstart.
    • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

Instellen

De clientbibliotheken installeren

Na het installeren van Java kunt u de clientbibliotheken installeren met behulp van Maven uit de MVN-opslagplaats.

Een nieuwe Java-toepassing maken

Maak een nieuw bestand met de naam quickstart.java en importeer de volgende 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.*;

Maak variabelen voor het Azure-eindpunt en de Azure-sleutel voor uw resource.

  • We gebruiken abonnementssleutel en creatiesleutel door elkaar. Volg Sleutels in QnA Maker voor meer informatie over het ontwerpen van sleutels.

  • De waarde van QNA_MAKER_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sleutels en eindpunt , onder Resourcebeheer om de ontwerpsleutel (abonnement) en het QnA Maker-eindpunt te zoeken.

QnA Maker-ontwerpeindpunt

  • De waarde van QNA_MAKER_RUNTIME_ENDPOINT heeft de indeling https://YOUR-RESOURCE-NAME.azurewebsites.net. Ga naar Azure Portal en zoek de QnA Maker-resource die u hebt gemaakt in de vereisten. Selecteer de pagina Sjabloon exporteren onder Automation om het runtime-eindpunt te vinden.

QnA Maker Runtime-eindpunt

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie het beveiligingsartikel over Azure AI-services voor meer informatie.

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";

Objectmodellen

In QnA Maker worden twee verschillende objectmodellen gebruikt:

  • QnAMakerClient is het object voor het maken, beheren, publiceren en downloaden van de Knowledge Base.
  • QnAMakerRuntime is het object waarmee u een query op de Knowledge Base gaat uitvoeren met behulp van de GenerateAnswer-API en nieuwe voorgestelde vragen verzendt met behulp van de Train-API (als onderdeel van actief leren).

Deze voorbeeld-Knowledge Base gebruiken

De Knowledge Base in deze quickstart begint met twee vraag-en-antwoordparen. Dit is met opzet gedaan om het voorbeeld te vereenvoudigen en om zeer voorspelbare id's te gebruiken in de bijwerkmethode, waarmee u vervolgprompts met vragen kunt koppelen aan nieuwe paren. Dit is gepland en geïmplementeerd in een specifieke volgorde voor deze quickstart.

Als u van plan bent om uw Knowledge Base in de loop der tijd te ontwikkelen met vervolgprompts die afhankelijk zijn van bestaande vraag-en-antwoordparen, kunt u kiezen uit de volgende mogelijkheden:

  • Voor grotere Knowledge Bases beheert u de Knowledge Base in een teksteditor of een hulpprogramma met door tabs gescheiden waarden dat automatisering ondersteunt, en vervangt u de KB vervolgens volledig door een update.
  • Voor kleinere Knowledge Bases beheert u de vervolgprompts volledig in de QnA Maker-portal.

Details over de vraag-en-antwoordparen die worden gebruikt in deze quickstart:

  • Typen vraag-en-antwoordparen: na de update zijn er twee typen vraag-en-antwoordparen in deze Knowledge Base: chitchat en domein-specifieke informatie. Dit is gebruikelijk als uw Knowledge Base is gekoppeld aan een conversatietoepassing zoals een chatbot.
  • Hoewel de antwoorden in de Knowledge Base kunnen worden gefilterd op metagegevens of er vervolgprompts kunnen worden gebruikt, komt dat niet terug in deze quickstart. Klik hier als u taalagnostische voorbeelden van het genereren van antwoorden wilt bekijken.
  • Antwoordtekst is markdown en kan allerlei soorten markdown bevatten, zoals afbeeldingen (openbaar beschikbare afbeeldingen op internet), koppelingen (naar openbaar beschikbare URL's) en opsommingstekens, maar de variëteit in deze quickstart is beperkt.

QnAMakerClient-objectmodel

De QnA Maker-ontwerpclient is een QnAMakerClient-object dat bij Azure wordt geverifieerd met behulp van MsRest::ServiceClientCredentials, waarin uw sleutel zich bevindt.

Zodra de client is gemaakt, gebruikt u de methoden van de eigenschap Knowledgebases van de client om uw Knowledge Base te maken, te beheren en te publiceren.

Voor directe bewerkingen wordt via een methode doorgaans het resultaat geretourneerd, als dat er is. Voor langlopende bewerkingen bestaat het antwoord uit een Operation-object. Roep de methode getDetails aan met de waarde operation.operationId om de status van de aanvraag te bepalen.

QnAMakerRuntimeClient-objectmodel

De runtimeclient van QnA Maker is een QnAMakerRuntimeClient-object.

Nadat u uw Knowledge Base hebt gepubliceerd met behulp van de creatieclient, gebruikt u de methode generateAnswer van de runtime-client om een antwoord te krijgen van de Knowledge Base.

U maakt een runtime-client door QnAMakerRuntimeManager.authenticate aan te roepen en een runtime-eindpuntsleutel door te geven. U haalt de runtime-eindpuntsleutel op door gebruik te maken van de creatieclient om getKeys aan te roepen.

De client voor het ontwerpen van de Knowledge Base verifiëren

Instantieer een client met uw creatie-eindpunt en abonnementssleutel.

/* 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();

Een kennisdatabase maken

In een Knowledge Base worden vraag-en-antwoordparen voor het CreateKbDTO-object opgeslagen die afkomstig zijn uit drie bronnen:

  • Gebruik voor redactionele inhoud het QnADTO-object.
    • Als u metagegevens en vervolgprompts wilt gebruiken, kiest u de redactionele context, aangezien deze gegevens op het niveau van een afzonderlijk vraag-en-antwoordpaar wordt toegevoegd.
  • Gebruik voor Bestanden het FileDTO-object. De FileDTO bevat de bestandsnaam en de openbare URL om het bestand te bereiken.
  • Gebruik voor URL's een lijst met tekenreeksen die openbaar beschikbare URL's vertegenwoordigen.

Roep de methode create aan en geef de eigenschap operationId van de geretourneerde bewerking door aan de methode getDetails om de status op te vragen.

Met de laatste regel van de volgende code wordt de Knowledge Base-id geretourneerd.

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;
}

Een kennisdatabase bijwerken

U kunt een Knowledge Base bijwerken door update aan te roepen en de Knowledge Base-id en een UpdateKbOperationDTO-object door te geven. Dat object kan het volgende bevatten:

Geef de eigenschap operationId van de geretourneerde bewerking door aan de methode getDetails om de status op te vragen.

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.");
}

Een Knowledge Base downloaden

Gebruik de download-methode om de database als een lijst van QnADocumentsDTO te downloaden. Dit is geen equivalent voor de exportbewerking vanuit de pagina Instellingen van de QnA Maker-portal omdat het resultaat van deze methode geen TSV-bestand is.

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");
}

Een kennisdatabase publiceren

Publiceer de Knowledge Base met behulp van de publish-methode. Hiervoor wordt het momenteel opgeslagen en getrainde model gebruikt waarnaar door de Knowledge Base-id wordt verwezen, en wordt dat model naar een eindpunt gepubliceerd.

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

Een antwoord genereren uit de Knowledge Base

Zodra een Knowledge Base is gepubliceerd, hebt u de runtime-eindpuntsleutel nodig om een query uit te voeren op de Knowledge Base. Dit is niet dezelfde abonnementssleutel als waarmee de ontwerpclient is gemaakt.

Gebruik de methode getKeys om een EndpointKeysDTO-object op te halen.

Maak een runtime-client door QnAMakerRuntimeManager.authenticate aan te roepen en een runtime-eindpuntsleutel van het EndpointKeysDTO-object door te geven.

Genereer een antwoord uit een gepubliceerde Knowledge Base met behulp van de methode generateAnswer. Deze methode accepteert de Knowledge Base-id en het object QueryDTO.

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();
}

Dit is een eenvoudig voorbeeld van het uitvoeren van een query op een Knowledge Base. Bekijk Andere queryvoorbeelden voor meer informatie over geavanceerde queryscenario's.

Een knowledge base verwijderen

Verwijder de Knowledge Base met behulp van de delete-methode met een parameter van de Knowledge Base-id.

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

De status van een bewerking ophalen

Sommige methoden, zoals maken en bijwerken, duren zo lang dat er niet wordt gewacht tot het proces is beëindigd maar een bewerking wordt geretourneerd. Gebruik de bewerkings-id uit de bewerking om een poll uit te voeren (met logica voor opnieuw proberen) om de status van de oorspronkelijke methode te bepalen.

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;
}

De toepassing uitvoeren

Hier volgt de belangrijkste methode voor de toepassing.

    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();
        }
    }

Voer de toepassing als volgt uit. Hierbij wordt ervan uitgegaan dat de naam van de klasse Quickstart is en dat uw afhankelijkheden zich in een submap met de naam lib onder de huidige map bevinden.

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

De broncode voor dit voorbeeld is te vinden op GitHub.

Resources opschonen

Als u een Azure AI-servicesabonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle bijbehorende resources verwijderd.

Volgende stappen

Zelfstudie: Uw Knowledge Base testen met een batchbestand