Quickstart: QnA Maker-clientbibliotheek

Vereisten

• 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

Een kennisdatabase maken

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

Informatie	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://docs.microsoft.com/en-in/azure/cognitive-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.

Informatie	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.

Informatie	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.

Informatie	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.

Informatie	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.

Informatie	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

• Referentiedocumentatie voor creatie
• Referentiedocumentatie voor runtime
• Voorbeelden van BASH-scripts met cURL

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

Vereisten

• 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 later in de quickstart 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

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

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 de abonnementssleutel en de ontwerpsleutel door elkaar. Voor meer informatie over de ontwerpsleutel volgt u Sleutels in QnA Maker.

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

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

• Overweeg om voor productie een veilige manier te gebruiken voor het opslaan en openen van uw referenties. Azure Key Vault biedt bijvoorbeeld beveiligde sleutelopslag.

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 ontwerpclient verifiëren
• Een kennisdatabase maken
• Een kennisdatabase bijwerken
• Een Knowledge Base downloaden
• Een kennisdatabase publiceren
• Een knowledge base verwijderen
• Een queryruntimesleutel ophalen
• De status van een bewerking ophalen
• De queryruntimeclient verifiëren
• Een antwoord uit de Knowledge Base genereren

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 functie , waarnaar wordt verwezen in de bovenstaande code, op bevat MonitorOperation om een Knowledge Base bij te werken.

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

Referentiedocumentatie | Bibliotheekbroncode | Pakket (NPM) | Node.js-voorbeelden

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 later in de quickstart 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

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 de abonnementssleutel en de ontwerpsleutel door elkaar. Voor meer informatie over de ontwerpsleutel volgt u Sleutels in QnA Maker.

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

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

• Overweeg om voor productie een veilige manier te gebruiken voor het opslaan en openen van uw referenties. Azure Key Vault biedt bijvoorbeeld beveiligde sleutelopslag.

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 ontwerpclient verifiëren
• Een kennisdatabase maken
• Een kennisdatabase bijwerken
• Een Knowledge Base downloaden
• Een kennisdatabase publiceren
• Een knowledge base verwijderen
• Een queryruntimesleutel ophalen
• De status van een bewerking ophalen
• De queryruntimeclient verifiëren
• Een antwoord uit de Knowledge Base genereren

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.

Genereer een antwoord 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 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 | Package (PyPi) | Python-voorbeelden

Vereisten

• 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 de abonnementssleutel en de ontwerpsleutel door elkaar. Voor meer informatie over de ontwerpsleutel volgt u Sleutels in QnA Maker.

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

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

• Overweeg om voor productie een veilige manier te gebruiken voor het opslaan en openen van uw referenties. Azure Key Vault biedt bijvoorbeeld beveiligde sleutelopslag.

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 bij Azure wordt geverifieerd met behulp van Microsoft.Rest.ServiceClientCredentials, die uw voorspellingsruntimesleutel bevat die wordt geretourneerd van de ontwerpclientaanroep, QnAMakerRuntimeClient, nadat de Knowledge Base is gepubliceerd.

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

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.

Genereer een antwoord 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

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 later in de quickstart 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 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 de abonnementssleutel en de ontwerpsleutel door elkaar. Voor meer informatie over de ontwerpsleutel volgt u Sleutels in QnA Maker.

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

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

• Overweeg om voor productie een veilige manier te gebruiken voor het opslaan en openen van uw referenties. Azure Key Vault biedt bijvoorbeeld beveiligde sleutelopslag.

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-creatieclient 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 runtime-client 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:

• add
• update
• verwijderen

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

Genereer een antwoord 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 creatieclient 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.

Gebruik de QnA Maker-clientbibliotheek voor Go 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 ophalen
• Een Knowledge Base verwijderen

Naslaginformatie (creatie) | Naslaginformatie (runtime) | Broncode van bibliotheek (creatie) | Broncode van bibliotheek (runtime) | Samples

Vereisten

• Azure-abonnement: Krijg een gratis abonnement
• Go
• 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 later in de quickstart 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

Een nieuwe Go-toepassing maken

Maak een nieuw bestand met de naam kb_sample.go en importeer de volgende bibliotheken.

import (
    "context"
    "fmt"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v4.0/qnamaker"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v4.0/qnamakerruntime"
    "github.com/Azure/go-autorest/autorest"
    "log"
    "strings"
    "time"
)

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

var subscription_key string = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE"
var authoring_endpoint string = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE"
var runtime_endpoint string = "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

Gebruik de KnowledgebaseClient om uw Knowledge Base te maken, bij te werken, te publiceren, te downloaden en te verwijderen. Deze bewerkingen komen in de volgende secties aan bod.

