Rövid útmutató: QnA Maker ügyfélkódtár

  • Cikk

Feljegyzés

Az Azure Open AI On Your Data nagy nyelvi modelleket (LLM-eket) használ a QnA Makerhez hasonló eredmények előállításához. Ha migrálni szeretné a QnA Maker-projektet az Azure Open AI On Your Data szolgáltatásba, tekintse meg útmutatónkat.

Ismerkedés a QnA Maker ügyfélkódtárával. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

Feljegyzés

A QnA Maker szolgáltatás 2025. március 31-én megszűnik. A kérdés- és válaszképesség újabb verziója már elérhető az Azure AI Language részeként. A Nyelvi szolgáltatáson belüli kérdések megválaszolási képességeiről a kérdések megválaszolása című témakörben olvashat. 2022. október 1-től nem hozhat létre új QnA Maker-erőforrásokat. A meglévő QnA Maker-tudásbázis kérdés megválaszolásához tekintse meg a migrálási útmutatót.

Előfeltételek

Feljegyzés

Ez a dokumentáció nem vonatkozik a legújabb kiadásra. A REST API legújabb kiadással való használatáról a REST API rövid útmutatójával kapcsolatos kérdésben olvashat

  • A cURL aktuális verziója. A rövid útmutatókban több parancssori kapcsolót is használnak, amelyeket a cURL dokumentációja is feljegyez.

  • A kulcs és az erőforrásnév használatához QnA Maker-erőforrással kell rendelkeznie. Az erőforrás neve az erőforrás létrehozásakor lett megadva, majd a kulcs létre lett hozva Önnek. A végpont altartományaként az erőforrás nevét használja a rendszer. A kulcs és az erőforrás nevének lekéréséhez válassza az erőforrás rövid útmutatóját az Azure Portalon. Az erőforrás neve a végpont URL-címének első altartománya:

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

Figyelemfelhívás

Az alábbi BASH-példák a sor folytatási karakterét \ használják. Ha a konzolon vagy a terminálon egy másik sor folytatási karaktert használ, használja ezt a karaktert.

Tudásbázis létrehozása

Ha a REST API-kkal és a cURL-vel szeretne tudásbázis létrehozni, az alábbi információkkal kell rendelkeznie:

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
QnA Maker-erőforráskulcs -hélőfej param Ocp-Apim-Subscription-Key Hitelesítés a QnA Maker szolgáltatásban
A tudásbázis leíró JSON -d Param Példák JSON-ra
A JSON mérete bájtban -hélőfej param Content-Size

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot saját erőforrásnevével, erőforráskulcsával és JSON-értékeivel és JSON-méretével.

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

A QnA Maker cURL-válasza tartalmazza a operationId művelet állapotának lekéréséhez szükséges elemet.

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

A művelet állapotának lekérése

Amikor létrehoz egy tudásbázis, mivel a művelet aszinkron, a válasz információkat tartalmaz az állapot meghatározásához.

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
Műveletazonosító URL-útvonal /operations/REPLACE-WITH-YOUR-OPERATION-ID
QnA Maker-erőforráskulcs -hélőfej param Ocp-Apim-Subscription-Key Hitelesítés a QnA Maker szolgáltatásban

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot saját erőforrásnevével, erőforráskulcsával és műveleti azonosítójával.

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"

A cURL-válasz tartalmazza az állapotot. Ha a művelet állapota sikeres, akkor a resourceLocation tudásbázis azonosítót is tartalmazza.

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

Tudásbázis közzététele

A tudásbázis lekérdezése előtt a következőt kell elvégeznie:

  • Tudásbázis közzététele
  • A futtatókörnyezet végpontkulcsának lekérése

Ez a feladat közzéteszi a tudásbázis. A futtatókörnyezet végpontkulcsának lekérése külön feladat.

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
QnA Maker-erőforráskulcs -hélőfej param Ocp-Apim-Subscription-Key Hitelesítés a QnA Maker szolgáltatásban
Tudásbázis azonosítója URL-útvonal /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot saját erőforrásnevével, erőforráskulcsával és tudásbázis azonosítójával.

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

A válasz állapota 204, eredmény nélkül. -v A parancssori paraméter használatával megtekintheti a cURL parancs részletes kimenetét. Ez magában foglalja a HTTP-állapotot.

Közzétett tudásbázis futtatókörnyezeti végpontkulcsának lekérése

A tudásbázis lekérdezése előtt a következőt kell elvégeznie:

  • Tudásbázis közzététele
  • A futtatókörnyezet végpontkulcsának lekérése

Ez a feladat lekéri a futtatókörnyezet végpontkulcsát. A tudásbázis közzététele külön feladat.

A futtatókörnyezet végpontkulcsa ugyanaz a kulcs a QnA Maker-erőforrást használó összes tudásbázis.

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
QnA Maker-erőforráskulcs -hélőfej param Ocp-Apim-Subscription-Key Hitelesítés a QnA Maker szolgáltatásban

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot a saját erőforrásnevével, erőforráskulcsával.

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"

A cURL-válasz tartalmazza a futtatókörnyezet végpontkulcsait. A lekérdezés során csak az egyik kulcs használatával kaphat választ a tudásbázis.

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

A közzétett tudásbázis válaszának lekérdezése

A tudásból való választ egy külön futtatókörnyezetből lehet megkapni, mint a tudásbázis kezelése. Mivel ez egy külön futtatókörnyezet, futtatókörnyezeti kulccsal kell hitelesítenie magát.

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
QnA Maker futtatókörnyezeti kulcs -hélőfej param Authorization A kulcs egy sztring része, amely tartalmazza a szót Endpointkey . Hitelesítés a QnA Maker szolgáltatásban
Tudásbázis azonosítója URL-útvonal /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
Lekérdezést leíró JSON -d Param Törzsparaméterek kérése és példák a JSON-ra
A JSON mérete bájtban -hélőfej param Content-Size

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot saját erőforrásnevével, erőforráskulcsával és tudásbázis azonosítójával.

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

A sikeres válasz magában foglalja a legfontosabb választ, valamint az ügyfélalkalmazások egyéb információival, például a csevegőrobottal kapcsolatos információkat, amelyeket a felhasználónak meg kell jelenítenie.

Tudásbázis törlése

Ha végzett a tudásbázis, törölje azt.

