Snabbstart: QnA Maker klientbibliotek

Förutsättningar

• Den aktuella versionen av cURL. Flera kommandoradsväxlar används i snabbstarterna, som anges i cURL-dokumentationen.

• Du måste ha en QnA Maker föratt kunna använda nyckeln och resursnamnet. Du angav resursnamnet när resursen skapades och sedan skapades nyckeln åt dig. Resursnamnet används som underdomän för slutpunkten. Om du vill hämta nyckeln och resursnamnet väljer du Snabbstart för resursen i Azure Portal. Resursnamnet är den första underdomänen för slutpunkts-URL:en:

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

Skapa en kunskapsbas

Om du vill skapa en kunskapsbas med REST-API:er och cURL måste du ha följande information:

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
QnA Maker resursnyckel	-h parameter för Ocp-Apim-Subscription-Key sidhuvud	Autentisera till QnA Maker tjänsten
JSON som beskriver kunskapsbas	-d Param	Exempel på JSON
Storleken på JSON i byte	-h parameter för Content-Size sidhuvud

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel och JSON-värden och storleken på JSON.

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

CURL-svaret från QnA Maker innehåller operationId , som krävs för att hämta status för åtgärden.

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

Hämta status för åtgärden

När du skapar en kunskapsbas, eftersom åtgärden är asynkron, innehåller svaret information för att fastställa statusen.

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
Åtgärds-ID	URL-väg	/operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker resursnyckel	-h parameter för Ocp-Apim-Subscription-Key sidhuvud	Autentisera till QnA Maker tjänsten

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel och åtgärds-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"

CURL-svaret innehåller statusen. Om åtgärdstillståndet har lyckats innehåller resourceLocation innehåller kunskapsbasens 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"
}

Publicera kunskapsbas

Innan du frågar kunskapsbasen måste du:

• Publicera kunskapsbas
• Hämta nyckeln för körningsslutpunkten

Den här uppgiften publicerar kunskapsbasen. Att hämta nyckeln för körningsslutpunkten är en separat uppgift.

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
QnA Maker resursnyckel	-h parameter för Ocp-Apim-Subscription-Key sidhuvud	Autentisera till QnA Maker tjänsten
Kunskapsbas-ID	URL-väg	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel och kunskapsbas-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 ''

Svarsstatusen är 204 utan resultat. Använd -v kommandoradsparametern för att se utförliga utdata för cURL-kommandot. Detta inkluderar HTTP-statusen.

Hämta den publicerade kunskapsbasens körningsslutpunktsnyckel

Innan du frågar kunskapsbasen måste du:

• Publicera kunskapsbas
• Hämta nyckeln för körningsslutpunkten

Den här uppgiften hämtar nyckeln för körningsslutpunkten. Publicering av kunskapsbasen är en separat uppgift.

Körningsslutpunktens nyckel är samma nyckel för alla kunskapsbaser som använder QnA Maker resursen.

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
QnA Maker resursnyckel	-h parameter för Ocp-Apim-Subscription-Key sidhuvud	Autentisera till QnA Maker tjänsten

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel.

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"

CURL-svaret innehåller körningsslutpunktsnycklarna. Använd bara en av nycklarna när du frågar för att få ett svar från kunskapsbasen.

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

Fråga efter svar från publicerad kunskapsbas

Att få ett svar från kunskapen görs från en separat körning än att hantera kunskapsbasen. Eftersom det är en separat körning måste du autentisera med en körningsnyckel.

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
QnA Maker för körning	-h parameter för Authorization sidhuvud	Nyckeln är en del av en sträng som innehåller ordet Endpointkey . Autentisera till QnA Maker tjänsten
Kunskapsbas-ID	URL-väg	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON som beskriver frågan	-d Param	Parametrar för begärandetext och exempel på JSON
Storleken på JSON i byte	-h parameter för Content-Size sidhuvud

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel och kunskapsbas-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="}'

Ett lyckat svar innehåller det översta svaret tillsammans med annan information som ett klientprogram, till exempel en chattrobot, behöver visa ett svar för användaren.

Ta bort kunskapsbas

När du är klar med kunskapsbasen tar du bort den.

Information	cURL-konfiguration	Syfte
QnA Maker resursnamn	URL	används för att skapa URL
QnA Maker resursnyckel	-h parameter för Ocp-Apim-Subscription-Key sidhuvud	Autentisera till QnA Maker tjänsten
Kunskapsbas-ID	URL-väg	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Kommandot cURL körs från ett BASH-gränssnitt. Redigera det här kommandot med ditt eget resursnamn, resursnyckel och kunskapsbas-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"

Svarsstatusen är 204 utan resultat. Använd -v kommandoradsparametern för att se utförliga utdata för cURL-kommandot. Detta inkluderar HTTP-statusen.

Ytterligare resurser

• Författande Referensdokumentation
• Runtime Referensdokumentation
• Exempel på BASH-skript med cURL

Använd QnA Maker för .NET för att:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få ett svar från en kunskapsbas
• Ta bort en kunskapsbas

Referensdokumentation | Bibliotekskällkod | Paket (NuGet) | C#-exempel

Förutsättningar

• Azure-prenumeration – Skapa en kostnadsfritt
• Den Visual Studio IDE eller den aktuella versionen av .NET Core.
• När du har din Azure-prenumeration skapar du en QnA Maker-resurs i Azure Portal för att hämta din redigeringsnyckel och resursnamn. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och resursnamnet från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Klistra in nyckeln och resursnamnet i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och senare uppgradera till en betald nivå för produktion.

Inrätta

CLI

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du kommandot för att skapa en dotnet new ny konsolapp med namnet qna-maker-quickstart . Det här kommandot skapar ett enkelt "Hello World" C#-projekt med en enda källfil: program.cs.

dotnet new console -n qna-maker-quickstart

