Rychlý Start: QnA Maker Klientská knihovna

Požadavky

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

• Abyste mohli použít klíč a název prostředku, musíte mít QnA maker Resource. Při vytváření prostředku jste zadali název prostředku, klíč byl proto vytvořen za vás. Název prostředku se používá jako subdoména pro koncový bod. Pokud chcete načíst svůj klíč a název prostředku, vyberte pro svůj prostředek v Azure Portal rychlý Start . Název prostředku je první subdoménou adresy URL koncového bodu:

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

Vytvoření znalostní báze

Chcete-li vytvořit znalostní bázi rozhraní REST API a oblé, je nutné mít následující informace:

Informace	Konfigurace kudrlinkou	Účel
Název prostředku QnA Maker	URL	slouží k vytvoření adresy URL.
Klíč prostředku QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování pro QnA Maker službu
JSON popisující znalostní bázi Knowledge Base	-d bajty	Příklady formátu JSON
Velikost JSON v bajtech	-h param pro Content-Size záhlaví

Příkaz kudrlinkou se spustí z prostředí BASH. Tento příkaz upravte pomocí vlastního názvu prostředku, klíče prostředku a hodnot JSON a velikosti JSON.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs"]}'

Odpověď složené z QnA Maker zahrnuje operationId , který je požadován 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ískat stav operace

Když vytvoříte znalostní bázi, protože operace je asynchronní, odpověď obsahuje informace o tom, jak určit stav.

Informace	Konfigurace kudrlinkou	Účel
Název prostředku QnA Maker	URL	slouží k vytvoření adresy URL.
ID operace	Trasa URL	/operations/REPLACE-WITH-YOUR-OPERATION-ID
Klíč prostředku QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování pro QnA Maker službu

Příkaz kudrlinkou se spustí z prostředí BASH. Tento příkaz upravte s vlastním názvem prostředku, klíčem 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ěď složeného pole zahrnuje stav. Pokud je stav operace úspěšný, pak resourceLocation zahrnuje 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 znalostní báze musíte:

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

Tato úloha publikuje znalostní bázi. Získání klíče běhového koncového bodu je samostatný úkol.

Informace	Konfigurace kudrlinkou	Účel
Název prostředku QnA Maker	URL	slouží k vytvoření adresy URL.
Klíč prostředku QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování pro QnA Maker službu
ID znalostní báze	Trasa URL	/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Příkaz kudrlinkou se spustí z prostředí BASH. Tento příkaz upravte s vlastním názvem prostředku, klíčem 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ů. Použijte -v parametr příkazového řádku pro zobrazení podrobného výstupu příkazu složeného. To bude zahrnovat stav HTTP.

Získat klíč koncového bodu běhové služby znalostní báze

Před dotazem znalostní báze musíte:

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

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

Klíč běhového koncového bodu je stejný klíč pro všechny znalostní báze pomocí prostředku QnA Maker.

Informace	Konfigurace kudrlinkou	Účel
Název prostředku QnA Maker	URL	slouží k vytvoření adresy URL.
Klíč prostředku QnA Maker	-h param pro Ocp-Apim-Subscription-Key záhlaví	Ověřování pro QnA Maker službu

Příkaz kudrlinkou se spustí z prostředí BASH. Tento příkaz upravte s vlastním názvem prostředku a 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"

Odezva na kudrlinkou zahrnuje klíče koncového bodu modulu runtime. Při dotazování na získání odpovědi ze znalostní báze použijte pouze 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ěď z publikované znalostní báze

Získání odpovědi od znalostní báze se provádí od samostatného modulu runtime, než správy znalostní báze. Vzhledem k tomu, že se jedná o samostatný modul runtime, je nutné ověřit klíč za běhu.

Informace	Konfigurace kudrlinkou	Účel
Název prostředku QnA Maker	URL	slouží k vytvoření adresy URL
QnA Maker klíče modulu runtime	-h param pro Authorization hlavičku	Klíč je součástí řetězce, který obsahuje slovo Endpointkey . Ověření ve QnA Maker službě
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 hlavičku

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 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 zobrazit odpověď uživateli.

Odstranění znalostní báze

Až budete se znalostní bázi hotovi, odstraňte ji.

Informace	Konfigurace cURL	Účel
QnA Maker názvu prostředku	URL	slouží k vytvoření adresy URL
QnA Maker klíče prostředku	-h param pro Ocp-Apim-Subscription-Key hlavičku	Ověření ve QnA Maker službě
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 s vlastním názvem prostředku, klíčem 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í -v parametru příkazového řádku zobrazte podrobný výstup příkazu cURL. To bude zahrnovat stav HTTP.

Další zdroje informací

• Vytváření Referenční dokumentace
• Runtime Referenční dokumentace
• Ukázkové skripty BASH s využitím cURL

Pomocí klientské knihovny QnA Maker pro .NET:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získat klíč koncového bodu předpovědi za běhu
• Počkat na dlouhodobě běžící úlohu
• Stáhnout znalostní báze
• Získat odpověď ze znalostní báze
• Odstranění znalostní báze

Referenční dokumentace | Zdrojový kód knihovny | ukázky balíčku (NuGet) | C#

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma .
• Visual Studio integrované vývojové prostředí (IDE ) nebo aktuální verze .net Core.
• Jakmile budete mít předplatné Azure, vytvořte v Azure Portal prostředek QnA maker , abyste získali svůj klíč pro vytváření 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. Svůj klíč a název prostředku vložte do níže uvedeného kódu později v rychlém startu.
  • K vyzkoušení služby můžete použít bezplatnou cenovou úroveň ( F0 ) a upgradovat ji později na placenou úroveň pro produkční prostředí.