Tájékoztatás cURL-konfiguráció Cél
QnA Maker-erőforrás neve URL-cím URL-cím létrehozásához használatos
QnA Maker-erőforráskulcs -hélőfej param Ocp-Apim-Subscription-Key Hitelesítés a QnA Maker szolgáltatásban
Tudásbázis azonosítója URL-útvonal /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

A cURL parancs egy BASH-rendszerhéjból lesz végrehajtva. Szerkessze ezt a parancsot saját erőforrásnevével, erőforráskulcsával és tudásbázis azonosítójával.

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"

A válasz állapota 204, eredmény nélkül. -v A parancssori paraméter használatával megtekintheti a cURL parancs részletes kimenetét. Ez magában foglalja a HTTP-állapotot.

További erőforrások

Használja a QnA Maker ügyfélkódtárát a .NET-hez a következő célokra:

  • Tudásbázis létrehozása
  • Tudásbázis frissítése
  • Tudásbázis közzététele
  • Előrejelzési futtatókörnyezet végpontkulcsának lekérése
  • Várjon a hosszú ideig futó tevékenységre
  • Tudásbázis letöltése
  • Válasz lekérése egy tudásbázisból
  • Tudásbázis törlése

Referenciadokumentáció Kódtár forráskódcsomagja | (NuGet) | C# minták |

Feljegyzés

A 2019. július 1. után létrehozott új erőforrások egyéni altartományneveket fognak használni. További információkért és a regionális végpontok teljes listájáért tekintse meg az Azure AI-szolgáltatások egyéni altartományneveit.

Előfeltételek

Feljegyzés

Ez a dokumentáció nem vonatkozik a legújabb kiadásra. A C# API legújabb kiadással való használatáról a C# rövid útmutatót megválaszoló kérdésben olvashat.

  • Azure-előfizetés – Ingyenes létrehozás
  • A Visual Studio IDE vagy a .NET Core aktuális verziója.
  • Miután megkapta az Azure-előfizetését, hozzon létre egy QnA Maker-erőforrást az Azure Portalon a szerzői kulcs és az erőforrásnév lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
    • Az alkalmazás QnA Maker API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és erőforrásnevére. Illessze be a kulcsot és az erőforrás nevét az alábbi kódba a rövid útmutató későbbi részében.
    • Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Beállítás

parancssori felület

Egy konzolablakban (például parancsmag, PowerShell vagy Bash) a dotnet new paranccsal hozzon létre egy új konzolalkalmazást a névvel qna-maker-quickstart. Ez a parancs létrehoz egy egyszerű ""Helló világ!" alkalmazás" C#-projektet egyetlen forrásfájllal: program.cs.

dotnet new console -n qna-maker-quickstart

Módosítsa a könyvtárat az újonnan létrehozott alkalmazásmappára. Az alkalmazást a következőkkel hozhatja létre:

dotnet build

A buildkimenet nem tartalmazhat figyelmeztetést vagy hibát.

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

Az alkalmazáskönyvtárban telepítse a QnA Maker ügyfélkódtárat a .NET-hez a következő paranccsal:

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

Tipp.

Szeretné egyben megtekinteni a teljes gyorsútmutatós kódfájlt? Megtalálhatja a GitHubon, amely a gyorsútmutató kódmintáit is tartalmazza.

Irányelvek használata

Nyissa meg a program.cs fájlt a projektkönyvtárban, és adja hozzá a következő using irányelveket:

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

Előfizetési kulcs és erőforrásvégpontok

Az alkalmazás metódusában Main adja hozzá a következő szakaszban látható változókat és kódot, hogy az ebben a rövid útmutatóban szereplő gyakori feladatokat használhassa.

  • Az előfizetési kulcsot és a szerzői kulcsot felcseréljük. A szerkesztési kulcsokkal kapcsolatos további részletekért kövesse a Kulcsok a QnA Makerben című témakört.

  • A QNA_MAKER_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Kulcsok és végpontok lapot az erőforrás-kezelés alatt a Szerzői (előfizetési) kulcs és a QnA Maker-végpont megkereséséhez.

QnA Maker szerzői végpontja

  • A QNA_MAKER_RUNTIME_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.azurewebsites.net. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Sablon exportálása lapot az Automation területen a futtatókörnyezeti végpont megkereséséhez.

QnA Maker futtatókörnyezet végpontja

Fontos

Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információkért tekintse meg az Azure AI-szolgáltatások biztonsági cikkét.

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

Objektummodellek

A QnA Maker két különböző objektummodellt használ:

  • A QnAMakerClient a tudásbázis létrehozásához, kezeléséhez, közzétételéhez és letöltéséhez szükséges objektum.
  • A QnAMakerRuntime az az objektum, amely lekérdezi a tudásbázis a GenerateAnswer API-val, és új javasolt kérdéseket küldhet a Train API használatával (az aktív tanulás részeként).

Ebben a példában tudásbázis

A tudásbázis ebben a rövid útmutatóban 2 beszélgetési QnA-párral kezdődik, ez a példa egyszerűsítése és a rendkívül kiszámítható azonosítók használata érdekében történik az Update metódusban, és az utánkövetési kérések társítása az új párokra vonatkozó kérdésekkel. Ezt a rövid útmutatóhoz egy meghatározott sorrendben tervezték és implementálták.

Ha a tudásbázis idővel a meglévő QnA-pároktól függő nyomon követési kérésekkel tervezi fejleszteni, a következő lehetőségek közül választhat:

  • Nagyobb tudásbázisok esetén kezelje a tudásbázis egy olyan szövegszerkesztőben vagy TSV-eszközben, amely támogatja az automatizálást, majd cserélje le a tudásbázis egyszerre egy frissítésre.
  • Kisebb tudásbázisok esetén az utánkövetési utasításokat teljes egészében a QnA Maker portálján kezelheti.

Az ebben a rövid útmutatóban használt QnA-párokkal kapcsolatos részletek:

  • A QnA-párok típusai – ebben a tudásbázis két QnA-pártípus található a frissítés után: chitchat és tartományspecifikus információk. Ez általában akkor jellemző, ha a tudásbázis egy beszélgetési alkalmazáshoz, például egy csevegőrobothoz van kötve.
  • Bár a tudásbázis válaszait metaadatok alapján szűrheti, vagy követési utasításokat használhat, ez a rövid útmutató nem jeleníti meg ezt. Keresse meg ezeket a nyelvi-agnosztikus generateAnswer példákat itt.
  • A válaszszöveg markdown, és számos különböző markdownt tartalmazhat, például képeket (nyilvánosan elérhető internetes képeket), hivatkozásokat (nyilvánosan elérhető URL-címekhez) és listajelpontokat. Ez a rövid útmutató nem használja ezt a változatosságot.