Ändra katalogen till den nyligen skapade appmappen. Du kan skapa programmet med:

dotnet build

Build-utdata får inte innehålla några varningar eller fel.

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

I programkatalogen installerar du QnA Maker för .NET med följande kommando:

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

Använda direktiv

Öppna filen program.cs från projektkatalogen och lägg till följande using -direktiv:

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

Prenumerationsnyckel och resursslutpunkter

I programmets -metod lägger du till variabler och kod, som visas i följande avsnitt, för att använda Main de vanliga uppgifterna i den här snabbstarten.

• Vi använder prenumerationsnyckel och redigeringsnyckel synonymt. Mer information om redigeringsnyckeln finns i Nycklar i QnA Maker.

• Värdet för QNA_MAKER_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumerationen) och QnA Maker slutpunkten.

• Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Exportera mall under Automation för att hitta körningsslutpunkten.

• Överväg att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter för produktion. Azure Key Vault tillhandahåller till exempel säker nyckellagring.

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

Objektmodeller

QnA Maker två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av API:et Train (som en del av aktiv inlärning).

Använda det här exemplet i kunskaps basen

Kunskaps basen i den här snabb starten börjar med 2 konversationer QnA-par, detta görs i syfte att förenkla exemplet och ha mycket förutsägbara ID: n som ska användas i uppdaterings metoden, som kopplar uppföljnings frågor med frågor till nya par. Detta har planer ATS och implementerats i en speciell ordning för den här snabb starten.

Om du planerar att utveckla din kunskaps bas över tid med uppföljnings-prompter som är beroende av befintliga QnA-par kan du välja:

• För större kunskaps basfrågor hanterar du kunskaps basen i ett text redigerings-eller TSV-verktyg som stöder Automation och ersätter sedan kunskaps basen helt samtidigt med en uppdatering.
• För mindre kunskaps baser kan du hantera uppföljnings anvisningarna helt i QnA Maker Portal.

Information om de QnA-par som används i den här snabb starten:

• Typer av QnA-par – det finns två typer av QnA-par i den här kunskaps basen efter uppdateringen: ChitChat och domänbaserad information. Detta är vanligt om din kunskaps bank är kopplad till ett konversations program, till exempel en chattrobot.
• Även om kunskaps Svaren kan filtreras efter metadata eller använda Uppföljnings frågor, visas inte den här snabb starten. Leta efter dessa språk oberoende generateAnswer-exempel här.
• Svars texten är markdown och kan innehålla en mängd olika markdown , t. ex. bilder (offentligt tillgängliga Internetbaserade avbildningar), länkar (till offentligt tillgängliga URL: er) och punkter, men den här snabb starten använder inte den sorten.

QnAMakerClient-objektmodell

Redigeringsklienten QnA Maker ett QnAMakerClient-objekt som autentiserar till Azure med hjälp av Microsoft.Rest.ServiceClientCredentials, som innehåller din nyckel.

När klienten har skapats använder du egenskapen Kunskapsbas för att skapa, hantera och publicera kunskapsbasen.

Hantera kunskapsbasen genom att skicka ett JSON-objekt. För omedelbara åtgärder returnerar en metod vanligtvis ett JSON-objekt som anger status. För långvariga åtgärder är svaret åtgärds-ID:t. Anropa klienten. Operations.GetDetailsAsync-metoden med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

Förutsägelseklienten QnA Maker är ett QnAMakerRuntimeClient-objekt som autentiserar till Azure med hjälp av Microsoft.Rest.ServiceClientCredentials, som innehåller din förutsägelsekörningsnyckel som returneras från redigeringsklientanropet när kunskapsbasen har client.EndpointKeys.GetKeys publicerats.

Använd metoden GenerateAnswer för att få ett svar från frågekörningen.

Kodexempel

De här kodfragmenten visar hur du gör följande med QnA Maker klientbibliotek för .NET:

• Autentisera redigeringsklienten
• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Ladda ned en kunskapsbas
• Publicera en kunskapsbas
• Ta bort en kunskapsbas
• Hämta nyckel för frågekörning
• Hämta status för en åtgärd
• Autentisera frågekörningsklienten
• Generera ett svar från kunskapsbasen

Autentisera klienten för redigering av kunskapsbasen

Instansiera ett klientobjekt med din nyckel och använd det med din resurs för att konstruera slutpunkten för att skapa en QnAMakerClient med din slutpunkt och nyckel. Skapa ett ServiceClientCredentials-objekt.

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

Skapa en kunskapsbas

En kunskapsbas lagrar par med frågor och svar för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet och den offentliga URL:en för att nå filen.
• För URL:er använder du en lista över strängar för att representera offentligt tillgängliga URL:er.

Skapandesteget innehåller även egenskaper för kunskapsbasen:

• defaultAnswerUsedForExtraction – vad som returneras när inget svar hittas
• enableHierarchicalExtraction – skapa automatiskt promptrelationer mellan extraherade QnA-par
• language – när du skapar den första kunskapsbasen för en resurs anger du det språk som ska användas i Azure Search-indexet.

Anropa metoden CreateAsync och skicka sedan det returnerade åtgärds-ID:t till metoden MonitorOperation för att avssöka efter status.

Den sista raden i följande kod returnerar kunskapsbasens ID från svaret från MonitorOperation.

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

Se till att inkludera MonitorOperation funktionen, som refereras i koden ovan, för att skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka kunskapsbas-ID:t och ett UpdatekbOperationDTO som innehåller lägg till,uppdatera och ta bort DTO-objekt till Metoden UpdateAsync. Använd metoden MonitorOperation för att avgöra om uppdateringen lyckades.

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

Se till att inkludera MonitorOperation funktionen, som refereras i koden ovan, för att kunna uppdatera en kunskapsbas.

Ladda ned en kunskapsbas

