Rychlý start: Klientská knihovna služby QnA Maker

Začínáme s klientskou knihovnou služby QnA Maker Podle těchto kroků nainstalujte balíček a vyzkoušejte ukázkový kód pro základní úlohy.

Poznámka:

Služba QnA Maker se vyřadí z provozu 31. března 2025. Novější verze funkce pro otázky a odpovědi je teď dostupná jako součást jazyka Azure AI. Možnosti odpovídání na otázky v rámci služby Language Service najdete v tématu odpovědi na otázky. Od 1. října 2022 nebudete moct vytvářet nové prostředky služby QnA Maker. Informace o migraci stávajících znalostní báze služby QnA Maker na zodpovězení otázek najdete v průvodci migrací.

Požadavky

Poznámka:

Tato dokumentace se nevztahuje na nejnovější verzi. Další informace o používání rozhraní REST API s nejnovější verzí najdete v rychlém startu k odpovědi na otázky týkající se rozhraní REST API.

• Aktuální verze cURL. V rychlých startech se používá několik přepínačů příkazového řádku, které jsou uvedené v dokumentaci cURL.

• Abyste mohli použít klíč a název prostředku, musíte mít prostředek služby QnA Maker. Během vytváření prostředku jste zadali název prostředku a pak jste klíč vytvořili za vás. Název prostředku se používá jako subdoména vašeho koncového bodu. Pokud chcete načíst klíč a název prostředku, vyberte rychlý start pro váš prostředek na webu Azure Portal. Název prostředku je první subdoménou adresy URL koncového bodu:

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

Upozornění

Následující příklady BASH používají \ znak pokračování řádku. Pokud konzolu nebo terminál používáte jiný znak pokračování řádku, použijte tento znak.

Vytvoření znalostní báze

Pokud chcete vytvořit znalostní báze s rozhraními REST API a cURL, musíte mít následující informace:

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
Klíč prostředku služby QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování ve službě QnA Maker
JSON popisující znalostní báze	-d Param	Příklady JSON
Velikost JSON v bajtech	-h param pro Content-Size záhlaví

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz s vlastním názvem prostředku, klíčem prostředku a hodnotami JSON a velikostí 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"]}'

Odpověď cURL od služby QnA Maker obsahuje operationId kód , který je nutný k získání stavu operace.

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

Získání stavu operace

Když vytvoříte znalostní báze, protože operace je asynchronní, obsahuje odpověď informace k určení stavu.

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
ID operace	Trasa adresy URL	/operations/REPLACE-WITH-YOUR-OPERATION-ID
Klíč prostředku služby QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování ve službě QnA Maker

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz s použitím vlastního názvu prostředku, klíče prostředku a ID operace.

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"

Odpověď cURL obsahuje stav. Pokud je stav operace úspěšný, resourceLocation zahrne id znalostní báze.

{
   "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"
}

Publikování znalostní báze

Před dotazem na znalostní báze potřebujete:

• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime

Tento úkol publikuje znalostní báze. Získání klíče koncového bodu modulu runtime je samostatná úloha.

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
Klíč prostředku služby QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování ve službě QnA Maker
ID znalostní báze	Trasa adresy URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz pomocí vlastního názvu prostředku, klíče prostředku a ID znalostní báze.

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

Stav odpovědi je 204 bez výsledků. Pomocí parametru příkazového -v řádku zobrazíte podrobný výstup příkazu cURL. To bude zahrnovat stav HTTP.

Získání publikovaného klíče koncového bodu modulu runtime znalostní báze

Před dotazem na znalostní báze potřebujete:

• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime

Tato úloha získá klíč koncového bodu modulu runtime. Publikování znalostní báze je samostatný úkol.

Klíč koncového bodu modulu runtime je stejný klíč pro všechny znalostní báze pomocí prostředku služby QnA Maker.

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
Klíč prostředku služby QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování ve službě QnA Maker

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz s vlastním názvem prostředku, klíčem prostředku.

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"

Odpověď cURL zahrnuje klíče koncového bodu modulu runtime. Při dotazování na získání odpovědi z znalostní báze použijte jenom jeden z těchto klíčů.

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

Dotaz na odpověď od publikovaných znalostní báze

Získání odpovědi z znalostí se provádí z samostatného modulu runtime, než je správa znalostní báze. Vzhledem k tomu, že se jedná o samostatný modul runtime, musíte se ověřit pomocí klíče modulu runtime.

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
Klíč modulu runtime služby QnA Maker	-h param pro Authorization záhlaví	Klíč je součástí řetězce, který obsahuje slovo Endpointkey . Ověřování ve službě QnA Maker
ID znalostní báze	Trasa adresy URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON popisující dotaz	-d Param	Parametry textu požadavku a příklady JSON
Velikost JSON v bajtech	-h param pro Content-Size záhlaví

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz pomocí vlastního názvu prostředku, klíče prostředku a ID znalostní báze.

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

Úspěšná odpověď zahrnuje hlavní odpověď spolu s dalšími informacemi, které klientská aplikace, jako je chatbot, potřebuje uživateli zobrazit odpověď.

Odstranění znalostní báze

Až skončíte s znalostní báze, odstraňte ho.