Gebruik de OperationsClient om de status van langlopende bewerkingen te controleren, zoals het maken en bijwerken van Knowledge Bases.

QnAMakerRuntimeClient-objectmodel

Nadat u uw Knowledge Base hebt gepubliceerd, gebruikt u RuntimeClient om query's uit te voeren op de Knowledge Base. Deze bewerking wordt behandeld in Query's uitvoeren op de Knowledge Base.

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.

// Create a knowledge base.
func create_kb () string {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewKnowledgebaseClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    name := "QnA Maker FAQ"

    /*
    The fields of QnADTO are pointers, and we cannot get the addresses of literal values,
    so we declare helper variables.
    */
    id := int32(0)
    answer := "You can use our REST APIs to manage your Knowledge Base. See here for details: https://westus.dev.cognitive.microsoft.com/docs/services/58994a073d9e04097c7ba6fe/operations/58994a073d9e041ad42d9baa"
    source := "Custom Editorial"
    questions := []string{ "How do I programmatically update my Knowledge Base?" }

    // The fields of MetadataDTO are also pointers.
    metadata_name_1 := "category"
    metadata_value_1 := "api"
    metadata := []qnamaker.MetadataDTO{ qnamaker.MetadataDTO{ Name: &metadata_name_1, Value: &metadata_value_1 } }
    qna_list := []qnamaker.QnADTO{ qnamaker.QnADTO{
        ID: &id,
        Answer: &answer,
        Source: &source,
        Questions: &questions,
        Metadata: &metadata,
    } }

    urls := []string{}
    files := []qnamaker.FileDTO{}

    // The fields of CreateKbDTO are all pointers, so we get the addresses of our variables.
    createKbPayload := qnamaker.CreateKbDTO{ Name: &name, QnaList: &qna_list, Urls: &urls, Files: &files }

    // Create the KB.
    kb_result, kb_err := client.Create (ctx, createKbPayload)
    if kb_err != nil {
        log.Fatal(kb_err)
    }

    // Wait for the KB create operation to finish.
    fmt.Println ("Waiting for KB create operation to finish...")
    // Operation.OperationID is a pointer, so we need to dereference it.
    return wait_for_operation (*kb_result.OperationID)
}

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:

• add
• update
• verwijderen

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

// Update a knowledge base.
func update_kb (kb_id string) {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewKnowledgebaseClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    // Add new Q&A lists, URLs, and files to the KB.
    /*
    The fields of QnADTO are pointers, and we cannot get the addresses of literal values,
    so we declare helper variables.
    */
    id := int32(1)
    answer := "You can change the default message if you use the QnAMakerDialog. See this for details: https://docs.botframework.com/en-us/azure-bot-service/templates/qnamaker/#navtitle"
    source := "Custom Editorial"
    questions := []string{ "How can I change the default message from QnA Maker?" }

    // The fields of MetadataDTO are also pointers.
    metadata_name_1 := "category"
    metadata_value_1 := "api"
    metadata := []qnamaker.MetadataDTO{ qnamaker.MetadataDTO{ Name: &metadata_name_1, Value: &metadata_value_1 } }
    qna_list := []qnamaker.QnADTO{ qnamaker.QnADTO{
        ID: &id,
        Answer: &answer,
        Source: &source,
        Questions: &questions,
        Metadata: &metadata,
    } }

    urls := []string{}
    files := []qnamaker.FileDTO{}

    /*
    The fields of UpdateKbOperationDTOAdd, updateKBUpdatePayload, updateKBDeletePayload,
    and UpdateKbOperationDTO are all pointers, so we get the addresses of our variables.
    */
    updateKBAddPayload := qnamaker.UpdateKbOperationDTOAdd{ QnaList: &qna_list, Urls: &urls, Files: &files }

    // Update the KB name.
    name := "New KB name"
    updateKBUpdatePayload := qnamaker.UpdateKbOperationDTOUpdate { Name: &name }

    // Delete the QnaList with ID 0.
    ids := []int32{ 0 }
    updateKBDeletePayload := qnamaker.UpdateKbOperationDTODelete { Ids: &ids }

    // Bundle the add, update, and delete requests.
    updateKbPayload := qnamaker.UpdateKbOperationDTO{ Add: &updateKBAddPayload, Update: &updateKBUpdatePayload, Delete: &updateKBDeletePayload }

    // Update the KB.
    kb_result, kb_err := client.Update (ctx, kb_id, updateKbPayload)
    if kb_err != nil {
        log.Fatal(kb_err)
    }

    // Wait for the KB update operation to finish.
    fmt.Println ("Waiting for KB update operation to finish...")
    // Operation.OperationID is a pointer, so we need to dereference it.
    wait_for_operation (*kb_result.OperationID)
}

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.