QnAMakerClient objektummodell

A tartalomkészítő QnA Maker-ügyfél egy QnAMakerClient objektum, amely a kulcsot tartalmazó Microsoft.Rest.ServiceClientCredentials használatával hitelesíti az Azure-t.

Az ügyfél létrehozása után használja a Tudásbázis tulajdonságot a tudásbázis létrehozásához, kezeléséhez és közzétételéhez.

A tudásbázis egy JSON-objektum elküldésével kezelheti. Azonnali műveletek esetén a metódus általában egy állapotot jelző JSON-objektumot ad vissza. Hosszú ideig futó műveletek esetén a válasz a művelet azonosítója. Hívja fel az ügyfelet . Operations.GetDetailsAsync metódus a műveletazonosítóval a kérés állapotának meghatározásához.

QnAMakerRuntimeClient objektummodell

Az előrejelzési QnA Maker-ügyfél egy QnAMakerRuntimeClient objektum, amely a tudásbázis közzététele után a Microsoft.Rest.ServiceClientCredentials használatával hitelesíti az Azure-t, amely tartalmazza az client.EndpointKeys.GetKeys előrejelzési futtatókörnyezet kulcsát.

A GenerateAnswer metódussal választ kaphat a lekérdezési futtatókörnyezetből.

Kódpéldák

Ezek a kódrészletek a következőket mutatják be a .NET-hez készült QnA Maker ügyfélkódtárban:

Az ügyfél hitelesítése a tudásbázis

Hozzon létre egy ügyfélobjektumot a kulccsal, és használja az erőforrással a végpont létrehozásához egy QnAMakerClient létrehozásához a végponttal és a kulccsal. Hozzon létre egy ServiceClientCredentials objektumot.

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

Tudásbázis létrehozása

Egy tudásbázis három forrásból tárolja a CreateKbDTO objektum kérdés- és válaszpárjait:

  • Szerkesztői tartalom esetén használja a QnADTO objektumot.
    • Metaadatok és nyomon követési kérések használatához használja a szerkesztői környezetet, mivel ezek az adatok az egyes QnA-párok szintjén lesznek hozzáadva.
  • Fájlok esetén használja a FileDTO objektumot. A FileDTO tartalmazza a fájlnevet és a nyilvános URL-címet a fájl eléréséhez.
  • URL-címek esetén a sztringek listájával jelölheti a nyilvánosan elérhető URL-címeket.

A létrehozási lépés a tudásbázis tulajdonságait is tartalmazza:

  • defaultAnswerUsedForExtraction - mit ad vissza a rendszer, ha nem talál választ
  • enableHierarchicalExtraction - automatikusan hozzon létre parancssori kapcsolatokat a kinyert QnA-párok között
  • language - egy erőforrás első tudásbázisának létrehozásakor állítsa be a használni kívánt nyelvet az Azure Search-indexben.

Hívja meg a CreateAsync metódust, majd adja át a visszaadott műveletazonosítót a MonitorOperation metódusnak az állapot lekérdezéséhez.

A következő kód utolsó sora a MonitorOperation válaszából származó tudásbázis azonosítót adja vissza.

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

A tudásbázis sikeres létrehozásához mindenképpen adja meg a MonitorOperation fenti kódban hivatkozott függvényt.

Tudásbázis frissítése

A tudásbázis a tudásbázis azonosító és a DTO-objektumok hozzáadását, frissítését és törlését tartalmazó UpdatekbOperationDTO azonosító megadásával frissítheti az UpdateAsync metódust. A MonitorOperation metódus használatával állapítsa meg, hogy a frissítés sikeres volt-e.

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

A tudásbázis sikeres frissítéséhez mindenképpen adja meg a MonitorOperation fenti kódban hivatkozott függvényt.

Tudásbázis letöltése

A DownloadAsync metódussal töltse le az adatbázist a QnADocumentsDTO listájaként. Ez nem egyenértékű a QnA Maker portál Gépház oldalról történő exportálásával, mert ennek a módszernek az eredménye nem fájl.

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
}

Tudásbázis közzététele

Tegye közzé a tudásbázis a PublishAsync metódussal. Ez az aktuálisan mentett és betanított modellt használja, amelyre az tudásbázis azonosító hivatkozik, és közzéteszi azt a végponton. Ez egy szükséges lépés a tudásbázis lekérdezéséhez.

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

Lekérdezés futtatókörnyezeti kulcsának lekérése

Miután közzétett egy tudásbázist, a futtatókörnyezet lekérdezéséhez szüksége lesz a lekérdezési futtatókörnyezet kulcsára. Ez nem ugyanaz a kulcs, amelyet az eredeti ügyfélobjektum létrehozásához használnak.

Az EndpointKeysDTO osztály lekéréséhez használja az EndpointKeysDTO metódust.

Használja az objektumban visszaadott kulcstulajdonságok egyikét a tudásbázis lekérdezéséhez.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

A tudásbázis lekérdezéséhez futtatókörnyezeti kulcs szükséges.

A válasz létrehozásához használt futtatókörnyezet hitelesítése

Hozzon létre egy QnAMakerRuntimeClientet a tudásbázis lekérdezéséhez, hogy választ hozzon létre vagy betaníthasson az aktív tanulásból.

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

A QnAMakerRuntimeClient használatával:

  • válasz kérése a tudásbázisból
  • új javasolt kérdések küldése a tudásbázis az aktív tanuláshoz.

Válasz létrehozása a tudásbázis

Válasz létrehozása közzétett tudásbázisból a RuntimeClient használatával.GenerateAnswerAsync metódus. Ez a metódus elfogadja a tudásbázis azonosítót és a QueryDTO-t. Hozzáférhet a QueryDTO további tulajdonságaihoz, például a legfelső és a környezethez , amelyeket a csevegőrobotban használhat.

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
}

Ez egy egyszerű példa a tudásbázis lekérdezésére. A speciális lekérdezési forgatókönyvek megismeréséhez tekintse át a többi lekérdezési példát.

Tudásbázis törlése

Törölje a tudásbázist a DeleteAsync metódussal a tudásbázis azonosító paraméterével.

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

Művelet állapotának lekérése

