Snabbstart: QnA Maker-klientbibliotek

  • Artikel

Kommentar

Azure Open AI On Your Data använder stora språkmodeller (LLM: er) för att ge liknande resultat som QnA Maker. Om du vill migrera ditt QnA Maker-projekt till Azure Open AI On Your Data kan du läsa vår guide.

Kom igång med QnA Maker-klientbiblioteket. Följ de här stegen för att installera paketet och prova exempelkoden för grundläggande uppgifter.

Kommentar

QnA Maker-tjänsten dras tillbaka den 31 mars 2025. En nyare version av fråge- och svarsfunktionen är nu tillgänglig som en del av Azure AI Language. Information om funktioner för frågesvar i språktjänsten finns i svar på frågor. Från och med den 1 oktober 2022 kommer du inte att kunna skapa nya QnA Maker-resurser. Information om hur du migrerar befintliga QnA Maker-kunskapsbas till frågesvar finns i migreringsguiden.

Förutsättningar

Kommentar

Den här dokumentationen gäller inte för den senaste versionen. Mer information om hur du använder REST-API:et med den senaste versionen finns i frågan som besvarar REST API-snabbstarten

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

  • Du måste ha en QnA Maker-resurs för att 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-portalen. Resursnamnet är den första underdomänen för slutpunkts-URL:en:

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

Varning

I följande BASH-exempel används radfortsättningstecknet \ . Om du använder ett annat radfortsättningstecken i konsolen eller terminalen använder du det här tecknet.

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 webbadress används för att konstruera URL
QnA Maker-resursnyckel -h param för Ocp-Apim-Subscription-Key rubrik Autentisera till QnA Maker-tjänsten
JSON som beskriver kunskapsbas -d Param Exempel på JSON
Storleken på JSON i byte -h param för Content-Size rubrik

cURL-kommandot 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://learn.microsoft.com/azure/ai-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 webbadress används för att konstruera URL
Åtgärds-ID URL-väg /operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker-resursnyckel -h param för Ocp-Apim-Subscription-Key rubrik Autentisera till QnA Maker-tjänsten

cURL-kommandot 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 slutförts resourceLocation innehåller det kunskapsbas-ID:t.