Använd metoden DownloadAsync för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en fil.

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
}

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av metoden PublishAsync. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den på din slutpunkt. Det här är ett nödvändigt steg för att köra frågor mot kunskapsbasen.

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

Hämta nyckel för frågekörning

När en kunskapsbas har publicerats behöver du frågekörningsnyckeln för att köra frågor mot körningen. Det här är inte samma nyckel som användes för att skapa det ursprungliga klientobjektet.

Använd metoden EndpointKeys för att hämta klassen EndpointKeysDTO.

Använd någon av de nyckelegenskaper som returneras i -objektet för att fråga kunskapsbasen.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

En körningsnyckel krävs för att köra frågor mot kunskapsbasen.

Autentisera körningen för att generera ett svar

Skapa en QnAMakerRuntimeClient för att köra frågor mot kunskapsbasen för att generera ett svar eller träna från aktiv inlärning.

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

Använd QnAMakerRuntimeClient för att:

• få ett svar från kunskapsbasen
• för att skicka nya föreslagna frågor till kunskapsbasen för aktiv inlärning.

Generera ett svar från kunskapsbasen

Generera ett svar från en publicerad kunskapsbas med hjälp av RuntimeClient. GenerateAnswerAsync-metod. Den här metoden accepterar kunskapsbas-ID:t och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel Top och Context som ska användas i chattroboten.

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
}

Det här är ett enkelt exempel som frågar kunskapsbasen. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med metoden DeleteAsync med en parameter för kunskapsbasens ID.

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

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt med tid så att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med omprövningslogik) för att fastställa status för den ursprungliga metoden.

Loopen och Task.Delay i följande kodblock används för att simulera omprövningslogik. Dessa bör ersättas med din egen logik för omförsök.

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

Kör programmet

Kör programmet med kommandot dotnet run från programkatalogen.

dotnet run

Källkoden för det här exemplet finns på GitHub.

Använd QnA Maker klientbibliotek för att Node.js:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få ett svar från en kunskapsbas
• Ta bort kunskapsbas

Referensdokumentation | Bibliotekskällkod | Paket (npm) | Node.js exempel

Förutsättningar

• Azure-prenumeration – Skapa en kostnadsfritt
• Den aktuella versionen av Node.js.
• När du har din Azure-prenumeration skapar du QnA Maker resurs i Azure Portal för att hämta din redigeringsnyckel och resurs. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och resursnamnet från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Klistra in nyckeln och resursnamnet i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och senare uppgradera till en betald nivå för produktion.

Inrätta

Skapa ett nytt Node.js-program

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) skapar du en ny katalog för din app och navigerar till den.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Kör kommandot npm init -y för att skapa ett nodprogram med en package.json -fil.

npm init -y

Installera klientbiblioteket

Installera följande NPM-paket:

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

Appens package.json fil uppdateras med beroendena.

Skapa en fil med index.js och importera följande bibliotek:

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

Skapa en variabel för resursens Azure-nyckel och resursnamn.

• Vi använder prenumerationsnyckel och redigeringsnyckel synonymt. Mer information om redigeringsnyckeln finns i Nycklar i QnA Maker.

• Värdet för QNA_MAKER_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumerationen) och QnA Maker slutpunkten.

• Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Exportera mall under Automation för att hitta körningsslutpunkten.

• Överväg att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter för produktion. Azure Key Vault tillhandahåller till exempel säker nyckellagring.

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

Objektmodeller

QnA Maker två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med API:et GenerateAnswer och skicka nya föreslagna frågor med hjälp av API:et Train (som en del av aktiv inlärning).

QnAMakerClient-objektmodell

Redigeringsklienten QnA Maker ett QnAMakerClient-objekt som autentiserar till Azure med dina autentiseringsuppgifter, som innehåller din nyckel.

När klienten har skapats använder du kunskapsbasen för att skapa, hantera och publicera din kunskapsbas.

Hantera kunskapsbasen genom att skicka ett JSON-objekt. För omedelbara åtgärder returnerar en metod vanligtvis ett JSON-objekt som anger status. För långvariga åtgärder är svaret åtgärds-ID:t. Anropa metoden client.operations.getDetails med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

Förutsägelseklienten QnA Maker är ett QnAMakerRuntimeClient-objekt som autentiserar till Azure med hjälp av Microsoft.Rest.ServiceClientCredentials, som innehåller din förutsägelsekörningsnyckel som returneras från redigeringsklientanropet, klienten. EndpointKeys.getKeys när kunskapsbasen har publicerats.

Kodexempel

Dessa kodfragment visar hur du gör följande med QnA Maker klientbibliotek för .NET:

• Autentisera redigeringsklienten
• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Ladda ned en kunskapsbas
• Publicera en kunskapsbas
• Ta bort en kunskapsbas
• Hämta nyckel för frågekörning
• Hämta status för en åtgärd
• Autentisera frågekörningsklienten
• Generera ett svar från kunskapsbasen

Autentisera klienten för redigering av kunskapsbasen

Instansiera en klient med din slutpunkt och nyckel. Skapa ett ServiceClientCredentials-objekt med din nyckel och använd det med slutpunkten för att skapa ett QnAMakerClient-objekt.

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

Skapa en kunskapsbas

En kunskapsbas lagrar frågor och svar-par för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet och den offentliga URL:en för att nå filen.
• För URL:er använder du en lista över strängar för att representera offentligt tillgängliga URL:er.

Skapandesteget innehåller även egenskaper för kunskapsbasen:

• defaultAnswerUsedForExtraction – vad returneras när inget svar hittas
• enableHierarchicalExtraction – skapa automatiskt promptrelationer mellan extraherade QnA-par
• language – när du skapar den första kunskapsbasen för en resurs anger du det språk som ska användas i Azure Search-indexet.

Anropa create-metoden med informationen om kunskapsbasen. Kunskapsbasens information är i princip ett JSON-objekt.