Egyes metódusok, például a létrehozás és a frissítés elegendő időt vehet igénybe, hogy a folyamat befejezésére való várakozás helyett a rendszer egy műveletet ad vissza. Az eredeti metódus állapotának meghatározásához használja a művelet műveletazonosítóját (újrapróbálkozási logikával).

A ciklus és Task.Delay a következő kódblokk az újrapróbálkozás logikájának szimulálására szolgál. Ezeket a saját újrapróbálkozással kapcsolatos logikával kell lecserélni.

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

Az alkalmazás futtatása

Futtassa az alkalmazást az dotnet run alkalmazáskönyvtárból származó paranccsal.

dotnet run

A minta forráskódja a GitHubon található.

Használja a QnA Maker ügyfélkódtárát Node.js a következő célokra:

  • Tudásbázis létrehozása
  • Tudásbázis frissítése
  • Tudásbázis közzététele
  • Előrejelzési futtatókörnyezet végpontkulcsának lekérése
  • Várjon a hosszú ideig futó tevékenységre
  • Tudásbázis letöltése
  • Válasz lekérése egy tudásbázisból
  • Tudásbázis törlése

Referenciadokumentáció csomag (npm) | Node.js minták |

Feljegyzés

A 2019. július 1. után létrehozott új erőforrások egyéni altartományneveket fognak használni. További információkért és a regionális végpontok teljes listájáért tekintse meg az Azure AI-szolgáltatások egyéni altartományneveit.

Előfeltételek

  • Azure-előfizetés – Ingyenes létrehozás
  • A Node.js aktuális verziója.
  • Miután megkapta az Azure-előfizetését, hozzon létre egy QnA Maker-erőforrást az Azure Portalon a szerzői kulcs és az erőforrás lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
    • Az alkalmazás QnA Maker API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és erőforrásnevére. Illessze be a kulcsot és az erőforrás nevét az alábbi kódba a rövid útmutató későbbi részében.
    • Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Beállítás

Új Node.js-alkalmazás létrehozása

Egy konzolablakban (pl. cmd, PowerShell vagy Bash) hozzon létre egy új mappát az alkalmazásnak, majd navigáljon oda.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Futtassa az npm init -y parancsot egy Node-alkalmazás package.json fájllal való létrehozásához.

npm init -y

Telepítse az ügyfélkódtárat

Telepítse a következő NPM-csomagokat:

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

Az alkalmazás fájlja package.json frissül a függőségekkel.

Hozzon létre egy index.js nevű fájlt, és importálja a következő kódtárakat:

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

Hozzon létre egy változót az erőforrás Azure-kulcsához és erőforrás nevéhez.

  • Az előfizetési kulcsot és a szerzői kulcsot felcseréljük. A szerkesztési kulcsokkal kapcsolatos további részletekért kövesse a Kulcsok a QnA Makerben című témakört.

  • A QNA_MAKER_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Kulcsok és végpontok lapot az erőforrás-kezelés alatt a Szerzői (előfizetési) kulcs és a QnA Maker-végpont megkereséséhez.

QnA Maker szerzői végpontja

  • A QNA_MAKER_RUNTIME_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.azurewebsites.net. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Sablon exportálása lapot az Automation területen a futtatókörnyezeti végpont megkereséséhez.

QnA Maker futtatókörnyezet végpontja

Fontos

Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információkért tekintse meg az Azure AI-szolgáltatások biztonsági cikkét.

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

Objektummodellek

A QnA Maker két különböző objektummodellt használ:

  • A QnAMakerClient a tudásbázis létrehozásához, kezeléséhez, közzétételéhez és letöltéséhez szükséges objektum.
  • A QnAMakerRuntime az az objektum, amely lekérdezi a tudásbázis a GenerateAnswer API-val, és új javasolt kérdéseket küldhet a Train API használatával (az aktív tanulás részeként).

QnAMakerClient objektummodell

A létrehozó QnA Maker-ügyfél egy QnAMakerClient-objektum , amely hitelesítő adataival hitelesíti az Azure-t, amely tartalmazza a kulcsot.

Az ügyfél létrehozása után használja a tudásbázist a tudásbázis létrehozásához, kezeléséhez és közzétételéhez.

A tudásbázis egy JSON-objektum elküldésével kezelheti. Azonnali műveletek esetén a metódus általában egy állapotot jelző JSON-objektumot ad vissza. Hosszú ideig futó műveletek esetén a válasz a művelet azonosítója. A kérelem állapotának meghatározásához hívja meg a client.operations.getDetails metódust a műveletazonosítóval.

QnAMakerRuntimeClient objektummodell

Az előrejelzési QnA Maker-ügyfél egy QnAMakerRuntimeClient objektum, amely a Microsoft.Rest.ServiceClientCredentials használatával hitelesíti az Azure-t, amely tartalmazza az előrejelzési futtatókörnyezeti kulcsot, amelyet a szerzői ügyfélhívásból, ügyféltől kapott. EndpointKeys.getKeys a tudásbázis közzététele után.

Kódpéldák

Ezek a kódrészletek a következőket mutatják be a .NET-hez készült QnA Maker ügyfélkódtárban:

Az ügyfél hitelesítése a tudásbázis

Ügyfél példányosítása a végponttal és a kulccsal. Hozzon létre egy ServiceClientCredentials objektumot a kulccsal, és használja a végponttal egy QnAMakerClient-objektum létrehozásához.

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

Tudásbázis létrehozása

Egy tudásbázis három forrásból tárolja a CreateKbDTO objektum kérdés- és válaszpárjait:

  • Szerkesztői tartalom esetén használja a QnADTO objektumot.
    • Metaadatok és nyomon követési kérések használatához használja a szerkesztői környezetet, mivel ezek az adatok az egyes QnA-párok szintjén lesznek hozzáadva.
  • Fájlok esetén használja a FileDTO objektumot. A FileDTO tartalmazza a fájlnevet és a nyilvános URL-címet a fájl eléréséhez.
  • URL-címek esetén a sztringek listájával jelölheti a nyilvánosan elérhető URL-címeket.

A létrehozási lépés a tudásbázis tulajdonságait is tartalmazza:

  • defaultAnswerUsedForExtraction - mit ad vissza a rendszer, ha nem talál választ
  • enableHierarchicalExtraction - automatikusan hozzon létre parancssori kapcsolatokat a kinyert QnA-párok között
  • language - egy erőforrás első tudásbázisának létrehozásakor állítsa be a használni kívánt nyelvet az Azure Search-indexben.