{
   "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 kör frågor mot kunskapsbas måste du:

  • Publicera kunskapsbas
  • Hämta slutpunktsnyckeln för körning

Den här uppgiften publicerar kunskapsbas. Att hämta slutpunktsnyckeln för körning är en separat uppgift.

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

cURL-kommandot 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. -v Använd kommandoradsparametern för att se utförliga utdata för cURL-kommandot. Detta inkluderar HTTP-status.

Publicera kunskapsbas slutpunktsnyckel för körning

Innan du kör frågor mot kunskapsbas måste du:

  • Publicera kunskapsbas
  • Hämta slutpunktsnyckeln för körning

Den här uppgiften hämtar slutpunktsnyckeln för körning. Att publicera kunskapsbas är en separat uppgift.

Slutpunktsnyckeln för körning är samma nyckel för alla kunskapsbas med hjälp av QnA Maker-resursen.

Information cURL-konfiguration Syfte
QnA Maker-resursnamn webbadress används för att konstruera URL
QnA Maker-resursnyckel -h param för Ocp-Apim-Subscription-Key rubrik Autentisera till QnA Maker-tjänsten

cURL-kommandot 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 slutpunktsnycklarna för körning. Använd bara en av nycklarna när du frågar för att få ett svar från kunskapsbas.

{
  "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 publicerade kunskapsbas

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

Information cURL-konfiguration Syfte
QnA Maker-resursnamn webbadress används för att konstruera URL
QnA Maker-körningsnyckel -h param för Authorization rubrik 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 param för Content-Size rubrik

cURL-kommandot 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, måste visa ett svar för användaren.

Ta bort kunskapsbas

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

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

cURL-kommandot 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. -v Använd kommandoradsparametern för att se utförliga utdata för cURL-kommandot. Detta inkluderar HTTP-status.

Ytterligare resurser

Använd QnA Maker-klientbiblioteket 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å tidskrävande uppgift
  • Ladda ned en kunskapsbas
  • Få ett svar från en kunskapsbas
  • Ta bort en kunskapsbas

Referensdokumentation Bibliotek källkodspaket | (NuGet) | C#-exempel |

Kommentar

Nya resurser som skapats efter den 1 juli 2019 använder anpassade underdomännamn. Mer information och en fullständig lista över regionala slutpunkter finns i Anpassade underdomännamn för Azure AI-tjänster.

Förutsättningar

Kommentar

Den här dokumentationen gäller inte för den senaste versionen. Mer information om hur du använder C#-API:et med den senaste versionen finns i frågan som besvarar C#-snabbstarten.

  • Azure-prenumeration – Skapa en kostnadsfritt
  • 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-portalen för att hämta redigeringsnyckeln och resursnamnet. 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 uppgradera senare till en betald nivå för produktion.

Konfigurera

CLI

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet new kommandot för att skapa en 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

Kompileringsutdata får inte innehålla några varningar eller fel.

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

Installera QnA Maker-klientbiblioteket för .NET i programkatalogen med följande kommando:

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

Dricks

Vill du visa hela snabbstartskodfilen på en gång? Du hittar den på GitHub, som innehåller kodexemplen i den här snabbstarten.

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 Main metod lägger du till variabler och kod, som visas i följande avsnitt, för att använda vanliga uppgifter i den här snabbstarten.

  • Vi använder prenumerationsnyckeln och redigeringsnyckeln på ett utbytbart sätt. Mer information om redigeringsnyckel 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-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumeration) och QnA Maker-slutpunkten.

QnA Maker-redigeringsslutpunkt

  • Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net. Gå till Azure-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Exportera mall under Automation för att hitta slutpunkten För körning.

QnA Maker Runtime-slutpunkt

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i säkerhetsartikeln för Azure AI-tjänster.

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 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 kunskapsbas med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av tränings-API:et (som en del av aktiv inlärning).

Använd det här exemplet kunskapsbas

Den kunskapsbas i den här snabbstarten börjar med två konversations-QnA-par, detta görs med syfte att förenkla exemplet och för att ha mycket förutsägbara ID:n att använda i metoden Uppdatera och associera uppföljningsprompter med frågor till nya par. Detta planerades och implementerades i en specifik ordning för den här snabbstarten.

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

  • För större kunskapsbaser kan du hantera kunskapsbas i ett textredigerare eller TSV-verktyg som stöder automatisering och sedan helt ersätta kunskapsbas på en gång med en uppdatering.
  • För mindre kunskapsbaser hanterar du uppföljningsprompterna helt i QnA Maker-portalen.

Information om QnA-paren som används i den här snabbstarten:

  • Typer av QnA-par – det finns två typer av QnA-par i den här kunskapsbas efter uppdateringen: chitchat och domänspecifik information. Detta är typiskt om din kunskapsbas är kopplad till ett konversationsprogram, till exempel en chattrobot.
  • Även om kunskapsbassvaren kan filtreras efter metadata eller använda uppföljningsprompter, visar den här snabbstarten inte det. Leta efter de språkagnostiska generateAnswer-exemplen här.
  • Svarstexten är markdown och kan innehålla en mängd olika markdown-objekt , till exempel bilder (offentligt tillgängliga internetbaserade bilder), länkar (till offentligt tillgängliga URL:er) och punktpunkter. Den här snabbstarten använder inte den sorten.

QnAMakerClient-objektmodell

Den redigerande QnA Maker-klienten är 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 dina kunskapsbas.

Hantera din kunskapsbas 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. Anropa klienten. Operations.GetDetailsAsync-metoden med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

QnA Maker-förutsägelseklienten ä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 client.EndpointKeys.GetKeys kunskapsbasen har publicerats.

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

Kodexempel

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

Autentisera klienten för redigering av kunskapsbas

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

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

Skapa en kunskapsbas

En kunskapsbas lagrar fråge- och svarspar för CreateKbDTO-objektet från tre källor:

  • Använd QnADTO-objektet för redaktionellt innehåll.
    • Om du vill använda metadata och uppföljningsprompter använder du den redaktionella kontexten eftersom dessa data läggs till på den enskilda QnA-parnivån.
  • 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.

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 metoden CreateAsync och skicka sedan det returnerade åtgärds-ID:t till metoden MonitorOperation för att söka efter status.

Den sista raden i följande kod returnerar kunskapsbas-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 kunna skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka in 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 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 kunskapsbas med metoden PublishAsync. Detta tar den aktuella sparade och tränade modellen, som refereras av kunskapsbas-ID:t, och publicerar den på slutpunkten. Det här är ett nödvändigt steg för att köra frågor mot din kunskapsbas.

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

Hämta frågekörningsnyckel

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änds 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 din kunskapsbas.

Autentisera körningen för att generera ett svar

Skapa en QnAMakerRuntimeClient för att fråga kunskapsbas 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 kunskapsbas för aktiv inlärning.

Generera ett svar från kunskapsbas

Generera ett svar från en publicerad kunskapsbas med hjälp av RuntimeClient.GenerateAnswerAsync-metod . Den här metoden accepterar kunskapsbas-ID och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel en top - och kontext 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 kunskapsbas 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 att i stället för att vänta på att processen ska slutföras returneras en åtgärd . Använd åtgärds-ID :t från åtgärden för att avsöka (med omförsökslogik) för att fastställa statusen för den ursprungliga metoden.

Loopen och Task.Delay i följande kodblock används för att simulera logik för återförsök. Dessa bör ersättas med din egen logik för återfö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 appen

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

dotnet run

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

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

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

Exempel på referensdokumentation (npm) | Node.js |

Kommentar

Nya resurser som skapats efter den 1 juli 2019 använder anpassade underdomännamn. Mer information och en fullständig lista över regionala slutpunkter finns i Anpassade underdomännamn för Azure AI-tjänster.

Förutsättningar

  • Azure-prenumeration – Skapa en kostnadsfritt
  • Den aktuella versionen av Node.js.
  • När du har din Azure-prenumeration skapar du en QnA Maker-resurs i Azure-portalen 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 uppgradera senare till en betald nivå för produktion.

Konfigurera

Skapa ett nytt Node.js-program

Skapa en ny katalog för din app i ett konsolfönster (till exempel cmd, PowerShell eller bash) och navigera 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 namnet 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 prenumerationsnyckeln och redigeringsnyckeln på ett utbytbart sätt. Mer information om redigeringsnyckel 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-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumeration) och QnA Maker-slutpunkten.