När metoden create returnerar skickar du det returnerade åtgärds-ID:t till wait_for_operation-metoden för att avssöka efter status. Den wait_for_operation metoden returnerar när åtgärden har slutförts. Parsa resourceLocation rubrikvärdet för den returnerade åtgärden för att hämta det nya kunskapsbas-ID:t.

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

Se till att inkludera wait_for_operation funktionen, som refereras i koden ovan, för att skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka kunskapsbas-ID:t och ett UpdateKbOperationDTO som innehåller lägg till, uppdateraoch ta bort DTO-objekt till uppdateringsmetoden. DTO:erna är också I princip JSON-objekt. Använd wait_for_operation för att avgöra om uppdateringen lyckades.

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
}

Se till att inkludera wait_for_operation funktionen, som refereras i koden ovan, för att kunna uppdatera en kunskapsbas.

Ladda ned en kunskapsbas

Använd nedladdningsmetoden för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en TSV-fil.

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
}

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den vid en slutpunkt. Kontrollera HTTP-svarskoden för att verifiera att publiceringen lyckades.

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
}

Köra frågor mot en kunskapsbas

Hämta nyckel för frågekörning

När en kunskapsbas har publicerats behöver du frågekörningsnyckeln för att köra frågor mot körningen. Det här är inte samma nyckel som användes för att skapa det ursprungliga klientobjektet.

Använd metoden EndpointKeys.getKeys för att hämta klassen EndpointKeysDTO.

Använd någon av de nyckelegenskaper som returneras i -objektet för att fråga kunskapsbasen.

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
}

Autentisera körningen för att generera ett svar

Skapa en QnAMakerRuntimeClient för att fråga kunskapsbasen för att generera ett svar eller träna från aktiv inlärning.

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

Använd QnAMakerRuntimeClient för att få ett svar från kunskapen eller för att skicka nya föreslagna frågor till kunskapsbasen för aktiv inlärning.

Generera ett svar från kunskapsbasen

Generera ett svar från en publicerad kunskapsbas med hjälp av metoden RuntimeClient.runtime.generateAnswer. Den här metoden accepterar kunskapsbas-ID:t och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel Top och Context som ska användas i chattroboten.

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

}

Det här är ett enkelt exempel på frågor mot kunskapsbasen. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med delete-metoden med en parameter för kunskapsbasens 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
}

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt lång tid att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med logik för omförsök) för att fastställa status för den ursprungliga metoden.

DelayTimer-anropet i följande kodblock används för att simulera logiken för omförsök. Ersätt detta med din egen omprövningslogik.

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

Kör programmet

Kör programmet med node index.js kommandot från programkatalogen.

node index.js

Källkoden för det här exemplet finns på GitHub.

Använd QnA Maker för Python för att:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få ett svar från en kunskapsbas
• Ta bort kunskapsbas

Referensdokumentation | Bibliotekskällkod | Paket (PyPi) | Python-exempel

Förutsättningar

• Azure-prenumeration – Skapa en kostnadsfritt
• Python 3.x
• När du har din Azure-prenumeration skapar du QnA Maker resurs i Azure Portal för att hämta din redigeringsnyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Du klistrar in nyckeln och slutpunkten i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och senare uppgradera till en betald nivå för produktion.

Inrätta

Installera klientbiblioteket

När du har installerat Python kan du installera klientbiblioteket med:

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

Skapa ett nytt Python-program

Skapa en ny Python-fil med quickstart-file.py namnet och importera följande bibliotek.

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

Skapa variabler för resursens Azure-slutpunkt och nyckel.

• Vi använder prenumerationsnyckel och redigeringsnyckel synonymt. Mer information om redigeringsnyckeln finns i Nycklar i QnA Maker.

• Värdet för QNA_MAKER_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumerationen) och QnA Maker slutpunkten.

• Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Exportera mall under Automation för att hitta körningsslutpunkten.

• Överväg att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter för produktion. Azure Key Vault tillhandahåller till exempel säker nyckellagring.

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'

Objektmodeller

QnA Maker använder två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av API:et Train (som en del av aktiv inlärning).

Använda det här exemplet i kunskaps basen

Kunskaps basen i den här snabb starten börjar med 2 konversationer QnA-par, detta görs i syfte att förenkla exemplet och ha mycket förutsägbara ID: n som ska användas i uppdaterings metoden, som kopplar uppföljnings frågor med frågor till nya par. Detta har planer ATS och implementerats i en speciell ordning för den här snabb starten.

Om du planerar att utveckla din kunskaps bas över tid med uppföljnings-prompter som är beroende av befintliga QnA-par kan du välja:

• För större kunskaps basfrågor hanterar du kunskaps basen i ett text redigerings-eller TSV-verktyg som stöder Automation och ersätter sedan kunskaps basen helt samtidigt med en uppdatering.
• För mindre kunskaps baser kan du hantera uppföljnings anvisningarna helt i QnA Maker Portal.

Information om de QnA-par som används i den här snabb starten:

• Typer av QnA-par – det finns två typer av QnA-par i den här kunskaps basen efter uppdateringen: ChitChat och domänbaserad information. Detta är vanligt om din kunskaps bank är kopplad till ett konversations program, till exempel en chattrobot.
• Även om kunskaps Svaren kan filtreras efter metadata eller använda Uppföljnings frågor, visas inte den här snabb starten. Leta efter dessa språk oberoende generateAnswer-exempel här.
• Svars texten är markdown och kan innehålla en mängd olika markdown , t. ex. bilder (offentligt tillgängliga Internetbaserade avbildningar), länkar (till offentligt tillgängliga URL: er) och punkter, men den här snabb starten använder inte den sorten.

QnAMakerClient-objektmodell

Redigeringsklienten QnA Maker ett QnAMakerClient-objekt som autentiserar till Azure med hjälp av Microsoft.Rest.ServiceClientCredentials, som innehåller din nyckel.