Hívja meg a létrehozási metódust a tudásbázis adataival. A tudásbázis információ alapvetően egy JSON-objektum.

Amikor a létrehozási módszer visszatér, adja át a visszaadott műveletazonosítót a wait_for_operation metódusnak az állapot lekérdezéséhez. A wait_for_operation metódus a művelet befejeződésekor ad vissza. resourceLocation A visszaadott művelet fejlécértékének elemzése az új tudásbázis azonosító lekéréséhez.

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

A tudásbázis sikeres létrehozásához mindenképpen adja meg a wait_for_operation fenti kódban hivatkozott függvényt.

Tudásbázis frissítése

A tudásbázis a tudásbázis azonosító és a DTO-objektumok hozzáadását, frissítését és törlését tartalmazó UpdateKbOperationDTO azonosító megadásával frissítheti a frissítési metódust. A DTO-k alapvetően JSON-objektumok is. A wait_for_operation metódus használatával állapítsa meg, hogy a frissítés sikeres volt-e.

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
}

A tudásbázis sikeres frissítéséhez győződjön meg arról, hogy a wait_for_operation fenti kódban hivatkozott függvényt is tartalmazza.

Tudásbázis letöltése

A letöltési módszerrel töltse le az adatbázist a QnADocumentsDTO listájaként. Ez nem egyenértékű a QnA Maker portál Gépház oldalról történő exportálásával, mert ennek a módszernek az eredménye nem TSV-fájl.

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
}

Tudásbázis közzététele

Tegye közzé a tudásbázis a közzétételi módszerrel. Ez az aktuálisan mentett és betanított modellt használja, amelyre az tudásbázis azonosító hivatkozik, és közzéteszi azt egy végponton. Ellenőrizze a HTTP-válaszkódot annak ellenőrzéséhez, hogy a közzététel sikeres volt-e.

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
}

Tudásbázis lekérdezése

Lekérdezés futtatókörnyezeti kulcsának lekérése

Miután közzétett egy tudásbázist, a futtatókörnyezet lekérdezéséhez szüksége lesz a lekérdezési futtatókörnyezet kulcsára. Ez nem ugyanaz a kulcs, amelyet az eredeti ügyfélobjektum létrehozásához használnak.

Az EndpointKeys.getKeys metódus használatával szerezze be az EndpointKeysDTO osztályt.

Használja az objektumban visszaadott kulcstulajdonságok egyikét a tudásbázis lekérdezéséhez.

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
}

A válasz létrehozásához használt futtatókörnyezet hitelesítése

Hozzon létre egy QnAMakerRuntimeClientet a tudásbázis lekérdezéséhez, hogy választ vagy betanítást hozzon létre az aktív tanulásból.

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

A QnAMakerRuntimeClient használatával választ kaphat a tudástól, vagy új javasolt kérdéseket küldhet az tudásbázis az aktív tanuláshoz.

Válasz létrehozása a tudásbázis

Válasz létrehozása közzétett tudásbázis a RuntimeClient.runtime.generateAnswer metódussal. Ez a metódus elfogadja a tudásbázis azonosítót és a QueryDTO-t. Hozzáférhet a QueryDTO további tulajdonságaihoz, például a legfelső és a környezethez, amelyeket a csevegőrobotban használhat.

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

}

Ez egy egyszerű példa a tudásbázis lekérdezésére. A speciális lekérdezési forgatókönyvek megismeréséhez tekintse át a többi lekérdezési példát.

Tudásbázis törlése

Törölje a tudásbázis a törlési módszerrel a tudásbázis azonosító paraméterével.

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
}

Művelet állapotának lekérése

Egyes metódusok, például a létrehozás és a frissítés elegendő időt vehet igénybe, hogy a folyamat befejezésére való várakozás helyett a rendszer egy műveletet ad vissza. Az eredeti metódus állapotának meghatározásához használja a művelet műveletazonosítóját (újrapróbálkozási logikával).

Az újrapróbálkozási logika szimulálására az alábbi kódblokkban található DelayTimer-hívás szolgál. Cserélje le ezt a saját újrapróbálkozással kapcsolatos logikára.

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

Az alkalmazás futtatása

Futtassa az alkalmazást node index.js az alkalmazáskönyvtárból származó paranccsal.

node index.js

A minta forráskódja a GitHubon található.

A Pythonhoz készült QnA Maker ügyfélkódtár használatával:

  • Tudásbázis létrehozása
  • Tudásbázis frissítése
  • Tudásbázis közzététele
  • Előrejelzési futtatókörnyezet végpontkulcsának lekérése
  • Várjon a hosszú ideig futó tevékenységre
  • Tudásbázis letöltése
  • Válasz lekérése egy tudásbázisból
  • Tudásbázis törlése

Referenciadokumentáció Kódtár forráskódcsomagja | (PyPi) | Python-minták |

Feljegyzés

A 2019. július 1. után létrehozott új erőforrások egyéni altartományneveket fognak használni. További információkért és a regionális végpontok teljes listájáért tekintse meg az Azure AI-szolgáltatások egyéni altartományneveit.

Előfeltételek

Feljegyzés

Ez a dokumentáció nem vonatkozik a legújabb kiadásra. A Python API legújabb kiadással való használatáról a Python rövid útmutatójával kapcsolatos kérdésben olvashat.

  • Azure-előfizetés – Ingyenes létrehozás
  • Python 3.x
  • Miután megkapta az Azure-előfizetését, hozzon létre egy QnA Maker-erőforrást az Azure Portalon a szerzői kulcs és a végpont lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
    • Az alkalmazás QnA Maker API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és végpontjára. A rövid útmutató későbbi részében illessze be a kulcsot és a végpontot az alábbi kódba.
    • Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Beállítás

Telepítse az ügyfélkódtárat

A Python telepítése után az ügyfélkódtárat a következővel telepítheti:

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

Új Python-alkalmazás létrehozása

Hozzon létre egy új Python-fájlt, és quickstart-file.py importálja a következő kódtárakat.

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

Hozzon létre változókat az erőforrás Azure-végpontja és -kulcsa számára.

  • Az előfizetési kulcsot és a szerzői kulcsot felcseréljük. A szerkesztési kulcsokkal kapcsolatos további részletekért kövesse a Kulcsok a QnA Makerben című témakört.

  • A QNA_MAKER_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Kulcsok és végpontok lapot az erőforrás-kezelés alatt a Szerzői (előfizetési) kulcs és a QnA Maker-végpont megkereséséhez.