// Download a knowledge base.
func download_kb (kb_id string) {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewKnowledgebaseClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    result, kb_err := client.Download (ctx, kb_id, "Prod")
    if kb_err != nil {
        log.Fatal(kb_err)
    }
    fmt.Println ("KB " + kb_id + " downloaded. It contains " + string (len(*result.QnaDocuments)) + " question/answer sets.")
}

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.

// Publish a knowledge base.
func publish_kb (kb_id string) {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewKnowledgebaseClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    _, kb_err := client.Publish (ctx, kb_id)
    if kb_err != nil {
        log.Fatal(kb_err)
    }
    fmt.Println ("KB " + kb_id + " published.")
}

Query's uitvoeren op 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 creatieclient is gemaakt.

Maak een EndpointKeysClient en gebruik de methode getKeys om een EndpointKeysDTO-object op te halen.

// Get runtime endpoint key.
func get_runtime_endpoint_key () string {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewEndpointKeysClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    result, err := client.GetKeys (ctx)
    if err != nil {
        log.Fatal(err)
    }

    return *result.PrimaryEndpointKey
}

Maak een RuntimeClient en roep de methode GenerateAnswer aan om een query uit te voeren op de Knowledge Base.

// Send a query to a knowledge base.
func query_kb (kb_id string) {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamakerruntime.NewRuntimeClient(runtime_endpoint)

    runtime_key := get_runtime_endpoint_key()
    // Set the runtime key on the client.
    headers := make(map[string]interface{})
    headers["Authorization"] = "EndpointKey " + runtime_key
    client.Authorizer = autorest.NewAPIKeyAuthorizerWithHeaders(headers)

    /*
    The fields of QueryDTO are pointers, and we cannot get the addresses of literal values,
    so we declare helper variables.
    */
    question := "Is the QnA Maker service free?"
    var answers int32
    answers = 3

    query := qnamakerruntime.QueryDTO {
        Question: &question,
        Top: &answers,
    }

    result, kb_err := client.GenerateAnswer (ctx, kb_id, query)
    if kb_err != nil {
        log.Fatal(kb_err)
    }
    fmt.Println ("Top answers:\n")
    for _, answer := range *result.Answers {
        fmt.Printf ("Answer: %s", *answer.Answer)
        fmt.Printf ("Score: %f\n", *answer.Score)
    }
}

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.

// Delete a knowledge base.
func delete_kb (kb_id string) {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    client := qnamaker.NewKnowledgebaseClient(authoring_endpoint)
    // Set the subscription key on the client.
    client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    _, kb_err := client.Delete (ctx, kb_id)
    if kb_err != nil {
        log.Fatal(kb_err)
    }
    fmt.Println ("KB " + kb_id + " delete.")
}

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.

func wait_for_operation (operation_id string) string {
    // Get the context, which is required by the SDK methods.
    ctx := context.Background()

    ops_client := qnamaker.NewOperationsClient(authoring_endpoint)
    // Set the subscription key on the client.
    ops_client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)

    result := ""
    done := false
    for done == false {
        op_result, op_err := ops_client.GetDetails (ctx, operation_id)
        if op_err != nil {
            log.Fatal(op_err)
        }
        // If the operation isn't finished, wait and query again.
        if op_result.OperationState == "Running" || op_result.OperationState == "NotStarted" {
            fmt.Println ("Operation is not finished. Waiting 10 seconds...")
            time.Sleep (time.Duration(10) * time.Second)
        } else {
            done = true
            fmt.Print ("Operation result: " + op_result.OperationState)
            fmt.Println ()
            if op_result.OperationState == "Failed" {
                handle_error (op_result)
                log.Fatal()
            } else {
                result = strings.ReplaceAll(*op_result.ResourceLocation, "/knowledgebases/", "")
            }
        }
    }
    return result
}

Fouten verwerken

In de volgende code is te zien hoe u fouten kunt afhandelen die kunnen worden geretourneerd door de functies van de SDK.

// Helper function to handle errors.
func print_inner_error (error qnamaker.InnerErrorModel) {
    if error.Code != nil {
        fmt.Println (*error.Code)
    }
    if error.InnerError != nil {
        print_inner_error (*error.InnerError)
    }
}

// Helper function to handle errors.
func print_error_details (errors []qnamaker.Error) {
    for _, err := range errors {
        if err.Message != nil {
            fmt.Println (*err.Message)
        }
        if err.Details != nil {
            print_error_details (*err.Details)
        }
        if err.InnerError != nil {
            print_inner_error (*err.InnerError)
        }
    }
}