Nastavení

Rozhraní příkazového řádku

V okně konzoly (například cmd, PowerShell nebo bash) použijte dotnet new příkaz k vytvoření nové aplikace konzoly s názvem qna-maker-quickstart . Tento příkaz vytvoří jednoduchý projekt C# "Hello World" 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 vytvořit pomocí:

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 QnA Maker klientskou knihovnu pro .NET pomocí následujícího příkazu:

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

Direktivy using

Z adresáře 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 Main metodě aplikace přidejte proměnné a kód zobrazené v následující části, chcete-li použít běžné úkoly v rámci tohoto rychlého startu.

• Používáme klíč předplatného a vytváříte klíč, který se zamění. Další informace o vytváření klíčů najdete pod klíči v QnA maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Přejít na Azure Portal a vyhledat prostředek QnA Maker, který jste vytvořili v části požadavky. V části Správa prostředků vyberte klíče a koncová stránka a vyhledejte klíč pro vytváření obsahu a QnA maker koncový bod.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net . Přejít na Azure Portal a vyhledat prostředek QnA Maker, který jste vytvořili v části požadavky. Vyberte stránku Exportovat šablonu v části Automatizace a vyhledejte koncový bod modulu runtime.

• V případě produkčního prostředí zvažte použití zabezpečeného způsobu ukládání a přístupu k vašim přihlašovacím údajům. Například Azure Key trezor poskytuje zabezpečené úložiště klíčů.

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, který slouží k vytvoření, správě, publikování a stažení znalostní báze Knowledge Base.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a posílání nových navrhovaných dotazů pomocí rozhraní API pro vlaky (jako součást aktivního učení).

V tomto příkladu znalostní báze Knowledge Base

Znalostní báze v tomto rychlém startu začíná 2 QnA páry, to je prováděno za účelem zjednodušení příkladu a použití vysoce předvídatelných identifikátorů, které je možné použít v metodě Update. přiřadíte tak následné výzvy k dotazům na nové páry. Toto bylo plánováno a implementováno v konkrétním pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvíjet znalostní bázi v průběhu času s následnými výzvami, které jsou závislé na stávajících QnAch párů, můžete zvolit tyto možnosti:

• V případě větších knowledgebases spravujte znalostní bázi v textovém editoru nebo v nástroji TSV, který podporuje automatizaci, a potom zcela nahraďte znalostní bázi aktualizací.
• V případě menších knowledgebases Spravujte všechny následné výzvy úplně na portálu QnA Maker.

Podrobnosti o dvojicích QnA použitých v tomto rychlém startu:

• Typy páru QnA – v této znalostní bázi existují 2 typy párů QnA, a to po aktualizaci: chitchat a informace specifické pro doménu. To je obvyklé, pokud je vaše znalostní báze svázána s aplikací konverzace, jako je chatovací robot.
• I když je možné odpovědi na znalostní báze filtrovat podle metadat nebo použít výzvy k následnému použití, tento rychlý Start tento kurz nezobrazuje. Tadyhledejte příklady jazyků nezávislá generateAnswer.
• Text odpovědi je Markdownu a může obsahovat širokou škálu Markdownu , jako jsou například obrázky (veřejně dostupné internetové image), odkazy (na veřejně dostupné adresy URL) a body odrážek. v tomto rychlém startu se tato odrůda nepoužívá.

Objektový model QnAMakerClient

Klient pro vytváření 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ázi odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON indikující stav. V případě dlouhotrvajících operací je odpověď ID operace. Zavolejte klientovi. Operations. GetDetailsAsync metoda s ID operace k určení stavu požadavku.

Objektový model QnAMakerRuntimeClient

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

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

Příklady kódu

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

• Ověření klienta pro vytváření obsahu
• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Stáhnout znalostní bázi
• Publikování znalostní báze
• Odstranění znalostní báze
• Získat klíč běhu dotazu
• Získat stav operace
• Ověření klienta nástroje Query runtime
• Vygenerovat odpověď ze znalostní báze Knowledge Base

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

Vytvořte instanci objektu klienta s klíčem a použijte ho u svého prostředku 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 dotazů a odpovědí pro objekt CreateKbDTO ze tří zdrojů:

• Pro redakční obsah použijte objekt QnADTO .
  • Chcete-li použít metadata a výzvy pro následné zpracování, použijte redakční kontext, protože tato data jsou přidána na jednotlivé úrovně páru QnA.
• Pro soubory použijte objekt FileDTO . FileDTO zahrnuje název souboru a veřejnou adresu URL pro přístup k souboru.
• V případě adres URL použijte seznam řetězců, které reprezentují veřejně dostupné adresy URL.

Krok vytvoření zahrnuje také vlastnosti pro 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ředků nastavte jazyk, který se má použít v indexu Azure Search.

Zavolejte metodu CreateAsync a pak předejte vrácené ID operace do metody MonitorOperation pro dotazování 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);
}

Aby MonitorOperation bylo možné úspěšně vytvořit znalostní bázi, nezapomeňte zahrnout funkci, na kterou se odkazuje ve výše uvedeném kódu.

Aktualizace znalostní báze