Informační	Konfigurace cURL	Účel
Název prostředku služby QnA Maker	Adresa URL	použité k vytvoření adresy URL
Klíč prostředku služby QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování ve službě QnA Maker
ID znalostní báze	Trasa adresy URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Příkaz cURL se spustí z prostředí BASH. Upravte tento příkaz pomocí vlastního názvu prostředku, klíče prostředku a ID znalostní báze.

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"

Stav odpovědi je 204 bez výsledků. Pomocí parametru příkazového -v řádku zobrazíte podrobný výstup příkazu cURL. To bude zahrnovat stav HTTP.

Další materiály

• Referenční dokumentace k vytváření obsahu
• Referenční dokumentace k modulu runtime
• Ukázkové skripty BASH pomocí cURL

Pomocí klientské knihovny služby QnA Maker pro .NET můžete:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime předpovědi
• Čekání na dlouho běžící úlohu
• Stažení znalostní báze
• Získání odpovědi z znalostní báze
• Odstranění znalostní báze

Referenční dokumentace | – ukázky balíčku zdrojového kódu | knihovny (NuGet) | C#

Poznámka:

Nové prostředky vytvořené po 1. červenci 2019 budou používat vlastní názvy subdomén. Další informace a úplný seznam regionálních koncových bodů najdete v tématu Vlastní subdomény pro služby Azure AI.

Požadavky

Poznámka:

Tato dokumentace se nevztahuje na nejnovější verzi. Další informace o používání rozhraní API jazyka C# s nejnovější verzí najdete v rychlém startu pro odpovědi na otázky v jazyce C#.

• Předplatné Azure: Můžete si ho vytvořit zdarma.
• Integrované vývojové prostředí sady Visual Studio nebo aktuální verze .NET Core.
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek služby QnA Maker, abyste získali svůj klíč pro vytváření obsahu a název prostředku. Po nasazení vyberte Přejít k prostředku.
  • K připojení aplikace k rozhraní API služby QnA Maker budete potřebovat klíč a název prostředku z prostředku, který vytvoříte. Do kódu níže v rychlém startu vložte svůj klíč a název prostředku.
  • K vyzkoušení služby můžete použít cenovou úroveňF0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

Nastavení

Rozhraní příkazového řádku

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem qna-maker-quickstart. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: program.cs.

dotnet new console -n qna-maker-quickstart

Změňte adresář na nově vytvořenou složku aplikace. Aplikaci můžete sestavit pomocí následujících:

dotnet build

Výstup sestavení by neměl obsahovat žádná upozornění ani chyby.

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

V adresáři aplikace nainstalujte klientskou knihovnu QnA Maker pro .NET pomocí následujícího příkazu:

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

Tip

Chcete zobrazit celý soubor s kódem rychlého startu najednou? Soubor s příklady kódu v tomto rychlém startu najdete na GitHubu.

Použití direktiv

V adresáři projektu otevřete soubor program.cs a přidejte následující using direktivy:

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

Klíč předplatného a koncové body prostředků

V metodě aplikace Main přidejte proměnné a kód, které jsou uvedené v následující části, abyste mohli používat běžné úlohy v tomto rychlém startu.

• Klíč předplatného a klíč pro vytváření klíčů používáme zaměnitelně. Další podrobnosti o klíči pro vytváření najdete v nástroji QnA Maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. V části Správa prostředků vyberte klíče a koncový bod a vyhledejte klíč pro vytváření (předplatné) a koncový bod služby QnA Maker.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. Výběrem stránky Exportovat šablonu v části Automatizace vyhledejte koncový bod modulu runtime.

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v článku zabezpečení služeb Azure AI.

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

Objektové modely

QnA Maker používá dva různé objektové modely:

• QnAMakerClient je objekt pro vytváření, správu, publikování a stahování znalostní báze.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a odesílání nových navrhovaných otázek pomocí rozhraní TRAIN API (jako součást aktivního učení).

Použití tohoto příkladu znalostní báze

Znalostní báze v tomto rychlém startu začíná 2 konverzačními dvojicemi QnA, to se provádí za účelem zjednodušení příkladu a použití vysoce předvídatelných ID pro použití v metodě update a přidružování následných výzev k novým párům. Toto bylo naplánováno a implementováno v určitém pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvinout znalostní báze v průběhu času s následnými výzvami, které jsou závislé na existujících párech QnA, můžete zvolit:

• U větších znalostních databází spravujte znalostní báze v textovém editoru nebo nástroji TSV, který podporuje automatizaci, a pak úplně nahraďte znalostní báze najednou aktualizací.
• U menších znalostních databází spravujte následné výzvy zcela na portálu služby QnA Maker.

Podrobnosti o párech QnA použitých v tomto rychlém startu:

• Typy páru QnA – v tomto znalostní báze existují dva typy párů QnA, po aktualizaci: chitchat a informace specifické pro doménu. To je typické, pokud je vaše znalostní báze svázaná s konverzační aplikací, jako je chatovací robot.
• Odpovědi na znalostní bázi sice můžou být filtrované podle metadat nebo pomocí následných výzev, ale tento rychlý start to nezobrazuje. Tady hledejte příklady generování jazyka nezávislé na jazyku.
• Text odpovědi je markdown a může obsahovat širokou škálu markdownů , jako jsou obrázky (veřejně dostupné internetové obrázky), odkazy (na veřejně dostupné adresy URL) a odrážky, tento rychlý start tuto rozmanitost nepoužívá.