När klienten har skapats använder du egenskapen Kunskapsbas för att skapa, hantera och publicera kunskapsbasen.

Hantera kunskapsbasen genom att skicka ett JSON-objekt. För omedelbara åtgärder returnerar en metod vanligtvis ett JSON-objekt som anger status. För långvariga åtgärder är svaret åtgärds-ID:t. Anropa operations.get_details med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

Förutsägelseklienten QnA Maker är ett objekt som autentiserar till Azure med hjälp av QnAMakerRuntimeClient Microsoft.Rest.ServiceClientCredentials, som innehåller din förutsägelsekörningsnyckel som returneras från redigeringsklientanropet, klienten. EndpointKeysOperations.get_keys när kunskapsbasen har publicerats.

Använd metoden generate_answer för att få ett svar från frågekörningen.

Autentisera klienten för redigering av kunskapsbasen

Instansiera en klient med din slutpunkt och nyckel. Skapa ett CognitiveServicesCredentials-objekt med din nyckel och använd det med slutpunkten för att skapa ett QnAMakerClient-objekt.

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

Skapa en kunskapsbas

Använd klientobjektet för att hämta ett objekt för kunskapsbasåtgärder.

En kunskapsbas lagrar par med frågor och svar för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet och den offentliga URL:en för att nå filen.
• För URL:er använder du en lista över strängar för att representera offentligt tillgängliga URL:er.

Anropa create-metoden och skicka sedan det returnerade åtgärds-ID:t till metoden Operations.getDetails för att avskanna efter status.

Den sista raden i följande kod returnerar kunskapsbasens ID från svaret från MonitorOperation.

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

Se till att inkludera _monitor_operation funktionen, som refereras i koden ovan, för att skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka kunskapsbas-ID:t och ett UpdateKbOperationDTO som innehåller lägg till,uppdatera och ta bort DTO-objekt till uppdateringsmetoden. Använd metoden Operation.getDetail för att avgöra om uppdateringen lyckades.

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

Se till att inkludera _monitor_operation funktionen, som refereras i koden ovan, för att kunna uppdatera en kunskapsbas.

Ladda ned en kunskapsbas

Använd nedladdningsmetoden för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en TSV-fil.

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

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den på en slutpunkt.

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

Köra frågor mot en kunskapsbas

Hämta nyckel för frågekörning

När en kunskapsbas har publicerats behöver du frågekörningsnyckeln för att köra frågor mot körningen. Det här är inte samma nyckel som användes för att skapa det ursprungliga klientobjektet.

Använd metoden EndpointKeysOperations.get_keys för att hämta klassen EndpointKeysDTO.

Använd någon av de nyckelegenskaper som returneras i -objektet för att fråga kunskapsbasen.

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

Autentisera körningen för att generera ett svar

Skapa en QnAMakerRuntimeClient för att fråga kunskapsbasen för att generera ett svar eller träna från aktiv inlärning.

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

Använd QnAMakerRuntimeClient för att få ett svar från kunskapen eller för att skicka nya föreslagna frågor till kunskapsbasen för aktiv inlärning.

Generera ett svar från kunskapsbasen

Generera ett svar från en publicerad kunskapsbas med hjälp QnAMakerRuntimeClient.runtime.generate_answer metod. Den här metoden accepterar kunskapsbas-ID:t och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel Top och Context som ska användas i chattroboten.

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

Det här är ett enkelt exempel på frågor mot kunskapsbasen. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med delete-metoden med en parameter för kunskapsbasens ID.

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

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt lång tid att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med logik för omförsök) för att fastställa status för den ursprungliga metoden.

SetTimeout-anropet i följande kodblock används för att simulera asynkron kod. Ersätt detta med logik för omförsök.

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

Kör programmet

Kör programmet med python-kommandot i snabbstartsfilen.

python quickstart-file.py

Källkoden för det här exemplet finns på GitHub.

Använd QnA Maker för Java för att:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få ett svar från en kunskapsbas
• Ta bort kunskapsbas

Bibliotekskällkod | Paket | Exempel

Förutsättningar

• Azure-prenumeration – Skapa en utan kostnad
• JDK
• När du har din Azure-prenumeration skapar du QnA Maker resurs i Azure Portal för att hämta din redigeringsnyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Klistra in nyckeln och slutpunkten i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.

Inrätta

Installera klientbiblioteken

När du har installerat Java kan du installera klientbiblioteken med hjälp av Maven från MVN-lagringsplatsen.

Skapa ett nytt Java-program

Skapa en ny fil med quickstart.java namnet och importera följande bibliotek.