Znalostní bázi můžete aktualizovat tak, že předáte ID znalostní báze a UpdatekbOperationDTO obsahující objekty pro Přidání, aktualizacia odstranění DTO do metody UpdateAsync . K určení, jestli se aktualizace zdařila, použijte metodu MonitorOperation .

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

Aby MonitorOperation bylo možné úspěšně aktualizovat znalostní bázi, nezapomeňte zahrnout funkci, na kterou se odkazuje ve výše uvedeném kódu.

Stáhnout znalostní bázi

Použijte metodu DownloadAsync ke stažení databáze jako seznamu QnADocumentsDTO. nejedná se o ekvivalent exportu QnA Makerho portálu ze Nastavení stránky, 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ázi 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 bodě. Jedná se o nezbytný krok k 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 budete potřebovat klíč modulu runtime dotazu k dotazování modulu runtime. Toto není stejný klíč, který jste použili k vytvoření původního objektu klienta.

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

K dotazování znalostní báze použijte některou z vlastností klíče 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 a vygenerování odpovědi nebo trénování z aktivního učení.

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

Pomocí QnAMakerRuntimeClient můžete:

• Získání odpovědi ze znalostní báze
• k odesílání nových navrhovaných otázek do znalostní báze pro aktivní učení.

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

Vygenerování odpovědi z publikované znalostní báze pomocí RuntimeClient. Metoda GenerateAnswerAsync. Tato metoda přijímá ID znalostní báze a QueryDTO. Přístup k dalším vlastnostem QueryDTO, jako je top a context pro použití v chatbotovi.

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í, zkontrolujte 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, například vytvoření a aktualizace, mohou trvat dostatečně dlouho, než se proces dokončí, ale vrátí se operace. Pomocí ID operace můžete dotazovat (s logikou opakování) k určení stavu původní metody.

Smyčka a Task.Delay v následujícím bloku kódu slouží 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 pomocí dotnet run příkazu z adresáře vaší aplikace.

dotnet run

Zdrojový kód této ukázky najdete na GitHub.

Pomocí QnA Maker knihovny pro Node.js 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 predikce
• Čekání na dlouhotr běžící úlohu
• Stažení znalostní báze
• Získání odpovědi ze znalostní báze
• Odstranění znalostní báze

Referenční dokumentace | Zdrojový kód knihovny | Balíček (npm) | Node.js ukázky

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma.
• Aktuální verze Node.js.
• Jakmile máte předplatné Azure, vytvořte prostředek QnA Maker v Azure Portal a získejte klíč a prostředek pro vytváření. Po nasazení vyberte Přejít k prostředku.
  • Budete potřebovat klíč a název prostředku z prostředku, který vytvoříte pro připojení aplikace k rozhraní QNA MAKER API. Název klíče a prostředku vložte do kódu níže v pozdější části tohoto rychlého startu.
  • K vyzkoušejí služby můžete použít bezplatnou cenovou úroveň ( ) a později upgradovat F0 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 nový adresář pro vaši aplikaci 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 Node se package.json souborem.

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 importujte 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 Azure vašeho prostředku.

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

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Přejděte do Azure Portal a vyhledejte prostředek QnA Maker, který jste vytvořili v požadavcích. Na stránce Klíče a koncový bod v části Správa prostředků vyhledejte Klíč vytváření (předplatné) a QnA Maker koncového bodu.

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

• V produkčním prostředí zvažte použití zabezpečeného způsobu ukládání přihlašovacích údajů a přístupu k přihlašovacím údajům. Trezor klíčů Azure například poskytuje zabezpečené úložiště klíčů.

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 vytvoření, správu, publikování a stažení 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 pro vytváření QnA Maker je objekt QnAMakerClient, který se ověřuje v Azure pomocí vašich přihlašovacích údajů, které obsahují 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ázi odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON označující stav. Pro dlouho běžící operace je odpovědí ID operace. Zavolejte metodu client.operations.getDetails s ID operace, abyste zjistili stav požadavku.

Objektový model QnAMakerRuntimeClient

Prediction QnA Maker client 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 pro .NET QnA Maker následujícím způsobem:

• Ověření klienta pro vytváření
• 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 dotazů
• Vygenerování odpovědi ze znalostní báze

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

Vytvořte instanci klienta s koncovým bodem a klíčem. Vytvořte objekt ServiceClientCredentials s vaším 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žívat 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 objekt FileDTO. 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 nenašla žádná odpověď
• enableHierarchicalExtraction – automaticky vytvářet relace výtek mezi extrahované 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 create s informacemi znalostní báze. Informace ve znalostní bázi jsou v podstatě objekt JSON.

Po vrácení metody create předejte ID vrácené operace metodě wait_for_operation dotazování na stav. Metoda wait_for_operation vrátí po dokončení operace. Parsování resourceLocation hodnoty hlavičky vrácené operace a získání nového 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;
}

Aby bylo možné úspěšně vytvořit znalostní bázi, nezapomeňte zahrnout funkci , na kterou odkazuje výše uvedený wait_for_operation kód.

Aktualizace znalostní báze

Znalostní bázi můžete aktualizovat předáním ID znalostní báze a updateKbOperationDTO obsahující objekty pro přidání,aktualizaci a odstranění objektů DTO do metody update. Objekty DTO jsou také v podstatě objekty JSON. Pomocí metody wait_for_operation zjistěte, jestli byla aktualizace ú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
}

Pokud chcete úspěšně aktualizovat znalostní bázi, ujistěte se, že zahrnuje funkci , na kterou odkazuje výše uvedený wait_for_operation kód.