// Helper function to handle errors.
func handle_error (result qnamaker.Operation) {
    if result.ErrorResponse != nil {
        response := *result.ErrorResponse
        if response.Error != nil {
            err := *response.Error
            if err.Message != nil {
                fmt.Println (*err.Message)
            }
            if err.Details != nil {
                print_error_details (*err.Details)
            }
            if err.InnerError != nil {
                print_inner_error (*err.InnerError)
            }
        }
    }
}

De toepassing uitvoeren

Hier volgt de belangrijkste methode voor de toepassing.

func main() {
    fmt.Println ("Creating KB...")
    kb_id := create_kb()
    fmt.Println ()

    list_kbs()
    fmt.Println ()

    fmt.Println ("Updating KB...")
    update_kb (kb_id)
    fmt.Println ()

    fmt.Println ("Publishing KB...")
    publish_kb (kb_id)
    fmt.Println ()

    fmt.Println ("Downloading KB...")
    download_kb (kb_id)
    fmt.Println ()

    fmt.Println ("Querying KB...")
    query_kb (kb_id)
    fmt.Println()

    fmt.Println ("Deleting KB...")
    delete_kb (kb_id)
    fmt.Println ()
}

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

go run kb_sample.go

De broncode voor dit voorbeeld is te vinden op GitHub

Gebruik de QnA Maker-clientbibliotheek voor Ruby 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 ophalen
• Een Knowledge Base verwijderen

Broncode van de bibliotheek (creatie) | Broncode van bibliotheek (runtime) | Pakket (creatie) | Pakket (runtime) | Ruby-samples

Vereisten

• Azure-abonnement: Krijg een gratis abonnement
• Ruby 2.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 clientbibliotheken installeren

Na de installatie van Ruby kunt u de clientbibliotheken installeren met:

gem install azure_cognitiveservices_qnamaker
gem install azure_cognitiveservices_qnamakerruntime

Een nieuwe Ruby-toepassing maken

Maak een nieuw bestand met de naam quickstart.rb en importeer de volgende bibliotheken.

require 'azure_cognitiveservices_qnamaker'
require 'azure_cognitiveservices_qnamakerruntime'
include Azure::CognitiveServices::Qnamaker::V4_0::Models
include Azure::CognitiveServices::QnamakerRuntime::V4_0::Models

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

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'
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 MsRest::ServiceClientCredentials, waarin uw sleutel zich bevindt.

Zodra de client is gemaakt, gebruikt u de methoden van de eigenschap knowledgebase 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 operations.get_details aan met de waarde operation.operation_id 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 runtime.generate_answer van de runtimeclient om een antwoord te krijgen van de Knowledge Base.

Wanneer u generate_answer aanroept, geeft u een hash door voor de optionele parameter custom_headers. Deze hash moet een sleutel Authorization en een waarde EndpointKey YOUR_ENDPOINT_KEY bevatten. Gebruik voor de waarde van YOUR_ENDPOINT_KEY de ontwerpclient om endpoint_keys.get_keys aan te roepen.

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

Instantieer een client met uw creatie-eindpunt en abonnementssleutel.

credentials = MsRestAzure::CognitiveServicesCredentials.new(subscription_key)
client = Azure::CognitiveServices::Qnamaker::V4_0::QnamakerClient.new(credentials)
client.endpoint = endpoint

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 operation_id van de geretourneerde bewerking door aan de methode operations.get_details om de status op te vragen.

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

def create_kb(client)
    print("Creating knowledge base...\n")

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

    metadata_2 = MetadataDTO.new()
    metadata_2.name = "Language"
    metadata_2.value = "Ruby"
    qna2 = QnADTO.new()
    qna2.answer = "Yes, You can use our [Ruby SDK](https://rubygems.org/gems/azure_cognitiveservices_qnamaker) to manage your knowledge base."
    qna2.questions = ["Can I program with Ruby?"]
    qna2.metadata = [metadata_1, metadata_2]

    create_kb_dto = CreateKbDTO.new()
    create_kb_dto.name = "QnA Maker Ruby SDK Quickstart"
    create_kb_dto.qna_list = [qna1, qna2]

    operation = client.knowledgebase.create(create_kb_payload=create_kb_dto)
    result = _monitor_operation(client, operation)
    knowledge_base_ID = result.resource_location.sub! "/knowledgebases/", ""

    print("Created KB with ID: #{knowledge_base_ID}\n")

    return knowledge_base_ID
end

Een kennisdatabase bijwerken

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

• add
• update
• verwijderen