Objektový model QnAMakerClient

Klient QnA Maker je objekt QnAMakerClient , který se ověřuje v Azure pomocí Microsoft.Rest.ServiceClientCredentials, který obsahuje váš klíč.

Po vytvoření klienta použijte vlastnost Znalostní báze k vytvoření, správě a publikování znalostní báze.

Spravujte znalostní báze odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON označující stav. U dlouhotrvajících operací je odpovědí ID operace. Zavolejte klienta. Operations.GetDetailsAsync metoda s ID operace k určení stavu požadavku.

Objektový model QnAMakerRuntimeClient

Prediktivní klient služby QnA Maker je objekt QnAMakerRuntimeClient , který se ověřuje v Azure pomocí Microsoft.Rest.ServiceClientCredentials, který obsahuje klíč modulu runtime předpovědi, vrácený z volání klienta pro vytváření po client.EndpointKeys.GetKeys publikování znalostní báze.

K získání odpovědi z modulu runtime dotazu použijte metodu GenerateAnswer.

Příklady kódu

Tyto fragmenty kódu ukazují, jak pomocí klientské knihovny služby QnA Maker pro .NET provést následující akce:

• Ověření klienta pro tvorbu
• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Stažení znalostní báze
• Publikování znalostní báze
• Odstranění znalostní báze
• Získání klíče modulu runtime dotazu
• Získání stavu operace
• Ověření klienta modulu runtime dotazu
• Vygenerování odpovědi z znalostní báze

Ověření klienta pro vytváření znalostní báze

Vytvořte instanci objektu klienta s klíčem a použijte ho s prostředkem k vytvoření koncového bodu pro vytvoření QnAMakerClient s vaším koncovým bodem a klíčem. Vytvořte objekt ServiceClientCredentials .

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

Vytvoření znalostní báze

Znalostní báze ukládá páry otázek a odpovědí pro objekt CreateKbDTO ze tří zdrojů:

• Pro redakční obsah použijte objekt QnADTO .
  • Pokud chcete použít metadata a následné výzvy, použijte redakční kontext, protože tato data se přidávají na úrovni jednotlivých párů QnA.
• Pro soubory použijte FileDTO objekt. FileDTO obsahuje název souboru a veřejnou adresu URL pro přístup k souboru.
• Pro adresy URL použijte seznam řetězců, které představují veřejně dostupné adresy URL.

Krok vytvoření obsahuje také vlastnosti znalostní báze:

• defaultAnswerUsedForExtraction – co se vrátí, když se nenajde žádná odpověď
• enableHierarchicalExtraction – automaticky vytvářet relace výzvy mezi extrahovanými páry QnA
• language – při vytváření první znalostní báze prostředku nastavte jazyk, který se má použít v indexu Azure Search.

Zavolejte metodu CreateAsync a pak předejte vrácené ID operace metodě MonitorOperation , která se má dotazovat na stav.

Poslední řádek následujícího kódu vrátí ID znalostní báze z odpovědi z 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);
}

Abyste mohli úspěšně vytvořit znalostní báze, nezapomeňte do výše uvedeného kódu zahrnout MonitorOperation funkci, na které odkazuje výše uvedený kód.

Aktualizace znalostní báze

Znalostní báze můžete aktualizovat předáním ID znalostní báze a objektu UpdatekbOperationDTO obsahujícího objekty DTO add, update a delete do metody UpdateAsync. Pomocí metody MonitorOperation určete, jestli aktualizace proběhla úspěšně.

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

Nezapomeňte zahrnout MonitorOperation funkci, na které odkazuje výše uvedený kód, aby bylo možné úspěšně aktualizovat znalostní báze.

Stažení znalostní báze

Pomocí metody DownloadAsync stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem exportu portálu QnA Maker ze stránky Nastavení, protože výsledek této metody není soubor.

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
}

Publikování znalostní báze

Publikujte znalostní báze pomocí metody PublishAsync. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho ve vašem koncovém bodu. Jedná se o nezbytný krok pro dotazování znalostní báze.

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

Získání klíče modulu runtime dotazu

Po publikování znalostní báze potřebujete klíč modulu runtime dotazu k dotazování modulu runtime. Nejedná se o stejný klíč, který se používá k vytvoření původního objektu klienta.

Pomocí metody EndpointKeys získejte třídu EndpointKeysDTO.

K dotazování znalostní báze použijte některou z klíčových vlastností vrácených v objektu.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Klíč modulu runtime je nezbytný k dotazování znalostní báze.

Ověření modulu runtime pro generování odpovědi

Vytvořte QnAMakerRuntimeClient pro dotazování znalostní báze pro vygenerování odpovědi nebo trénování z aktivního učení.

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

Pomocí QnAMakerRuntimeClient:

• získání odpovědi z znalostní báze
• odeslat nové navrhované otázky znalostní báze pro aktivní učení.

Vygenerování odpovědi z znalostní báze

Vygenerujte odpověď z publikované znalostní báze pomocí RuntimeClient.GenerateAnswerAsync – metoda Tato metoda přijímá ID znalostní báze a QueryDTO. Získejte přístup k dalším vlastnostem dotazu QueryDTO, například Top a Context , které se mají použít v chatovacím robotovi.

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
}

Toto je jednoduchý příklad dotazování znalostní báze. Pokud chcete porozumět pokročilým scénářům dotazování, projděte si další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní bázi pomocí metody DeleteAsync s parametrem id znalostní báze.

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