/* 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.*;

Skapa variabler för resursens Azure-slutpunkt och nyckel.

• Vi använder prenumerationsnyckel och redigeringsnyckel synonymt. Mer information om redigeringsnyckeln finns i Nycklar i QnA Maker.

• Värdet för QNA_MAKER_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumerationen) och QnA Maker slutpunkten.

• Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net . Gå till Azure Portal och leta upp QnA Maker som du skapade i förutsättningarna. Välj sidan Exportera mall under Automation för att hitta körningsslutpunkten.

• Överväg att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter för produktion. Azure Key Vault tillhandahåller till exempel säker nyckellagring.

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

Objektmodeller

QnA Maker två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med API:et GenerateAnswer och skicka nya föreslagna frågor med hjälp av API:et Train (som en del av aktiv inlärning).

Använda det här exemplet i kunskaps basen

Kunskaps basen i den här snabb starten börjar med 2 konversationer QnA-par, detta görs i syfte att förenkla exemplet och ha mycket förutsägbara ID: n som ska användas i uppdaterings metoden, som kopplar uppföljnings frågor med frågor till nya par. Detta har planer ATS och implementerats i en speciell ordning för den här snabb starten.

Om du planerar att utveckla din kunskaps bas över tid med uppföljnings-prompter som är beroende av befintliga QnA-par kan du välja:

• För större kunskaps basfrågor hanterar du kunskaps basen i ett text redigerings-eller TSV-verktyg som stöder Automation och ersätter sedan kunskaps basen helt samtidigt med en uppdatering.
• För mindre kunskaps baser kan du hantera uppföljnings anvisningarna helt i QnA Maker Portal.

Information om de QnA-par som används i den här snabb starten:

• Typer av QnA-par – det finns två typer av QnA-par i den här kunskaps basen efter uppdateringen: ChitChat och domänbaserad information. Detta är vanligt om din kunskaps bank är kopplad till ett konversations program, till exempel en chattrobot.
• Även om kunskaps Svaren kan filtreras efter metadata eller använda Uppföljnings frågor, visas inte den här snabb starten. Leta efter dessa språk oberoende generateAnswer-exempel här.
• Svars texten är markdown och kan innehålla en mängd olika markdown , t. ex. bilder (offentligt tillgängliga Internetbaserade avbildningar), länkar (till offentligt tillgängliga URL: er) och punkter, men den här snabb starten använder inte den sorten.

QnAMakerClient-objektmodell

Redigeringsklienten QnA Maker ett QnAMakerClient-objekt som autentiserar till Azure med hjälp av MsRest::ServiceClientCredentials, som innehåller din nyckel.

När klienten har skapats använder du metoderna i klientens knowledgebases-egenskap för att skapa, hantera och publicera kunskapsbasen.

För omedelbara åtgärder returnerar en metod vanligtvis resultatet, om det finns någon. För långvariga åtgärder är svaret ett åtgärdsobjekt. Anropa metoden getDetails med värdet operation.operationId för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

Körningsklienten QnA Maker ett QnAMakerRuntimeClient-objekt.

När du har publicerat kunskapsbasen med redigeringsklienten använder du runtime-klientens generateAnswer-metod för att få ett svar från kunskapsbasen.

Du skapar en körningsklient genom att anropa QnAMakerRuntimeManager.authenticate och skicka en nyckel för körningsslutpunkten. Hämta nyckeln för körningsslutpunkten genom att använda redigeringsklienten för att anropa getKeys.

Autentisera klienten för redigering av kunskapsbasen

Instansiera en klient med redigeringsslutpunkten och prenumerationsnyckeln.

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

Skapa en kunskapsbas

En kunskapsbas lagrar frågor och svar-par för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet och den offentliga URL:en för att nå filen.
• För URL:er använder du en lista över strängar för att representera offentligt tillgängliga URL:er.

Anropa create-metoden och skicka sedan operationId egenskapen för den returnerade åtgärden till metoden getDetails för att avskanna efter status.

Den sista raden i följande kod returnerar kunskapsbasens ID.

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

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att anropa uppdatering och skicka in kunskapsbasens ID och ett UpdateKbOperationDTO-objekt. Det objektet kan i sin tur innehålla:

• Add
• Uppdatering
• Ta bort

Skicka egenskapen operationId för den returnerade åtgärden till metoden getDetails för att avskanna efter status.

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

Ladda ned en kunskapsbas

Använd nedladdningsmetoden för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en TSV-fil.

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

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den vid en slutpunkt.

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

Generera ett svar från kunskapsbasen

När en kunskapsbas har publicerats behöver du nyckeln för körningsslutpunkten för att köra frågor mot kunskapsbasen. Detta är inte samma som prenumerationsnyckeln som användes för att skapa redigeringsklienten.

Använd metoden getKeys för att hämta ett EndpointKeysDTO-objekt.

Skapa en körningsklient genom att anropa QnAMakerRuntimeManager.authenticate och skicka en nyckel för körningsslutpunkten från EndpointKeysDTO-objektet.

Generera ett svar från en publicerad kunskapsbas med hjälp av metoden generateAnswer. Den här metoden accepterar kunskapsbas-ID:t och ett QueryDTO-objekt.

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

Det här är ett enkelt exempel på att köra frågor mot en kunskapsbas. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med delete-metoden med en parameter för kunskapsbasens ID.

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

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt med tid så att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med omprövningslogik) för att fastställa status för den ursprungliga metoden.

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

Kör programmet

Här är huvudmetoden för programmet.

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

Kör programmet på följande sätt. Detta förutsätter att klassnamnet är Quickstart och att dina beroenden finns i en undermapp med namnet lib under den aktuella mappen.

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

Källkoden för det här exemplet finns på GitHub.

Använd QnA Maker klientbibliotek för Go för att:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få svar
• Ta bort kunskapsbas

Referens (redigering) | Referens (körning) | Bibliotekskällkod (redigering) | Bibliotekskällkod (runtime) | Exempel

Förutsättningar

• Azure-prenumeration – Skapa en kostnadsfritt
• Kör
• När du har din Azure-prenumeration skapar du QnA Maker resurs i Azure Portal för att hämta din redigeringsnyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Klistra in nyckeln och slutpunkten i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och senare uppgradera till en betald nivå för produktion.

Inrätta

Skapa ett nytt Go-program

Skapa en ny fil med kb_sample.go namnet och importera följande bibliotek.

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

Skapa variabler för resursens Azure-slutpunkt och nyckel.

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"

Objektmodeller

QnA Maker två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av API:et Train (som en del av aktiv inlärning).

Använda det här exemplet i kunskaps basen

Kunskaps basen i den här snabb starten börjar med 2 konversationer QnA-par, detta görs i syfte att förenkla exemplet och ha mycket förutsägbara ID: n som ska användas i uppdaterings metoden, som kopplar uppföljnings frågor med frågor till nya par. Detta har planer ATS och implementerats i en speciell ordning för den här snabb starten.

Om du planerar att utveckla din kunskaps bas över tid med uppföljnings-prompter som är beroende av befintliga QnA-par kan du välja:

• För större kunskaps basfrågor hanterar du kunskaps basen i ett text redigerings-eller TSV-verktyg som stöder Automation och ersätter sedan kunskaps basen helt samtidigt med en uppdatering.
• För mindre kunskaps baser kan du hantera uppföljnings anvisningarna helt i QnA Maker Portal.

Information om de QnA-par som används i den här snabb starten:

• Typer av QnA-par – det finns två typer av QnA-par i den här kunskaps basen efter uppdateringen: ChitChat och domänbaserad information. Detta är vanligt om din kunskaps bank är kopplad till ett konversations program, till exempel en chattrobot.
• Även om kunskaps Svaren kan filtreras efter metadata eller använda Uppföljnings frågor, visas inte den här snabb starten. Leta efter dessa språk oberoende generateAnswer-exempel här.
• Svars texten är markdown och kan innehålla en mängd olika markdown , t. ex. bilder (offentligt tillgängliga Internetbaserade avbildningar), länkar (till offentligt tillgängliga URL: er) och punkter, men den här snabb starten använder inte den sorten.

QnAMakerClient-objektmodell

Använd KnowledgebaseClient för att skapa, uppdatera, publicera, ladda ned och ta bort din kunskapsbas. Dessa åtgärder beskrivs i följande avsnitt.

Använd OperationsClient för att kontrollera status för långvariga åtgärder, till exempel skapa och uppdatera kunskapsbaser.

QnAMakerRuntimeClient-objektmodell

När du har publicerat kunskapsbasen använder du RuntimeClient för att köra frågor mot kunskapsbasen. Den här åtgärden finns i Fråga kunskapsbasen.

Skapa en kunskapsbas

En kunskapsbas lagrar par med frågor och svar för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet och den offentliga URL:en för att nå filen.
• För URL:er använder du en lista med strängar för att representera offentligt tillgängliga URL:er.

Anropa create-metoden och skicka sedan operationId egenskapen för den returnerade åtgärden till metoden getDetails för att avskanna efter status.

Den sista raden i följande kod returnerar kunskapsbasens ID.

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

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att anropa uppdatering och skicka in kunskapsbasens ID och ett UpdateKbOperationDTO-objekt. Objektet kan i sin tur innehålla:

• Add
• Uppdatering
• Ta bort

Skicka egenskapen operationId för den returnerade åtgärden till metoden getDetails för att avskanna efter status.

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

Ladda ned en kunskapsbas

Använd nedladdningsmetoden för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en TSV-fil.

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

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den på en slutpunkt.

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

Köra frågor mot kunskapsbasen

När en kunskapsbas har publicerats behöver du nyckeln för körningsslutpunkten för att köra frågor mot kunskapen. Detta är inte samma som prenumerationsnyckeln som används för att skapa redigeringsklienten.

Skapa en EndpointKeysClient och använd metoden getKeys för att hämta ett EndpointKeysDTO-objekt.

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

Skapa en RuntimeClient och anropa metoden GenerateAnswer för att fråga kunskapsbasen.

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

Det här är ett enkelt exempel på att köra frågor mot en kunskapsbas. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med delete-metoden med en parameter för kunskapsbasens 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.")
}

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt lång tid att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med omprövningslogik) för att fastställa status för den ursprungliga metoden.

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
}

Hantera fel

Följande kod visar hur du hanterar fel som kan returneras av SDK:ns funktioner.

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

Kör programmet

Här är huvudmetoden för programmet.

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

Kör programmet med kommandot go i snabbstartsfilen.

go run kb_sample.go

Källkoden för det här exemplet finns på GitHub

Använd QnA Maker för Ruby för att:

• Skapa en kunskapsbas
• Uppdatera en kunskapsbas
• Publicera en kunskapsbas
• Hämta slutpunktsnyckel för förutsägelsekörning
• Vänta på en långvarig uppgift
• Ladda ned en kunskapsbas
• Få svar
• Ta bort kunskapsbas

Bibliotekskällkod (redigering) | Bibliotekskällkod (runtime) | Paket (redigering) | Paket (körning) | Ruby-exempel

Förutsättningar

• Azure-prenumeration – Skapa en utan kostnad
• Ruby 2.x
• När du har din Azure-prenumeration skapar du QnA Maker resurs i Azure Portal för att hämta din redigeringsnyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
  • Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till QnA Maker-API:et. Du klistrar in nyckeln och slutpunkten i koden nedan senare i snabbstarten.
  • Du kan använda den kostnadsfria prisnivån ( F0 ) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.

Inrätta

Installera klientbiblioteken

När du har installerat Ruby kan du installera klientbiblioteken med:

gem install azure_cognitiveservices_qnamaker
gem install azure_cognitiveservices_qnamakerruntime

Skapa ett nytt Ruby-program

Skapa en ny fil med quickstart.rb namnet och importera följande bibliotek.

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

Skapa variabler för resursens Azure-slutpunkt och nyckel.

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'

Objektmodeller

QnA Maker två olika objektmodeller:

• QnAMakerClient är objektet för att skapa, hantera, publicera och ladda ned kunskapsbasen.
• QnAMakerRuntime är objektet för att fråga kunskapsbasen med API:et GenerateAnswer och skicka nya föreslagna frågor med hjälp av Api:et Train (som en del av aktiv inlärning).

Använda det här exemplet i kunskaps basen

Kunskaps basen i den här snabb starten börjar med 2 konversationer QnA-par, detta görs i syfte att förenkla exemplet och ha mycket förutsägbara ID: n som ska användas i uppdaterings metoden, som kopplar uppföljnings frågor med frågor till nya par. Detta har planer ATS och implementerats i en speciell ordning för den här snabb starten.

Om du planerar att utveckla din kunskaps bas över tid med uppföljnings-prompter som är beroende av befintliga QnA-par kan du välja:

• För större kunskaps basfrågor hanterar du kunskaps basen i ett text redigerings-eller TSV-verktyg som stöder Automation och ersätter sedan kunskaps basen helt samtidigt med en uppdatering.
• För mindre kunskaps baser kan du hantera uppföljnings anvisningarna helt i QnA Maker Portal.

Information om de QnA-par som används i den här snabb starten:

• Typer av QnA-par – det finns två typer av QnA-par i den här kunskaps basen efter uppdateringen: ChitChat och domänbaserad information. Detta är vanligt om din kunskaps bank är kopplad till ett konversations program, till exempel en chattrobot.
• Även om kunskaps Svaren kan filtreras efter metadata eller använda Uppföljnings frågor, visas inte den här snabb starten. Leta efter dessa språk oberoende generateAnswer-exempel här.
• Svars texten är markdown och kan innehålla en mängd olika markdown , t. ex. bilder (offentligt tillgängliga Internetbaserade avbildningar), länkar (till offentligt tillgängliga URL: er) och punkter, men den här snabb starten använder inte den sorten.

QnAMakerClient-objektmodell

Redigeringsklienten QnA Maker ett QnAMakerClient-objekt som autentiserar till Azure med hjälp av MsRest::ServiceClientCredentials, som innehåller din nyckel.

När klienten har skapats använder du metoderna i klientens kunskapsbasegenskap för att skapa, hantera och publicera kunskapsbasen.

För omedelbara åtgärder returnerar en metod vanligtvis resultatet, om det finns någon. För långvariga åtgärder är svaret ett åtgärdsobjekt. Anropa operations.get_details med värdet operation.operation_id för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

Körningsklienten QnA Maker ett QnAMakerRuntimeClient-objekt.

När du har publicerat kunskapsbasen med redigeringsklienten använder du runtime-klientens runtime.generate_answer för att få ett svar från kunskapsbasen.

När du generate_answer anropar skickar du en hash för den custom_headers valfria parametern. Den här hashen ska innehålla en Authorization nyckel och ett värde EndpointKey YOUR_ENDPOINT_KEY . För värdet för YOUR_ENDPOINT_KEY använder du redigeringsklienten för att anropa endpoint_keys.get_keys.

Autentisera klienten för redigering av kunskapsbasen

Instansiera en klient med redigeringsslutpunkten och prenumerationsnyckeln.

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

Skapa en kunskapsbas

En kunskapsbas lagrar frågor och svar-par för CreateKbDTO-objektet från tre källor:

• För redigeringsinnehåll använder du QnADTO-objektet.
  • Om du vill använda metadata och uppföljningsuppföljningar använder du den redigeringskontext, eftersom dessa data läggs till på nivån för enskilt QnA-par.
• För filer använder du FileDTO-objektet. FileDTO innehåller filnamnet samt den offentliga URL:en för att nå filen.
• För URL:er använder du en lista över strängar för att representera offentligt tillgängliga URL:er.

Anropa create-metoden och skicka sedan egenskapen för den returnerade åtgärden till operation_id operations.get_details för att avssöka efter status.

Den sista raden i följande kod returnerar kunskapsbasens ID.

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

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att anropa knowledgebase.update och skicka in kunskapsbasens ID och ett UpdateKbOperationDTO-objekt. Det objektet kan i sin tur innehålla:

• Add
• update
• Ta bort

Skicka egenskapen operation_id för den returnerade åtgärden till operations.get_details för att avse status.

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

Ladda ned en kunskapsbas

Använd metoden knowledgebase.download för att ladda ned databasen som en lista över QnADocumentsDTO. Detta motsvarar inte QnA Maker-portalens export från sidan Inställningar eftersom resultatet av den här metoden inte är en TSV-fil.

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

Publicera en kunskapsbas

Publicera kunskapsbasen med hjälp av metoden knowledgebase.publish. Detta tar den aktuella sparade och tränade modellen, som refereras till av kunskapsbasens ID, och publicerar den vid en slutpunkt.

def publish_kb(client, kb_id)
    print("Publishing knowledge base...\n")
    client.knowledgebase.publish(kb_id)
    print("Published knowledge base.\n")
end

Hämta nyckel för frågekörning

När en kunskapsbas har publicerats behöver du nyckeln för körningsslutpunkten för att köra frågor mot kunskapen. Detta är inte samma som prenumerationsnyckeln som användes för att skapa redigeringsklienten.

Använd metoden endpoint_keys.get_keys för att hämta ett EndpointKeysDTO-objekt.

Använd någon av de nyckelegenskaper som returneras i -objektet för att fråga kunskapsbasen.

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

Autentisera körningen för att generera ett svar

Skapa en QnAMakerRuntimeClient för att köra frågor mot kunskapsbasen för att generera ett svar eller träna från aktiv inlärning.

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

Använd QnAMakerRuntimeClient för att få ett svar från kunskapen eller för att skicka nya föreslagna frågor till kunskapsbasen för aktiv inlärning.

Generera ett svar från kunskapsbasen

Generera ett svar från en publicerad kunskapsbas med hjälp av metoden RuntimeClient.runtime.generateAnswer. Den här metoden accepterar kunskapsbasens ID och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel Top och Context som ska användas i chattroboten.

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

Det här är ett enkelt exempel på att köra frågor mot en kunskapsbas. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbasen med hjälp av metoden knowledgebase.delete med en parameter för kunskapsbasens ID.

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

Hämta status för en åtgärd

Vissa metoder, till exempel skapa och uppdatera, kan ta tillräckligt med tid så att en åtgärd returneras i stället för att vänta på att processen ska slutföras. Använd åtgärds-ID:t från åtgärden för att avssöka (med omprövningslogik) för att fastställa status för den ursprungliga metoden.

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

Kör programmet

Här är huvudmetoden för programmet.

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)

Kör programmet med Ruby-kommandot i snabbstartsfilen.

ruby quickstart.rb

Källkoden för det här exemplet finns på GitHub.