QnA Maker-redigeringsslutpunkt

  • Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net. Gå till Azure-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Exportera mall under Automation för att hitta slutpunkten För körning.

QnA Maker Runtime-slutpunkt

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i säkerhetsartikeln för Azure AI-tjänster.

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 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 kunskapsbas med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av tränings-API:et (som en del av aktiv inlärning).

QnAMakerClient-objektmodell

Den redigerande QnA Maker-klienten är 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 dina kunskapsbas.

Hantera din kunskapsbas 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. Anropa metoden client.operations.getDetails med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

QnA Maker-prediktionsklienten ä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 det redigeringsklientanropet, klienten. EndpointKeys.getKeys när kunskapsbasen har publicerats .

Kodexempel

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

Autentisera klienten för redigering av kunskapsbas

Instansiera en klient med slutpunkten och nyckeln. Skapa ett ServiceClientCredentials-objekt med nyckeln 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åge- och svarspar för CreateKbDTO-objektet från tre källor:

  • Använd QnADTO-objektet för redaktionellt innehåll.
    • Om du vill använda metadata och uppföljningsprompter använder du den redaktionella kontexten eftersom dessa data läggs till på den enskilda QnA-parnivån.
  • 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.

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 kunskapsbas information. Den kunskapsbas informationen ä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 söka efter status. Metoden wait_for_operation returnerar när åtgärden är klar. 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 kunna skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka in kunskapsbas-ID:t och ett UpdateKbOperationDTO som innehåller lägg till, uppdatera och ta bort DTO-objekt i uppdateringsmetoden. DTU:er är också i princip JSON-objekt. Använd metoden 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 kunskapsbas med publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras av kunskapsbas-ID:t, och publicerar den på 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 frågekörningsnyckel

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änds 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 kunskapsbas 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 kunskapsbas för aktiv inlärning.