Stažení znalostní báze

Pomocí metody download stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem QnA Maker portálu z Nastavení, protože výsledkem 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ázi pomocí metody publish. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho v koncovém bodě. 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 budete pro dotaz na modul runtime potřebovat klíč runtime dotazů. To není 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 .

Použijte jednu z klíčových vlastností vrácených v objektu k dotazování znalostní báze.

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 vygenerování odpovědi

Vytvořte QnAMakerRuntimeClient pro dotazování znalostní báze a vygenerujte odpověď nebo vlak z aktivního učení.

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

Použijte QnAMakerRuntimeClient k získání odpovědi ze znalostí nebo k odeslání nových navrhovaných otázek do znalostní báze pro aktivní učení.

Vygenerovat odpověď ze znalostní báze Knowledge Base

Vygenerujte odpověď z publikované znalostní báze pomocí metody RuntimeClient. Runtime. generateAnswer. Tato metoda přijímá ID znalostní báze a QueryDTO. Získejte přístup k dalším vlastnostem QueryDTO, jako je například začátek a kontext, který se má použít v robotu chatu.

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 dotazování znalostní báze. Pokud chcete pochopit pokročilé scénáře dotazování, Projděte si Další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní bázi 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ískat stav operace

Některé metody, jako například vytváření a aktualizace, mohou trvat dostatek času, než čeká na dokončení procesu, a vrátí se 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 slouží k simulaci logiky opakování. Nahraďte 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 pomocí node index.js příkazu z adresáře aplikace.

node index.js

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

Použití klientské knihovny QnA Maker pro Python pro:

• Vytvoření znalostní báze
• Aktualizace znalostní báze
• Publikování znalostní báze
• Získat klíč koncového bodu předpovědi za běhu
• Počkat na dlouhodobě běžící úlohu
• Stáhnout znalostní báze
• Získat odpověď ze znalostní báze
• Odstranit znalostní bázi

Referenční dokumentace | Zdrojový kód knihovny | Balíček (PyPi) | Ukázky Pythonu

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma .
• Python 3.x
• Jakmile budete mít předplatné Azure, vytvořte v Azure Portal prostředek QnA maker , abyste získali svůj klíč a koncový bod 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 koncový bod z prostředku, který vytvoříte. Svůj klíč a koncový bod vložíte do níže uvedeného kódu později v rychlém startu.
  • K vyzkoušení služby můžete použít bezplatnou cenovou úroveň ( F0 ) a upgradovat ji později na placenou úroveň pro produkční prostředí.

Nastavení

Instalace klientské knihovny

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

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 importujte 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 prostředku.

• Používáme klíč předplatného a vytváříte klíč, který se zamění. Další informace o vytváření klíčů najdete pod klíči v QnA maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Přejít na Azure Portal a vyhledat prostředek QnA Maker, který jste vytvořili v části požadavky. V části Správa prostředků vyberte klíče a koncová stránka a vyhledejte klíč pro vytváření obsahu a QnA maker koncový bod.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net . Přejít na Azure Portal a vyhledat prostředek QnA Maker, který jste vytvořili v části požadavky. Vyberte stránku Exportovat šablonu v části Automatizace a vyhledejte koncový bod modulu runtime.

• V případě produkčního prostředí zvažte použití zabezpečeného způsobu ukládání a přístupu k vašim přihlašovacím údajům. Například Azure Key trezor poskytuje zabezpečené úložiště klíčů.

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, který slouží k vytvoření, správě, publikování a stažení znalostní báze Knowledge Base.
• QnAMakerRuntime je objekt pro dotazování znalostní báze pomocí rozhraní GenerateAnswer API a posílání nových navrhovaných dotazů pomocí rozhraní API pro vlaky (jako součást aktivního učení).

V tomto příkladu znalostní báze Knowledge Base

Znalostní báze v tomto rychlém startu začíná 2 QnA páry, to je prováděno za účelem zjednodušení příkladu a použití vysoce předvídatelných identifikátorů, které je možné použít v metodě Update. přiřadíte tak následné výzvy k dotazům na nové páry. Toto bylo plánováno a implementováno v konkrétním pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvíjet znalostní bázi v průběhu času s následnými výzvami, které jsou závislé na stávajících QnAch párů, můžete zvolit tyto možnosti:

• V případě větších knowledgebases spravujte znalostní bázi v textovém editoru nebo v nástroji TSV, který podporuje automatizaci, a potom zcela nahraďte znalostní bázi aktualizací.
• V případě menších knowledgebases Spravujte všechny následné výzvy úplně na portálu QnA Maker.

Podrobnosti o dvojicích QnA použitých v tomto rychlém startu:

• Typy páru QnA – v této znalostní bázi existují 2 typy párů QnA, a to po aktualizaci: chitchat a informace specifické pro doménu. To je obvyklé, pokud je vaše znalostní báze svázána s aplikací konverzace, jako je chatovací robot.
• I když je možné odpovědi na znalostní báze filtrovat podle metadat nebo použít výzvy k následnému použití, tento rychlý Start tento kurz nezobrazuje. Tadyhledejte příklady jazyků nezávislá generateAnswer.
• Text odpovědi je Markdownu a může obsahovat širokou škálu Markdownu , jako jsou například obrázky (veřejně dostupné internetové image), odkazy (na veřejně dostupné adresy URL) a body odrážek. v tomto rychlém startu se tato odrůda nepoužívá.