Získání stavu operace

Některé metody, jako je vytvoření a aktualizace, mohou trvat dostatek času, aby se místo čekání na dokončení procesu vrátila operace . K určení stavu původní metody použijte ID operace z operace k dotazování (s logikou opakování).

Smyčka a Task.Delay v následujícím bloku kódu se používají k simulaci logiky opakování. Ty by se měly nahradit vlastní logikou opakování.

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

Spuštění aplikace

Spusťte aplikaci příkazem dotnet run z adresáře aplikace.

dotnet run

Zdrojový kód pro tuto ukázku najdete na GitHubu.

Ke Node.js použijte klientskou knihovnu služby QnA Maker:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime předpovědi
• Čekání na dlouho běžící úlohu
• Stažení znalostní báze
• Získání odpovědi z znalostní báze
• Odstranění znalostní báze

Referenční dokumentace | – ukázky (npm) | Node.js

Poznámka:

Nové prostředky vytvořené po 1. červenci 2019 budou používat vlastní názvy subdomén. Další informace a úplný seznam regionálních koncových bodů najdete v tématu Vlastní subdomény pro služby Azure AI.

Požadavky

• Předplatné Azure: Můžete si ho vytvořit zdarma.
• Aktuální verze Node.js.
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek služby QnA Maker, abyste získali klíč a prostředek pro vytváření obsahu. Po nasazení vyberte Přejít k prostředku.
  • K připojení aplikace k rozhraní API služby QnA Maker budete potřebovat klíč a název prostředku z prostředku, který vytvoříte. Do kódu níže v rychlém startu vložte svůj klíč a název prostředku.
  • K vyzkoušení služby můžete použít cenovou úroveňF0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

Nastavení

Vytvoření nové aplikace Node.js

V okně konzoly (například cmd, PowerShell nebo Bash) vytvořte pro vaši aplikaci nový adresář a přejděte do něj.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Spuštěním příkazu npm init -y vytvoříte aplikaci uzlu se souborem package.json.

npm init -y

Instalace klientské knihovny

Nainstalujte následující balíčky NPM:

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

Soubor vaší aplikace package.json se aktualizuje o závislosti.

Vytvořte soubor s názvem index.js a naimportujte následující knihovny:

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

Vytvořte proměnnou pro klíč a název prostředku prostředku.

• Klíč předplatného a klíč pro vytváření klíčů používáme zaměnitelně. Další podrobnosti o klíči pro vytváření najdete v nástroji QnA Maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. V části Správa prostředků vyberte klíče a koncový bod a vyhledejte klíč pro vytváření (předplatné) a koncový bod služby QnA Maker.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. Výběrem stránky Exportovat šablonu v části Automatizace vyhledejte koncový bod modulu runtime.

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v článku zabezpečení služeb Azure AI.

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

Objektové modely

QnA Maker používá dva různé objektové modely:

• QnAMakerClient je objekt pro vytváření, správu, publikování a stahování znalostní báze.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a odesílání nových navrhovaných otázek pomocí rozhraní TRAIN API (jako součást aktivního učení).

Objektový model QnAMakerClient

Klient služby QnA Maker je objekt QnAMakerClient , který se ověřuje v Azure pomocí vašich přihlašovacích údajů, který obsahuje váš klíč.

Po vytvoření klienta použijte znalostní bázi k vytvoření, správě a publikování znalostní báze.

Spravujte znalostní báze odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON označující stav. U dlouhotrvajících operací je odpovědí ID operace. Zavolejte metodu client.operations.getDetails s ID operace a určete stav požadavku.

Objektový model QnAMakerRuntimeClient

Prediktivní klient QnA Maker je objekt QnAMakerRuntimeClient, který se ověřuje v Azure pomocí Microsoft.Rest.ServiceClientCredentials, který obsahuje klíč modulu runtime predikce vrácený z volání klienta pro vytváření, klienta. EndpointKeys.getKeys po publikování znalostní báze

Příklady kódu

Tyto fragmenty kódu ukazují, jak pomocí klientské knihovny služby QnA Maker pro .NET provést následující akce:

• Ověření klienta pro tvorbu
• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Stažení znalostní báze
• Publikování znalostní báze
• Odstranění znalostní báze
• Získání klíče modulu runtime dotazu
• Získání stavu operace
• Ověření klienta modulu runtime dotazu
• Vygenerování odpovědi z znalostní báze

Ověření klienta pro vytváření znalostní báze

Vytvořte instanci klienta pomocí koncového bodu a klíče. Vytvořte objekt ServiceClientCredentials s klíčem a použijte ho s koncovým bodem k vytvoření objektu QnAMakerClient .

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

Vytvoření znalostní báze

Znalostní báze ukládá páry otázek a odpovědí pro objekt CreateKbDTO ze tří zdrojů:

• Pro redakční obsah použijte objekt QnADTO .
  • Pokud chcete použít metadata a následné výzvy, použijte redakční kontext, protože tato data se přidávají na úrovni jednotlivých párů QnA.
• Pro soubory použijte FileDTO objekt. FileDTO obsahuje název souboru a veřejnou adresu URL pro přístup k souboru.
• Pro adresy URL použijte seznam řetězců, které představují veřejně dostupné adresy URL.