Generera ett svar från kunskapsbas

Generera ett svar från en publicerad kunskapsbas med hjälp av metoden RuntimeClient.runtime.generateAnswer. Den här metoden accepterar kunskapsbas-ID och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel en top- och kontext 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 som frågar kunskapsbas. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbas med hjälp av borttagningsmetoden med en parameter för kunskapsbas-ID:t.

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 med tid att i stället för att vänta på att processen ska slutföras returneras en åtgärd . Använd åtgärds-ID :t från åtgärden för att avsöka (med omförsökslogik) för att fastställa statusen för den ursprungliga metoden.

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

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 appen

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-klientbiblioteket 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å tidskrävande uppgift
  • Ladda ned en kunskapsbas
  • Få ett svar från en kunskapsbas
  • Ta bort kunskapsbas

Referensdokumentation BibliotekskällkodPaket | (PyPi)Python-exempel | |

Kommentar

Nya resurser som skapats efter den 1 juli 2019 använder anpassade underdomännamn. Mer information och en fullständig lista över regionala slutpunkter finns i Anpassade underdomännamn för Azure AI-tjänster.

Förutsättningar

Kommentar

Den här dokumentationen gäller inte för den senaste versionen. Mer information om hur du använder Python-API:et med den senaste versionen finns i frågan som besvarar Python-snabbstarten.

  • Azure-prenumeration – Skapa en kostnadsfritt
  • Python 3.x
  • När du har din Azure-prenumeration skapar du en QnA Maker-resurs i Azure-portalen för att hämta redigeringsnyckeln och slutpunkten. 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.

Konfigurera

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 namnet quickstart-file.py 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 din resurs Azure-slutpunkt och nyckel.

  • Vi använder prenumerationsnyckeln och redigeringsnyckeln på ett utbytbart sätt. Mer information om redigeringsnyckel 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-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumeration) och QnA Maker-slutpunkten.

QnA Maker-redigeringsslutpunkt

  • Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net. Gå till Azure-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Exportera mall under Automation för att hitta slutpunkten För körning.

QnA Maker Runtime-slutpunkt

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i säkerhetsartikeln för Azure AI-tjänster.

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 kunskapsbas med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av tränings-API:et (som en del av aktiv inlärning).

Använd det här exemplet kunskapsbas

Den kunskapsbas i den här snabbstarten börjar med två konversations-QnA-par, detta görs med syfte att förenkla exemplet och för att ha mycket förutsägbara ID:n att använda i metoden Uppdatera och associera uppföljningsprompter med frågor till nya par. Detta planerades och implementerades i en specifik ordning för den här snabbstarten.

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

  • För större kunskapsbaser kan du hantera kunskapsbas i ett textredigerare eller TSV-verktyg som stöder automatisering och sedan helt ersätta kunskapsbas på en gång med en uppdatering.
  • För mindre kunskapsbaser hanterar du uppföljningsprompterna helt i QnA Maker-portalen.

Information om QnA-paren som används i den här snabbstarten:

  • Typer av QnA-par – det finns två typer av QnA-par i den här kunskapsbas efter uppdateringen: chitchat och domänspecifik information. Detta är typiskt om din kunskapsbas är kopplad till ett konversationsprogram, till exempel en chattrobot.
  • Även om kunskapsbassvaren kan filtreras efter metadata eller använda uppföljningsprompter, visar den här snabbstarten inte det. Leta efter de språkagnostiska generateAnswer-exemplen här.
  • Svarstexten är markdown och kan innehålla en mängd olika markdown-objekt , till exempel bilder (offentligt tillgängliga internetbaserade bilder), länkar (till offentligt tillgängliga URL:er) och punktpunkter. Den här snabbstarten använder inte den sorten.

QnAMakerClient-objektmodell

Den redigerande QnA Maker-klienten är 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 dina kunskapsbas.

Hantera din kunskapsbas 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. Anropa metoden operations.get_details med åtgärds-ID:t för att fastställa status för begäran.

QnAMakerRuntimeClient-objektmodell