Objektový model QnAMakerClient

Klient pro vytváření 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ázi odesláním objektu JSON. Pro okamžité operace metoda obvykle vrací objekt JSON indikující stav. V případě dlouhotrvajících operací je odpověď ID operace. Chcete-li určit stav žádosti, zavolejte metodu Operations.get_details s ID operace.

Objektový model QnAMakerRuntimeClient

Předpověď QnA Maker klient je QnAMakerRuntimeClient objekt, který se ověřuje v Azure pomocí Microsoft. REST. ServiceClientCredentials, který obsahuje klíč runtime předpovědi, který se vrátí z klientského volání pro vytváření . EndpointKeysOperations.get_keys po publikování znalostní báze.

Použijte generate_answer metodu k získání odpovědi z modulu runtime dotazu.

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

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

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

Vytvoření znalostní báze

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

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

• Pro redakční obsah použijte objekt QnADTO .
  • Chcete-li použít metadata a výzvy pro následné zpracování, použijte redakční kontext, protože tato data jsou přidána na jednotlivé úrovně páru QnA.
• Pro soubory použijte objekt FileDTO . FileDTO zahrnuje název souboru a veřejnou adresu URL pro přístup k souboru.
• V případě adres URL použijte seznam řetězců, které reprezentují veřejně dostupné adresy URL.

Zavolejte metodu Create a potom předejte vrácené ID operace do metody Operations. GetDetails pro dotazování na stav.

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

Aby bylo možné úspěšně vytvořit znalostní bázi, ujistěte se, že je zahrnutá _monitor_operation funkce, na kterou se odkazuje v kódu výše.

Aktualizace znalostní báze

Znalostní bázi můžete aktualizovat tak, že do metody aktualizace předáte ID znalostní báze a UpdateKbOperationDTO obsahující objekty pro Přidání, aktualizacia odstranění DTO. K určení, jestli se aktualizace zdařila, použijte metodu Operational detail .

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

Aby _monitor_operation bylo možné úspěšně aktualizovat znalostní bázi, ujistěte se, že obsahuje funkci, na kterou se odkazuje ve výše uvedeném kódu.

Stáhnout znalostní bázi

Použijte metodu Download ke stažení databáze jako seznamu QnADocumentsDTO. nejedná se o ekvivalent exportu QnA Makerového portálu 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ázi pomocí metody Publish . Tím se převezme aktuální uložený a vycvičený 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ískat klíč běhu dotazu

Po publikování znalostní báze budete pro dotaz na modul runtime potřebovat klíč runtime dotazů. To není 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 .

Použijte jednu z klíčových vlastností vrácených v objektu k dotazování znalostní báze.

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 vygenerování odpovědi

Vytvořte QnAMakerRuntimeClient pro dotazování znalostní báze a vygenerujte odpověď nebo vlak z aktivního učení.

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

Použijte QnAMakerRuntimeClient k získání odpovědi ze znalostí nebo k odeslání nových navrhovaných otázek do znalostní báze pro aktivní učení.

Vygenerovat odpověď ze znalostní báze Knowledge Base

Vygenerujte odpověď z publikované znalostní báze pomocí metody QnAMakerRuntimeClient.runtime.generate_answer. Tato metoda přijímá ID znalostní báze a QueryDTO. Získejte přístup k dalším vlastnostem QueryDTO, jako je například začátek a kontext, který se má použít v robotu chatu.

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 pochopit pokročilé scénáře dotazování, Projděte si Další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní bázi 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ískat stav operace

Některé metody, jako například vytváření a aktualizace, mohou trvat dostatek času, než čeká na dokončení procesu, a vrátí se 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 slouží k simulaci asynchronního kódu. Nahraďte 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 pro rychlý Start.

python quickstart-file.py

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

Pomocí klientské 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 predikce
• Čekání na dlouhotr běžící úlohu
• Stažení znalostní báze
• Získání odpovědi ze znalostní báze
• Odstranění znalostní báze

Zdrojový kód knihovny | Balíček | Ukázky

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma.
• JDK
• Jakmile máte předplatné Azure, vytvořte prostředek QnA Maker v Azure Portal a získejte klíč a koncový bod pro vytváření. Po nasazení vyberte Přejít k prostředku.
  • Klíč a koncový bod z prostředku, který vytvoříte, budete potřebovat pro připojení aplikace k QnA Maker API. Vložte svůj klíč a koncový bod do kódu níže v pozdější části tohoto rychlého startu.
  • K vyzkoušejí služby můžete použít bezplatnou cenovou úroveň ( ) a později upgradovat F0 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 a quickstart.java 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í používáme zaměnitelně. Další podrobnosti o klíči pro vytváření najdete v tématu Klíče v QnA Maker.

• Hodnota QNA_MAKER_ENDPOINT má formát https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com . Přejděte do Azure Portal a vyhledejte prostředek QnA Maker, který jste vytvořili v požadavcích. Na stránce Klíče a koncový bod v části Správa prostředků vyhledejte Klíč vytváření (předplatné) a QnA Maker koncového bodu.

• Hodnota QNA_MAKER_RUNTIME_ENDPOINT má formát https://YOUR-RESOURCE-NAME.azurewebsites.net . Přejděte do Azure Portal a vyhledejte prostředek QnA Maker, který jste vytvořili v požadavcích. V části Automation vyberte exportovat šablonu a vyhledejte koncový bod modulu runtime.