Krok vytvoření obsahuje také vlastnosti znalostní báze:

• defaultAnswerUsedForExtraction – co se vrátí, když se nenajde žádná odpověď
• enableHierarchicalExtraction – automaticky vytvářet relace výzvy mezi extrahovanými páry QnA
• language – při vytváření první znalostní báze prostředku nastavte jazyk, který se má použít v indexu Azure Search.

Volejte metodu create s znalostní báze informacemi. Informace o znalostní báze jsou v podstatě objekt JSON.

Když metoda create vrátí, předejte vrácené ID operace wait_for_operation metodu dotazování na stav. Metoda wait_for_operation vrátí po dokončení operace. Parsujte resourceLocation hodnotu záhlaví vrácené operace a získejte nové ID znalostní báze.

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

Abyste mohli úspěšně vytvořit znalostní báze, nezapomeňte do výše uvedeného kódu zahrnout wait_for_operation funkci, na které odkazuje výše uvedený kód.

Aktualizace znalostní báze

Znalostní báze můžete aktualizovat předáním ID znalostní báze a aktualizačního objektu UpdateKbOperationDTO obsahujícího objekty DTO přidat, aktualizovat a odstranit do metody aktualizace. Objekty DTO jsou také v podstatě objekty JSON. Pomocí metody wait_for_operation určete, jestli aktualizace proběhla úspěšně.

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
}

Ujistěte se, že funkce, wait_for_operation na která odkazuje výše uvedený kód, aby bylo možné úspěšně aktualizovat znalostní báze.

Stažení znalostní báze

Pomocí metody stahování stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem exportu portálu QnA Maker ze stránky Nastavení, protože výsledek této metody není soubor TSV.

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
}

Publikování znalostní báze

Publikujte znalostní báze pomocí metody publikování. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho na koncovém bodu. Zkontrolujte kód odpovědi HTTP a ověřte, že publikování proběhlo úspěšně.

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
}

Dotazování znalostní báze

Získání klíče modulu runtime dotazu

Po publikování znalostní báze potřebujete klíč modulu runtime dotazu k dotazování modulu runtime. Nejedná se o stejný klíč, který se používá k vytvoření původního objektu klienta.

K získání třídy EndpointKeysDTO použijte metodu EndpointKeys.getKeys.

K dotazování znalostní báze použijte některou z klíčových vlastností vrácených v objektu.

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
}

Ověření modulu runtime pro generování odpovědi

Vytvořte QnAMakerRuntimeClient pro dotazování znalostní báze pro vygenerování odpovědi nebo trénování z aktivního učení.

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

Pomocí QnAMakerRuntimeClient získáte odpověď ze znalostí nebo odešlete nové navrhované otázky do znalostní báze pro aktivní učení.

Vygenerování odpovědi z znalostní báze

Pomocí metody RuntimeClient.runtime.generateAnswer vygenerujte odpověď z publikovaného znalostní báze. Tato metoda přijímá ID znalostní báze a QueryDTO. Získejte přístup k dalším vlastnostem dotazu QueryDTO, například Top a Context, které se mají použít v chatovacím robotovi.

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

}

Toto je jednoduchý příklad dotazu na znalostní báze. Pokud chcete porozumět pokročilým scénářům dotazování, projděte si další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní báze pomocí metody delete s parametrem ID znalostní báze.

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
}

Získání stavu operace

Některé metody, jako je vytvoření a aktualizace, mohou trvat dostatek času, aby se místo čekání na dokončení procesu vrátila operace . K určení stavu původní metody použijte ID operace z operace k dotazování (s logikou opakování).

Volání delayTimer v následujícím bloku kódu se používá k simulaci logiky opakování. Nahraďte ji vlastní logikou opakování.

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

Spuštění aplikace

Spusťte aplikaci příkazem node index.js z adresáře aplikace.

node index.js

Zdrojový kód pro tuto ukázku najdete na GitHubu.

Pomocí klientské knihovny služby QnA Maker pro Python můžete:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime předpovědi
• Čekání na dlouho běžící úlohu
• Stažení znalostní báze
• Získání odpovědi z znalostní báze
• Odstranění znalostní báze

Referenční dokumentace | – ukázky balíčku zdrojového kódu | knihovny (PyPi)Python |

Poznámka:

Nové prostředky vytvořené po 1. červenci 2019 budou používat vlastní názvy subdomén. Další informace a úplný seznam regionálních koncových bodů najdete v tématu Vlastní subdomény pro služby Azure AI.

Požadavky

Poznámka:

Tato dokumentace se nevztahuje na nejnovější verzi. Další informace o používání rozhraní Python API s nejnovější verzí najdete v rychlém startu pro odpovědi na otázky v Pythonu.

• Předplatné Azure: Můžete si ho vytvořit zdarma.
• Python 3.x
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek služby QnA Maker, abyste získali klíč pro vytváření obsahu a koncový bod. Po nasazení vyberte Přejít k prostředku.
  • K připojení aplikace k rozhraní API služby QnA Maker budete potřebovat klíč a koncový bod z prostředku, který vytvoříte. Klíč a koncový bod vložíte do kódu níže v rychlém startu.
  • K vyzkoušení služby můžete použít cenovou úroveňF0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

Nastavení

Instalace klientské knihovny

Po instalaci Pythonu můžete nainstalovat klientskou knihovnu pomocí:

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