QnA Maker-prediktionsklienten ä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. EndpointKeysOperations.get_keys efter att kunskapsbasen har publicerats.

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

Autentisera klienten för redigering av kunskapsbas

Instansiera en klient med slutpunkten och nyckeln. 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 kunskapsbas-driftobjekt.

En kunskapsbas lagrar fråge- och svarspar för CreateKbDTO-objektet från tre källor:

  • Använd QnADTO-objektet för redaktionellt innehåll.
    • Om du vill använda metadata och uppföljningsprompter använder du den redaktionella kontexten eftersom dessa data läggs till på den enskilda QnA-parnivån.
  • 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 metoden create och skicka sedan det returnerade åtgärds-ID:t till metoden Operations.getDetails för att söka efter status.

Den sista raden i följande kod returnerar kunskapsbas-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 kunna skapa en kunskapsbas.

Uppdatera en kunskapsbas

Du kan uppdatera en kunskapsbas genom att skicka in kunskapsbas-ID:t och ett UpdateKbOperationDTO som innehåller lägg till, uppdatera och ta bort DTO-objekt i 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 kunskapsbas med publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras av kunskapsbas-ID:t, 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 frågekörningsnyckel

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änds 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 kunskapsbas 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 kunskapsbas för aktiv inlärning.

Generera ett svar från kunskapsbas

Generera ett svar från en publicerad kunskapsbas med hjälp av metoden QnAMakerRuntimeClient.runtime.generate_answer. Den här metoden accepterar kunskapsbas-ID och QueryDTO. Få åtkomst till ytterligare egenskaper för QueryDTO, till exempel en top- och kontext 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å hur du kör frågor mot kunskapsbas. Om du vill förstå avancerade frågescenarier kan du läsa andra frågeexempel.

Ta bort en kunskapsbas

Ta bort kunskapsbas med hjälp av borttagningsmetoden med en parameter för kunskapsbas-ID:t.

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 med tid att i stället för att vänta på att processen ska slutföras returneras en åtgärd . Använd åtgärds-ID:t från åtgärden för att avsöka (med omförsökslogik) för att fastställa statusen 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 återfö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 appen

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-klientbiblioteket 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å tidskrävande uppgift
  • Ladda ned en kunskapsbas
  • Få ett svar från en kunskapsbas
  • Ta bort kunskapsbas

Paketexempel för bibliotekskällkod | |

Kommentar

Nya resurser som skapats efter den 1 juli 2019 använder anpassade underdomännamn. Mer information och en fullständig lista över regionala slutpunkter finns i Anpassade underdomännamn för Azure AI-tjänster.

Förutsättningar

  • Azure-prenumeration – Skapa en kostnadsfritt
  • JDK
  • När du har din Azure-prenumeration skapar du en QnA Maker-resurs i Azure-portalen för att hämta redigeringsnyckeln och slutpunkten. 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 din nyckel och slutpunkt 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.

Konfigurera

Installera klientbiblioteken

När du har installerat Java kan du installera klientbiblioteken med maven från MVN-lagringsplatsen.

Skapa ett nytt Java-program

Skapa en ny fil med namnet quickstart.java 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 din resurs Azure-slutpunkt och nyckel.

  • Vi använder prenumerationsnyckeln och redigeringsnyckeln på ett utbytbart sätt. Mer information om redigeringsnyckel 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-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Nycklar och slutpunkt under resurshantering för att hitta redigeringsnyckeln (prenumeration) och QnA Maker-slutpunkten.

QnA Maker-redigeringsslutpunkt

  • Värdet för QNA_MAKER_RUNTIME_ENDPOINT har formatet https://YOUR-RESOURCE-NAME.azurewebsites.net. Gå till Azure-portalen och leta reda på QnA Maker-resursen som du skapade i förhandskraven. Välj sidan Exportera mall under Automation för att hitta slutpunkten För körning.

QnA Maker Runtime-slutpunkt

Viktigt!

Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion använder du ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter som Azure Key Vault. Mer information finns i säkerhetsartikeln för Azure AI-tjänster.

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 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 kunskapsbas med GenerateAnswer-API:et och skicka nya föreslagna frågor med hjälp av tränings-API:et (som en del av aktiv inlärning).