• V produkčním prostředí zvažte použití zabezpečeného způsobu ukládání přihlašovacích údajů a přístupu k přihlašovacím údajům. Azure Key Vault například poskytuje zabezpečené úložiště klíčů.

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 vytvoření, správu, publikování a stažení 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í).

V tomto příkladu znalostní báze Knowledge Base

Znalostní báze v tomto rychlém startu začíná 2 QnA páry, to je prováděno za účelem zjednodušení příkladu a použití vysoce předvídatelných identifikátorů, které je možné použít v metodě Update. přiřadíte tak následné výzvy k dotazům na nové páry. Toto bylo plánováno a implementováno v konkrétním pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvíjet znalostní bázi v průběhu času s následnými výzvami, které jsou závislé na stávajících QnAch párů, můžete zvolit tyto možnosti:

• V případě větších knowledgebases spravujte znalostní bázi v textovém editoru nebo v nástroji TSV, který podporuje automatizaci, a potom zcela nahraďte znalostní bázi aktualizací.
• V případě menších knowledgebases Spravujte všechny následné výzvy úplně na portálu QnA Maker.

Podrobnosti o dvojicích QnA použitých v tomto rychlém startu:

• Typy páru QnA – v této znalostní bázi existují 2 typy párů QnA, a to po aktualizaci: chitchat a informace specifické pro doménu. To je obvyklé, pokud je vaše znalostní báze svázána s aplikací konverzace, jako je chatovací robot.
• I když je možné odpovědi na znalostní báze filtrovat podle metadat nebo použít výzvy k následnému použití, tento rychlý Start tento kurz nezobrazuje. Tadyhledejte příklady jazyků nezávislá generateAnswer.
• Text odpovědi je Markdownu a může obsahovat širokou škálu Markdownu , jako jsou například obrázky (veřejně dostupné internetové image), odkazy (na veřejně dostupné adresy URL) a body odrážek. v tomto rychlém startu se tato odrůda nepoužívá.

Objektový model QnAMakerClient

Klient pro vytváření 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 je k dispozici. Pro dlouho běžící operace je odpovědí objekt Operation. Zavolejte metodu getDetails s hodnotou , operation.operationId abyste zjistili stav požadavku.

Objektový model QnAMakerRuntimeClient

Klient modulu runtime QnA Maker je objekt QnAMakerRuntimeClient.

Po publikování znalostní báze pomocí klienta pro vytváření můžete získat odpověď ze znalostní báze pomocí metody generateAnswer klienta modulu runtime.

Klienta modulu runtime vytvoříte tak, že zavoláte QnAMakerRuntimeManager.authenticate a předáte klíč koncového bodu modulu runtime. Pokud chcete získat klíč koncového bodu modulu runtime, použijte k volání metody getKeysklienta pro vytváření.

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

Vytvořte instanci klienta s koncovým bodem vytváření a klíčem 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žívat 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 objekt FileDTO. 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 vlastnost vrácené operace do metody operationId getDetails, která se dotazuje na stav.

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ázi 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
• delete

Předejte operationId vlastnost vrácené operace metodě getDetails, která se dotazuje 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 download stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem QnA Maker portálu z Nastavení, protože výsledkem 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ázi pomocí metody publish. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho v koncovém bodě.

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 ze znalostní báze

Po publikování znalostní báze potřebujete klíč koncového bodu modulu runtime k dotazování znalostní báze. Není stejný jako klíč předplatného použitý k vytvoření klienta pro vytváření.

Pomocí metody getKeys získejte objekt EndpointKeysDTO.

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.

Vygenerování odpovědi z publikované 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í, zkontrolujte další příklady dotazů.

Odstranění znalostní báze

Odstraňte znalostní bázi 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, například vytvoření a aktualizace, mohou trvat dostatečně dlouho, než se proces dokončí, ale vrátí se operace. Id operace z operace použijte k dotazování (s logikou opakování) k určení stavu původní metody.

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

    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 vaší třídy je a závislosti jsou v Quickstart podsložce s názvem lib pod aktuální složku.

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

Zdrojový kód této ukázky najdete na GitHub.

Pomocí klientské QnA Maker pro go:

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

Referenční informace (vytváření) | Referenční informace (modul runtime) | Zdrojový kód knihovny (vytváření obsahu) | Zdrojový kód knihovny (modul runtime) | Ukázky

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma.
• Přejít
• Jakmile máte předplatné Azure, vytvořte si v QnA Maker prostředku Azure Portal klíč a koncový bod pro vytváření. Po nasazení vyberte Přejít k prostředku.
  • Klíč a koncový bod z prostředku, který vytvoříte, budete potřebovat pro připojení aplikace k QnA Maker API. Vložte svůj klíč a koncový bod do kódu níže v pozdější části tohoto rychlého startu.
  • K vyzkoušejí služby můžete použít bezplatnou cenovou úroveň ( ) a později upgradovat F0 na placenou úroveň pro produkční prostředí.

Nastavení

Vytvoření nové aplikace v Go

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

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

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

var subscription_key string = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE"
var authoring_endpoint string = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE"
var runtime_endpoint string = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE"

Objektové modely

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

• QnAMakerClient je objekt pro vytvoření, správu, publikování a stažení 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í).

V tomto příkladu znalostní báze Knowledge Base