Vytvoření nové aplikace v Pythonu

Vytvořte nový soubor Pythonu s názvem quickstart-file.py a naimportujte následující knihovny.

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

Vytvořte proměnné pro koncový bod a klíč Azure vašeho prostředku.

• Klíč předplatného a klíč pro vytváření klíčů používáme zaměnitelně. Další podrobnosti o klíči pro vytváření najdete v nástroji QnA Maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. V části Správa prostředků vyberte klíče a koncový bod a vyhledejte klíč pro vytváření (předplatné) a koncový bod služby QnA Maker.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. Výběrem stránky Exportovat šablonu v části Automatizace vyhledejte koncový bod modulu runtime.

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v článku zabezpečení služeb Azure AI.

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'

Objektové modely

QnA Maker používá dva různé objektové modely:

• QnAMakerClient je objekt pro vytváření, správu, publikování a stahování znalostní báze.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a odesílání nových navrhovaných otázek pomocí rozhraní TRAIN API (jako součást aktivního učení).

Použití tohoto příkladu znalostní báze

Znalostní báze v tomto rychlém startu začíná 2 konverzačními dvojicemi QnA, to se provádí za účelem zjednodušení příkladu a použití vysoce předvídatelných ID pro použití v metodě update a přidružování následných výzev k novým párům. Toto bylo naplánováno a implementováno v určitém pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvinout znalostní báze v průběhu času s následnými výzvami, které jsou závislé na existujících párech QnA, můžete zvolit:

• U větších znalostních databází spravujte znalostní báze v textovém editoru nebo nástroji TSV, který podporuje automatizaci, a pak úplně nahraďte znalostní báze najednou aktualizací.
• U menších znalostních databází spravujte následné výzvy zcela na portálu služby QnA Maker.

Podrobnosti o párech QnA použitých v tomto rychlém startu:

• Typy páru QnA – v tomto znalostní báze existují dva typy párů QnA, po aktualizaci: chitchat a informace specifické pro doménu. To je typické, pokud je vaše znalostní báze svázaná s konverzační aplikací, jako je chatovací robot.
• Odpovědi na znalostní bázi sice můžou být filtrované podle metadat nebo pomocí následných výzev, ale tento rychlý start to nezobrazuje. Tady hledejte příklady generování jazyka nezávislé na jazyku.
• Text odpovědi je markdown a může obsahovat širokou škálu markdownů , jako jsou obrázky (veřejně dostupné internetové obrázky), odkazy (na veřejně dostupné adresy URL) a odrážky, tento rychlý start tuto rozmanitost nepoužívá.

Objektový model QnAMakerClient

Klient QnA Maker je objekt QnAMakerClient , který se ověřuje v Azure pomocí Microsoft.Rest.ServiceClientCredentials, který obsahuje váš klíč.

Po vytvoření klienta použijte vlastnost Znalostní báze k vytvoření, správě a publikování znalostní báze.

Spravujte znalostní báze odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON označující stav. U dlouhotrvajících operací je odpovědí ID operace. Zavolejte metodu operations.get_details s ID operace a určete stav požadavku.

Objektový model QnAMakerRuntimeClient

Prediktivní klient služby QnA Maker je QnAMakerRuntimeClient objekt, který se ověřuje v Azure pomocí Microsoft.Rest.ServiceClientCredentials, který obsahuje klíč modulu runtime predikce vrácený z volání klienta pro vytváření. EndpointKeysOperations.get_keys po publikování znalostní báze.

generate_answer Pomocí metody získejte odpověď z modulu runtime dotazu.

Ověření klienta pro vytváření znalostní báze

Vytvořte instanci klienta pomocí koncového bodu a klíče. Vytvořte objekt CognitiveServicesCredentials s klíčem a použijte ho s koncovým bodem k vytvoření objektu QnAMakerClient .

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

Vytvoření znalostní báze

Objekt klienta slouží k získání objektu znalostní báze operací.

Znalostní báze ukládá páry otázek a odpovědí pro objekt CreateKbDTO ze tří zdrojů:

• Pro redakční obsah použijte objekt QnADTO .
  • Pokud chcete použít metadata a následné výzvy, použijte redakční kontext, protože tato data se přidávají na úrovni jednotlivých párů QnA.
• Pro soubory použijte FileDTO objekt. FileDTO obsahuje název souboru a veřejnou adresu URL pro přístup k souboru.
• Pro adresy URL použijte seznam řetězců, které představují veřejně dostupné adresy URL.

Zavolejte metodu create a pak předejte vrácené ID operace metodě Operations.getDetails k dotazování stavu.

Poslední řádek následujícího kódu vrátí ID znalostní báze z odpovědi z 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

Ujistěte se, že funkce, _monitor_operation na která odkazuje výše uvedený kód, aby bylo možné úspěšně vytvořit znalostní báze.

Aktualizace znalostní báze

Znalostní báze můžete aktualizovat předáním ID znalostní báze a aktualizačního objektu UpdateKbOperationDTO obsahujícího objekty DTO přidat, aktualizovat a odstranit do metody aktualizace. K určení, jestli aktualizace proběhla úspěšně, použijte metodu Operation.getDetail .

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

Ujistěte se, že funkce, _monitor_operation na která odkazuje výše uvedený kód, aby bylo možné úspěšně aktualizovat znalostní báze.

Stažení znalostní báze