QnA Maker szerzői végpontja

  • A QNA_MAKER_RUNTIME_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.azurewebsites.net. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Sablon exportálása lapot az Automation területen a futtatókörnyezeti végpont megkereséséhez.

QnA Maker futtatókörnyezet végpontja

Fontos

Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információkért tekintse meg az Azure AI-szolgáltatások biztonsági cikkét.

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'

Objektummodellek

A QnA Maker két különböző objektummodellt használ:

  • A QnAMakerClient a tudásbázis létrehozásához, kezeléséhez, közzétételéhez és letöltéséhez szükséges objektum.
  • A QnAMakerRuntime az az objektum, amely lekérdezi a tudásbázis a GenerateAnswer API-val, és új javasolt kérdéseket küldhet a Train API használatával (az aktív tanulás részeként).

Ebben a példában tudásbázis

A tudásbázis ebben a rövid útmutatóban 2 beszélgetési QnA-párral kezdődik, ez a példa egyszerűsítése és a rendkívül kiszámítható azonosítók használata érdekében történik az Update metódusban, és az utánkövetési kérések társítása az új párokra vonatkozó kérdésekkel. Ezt a rövid útmutatóhoz egy meghatározott sorrendben tervezték és implementálták.

Ha a tudásbázis idővel a meglévő QnA-pároktól függő nyomon követési kérésekkel tervezi fejleszteni, a következő lehetőségek közül választhat:

  • Nagyobb tudásbázisok esetén kezelje a tudásbázis egy olyan szövegszerkesztőben vagy TSV-eszközben, amely támogatja az automatizálást, majd cserélje le a tudásbázis egyszerre egy frissítésre.
  • Kisebb tudásbázisok esetén az utánkövetési utasításokat teljes egészében a QnA Maker portálján kezelheti.

Az ebben a rövid útmutatóban használt QnA-párokkal kapcsolatos részletek:

  • A QnA-párok típusai – ebben a tudásbázis két QnA-pártípus található a frissítés után: chitchat és tartományspecifikus információk. Ez általában akkor jellemző, ha a tudásbázis egy beszélgetési alkalmazáshoz, például egy csevegőrobothoz van kötve.
  • Bár a tudásbázis válaszait metaadatok alapján szűrheti, vagy követési utasításokat használhat, ez a rövid útmutató nem jeleníti meg ezt. Keresse meg ezeket a nyelvi-agnosztikus generateAnswer példákat itt.
  • A válaszszöveg markdown, és számos különböző markdownt tartalmazhat, például képeket (nyilvánosan elérhető internetes képeket), hivatkozásokat (nyilvánosan elérhető URL-címekhez) és listajelpontokat. Ez a rövid útmutató nem használja ezt a változatosságot.

QnAMakerClient objektummodell

A tartalomkészítő QnA Maker-ügyfél egy QnAMakerClient objektum, amely a kulcsot tartalmazó Microsoft.Rest.ServiceClientCredentials használatával hitelesíti az Azure-t.

Az ügyfél létrehozása után használja a Tudásbázis tulajdonságot a tudásbázis létrehozásához, kezeléséhez és közzétételéhez.

A tudásbázis egy JSON-objektum elküldésével kezelheti. Azonnali műveletek esetén a metódus általában egy állapotot jelző JSON-objektumot ad vissza. Hosszú ideig futó műveletek esetén a válasz a művelet azonosítója. A kérelem állapotának meghatározásához hívja meg a operations.get_details metódust a műveletazonosítóval.

QnAMakerRuntimeClient objektummodell

Az előrejelzési QnA Maker-ügyfél egy QnAMakerRuntimeClient objektum, amely a Microsoft.Rest.ServiceClientCredentials használatával hitelesíti az Azure-t, amely tartalmazza az előrejelzési futtatókörnyezeti kulcsot, amelyet a szerzői ügyfélhívásból, ügyféltől kapott. EndpointKeysOperations.get_keys a tudásbázis közzététele után.

generate_answer A metódus használatával választ kaphat a lekérdezési futtatókörnyezetből.

Az ügyfél hitelesítése a tudásbázis

Ügyfél példányosítása a végponttal és a kulccsal. Hozzon létre egy CognitiveServicesCredentials objektumot a kulccsal, és használja a végponttal egy QnAMakerClient-objektum létrehozásához.

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

Tudásbázis létrehozása

Az ügyfélobjektum használatával lekérhet egy tudásbázis műveleti objektumot.

Egy tudásbázis három forrásból tárolja a CreateKbDTO objektum kérdés- és válaszpárjait:

  • Szerkesztői tartalom esetén használja a QnADTO objektumot.
    • Metaadatok és nyomon követési kérések használatához használja a szerkesztői környezetet, mivel ezek az adatok az egyes QnA-párok szintjén lesznek hozzáadva.
  • Fájlok esetén használja a FileDTO objektumot. A FileDTO tartalmazza a fájlnevet és a nyilvános URL-címet a fájl eléréséhez.
  • URL-címek esetén a sztringek listájával jelölheti a nyilvánosan elérhető URL-címeket.

Hívja meg a létrehozási metódust, majd adja át a visszaadott műveletazonosítót az Operations.getDetails metódusnak az állapot lekérdezéséhez.

A következő kód utolsó sora a MonitorOperation válaszából származó tudásbázis azonosítót adja vissza.

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

A tudásbázis sikeres létrehozásához győződjön meg arról, hogy a _monitor_operation fenti kódban hivatkozott függvényt is tartalmazza.

Tudásbázis frissítése

A tudásbázis a tudásbázis azonosító és a DTO-objektumok hozzáadását, frissítését és törlését tartalmazó UpdateKbOperationDTO azonosító megadásával frissítheti a frissítési metódust. Az Operation.getDetail metódus használatával állapítsa meg, hogy a frissítés sikeres volt-e.

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

A tudásbázis sikeres frissítéséhez győződjön meg arról, hogy a _monitor_operation fenti kódban hivatkozott függvényt is tartalmazza.

Tudásbázis letöltése

A letöltési módszerrel töltse le az adatbázist a QnADocumentsDTO listájaként. Ez nem egyenértékű a QnA Maker portál Gépház oldalról történő exportálásával, mert ennek a módszernek az eredménye nem TSV-fájl.

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

Tudásbázis közzététele

Tegye közzé a tudásbázis a közzétételi módszerrel. Ez az aktuálisan mentett és betanított modellt használja, amelyre az tudásbázis azonosító hivatkozik, és közzéteszi azt egy végponton.

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