Roep de methode operation_id aan en geef de geretourneerde bewerking door aan de methode operations.get_details om de status op te vragen.

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

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

    metadata_2 = MetadataDTO.new()
    metadata_2.name = "Chitchat"
    metadata_2.value = "begin"
    prompt_1 = PromptDTO.new()
    prompt_1.display_order = 1
    prompt_1.display_text = "Use REST"
    prompt_1.qna_id = 1
    prompt_2 = PromptDTO.new()
    prompt_2.display_order = 2
    prompt_2.display_text = "Use .NET NuGet package"
    prompt_2.qna_id = 2
    context = QnADTOContext.new()
    context.is_context_only = false
    context.prompts = [prompt_1, prompt_2]
    qna4 = QnADTO.new()
    qna4.answer = "Hello, please select from the list of questions or enter a new question to continue."
    qna4.questions = ["hello", "hi", "start"]
    qna4.metadata=[metadata_1, metadata_2]
    qna4.context = context

    add = UpdateKbOperationDTOAdd.new()
    add.qna_list = [qna3, qna4]
    add.urls = ["https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"]
    update_kb_operation_dto = UpdateKbOperationDTO.new()
    update_kb_operation_dto.add = add

    operation = client.knowledgebase.update(kb_id, update_kb_operation_dto)
    _monitor_operation(client, operation)
    print("Updated knowledge base.\n")
end

Een Knowledge Base downloaden

Gebruik de methode knowledgebase.download 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...\n")
    kb_data = client.knowledgebase.download(kb_id, "Prod")
    print("Downloaded knowledge base. It has #{kb_data.qna_documents.length()} QnAs.\n")
end

Een kennisdatabase publiceren

Publiceer de Knowledge Base met behulp van de methode knowledgebase.publish. 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...\n")
    client.knowledgebase.publish(kb_id)
    print("Published knowledge base.\n")
end

Een queryruntimesleutel ophalen

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 endpoint_keys.get_keys om een EndpointKeysDTO-object 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...\n")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: #{keys.primary_endpoint_key}.\n")

    return keys.primary_endpoint_key
end

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.

credentials = MsRestAzure::CognitiveServicesCredentials.new(subscription_key)
runtime_client = Azure::CognitiveServices::QnamakerRuntime::V4_0::QnamakerRuntimeClient.new(credentials)
runtime_client.runtime_endpoint = 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.

Genereer een antwoord 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.

def generate_answer(client, kb_id, endpoint_key)
    print("Querying knowledge base...\n")

    query = QueryDTO.new()
    query.question = "How do I manage my knowledgebase?"
    headers = Hash.new
    headers["Authorization"] = "EndpointKey #{endpoint_key}"
    listSearchResults = client.runtime.generate_answer(kb_id, query, custom_headers:headers)

    for i in listSearchResults.answers
        print("Answer ID: #{i.id}.\n")
        print("Answer: #{i.answer}.\n")
        print("Answer score: #{i.score}.\n")
    end
end

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 methode knowledgebase.delete met een parameter van de Knowledge Base-id.

def delete_kb(client, kb_id)
    print("Deleting knowledge base...\n")
    client.knowledgebase.delete(kb_id)
    print("Deleted knowledge base.\n")
end

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.

def _monitor_operation(client, operation)

    for i in 1..20
        if ["NotStarted", "Running"].include?(operation.operation_state)
            print("Waiting for operation: #{operation.operation_id} to complete.\n")
            sleep(10)
            operation = client.operations.get_details(operation.operation_id)
        else
            break
        end
    end
    if operation.operation_state != "Succeeded"
        raise Exception("Operation #{operation.operation_id} failed to complete.")
    end

    return operation
end

De toepassing uitvoeren

Hier volgt de belangrijkste methode voor de toepassing.

credentials = MsRestAzure::CognitiveServicesCredentials.new(subscription_key)
client = Azure::CognitiveServices::Qnamaker::V4_0::QnamakerClient.new(credentials)
client.endpoint = endpoint

kb_id = create_kb(client)
update_kb(client, kb_id)
publish_kb(client, kb_id)
download_kb(client, kb_id)

runtime_endpoint_key = getEndpointKeys_kb(client)

credentials = MsRestAzure::CognitiveServicesCredentials.new(subscription_key)
runtime_client = Azure::CognitiveServices::QnamakerRuntime::V4_0::QnamakerRuntimeClient.new(credentials)
runtime_client.runtime_endpoint = runtime_endpoint

generate_answer(runtime_client, kb_id, runtime_endpoint_key)

delete_kb(client, kb_id)

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

ruby quickstart.rb

De broncode voor dit voorbeeld is te vinden op GitHub.