Znalostní báze v tomto rychlém startu začíná 2 QnA páry, to je prováděno za účelem zjednodušení příkladu a použití vysoce předvídatelných identifikátorů, které je možné použít v metodě Update. přiřadíte tak následné výzvy k dotazům na nové páry. Toto bylo plánováno a implementováno v konkrétním pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvíjet znalostní bázi v průběhu času s následnými výzvami, které jsou závislé na stávajících QnAch párů, můžete zvolit tyto možnosti:

• V případě větších knowledgebases spravujte znalostní bázi v textovém editoru nebo v nástroji TSV, který podporuje automatizaci, a potom zcela nahraďte znalostní bázi aktualizací.
• V případě menších knowledgebases Spravujte všechny následné výzvy úplně na portálu QnA Maker.

Podrobnosti o dvojicích QnA použitých v tomto rychlém startu:

• Typy páru QnA – v této znalostní bázi existují 2 typy párů QnA, a to po aktualizaci: chitchat a informace specifické pro doménu. To je obvyklé, pokud je vaše znalostní báze svázána s aplikací konverzace, jako je chatovací robot.
• I když je možné odpovědi na znalostní báze filtrovat podle metadat nebo použít výzvy k následnému použití, tento rychlý Start tento kurz nezobrazuje. Tadyhledejte příklady jazyků nezávislá generateAnswer.
• Text odpovědi je Markdownu a může obsahovat širokou škálu Markdownu , jako jsou například obrázky (veřejně dostupné internetové image), odkazy (na veřejně dostupné adresy URL) a body odrážek. v tomto rychlém startu se tato odrůda nepoužívá.

Objektový model QnAMakerClient

K vytvoření, aktualizaci, publikování, stažení a odstranění znalostní báze použijte KnowledgebaseClient. Tyto operace jsou uvedená v následujících částech.

Pomocí operationsclient můžete zkontrolovat stav dlouhotrých operací, jako je vytváření a aktualizace znalostních báců.

Objektový model QnAMakerRuntimeClient

Po publikování znalostní báze použijte RuntimeClient k dotazování znalostní báze. Tato operace je předmětem dotazu znalostní báze.

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žívat 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 objekt FileDTO. 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 vlastnost vrácené operace metodě operationId getDetails, která se bude dotazovat na stav.

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

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

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

    name := "QnA Maker FAQ"

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

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

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

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

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

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

Aktualizace znalostní báze

Znalostní bázi 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
• delete

Předejte operationId vlastnost vrácené operace metodě getDetails, která se bude dotazovat na stav.

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

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

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

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

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

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

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

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

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

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

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

Stažení znalostní báze

Pomocí metody download stáhněte databázi jako seznam QnADocumentsDTO. Toto není ekvivalentem exportu QnA Maker z webu Nastavení, protože výsledkem této metody není soubor TSV.

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

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

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

Publikování znalostní báze

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

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

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

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

Dotazování znalostní báze

Po publikování znalostní báze potřebujete klíč koncového bodu modulu runtime k dotazování znalostní báze. Není stejný jako klíč předplatného použitý k vytvoření klienta pro vytváření.

Vytvořte EndpointKeysClient a pomocí metody getKeys získejte objekt EndpointKeysDTO.

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

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

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

    return *result.PrimaryEndpointKey
}

Vytvořte RuntimeClient a zavolejte metodu GenerateAnswer pro dotazování znalostní báze.

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

    client := qnamakerruntime.NewRuntimeClient(runtime_endpoint)

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

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

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

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

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

Odstranění znalostní báze

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

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

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

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

Získání stavu operace

Některé metody, například vytvoření a aktualizace, mohou trvat dostatečně dlouho, než se proces dokončí, ale vrátí se operace. Pomocí ID operace můžete dotazovat (s logikou opakování) k určení stavu původní metody.

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

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

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

Ošetření chyb

Následující kód ukazuje, jak zpracovat chyby, které mohou být vráceny funkcemi sady SDK.

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

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

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

Spuštění aplikace

Tady je hlavní metoda aplikace.

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

    list_kbs()
    fmt.Println ()

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

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

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

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

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

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

go run kb_sample.go

Zdrojový kód této ukázky najdete na GitHub

Pomocí klientské QnA Maker pro Ruby:

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

Zdrojový kód knihovny (vytváření obsahu) | Zdrojový kód knihovny (modul runtime) | Balíček (vytváření) | Balíček (modul runtime) | Ukázky Ruby

Požadavky

• Předplatné Azure – Vytvořte si ho zdarma.
• Ruby 2.x
• Jakmile máte předplatné Azure, vytvořte prostředek QnA Maker v Azure Portal a získejte klíč a koncový bod pro vytváření. Po nasazení vyberte Přejít k prostředku.
  • Klíč a koncový bod z prostředku, který vytvoříte, budete potřebovat pro připojení aplikace k QnA Maker API. Svůj klíč a koncový bod vložíte do kódu níže v pozdější části tohoto rychlého startu.
  • K vyzkoušejí služby můžete použít bezplatnou cenovou úroveň ( ) a později upgradovat F0 na placenou úroveň pro produkční prostředí.

Nastavení

Instalace klientských knihoven

Po instalaci Ruby můžete klientské knihovny nainstalovat pomocí:

gem install azure_cognitiveservices_qnamaker
gem install azure_cognitiveservices_qnamakerruntime

Vytvoření nové aplikace v Ruby

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

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

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

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'
endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'
runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

Objektové modely

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

• QnAMakerClient je objekt pro vytvoření, správu, publikování a stažení 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í).

V tomto příkladu znalostní báze Knowledge Base