Tudásbázis lekérdezése

Lekérdezés futtatókörnyezeti kulcsának lekérése

Miután közzétett egy tudásbázist, a futtatókörnyezet lekérdezéséhez szüksége lesz a lekérdezési futtatókörnyezet kulcsára. Ez nem ugyanaz a kulcs, amelyet az eredeti ügyfélobjektum létrehozásához használnak.

Az EndpointKeysDTO osztály lekéréséhez használja a EndpointKeysOperations.get_keys metódust.

Használja az objektumban visszaadott kulcstulajdonságok egyikét a tudásbázis lekérdezéséhez.

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

A válasz létrehozásához használt futtatókörnyezet hitelesítése

Hozzon létre egy QnAMakerRuntimeClientet a tudásbázis lekérdezéséhez, hogy választ hozzon létre vagy betaníthasson az aktív tanulásból.

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

A QnAMakerRuntimeClient használatával választ kaphat a tudástól, vagy új javasolt kérdéseket küldhet az tudásbázis az aktív tanuláshoz.

Válasz létrehozása a tudásbázis

Hozzon létre egy választ egy közzétett tudásbázis a QnAMakerRuntimeClient.runtime.generate_answer metódus használatával. Ez a metódus elfogadja a tudásbázis azonosítót és a QueryDTO-t. Hozzáférhet a QueryDTO további tulajdonságaihoz, például a legfelső és a környezethez, amelyeket a csevegőrobotban használhat.

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

Ez egy egyszerű példa a tudásbázis lekérdezésére. A speciális lekérdezési forgatókönyvek megismeréséhez tekintse át a többi lekérdezési példát.

Tudásbázis törlése

Törölje a tudásbázis a törlési módszerrel a tudásbázis azonosító paraméterével.

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

Művelet állapotának lekérése

Egyes metódusok, például a létrehozás és a frissítés elegendő időt vehet igénybe, hogy a folyamat befejezésére való várakozás helyett a rendszer egy műveletet ad vissza. Az eredeti metódus állapotának meghatározásához használja a művelet műveletazonosítóját (újrapróbálkozási logikával).

Az alábbi kódblokkban található setTimeout-hívás az aszinkron kód szimulálására szolgál. Cserélje le ezt újrapróbálkozással kapcsolatos logikára.

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

Az alkalmazás futtatása

Futtassa az alkalmazást a Python-paranccsal a rövid útmutatófájlban.

python quickstart-file.py

A minta forráskódja a GitHubon található.

A QnA Maker Java-ügyfélkódtárával:

  • Tudásbázis létrehozása
  • Tudásbázis frissítése
  • Tudásbázis közzététele
  • Előrejelzési futtatókörnyezet végpontkulcsának lekérése
  • Várjon a hosszú ideig futó tevékenységre
  • Tudásbázis letöltése
  • Válasz lekérése egy tudásbázisból
  • Tudásbázis törlése

Kódtár forráskódcsomag-mintái | |

Feljegyzés

A 2019. július 1. után létrehozott új erőforrások egyéni altartományneveket fognak használni. További információkért és a regionális végpontok teljes listájáért tekintse meg az Azure AI-szolgáltatások egyéni altartományneveit.

Előfeltételek

  • Azure-előfizetés – Ingyenes létrehozás
  • JDK
  • Miután megkapta az Azure-előfizetését, hozzon létre egy QnA Maker-erőforrást az Azure Portalon a szerzői kulcs és a végpont lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
    • Az alkalmazás QnA Maker API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és végpontjára. Illessze be a kulcsot és a végpontot az alábbi kódba a rövid útmutató későbbi részében.
    • Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Beállítás

Az ügyfélkódtárak telepítése

A Java telepítése után telepítheti az ügyfélkódtárakat a Maven használatával az MVN-adattárból.

Új Java-alkalmazás létrehozása

Hozzon létre egy új, elnevezett quickstart.java fájlt, és importálja a következő kódtárakat.

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

Hozzon létre változókat az erőforrás Azure-végpontja és -kulcsa számára.

  • Az előfizetési kulcsot és a szerzői kulcsot felcseréljük. A szerkesztési kulcsokkal kapcsolatos további részletekért kövesse a Kulcsok a QnA Makerben című témakört.

  • A QNA_MAKER_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Kulcsok és végpontok lapot az erőforrás-kezelés alatt a Szerzői (előfizetési) kulcs és a QnA Maker-végpont megkereséséhez.

QnA Maker szerzői végpontja

  • A QNA_MAKER_RUNTIME_ENDPOINT értéke formátuma https://YOUR-RESOURCE-NAME.azurewebsites.net. Nyissa meg az Azure Portalt, és keresse meg az előfeltételekben létrehozott QnA Maker-erőforrást. Válassza a Sablon exportálása lapot az Automation területen a futtatókörnyezeti végpont megkereséséhez.

QnA Maker futtatókörnyezet végpontja

Fontos

Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információkért tekintse meg az Azure AI-szolgáltatások biztonsági cikkét.

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

Objektummodellek

A QnA Maker két különböző objektummodellt használ:

  • A QnAMakerClient a tudásbázis létrehozásához, kezeléséhez, közzétételéhez és letöltéséhez szükséges objektum.
  • A QnAMakerRuntime az az objektum, amely lekérdezi a tudásbázis a GenerateAnswer API-val, és új javasolt kérdéseket küldhet a Train API használatával (az aktív tanulás részeként).

Ebben a példában tudásbázis

A tudásbázis ebben a rövid útmutatóban 2 beszélgetési QnA-párral kezdődik, ez a példa egyszerűsítése és a rendkívül kiszámítható azonosítók használata érdekében történik az Update metódusban, és az utánkövetési kérések társítása az új párokra vonatkozó kérdésekkel. Ezt a rövid útmutatóhoz egy meghatározott sorrendben tervezték és implementálták.

Ha a tudásbázis idővel a meglévő QnA-pároktól függő nyomon követési kérésekkel tervezi fejleszteni, a következő lehetőségek közül választhat:

  • Nagyobb tudásbázisok esetén kezelje a tudásbázis egy olyan szövegszerkesztőben vagy TSV-eszközben, amely támogatja az automatizálást, majd cserélje le a tudásbázis egyszerre egy frissítésre.
  • Kisebb tudásbázisok esetén az utánkövetési utasításokat teljes egészében a QnA Maker portálján kezelheti.