Använd det här exemplet kunskapsbas

Den kunskapsbas i den här snabbstarten börjar med två konversations-QnA-par, detta görs med syfte att förenkla exemplet och för att ha mycket förutsägbara ID:n att använda i metoden Uppdatera och associera uppföljningsprompter med frågor till nya par. Detta planerades och implementerades i en specifik ordning för den här snabbstarten.

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

  • För större kunskapsbaser kan du hantera kunskapsbas i ett textredigerare eller TSV-verktyg som stöder automatisering och sedan helt ersätta kunskapsbas på en gång med en uppdatering.
  • För mindre kunskapsbaser hanterar du uppföljningsprompterna helt i QnA Maker-portalen.

Information om QnA-paren som används i den här snabbstarten:

  • Typer av QnA-par – det finns två typer av QnA-par i den här kunskapsbas efter uppdateringen: chitchat och domänspecifik information. Detta är typiskt om din kunskapsbas är kopplad till ett konversationsprogram, till exempel en chattrobot.
  • Även om kunskapsbassvaren kan filtreras efter metadata eller använda uppföljningsprompter, visar den här snabbstarten inte det. Leta efter de språkagnostiska generateAnswer-exemplen här.
  • Svarstexten är markdown och kan innehålla en mängd olika markdown-objekt , till exempel bilder (offentligt tillgängliga internetbaserade bilder), länkar (till offentligt tillgängliga URL:er) och punktpunkter. Den här snabbstarten använder inte den sorten.

QnAMakerClient-objektmodell

Den redigerande QnA Maker-klienten är 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 för klientens Knowledgebases-egenskap för att skapa, hantera och publicera din kunskapsbas.

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

QnAMakerRuntimeClient-objektmodell

QnA Maker-klienten för körning är ett QnAMakerRuntimeClient-objekt .

När du har publicerat din kunskapsbas med redigeringsklienten använder du körningsklientens generateAnswer-metod för att få ett svar från kunskapsbas.

Du skapar en körningsklient genom att anropa QnAMakerRuntimeManager.authenticate och skicka en slutpunktsnyckel för körning. Om du vill hämta slutpunktsnyckeln för körning använder du redigeringsklienten för att anropa getKeys.

Autentisera klienten för redigering av kunskapsbas

Instansiera en klient med din redigeringsslutpunkt och prenumerationsnyckel.

/* 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åge- och svarspar för CreateKbDTO-objektet från tre källor:

  • Använd QnADTO-objektet för redaktionellt innehåll.
    • Om du vill använda metadata och uppföljningsprompter använder du den redaktionella kontexten eftersom dessa data läggs till på den enskilda QnA-parnivån.
  • 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 metoden create och skicka operationId sedan egenskapen för den returnerade åtgärden till metoden getDetails för att söka efter status.

Den sista raden i följande kod returnerar kunskapsbas-ID:t.

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 kunskapsbas-ID:t och ett UpdateKbOperationDTO-objekt. Objektet kan i sin tur innehålla:

Skicka egenskapen för operationId den returnerade åtgärden till metoden getDetails för att söka 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 kunskapsbas med publiceringsmetoden. Detta tar den aktuella sparade och tränade modellen, som refereras av kunskapsbas-ID:t, och publicerar den på 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 kunskapsbas

När en kunskapsbas har publicerats behöver du slutpunktsnyckeln för körning för att köra frågor mot kunskapsbas. Detta är inte samma sak som prenumerationsnyckeln som används 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 slutpunktsnyckel för körning från EndpointKeysDTO-objektet.

Generera ett svar från en publicerad kunskapsbas med 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å hur du kör 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 kunskapsbas med hjälp av borttagningsmetoden med en parameter för kunskapsbas-ID:t.

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 att i stället för att vänta på att processen ska slutföras returneras en åtgärd . Använd åtgärds-ID:t från åtgärden för att avsöka (med omförsökslogik) för att fastställa statusen 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 appen

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 ditt klassnamn ä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.

Rensa resurser

Om du vill rensa och ta bort en Azure AI-tjänstprenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort.

Nästa steg

Självstudie: Testa kunskapsbas med en batchfil