Znalostní báze v tomto rychlém startu začíná 2 QnA páry, to je prováděno za účelem zjednodušení příkladu a použití vysoce předvídatelných identifikátorů, které je možné použít v metodě Update. přiřadíte tak následné výzvy k dotazům na nové páry. Toto bylo plánováno a implementováno v konkrétním pořadí pro účely tohoto rychlého startu.

Pokud plánujete vyvíjet znalostní bázi v průběhu času s následnými výzvami, které jsou závislé na stávajících QnAch párů, můžete zvolit tyto možnosti:

• V případě větších knowledgebases spravujte znalostní bázi v textovém editoru nebo v nástroji TSV, který podporuje automatizaci, a potom zcela nahraďte znalostní bázi aktualizací.
• V případě menších knowledgebases Spravujte všechny následné výzvy úplně na portálu QnA Maker.

Podrobnosti o dvojicích QnA použitých v tomto rychlém startu:

• Typy páru QnA – v této znalostní bázi existují 2 typy párů QnA, a to po aktualizaci: chitchat a informace specifické pro doménu. To je obvyklé, pokud je vaše znalostní báze svázána s aplikací konverzace, jako je chatovací robot.
• I když je možné odpovědi na znalostní báze filtrovat podle metadat nebo použít výzvy k následnému použití, tento rychlý Start tento kurz nezobrazuje. Tadyhledejte příklady jazyků nezávislá generateAnswer.
• Text odpovědi je Markdownu a může obsahovat širokou škálu Markdownu , jako jsou například obrázky (veřejně dostupné internetové image), odkazy (na veřejně dostupné adresy URL) a body odrážek. v tomto rychlém startu se tato odrůda nepoužívá.

Objektový model QnAMakerClient

Klient pro 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 znalostní báze klienta k vytvoření, správě a publikování znalostní báze.

Pro okamžité operace metoda obvykle vrátí výsledek, pokud je k dispozici. Pro dlouho běžící operace je odpovědí objekt operace. Zavolejte operations.get_details s operation.operation_id hodnotou a určete stav požadavku.

Objektový model QnAMakerRuntimeClient

Klient modulu runtime QnA Maker je objekt QnAMakerRuntimeClient.

Po publikování znalostní báze pomocí klienta pro vytváření můžete pomocí metody runtime.generate_answer klienta modulu runtime získat odpověď ze znalostní báze.

Při volání metody generate_answer předejte hodnotu hash custom_headers volitelného parametru. Tato hodnota hash by měla obsahovat Authorization klíč a hodnotu EndpointKey YOUR_ENDPOINT_KEY . Jako hodnotu YOUR_ENDPOINT_KEY použijte klienta pro vytváření, který volá endpoint_keys.get_keys.

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

Vytvořte instanci klienta s koncovým bodem vytváření a klíčem předplatného.

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

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žívat 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 objekt FileDTO. 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 vlastnost vrácené operace operation_id metodě operations.get_details dotazování na stav.

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

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

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

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

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

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

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

    return knowledge_base_ID
end

Aktualizace znalostní báze

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

• add
• update
• delete

Předejte operation_id vlastnost vrácené operace metodě operations.get_details dotazování na stav.

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

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

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

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

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

Stažení znalostní báze

Pomocí metody knowledgebase.download stáhněte databázi jako seznam QnADocumentsDTO. To není ekvivalentem QnA Maker portálu aplikace z Nastavení, protože výsledkem této metody není soubor TSV.

def download_kb(client, kb_id)
    print("Downloading knowledge base...\n")
    kb_data = client.knowledgebase.download(kb_id, "Prod")
    print("Downloaded knowledge base. It has #{kb_data.qna_documents.length()} QnAs.\n")
end

Publikování znalostní báze

Publikujte znalostní bázi pomocí metody knowledgebase.publish. Tím se vezme aktuální uložený a natrénovaný model, na který odkazuje ID znalostní báze, a publikuje ho v koncovém bodě.

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

Získání klíče modulu runtime dotazů

Po publikování znalostní báze potřebujete klíč koncového bodu modulu runtime k dotazování znalostní báze. Není stejný jako klíč předplatného použitý k vytvoření klienta pro vytváření.

K získání endpoint_keys EndpointKeysDTO použijte metodu endpoint_keys.get_keys.

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

def getEndpointKeys_kb(client)
    print("Getting runtime endpoint keys...\n")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: #{keys.primary_endpoint_key}.\n")

    return keys.primary_endpoint_key
end

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

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

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

Vygenerování odpovědi z publikované znalostní báze pomocí metody RuntimeClient.runtime.generateAnswer Tato metoda přijímá ID znalostní báze a QueryDTO. Přístup k dalším vlastnostem QueryDTO, jako je top a context pro použití v chatbotovi.

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

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

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

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

Odstranění znalostní báze

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

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

Získání stavu operace

Některé metody, například vytvoření a aktualizace, mohou trvat dostatečně dlouho, než se proces dokončí, ale vrátí se operace. Pomocí ID operace můžete dotazovat (s logikou opakování) k určení stavu původní metody.

def _monitor_operation(client, operation)

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

    return operation
end

Spuštění aplikace

Tady je hlavní metoda aplikace.

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

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

runtime_endpoint_key = getEndpointKeys_kb(client)

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

generate_answer(runtime_client, kb_id, runtime_endpoint_key)

delete_kb(client, kb_id)

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

ruby quickstart.rb

Zdrojový kód této ukázky najdete na GitHub.