Az ebben a rövid útmutatóban használt QnA-párokkal kapcsolatos részletek:

  • A QnA-párok típusai – ebben a tudásbázis két QnA-pártípus található a frissítés után: chitchat és tartományspecifikus információk. Ez általában akkor jellemző, ha a tudásbázis egy beszélgetési alkalmazáshoz, például egy csevegőrobothoz van kötve.
  • Bár a tudásbázis válaszait metaadatok alapján szűrheti, vagy követési utasításokat használhat, ez a rövid útmutató nem jeleníti meg ezt. Keresse meg ezeket a nyelvi-agnosztikus generateAnswer példákat itt.
  • A válaszszöveg markdown, és számos különböző markdownt tartalmazhat, például képeket (nyilvánosan elérhető internetes képeket), hivatkozásokat (nyilvánosan elérhető URL-címekhez) és listajelpontokat. Ez a rövid útmutató nem használja ezt a változatosságot.

QnAMakerClient objektummodell

A létrehozó QnA Maker-ügyfél egy QnAMakerClient-objektum , amely az MsRest::ServiceClientCredentials használatával hitelesíti az Azure-t, amely tartalmazza a kulcsot.

Az ügyfél létrehozása után használja az ügyfél Knowledgebases tulajdonságának metódusait a tudásbázis létrehozásához, kezeléséhez és közzétételéhez.

Azonnali műveletek esetén egy metódus általában visszaadja az eredményt, ha van ilyen. Hosszú ideig futó műveletek esetén a válasz egy műveleti objektum. Hívja meg a getDetails metódust az értékkel a operation.operationIdkérés állapotának meghatározásához.

QnAMakerRuntimeClient objektummodell

A futtatókörnyezeti QnA Maker-ügyfél egy QnAMakerRuntimeClient objektum.

Miután közzétette a tudásbázis a szerzői ügyféllel, a futtatókörnyezeti ügyfél generateAnswer metódusával választ kaphat a tudásbázis.

Futtatókörnyezeti ügyfelet úgy hozhat létre, hogy meghívja a QnAMakerRuntimeManager.authenticate parancsot , és átad egy futtatókörnyezeti végpontkulcsot. A futtatókörnyezet végpontkulcsának beszerzéséhez használja a szerzői ügyfelet a getKeys meghívásához.

Az ügyfél hitelesítése a tudásbázis

Ügyfél példányosítása a szerzői végponttal és az előfizetési kulccsal.

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

Tudásbázis létrehozása

Egy tudásbázis három forrásból tárolja a CreateKbDTO objektum kérdés- és válaszpárjait:

  • Szerkesztői tartalom esetén használja a QnADTO objektumot.
    • Metaadatok és nyomon követési kérések használatához használja a szerkesztői környezetet, mivel ezek az adatok az egyes QnA-párok szintjén lesznek hozzáadva.
  • Fájlok esetén használja a FileDTO objektumot. A FileDTO tartalmazza a fájlnevet és a nyilvános URL-címet a fájl eléréséhez.
  • URL-címek esetén a sztringek listájával jelölheti a nyilvánosan elérhető URL-címeket.

Hívja meg a létrehozási metódust, majd adja át a operationId visszaadott művelet tulajdonságát a getDetails metódusnak az állapot lekérdezéséhez.

A következő kód utolsó sora a tudásbázis azonosítót adja vissza.

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

Tudásbázis frissítése

A tudásbázis úgy frissítheti, hogy meghívja a frissítést, és átadja a tudásbázis azonosítót és egy UpdateKbOperationDTO objektumot. Ez az objektum a következőket tartalmazhatja:

Adja át a operationId visszaadott művelet tulajdonságát a getDetails metódusnak az állapot lekérdezéséhez.

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

Tudásbázis letöltése

A letöltési módszerrel töltse le az adatbázist a QnADocumentsDTO listájaként. Ez nem egyenértékű a QnA Maker portál Gépház oldalról történő exportálásával, mert ennek a módszernek az eredménye nem TSV-fájl.

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

Tudásbázis közzététele

Tegye közzé a tudásbázis a közzétételi módszerrel. Ez az aktuálisan mentett és betanított modellt használja, amelyre az tudásbázis azonosító hivatkozik, és közzéteszi azt egy végponton.

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

Válasz létrehozása a tudásbázis

Miután közzétett egy tudásbázis, szüksége lesz a futtatókörnyezet végpontkulcsára a tudásbázis lekérdezéséhez. Ez nem ugyanaz, mint a szerzői ügyfél létrehozásához használt előfizetési kulcs.

Az EndpointKeysDTO objektum lekéréséhez használja a getKeys metódust.

Futtatókörnyezeti ügyfél létrehozásához hívja meg a QnAMakerRuntimeManager.authenticate parancsot , és adjon át egy futtatókörnyezeti végpontkulcsot az EndpointKeysDTO objektumból.

Válasz létrehozása közzétett tudásbázis a generateAnswer metódussal. Ez a metódus elfogadja a tudásbázis azonosítót és egy QueryDTO-objektumot.

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

Ez egy egyszerű példa egy tudásbázis lekérdezésére. A speciális lekérdezési forgatókönyvek megismeréséhez tekintse át a többi lekérdezési példát.

Tudásbázis törlése

Törölje a tudásbázis a törlési módszerrel a tudásbázis azonosító paraméterével.

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

Művelet állapotának lekérése

Egyes metódusok, például a létrehozás és a frissítés elegendő időt vehet igénybe, hogy a folyamat befejezésére való várakozás helyett a rendszer egy műveletet ad vissza. Az eredeti metódus állapotának meghatározásához használja a művelet műveletazonosítóját (újrapróbálkozási logikával).

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

Az alkalmazás futtatása

Itt található az alkalmazás fő metódusa.

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

Futtassa az alkalmazást az alábbiak szerint. Ez feltételezi, hogy az osztály neve, Quickstart és a függőségek az aktuális mappa alatt elnevezett lib almappában találhatók.

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

A minta forráskódja a GitHubon található.

Az erőforrások eltávolítása

Ha törölni és eltávolítani szeretne egy Azure AI-szolgáltatási előfizetést, törölheti az erőforrást vagy az erőforráscsoportot. Az erőforráscsoport törlése a hozzá társított egyéb erőforrásokat is törli.

Következő lépések

Oktatóanyag: A tudásbázis tesztelése kötegelt fájllal