Pomocí metody stahování stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem exportu portálu QnA Maker ze stránky Nastavení, protože výsledek této metody není soubor TSV.

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

Publikování znalostní báze

Publikujte znalostní báze pomocí metody publikování. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho na koncovém bodu.

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

Dotazování znalostní báze

Získání klíče modulu runtime dotazu

Po publikování znalostní báze potřebujete klíč modulu runtime dotazu k dotazování modulu runtime. Nejedná se o stejný klíč, který se používá k vytvoření původního objektu klienta.

K získání třídy EndpointKeysDTO použijte metodu EndpointKeysOperations.get_keys.

K dotazování znalostní báze použijte některou z klíčových vlastností vrácených v objektu.

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

Ověření modulu runtime pro generování odpovědi

Vytvořte QnAMakerRuntimeClient pro dotazování znalostní báze pro vygenerování odpovědi nebo trénování z aktivního učení.

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

Pomocí QnAMakerRuntimeClient získáte odpověď ze znalostí nebo odešlete nové navrhované otázky do znalostní báze pro aktivní učení.

Vygenerování odpovědi z znalostní báze

Pomocí metody QnAMakerRuntimeClient.runtime.generate_answer vygenerujte odpověď z publikovaného znalostní báze. Tato metoda přijímá ID znalostní báze a QueryDTO. Získejte přístup k dalším vlastnostem dotazu QueryDTO, například Top a Context, které se mají použít v chatovacím robotovi.

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

Toto je jednoduchý příklad dotazování znalostní báze. Pokud chcete porozumět pokročilým scénářům dotazování, projděte si další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní báze pomocí metody delete s parametrem ID znalostní báze.

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

Získání stavu operace

Některé metody, jako je vytvoření a aktualizace, mohou trvat dostatek času, aby se místo čekání na dokončení procesu vrátila operace . K určení stavu původní metody použijte ID operace z operace k dotazování (s logikou opakování).

Volání setTimeout v následujícím bloku kódu se používá k simulaci asynchronního kódu. Nahraďte ji logikou opakování.

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

Spuštění aplikace

Spusťte aplikaci pomocí příkazu Pythonu v souboru rychlého startu.

python quickstart-file.py

Zdrojový kód pro tuto ukázku najdete na GitHubu.

Pomocí klientské knihovny služby QnA Maker pro Javu můžete:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získání klíče koncového bodu modulu runtime předpovědi
• Čekání na dlouho běžící úlohu
• Stažení znalostní báze
• Získání odpovědi z znalostní báze
• Odstranění znalostní báze

Ukázky balíčků zdrojového | kódu knihovny |

Poznámka:

Nové prostředky vytvořené po 1. červenci 2019 budou používat vlastní názvy subdomén. Další informace a úplný seznam regionálních koncových bodů najdete v tématu Vlastní subdomény pro služby Azure AI.

Požadavky

• Předplatné Azure: Můžete si ho vytvořit zdarma.
• JDK
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek služby QnA Maker, abyste získali klíč pro vytváření obsahu a koncový bod. Po nasazení vyberte Přejít k prostředku.
  • K připojení aplikace k rozhraní API služby QnA Maker budete potřebovat klíč a koncový bod z prostředku, který vytvoříte. Klíč a koncový bod vložte do kódu níže v rychlém startu.
  • K vyzkoušení služby můžete použít cenovou úroveňF0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

Nastavení

Instalace klientských knihoven

Po instalaci Javy můžete klientské knihovny nainstalovat pomocí Mavenu z úložiště MVN.

Vytvoření nové aplikace v Javě

Vytvořte nový soubor s názvem quickstart.java a naimportujte následující knihovny.

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

Vytvořte proměnné pro koncový bod a klíč Azure vašeho prostředku.

• Klíč předplatného a klíč pro vytváření klíčů používáme zaměnitelně. Další podrobnosti o klíči pro vytváření najdete v nástroji QnA Maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. V části Správa prostředků vyberte klíče a koncový bod a vyhledejte klíč pro vytváření (předplatné) a koncový bod služby QnA Maker.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net. Přejděte na web Azure Portal a vyhledejte prostředek služby QnA Maker, který jste vytvořili v požadavcích. Výběrem stránky Exportovat šablonu v části Automatizace vyhledejte koncový bod modulu runtime.

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v článku zabezpečení služeb Azure AI.

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

Objektové modely

QnA Maker používá dva různé objektové modely:

• QnAMakerClient je objekt pro vytváření, správu, publikování a stahování znalostní báze.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a odesílání nových navrhovaných otázek pomocí rozhraní TRAIN API (jako součást aktivního učení).

Použití tohoto příkladu znalostní báze

Znalostní báze v tomto rychlém startu začíná 2 konverzačními dvojicemi QnA, to se provádí za účelem zjednodušení příkladu a použití vysoce předvídatelných ID pro použití v metodě update a přidružování následných výzev k novým párům. Toto bylo naplánováno a implementováno v určitém pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvinout znalostní báze v průběhu času s následnými výzvami, které jsou závislé na existujících párech QnA, můžete zvolit:

• U větších znalostních databází spravujte znalostní báze v textovém editoru nebo nástroji TSV, který podporuje automatizaci, a pak úplně nahraďte znalostní báze najednou aktualizací.
• U menších znalostních databází spravujte následné výzvy zcela na portálu služby QnA Maker.

Podrobnosti o párech QnA použitých v tomto rychlém startu:

• Typy páru QnA – v tomto znalostní báze existují dva typy párů QnA, po aktualizaci: chitchat a informace specifické pro doménu. To je typické, pokud je vaše znalostní báze svázaná s konverzační aplikací, jako je chatovací robot.
• Odpovědi na znalostní bázi sice můžou být filtrované podle metadat nebo pomocí následných výzev, ale tento rychlý start to nezobrazuje. Tady hledejte příklady generování jazyka nezávislé na jazyku.
• Text odpovědi je markdown a může obsahovat širokou škálu markdownů , jako jsou obrázky (veřejně dostupné internetové obrázky), odkazy (na veřejně dostupné adresy URL) a odrážky, tento rychlý start tuto rozmanitost nepoužívá.

Objektový model QnAMakerClient

Klient služby QnA Maker je objekt QnAMakerClient , který se ověřuje v Azure pomocí MsRest::ServiceClientCredentials, který obsahuje váš klíč.

Po vytvoření klienta použijte metody vlastnosti KnowledgeBases klienta k vytvoření, správě a publikování znalostní báze.

Pro okamžité operace metoda obvykle vrátí výsledek, pokud existuje. U dlouhotrvajících operací je odpovědí objekt Operace . Zavolejte metodu getDetails s operation.operationId hodnotou k určení stavu požadavku.

Objektový model QnAMakerRuntimeClient

Klient QnA Maker modulu runtime je objekt QnAMakerRuntimeClient .

Po publikování znalostní báze pomocí klienta pro vytváření použijte metodu generateAnswer klienta modulu runtime k získání odpovědi z znalostní báze.

Klienta modulu runtime vytvoříte voláním QnAMakerRuntimeManager.authenticate a předáním klíče koncového bodu modulu runtime. K získání klíče koncového bodu modulu runtime použijte klienta pro vytváření volání getKeys.

Ověření klienta pro vytváření znalostní báze

Vytvořte instanci klienta pomocí koncového bodu pro vytváření obsahu a klíče předplatného.

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

Vytvoření znalostní báze

Znalostní báze ukládá páry otázek a odpovědí pro objekt CreateKbDTO ze tří zdrojů:

• Pro redakční obsah použijte objekt QnADTO .
  • Pokud chcete použít metadata a následné výzvy, použijte redakční kontext, protože tato data se přidávají na úrovni jednotlivých párů QnA.
• Pro soubory použijte FileDTO objekt. FileDTO obsahuje název souboru a veřejnou adresu URL pro přístup k souboru.
• Pro adresy URL použijte seznam řetězců, které představují veřejně dostupné adresy URL.

Zavolejte metodu create a pak předejte operationId vlastnost vrácené operace metodě getDetails k dotazování stavu.

Poslední řádek následujícího kódu vrátí ID znalostní báze.

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

Aktualizace znalostní báze

Znalostní báze můžete aktualizovat voláním aktualizace a předáním ID znalostní báze a objektu UpdateKbOperationDTO. Tento objekt pak může obsahovat:

• add
• update
• odstranění

operationId Předejte vlastnost vrácené operace metodě getDetails k dotazování na stav.

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

Stažení znalostní báze

Pomocí metody stahování stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem exportu portálu QnA Maker ze stránky Nastavení, protože výsledek této metody není soubor TSV.

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

Publikování znalostní báze

Publikujte znalostní báze pomocí metody publikování. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho na koncovém bodu.

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

Vygenerování odpovědi z znalostní báze

Po publikování znalostní báze potřebujete klíč koncového bodu modulu runtime k dotazování znalostní báze. Nejedná se o stejný klíč předplatného, který se používá k vytvoření klienta pro vytváření obsahu.

K získání objektu EndpointKeysDTO použijte metodu getKeysDTO.

Vytvořte klienta modulu runtime voláním QnAMakerRuntimeManager.authenticate a předáním klíče koncového bodu modulu runtime z objektu EndpointKeysDTO.

Vygenerujte odpověď z publikovaného znalostní báze pomocí metody generateAnswer. Tato metoda přijímá id znalostní báze a objekt QueryDTO.

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

Toto je jednoduchý příklad dotazování znalostní báze. Pokud chcete porozumět pokročilým scénářům dotazování, projděte si další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní báze pomocí metody delete s parametrem ID znalostní báze.

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

Získání stavu operace

Některé metody, jako je vytvoření a aktualizace, mohou trvat dostatek času, aby se místo čekání na dokončení procesu vrátila operace . K určení stavu původní metody použijte ID operace z operace k dotazování (s logikou opakování).

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

Spuštění aplikace

Tady je hlavní metoda pro aplikaci.

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

Spusťte aplikaci následujícím způsobem. Předpokládá se, že název třídy je Quickstart a vaše závislosti jsou v podsložce s názvem lib pod aktuální složkou.

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

Zdrojový kód pro tuto ukázku najdete na GitHubu.

Vyčištění prostředků

Pokud chcete vyčistit a odebrat předplatné služeb Azure AI, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní prostředky, které jsou k ní přidružené.

• Azure Portal
• Azure CLI

Další kroky

Kurz: Testování znalostní báze pomocí dávkového souboru

• Co je rozhraní API služby QnA Maker?
• Úprava znalostní báze
• Získání analýzy využití