Szybki start: biblioteka klienta usługi QnA Maker

  • Artykuł

Uwaga

Usługa Azure Open AI On Your Data korzysta z dużych modeli językowych (LLMs), aby wygenerować podobne wyniki do usługi QnA Maker. Jeśli chcesz przeprowadzić migrację projektu usługi QnA Maker do usługi Azure Open AI On Your Data, zapoznaj się z naszym przewodnikiem.

Wprowadzenie do biblioteki klienta usługi QnA Maker. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Uwaga

Usługa QnA Maker jest wycofywana 31 marca 2025 r. Nowsza wersja funkcji pytań i odpowiedzi jest teraz dostępna w ramach języka sztucznej inteligencji platformy Azure. Aby uzyskać odpowiedzi na pytania w usłudze językowej, zobacz odpowiadanie na pytania. Od 1 października 2022 r. nie będzie można tworzyć nowych zasobów usługi QnA Maker. Aby uzyskać informacje na temat migrowania istniejących baza wiedzy usługi QnA Maker do odpowiadania na pytania, zapoznaj się z przewodnikiem migracji.

Wymagania wstępne

Uwaga

Ta dokumentacja nie ma zastosowania do najnowszej wersji. Aby dowiedzieć się więcej na temat korzystania z interfejsu API REST z najnowszą wersją, zapoznaj się z przewodnikiem Szybki start dotyczącym odpowiadania na pytania dotyczące interfejsu API REST

  • Bieżąca wersja programu cURL. Kilka przełączników wiersza polecenia jest używanych w przewodnikach Szybki start, które zostały zanotowane w dokumentacji biblioteki cURL.

  • Aby użyć klucza i nazwy zasobu, musisz mieć zasób usługi QnA Maker. Podczas tworzenia zasobu wprowadzono nazwę zasobu, a następnie został utworzony klucz. Nazwa zasobu jest używana jako poddomena punktu końcowego. Aby pobrać klucz i nazwę zasobu, wybierz pozycję Szybki start dla zasobu w witrynie Azure Portal. Nazwa zasobu to pierwsza poddomena adresu URL punktu końcowego:

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

Uwaga

W poniższych przykładach powłoki BASH użyto \ znaku kontynuacji wiersza. Jeśli konsola lub terminal używa innego znaku kontynuacji wiersza, użyj tego znaku.

Tworzenie bazy wiedzy

Aby utworzyć baza wiedzy przy użyciu interfejsów API REST i biblioteki cURL, musisz mieć następujące informacje:

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -hparametr dla nagłówka Ocp-Apim-Subscription-Key Uwierzytelnianie w usłudze QnA Maker
Kod JSON opisujący baza wiedzy -d Param Przykłady kodu JSON
Rozmiar kodu JSON w bajtach -hparametr dla nagłówka Content-Size

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i wartości JSON oraz rozmiaru kodu JSON.

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

Odpowiedź cURL z usługi QnA Maker zawiera operationId element , który jest wymagany do uzyskania stanu operacji.

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

Uzyskiwanie stanu operacji

Podczas tworzenia baza wiedzy, ponieważ operacja jest asynchronizuj, odpowiedź zawiera informacje określające stan.

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Identyfikator operacji Trasa adresu URL /operations/REPLACE-WITH-YOUR-OPERATION-ID
Klucz zasobu usługi QnA Maker -hparametr dla nagłówka Ocp-Apim-Subscription-Key Uwierzytelnianie w usłudze QnA Maker

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora operacji.

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"

Odpowiedź cURL zawiera stan. Jeśli stan operacji zakończył się pomyślnie, resourceLocation element zawiera identyfikator baza wiedzy.

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

Publikowanie bazy wiedzy

Przed wykonaniem zapytania o baza wiedzy należy wykonać następujące kroki:

  • Publikowanie bazy wiedzy
  • Pobieranie klucza punktu końcowego środowiska uruchomieniowego

To zadanie publikuje baza wiedzy. Pobieranie klucza punktu końcowego środowiska uruchomieniowego jest osobnym zadaniem.

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -hparametr dla nagłówka Ocp-Apim-Subscription-Key Uwierzytelnianie w usłudze QnA Maker
Identyfikator bazy wiedzy Trasa adresu URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.

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

Stan odpowiedzi to 204 bez wyników. Użyj parametru -v wiersza polecenia, aby wyświetlić pełne dane wyjściowe polecenia cURL. Będzie to obejmować stan HTTP.

Pobieranie opublikowanego klucza punktu końcowego środowiska uruchomieniowego baza wiedzy

Przed wykonaniem zapytania o baza wiedzy należy wykonać następujące kroki:

  • Publikowanie bazy wiedzy
  • Pobieranie klucza punktu końcowego środowiska uruchomieniowego

To zadanie pobiera klucz punktu końcowego środowiska uruchomieniowego. Publikowanie baza wiedzy jest osobnym zadaniem.

Klucz punktu końcowego środowiska uruchomieniowego jest tym samym kluczem dla wszystkich baza wiedzy przy użyciu zasobu usługi QnA Maker.

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -hparametr dla nagłówka Ocp-Apim-Subscription-Key Uwierzytelnianie w usłudze QnA Maker

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu.

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"

Odpowiedź cURL zawiera klucze punktu końcowego środowiska uruchomieniowego. Użyj tylko jednego z kluczy podczas wykonywania zapytań, aby uzyskać odpowiedź z baza wiedzy.

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

Zapytanie o odpowiedź z opublikowanej baza wiedzy

Uzyskanie odpowiedzi na podstawie wiedzy odbywa się z oddzielnego środowiska uruchomieniowego niż zarządzanie baza wiedzy. Ponieważ jest to oddzielne środowisko uruchomieniowe, należy uwierzytelnić się przy użyciu klucza środowiska uruchomieniowego.

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Klucz środowiska uruchomieniowego usługi QnA Maker -hparametr dla nagłówka Authorization Klucz jest częścią ciągu zawierającego wyraz Endpointkey . Uwierzytelnianie w usłudze QnA Maker
Identyfikator bazy wiedzy Trasa adresu URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
Kod JSON opisujący zapytanie -d Param Parametry treści żądania i przykłady kodu JSON
Rozmiar kodu JSON w bajtach -hparametr dla nagłówka Content-Size

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.

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

Pomyślna odpowiedź zawiera górną odpowiedź wraz z innymi informacjami, które aplikacja kliencka, taka jak czatbot, musi wyświetlić odpowiedź użytkownikowi.

Usuwanie baza wiedzy

Gdy skończysz z baza wiedzy, usuń go.

Informacja Konfiguracja programu cURL Purpose
Nazwa zasobu usługi QnA Maker URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -hparametr dla nagłówka Ocp-Apim-Subscription-Key Uwierzytelnianie w usłudze QnA Maker
Identyfikator bazy wiedzy Trasa adresu URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.

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"

Stan odpowiedzi to 204 bez wyników. Użyj parametru -v wiersza polecenia, aby wyświetlić pełne dane wyjściowe polecenia cURL. Będzie to obejmować stan HTTP.

Dodatkowe zasoby

Użyj biblioteki klienta usługi QnA Maker dla platformy .NET, aby:

  • Tworzenie bazy wiedzy
  • Aktualizowanie bazy wiedzy
  • Publikowanie bazy wiedzy
  • Uzyskiwanie klucza punktu końcowego środowiska uruchomieniowego przewidywania
  • Poczekaj na długotrwałe zadanie
  • Pobieranie bazy wiedzy
  • Uzyskiwanie odpowiedzi z bazy wiedzy
  • Usuwanie bazy wiedzy

Dokumentacja — przykłady | kodu źródłowego biblioteki źródłowej | (NuGet) | C#

Uwaga

Nowe zasoby utworzone po 1 lipca 2019 r. będą używać niestandardowych nazw domen podrzędnych. Aby uzyskać więcej informacji i pełną listę regionalnych punktów końcowych, zobacz Niestandardowe nazwy poddomeny dla usług Azure AI.

Wymagania wstępne

Uwaga

Ta dokumentacja nie ma zastosowania do najnowszej wersji. Aby dowiedzieć się więcej na temat korzystania z interfejsu API języka C# z najnowszą wersją, zapoznaj się z przewodnikiem Szybki start dotyczącym odpowiadania na pytania w języku C#.

  • Subskrypcja platformy Azure — utwórz bezpłatnie
  • Środowisko IDE programu Visual Studio lub bieżąca wersja platformy .NET Core.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w witrynie Azure Portal, aby uzyskać klucz tworzenia i nazwę zasobu. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Aby połączyć aplikację z interfejsem API usługi QnA Maker, potrzebny będzie klucz i nazwa zasobu z utworzonego zasobu. Wklej klucz i nazwę zasobu do poniższego kodu w dalszej części przewodnika Szybki start.
    • Możesz użyć warstwy cenowej bezpłatna (F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

Konfigurowanie

Interfejs wiersza polecenia

W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj dotnet new polecenia , aby utworzyć nową aplikację konsolową o nazwie qna-maker-quickstart. To polecenie tworzy prosty projekt języka C# "Hello World" z jednym plikiem źródłowym: program.cs.

dotnet new console -n qna-maker-quickstart

Zmień katalog na nowo utworzony folder aplikacji. Aplikację można skompilować za pomocą następujących funkcji:

dotnet build

Dane wyjściowe kompilacji nie powinny zawierać żadnych ostrzeżeń ani błędów.

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

W katalogu aplikacji zainstaluj bibliotekę klienta usługi QnA Maker dla platformy .NET za pomocą następującego polecenia:

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

Napiwek

Czy chcesz wyświetlić cały plik z kodem przewodnika Szybki start od razu? Można go znaleźć w witrynie GitHub, która zawiera przykłady kodu z tego przewodnika Szybki start.

Używanie dyrektyw

W katalogu projektu otwórz plik program.cs i dodaj następujące using dyrektywy:

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

Klucz subskrypcji i punkty końcowe zasobów

W metodzie aplikacji Main dodaj zmienne i kod, jak pokazano w poniższej sekcji, aby użyć typowych zadań w tym przewodniku Szybki start.

  • Używamy klucza subskrypcji i klucza tworzenia zamiennie. Aby uzyskać więcej informacji na temat tworzenia klucza, zobacz Klucze w usłudze QnA Maker.

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Klucze i punkt końcowy w obszarze zarządzanie zasobami, aby zlokalizować klucz tworzenia (subskrypcja) i punkt końcowy usługi QnA Maker.

Punkt końcowy tworzenia usługi QnA Maker

  • Wartość QNA_MAKER_RUNTIME_ENDPOINT ma format https://YOUR-RESOURCE-NAME.azurewebsites.net. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Eksportuj szablon w obszarze Automatyzacja , aby zlokalizować punkt końcowy środowiska uruchomieniowego.

Punkt końcowy środowiska uruchomieniowego usługi QnA Maker

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Azure AI.

var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modele obiektów

Usługa QnA Maker używa dwóch różnych modeli obiektów:

  • QnAMakerClient to obiekt do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime to obiekt, który wysyła zapytanie do baza wiedzy przy użyciu interfejsu API GenerateAnswer i wysyła nowe sugerowane pytania przy użyciu interfejsu API trenowania (w ramach aktywnego uczenia).

Przy użyciu tego przykładu baza wiedzy

Baza wiedzy w tym przewodniku Szybki start rozpoczyna się od 2 par pytań i odpowiedzi do konwersacji. W tym celu należy uprościć przykład i mieć wysoce przewidywalne identyfikatory do użycia w metodzie Update, kojarząc monity z monitami z pytaniami do nowych par. Zostało to zaplanowane i zaimplementowane w określonej kolejności dla tego przewodnika Szybki start.

Jeśli planujesz opracować baza wiedzy w miarę upływu czasu z monitami, które są zależne od istniejących par pytań i odpowiedzi, możesz wybrać następujące opcje:

  • W przypadku większych baz wiedzy zarządzaj baza wiedzy w edytorze tekstów lub narzędziem TSV obsługującym automatyzację, a następnie całkowicie zastąp baza wiedzy jednocześnie aktualizacją.
  • W przypadku mniejszych baz wiedzy zarządzaj monitami monitów w całości w portalu usługi QnA Maker.

Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:

  • Typy pary pytań i odpowiedzi — istnieją 2 typy par pytań i odpowiedzi w tym baza wiedzy po aktualizacji: chitchat i informacje specyficzne dla domeny. Jest to typowe, jeśli baza wiedzy jest powiązana z aplikacją konwersacji, taką jak czatbot.
  • Chociaż odpowiedzi bazy wiedzy można filtrować według metadanych lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj tych nieznistych przykładów generateAnswer języka.
  • Tekst odpowiedzi jest markdown i może zawierać szeroką gamę znaczników markdown , takich jak obrazy (publicznie dostępne obrazy internetowe), linki (do publicznie dostępnych adresów URL) i punktory, ten przewodnik Szybki start nie używa tej różnorodności.

Model obiektów QnAMakerClient

Tworzenie klienta usługi QnA Maker jest obiektem QnAMakerClient , który uwierzytelnia się na platformie Azure przy użyciu elementu Microsoft.Rest.ServiceClientCredentials, który zawiera klucz.

Po utworzeniu klienta użyj właściwości Bazy wiedzy, aby utworzyć, zarządzać i publikować baza wiedzy.

Zarządzanie baza wiedzy przez wysłanie obiektu JSON. W przypadku operacji natychmiastowych metoda zwykle zwraca obiekt JSON wskazujący stan. W przypadku długotrwałych operacji odpowiedź to identyfikator operacji. Wywołaj klienta. Operations.GetDetailsAsync , metoda z identyfikatorem operacji w celu określenia stanu żądania.

Model obiektów QnAMakerRuntimeClient

Klient usługi QnA Maker przewidywania jest obiektem QnAMakerRuntimeClient , który uwierzytelnia się na platformie Azure przy użyciu elementu Microsoft.Rest.ServiceClientCredentials, który zawiera klucz środowiska uruchomieniowego przewidywania zwrócony z wywołania klienta tworzenia po client.EndpointKeys.GetKeys opublikowaniu bazy wiedzy.

Użyj metody GenerateAnswer, aby uzyskać odpowiedź ze środowiska uruchomieniowego zapytania.

Przykłady kodu

Te fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi QnA Maker dla platformy .NET:

Uwierzytelnianie klienta na potrzeby tworzenia baza wiedzy

Utwórz wystąpienie obiektu klienta przy użyciu klucza i użyj go z zasobem, aby skonstruować punkt końcowy w celu utworzenia klasy QnAMakerClient z punktem końcowym i kluczem. Utwórz obiekt ServiceClientCredentials .

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

Tworzenie bazy wiedzy

Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:

  • W przypadku zawartości redakcyjnej użyj obiektu QnADTO .
    • Aby użyć metadanych i monitów z monitami, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie poszczególnych par pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . Element FileDTO zawiera nazwę pliku i publiczny adres URL umożliwiający dotarcie do pliku.
  • W przypadku adresów URL użyj listy ciągów do reprezentowania publicznie dostępnych adresów URL.

Krok tworzenia zawiera również właściwości bazy wiedzy:

  • defaultAnswerUsedForExtraction - co jest zwracane, gdy nie znaleziono odpowiedzi
  • enableHierarchicalExtraction — automatyczne tworzenie relacji monitów między wyodrębnionych par pytań i odpowiedzi
  • language — podczas tworzenia pierwszej bazy wiedzy zasobu ustaw język, który ma być używany w indeksie usługi Azure Search.

Wywołaj metodę CreateAsync , a następnie przekaż zwrócony identyfikator operacji do metody MonitorOperation w celu sondowania stanu.

Ostatni wiersz poniższego kodu zwraca identyfikator baza wiedzy z odpowiedzi 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);
}

Pamiętaj, aby uwzględnić MonitorOperation funkcję, do których odwołuje się powyższy kod, aby pomyślnie utworzyć baza wiedzy.

Aktualizowanie bazy wiedzy

Można zaktualizować baza wiedzy, przekazując identyfikator baza wiedzy i updatekbOperationDTO zawierające obiekty dodawania, aktualizowania i usuwania obiektów DTO do metody UpdateAsync. Użyj metody MonitorOperation, aby określić, czy aktualizacja zakończyła się pomyślnie.

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

Pamiętaj, aby uwzględnić MonitorOperation funkcję, do których odwołuje się powyższy kod, aby pomyślnie zaktualizować baza wiedzy.

Pobieranie baza wiedzy

Użyj metody DownloadAsync, aby pobrać bazę danych jako listę QnADocumentsDTO. Nie jest to odpowiednik eksportu portalu usługi QnA Maker ze strony Ustawienia, ponieważ wynik tej metody nie jest plikiem.

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
}

Publikowanie bazy wiedzy

Opublikuj baza wiedzy przy użyciu metody PublishAsync. Spowoduje to przejście do bieżącego zapisanego i wytrenowanego modelu, do którego odwołuje się identyfikator baza wiedzy, i opublikowanie go w punkcie końcowym. Jest to niezbędny krok w celu wykonania zapytania względem bazy wiedzy.

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

Pobieranie klucza środowiska uruchomieniowego zapytania

Po opublikowaniu bazy wiedzy potrzebny jest klucz środowiska uruchomieniowego zapytania, aby wykonać zapytanie względem środowiska uruchomieniowego. Nie jest to ten sam klucz używany do tworzenia oryginalnego obiektu klienta.

Użyj metody EndpointKeys, aby uzyskać klasę EndpointKeysDTO.

Użyj jednej z właściwości klucza zwróconych w obiekcie, aby wysłać zapytanie do bazy wiedzy.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Klucz środowiska uruchomieniowego jest niezbędny do wykonywania zapytań względem bazy wiedzy.

Uwierzytelnianie środowiska uruchomieniowego na potrzeby generowania odpowiedzi

Utwórz obiekt QnAMakerRuntimeClient, aby wysłać zapytanie do baza wiedzy w celu wygenerowania odpowiedzi lub szkolenia na podstawie aktywnej nauki.

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

Użyj klasy QnAMakerRuntimeClient, aby:

  • uzyskiwanie odpowiedzi z bazy wiedzy
  • w celu wysłania nowych sugerowanych pytań do baza wiedzy na potrzeby aktywnego uczenia się.

Generowanie odpowiedzi na podstawie baza wiedzy

Wygeneruj odpowiedź na podstawie opublikowanej bazy wiedzy przy użyciu elementu RuntimeClient.GenerateAnswerAsync , metoda. Ta metoda akceptuje identyfikator baza wiedzy i QueryDTO. Uzyskaj dostęp do dodatkowych właściwości obiektu QueryDTO, takich jak Top i Context do użycia w czatbotze.

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
}

Jest to prosty przykład wykonywania zapytań względem bazy wiedzy. Aby poznać zaawansowane scenariusze wykonywania zapytań, zapoznaj się z innymi przykładami zapytań.

Usuwanie bazy wiedzy

Usuń bazę wiedzy przy użyciu metody DeleteAsync z parametrem identyfikatora baza wiedzy.

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

Uzyskiwanie stanu operacji

Niektóre metody, takie jak tworzenie i aktualizowanie, mogą zająć wystarczająco dużo czasu, aby zamiast czekać na zakończenie procesu, zwracana jest operacja . Użyj identyfikatora operacji z operacji do sondowania (z logiką ponawiania prób), aby określić stan oryginalnej metody.

Pętla i Task.Delay poniższy blok kodu służą do symulowania logiki ponawiania prób. Należy je zastąpić własną logiką ponawiania prób.

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

Uruchamianie aplikacji

Uruchom aplikację za pomocą dotnet run polecenia z katalogu aplikacji.

dotnet run

Kod źródłowy tego przykładu można znaleźć w usłudze GitHub.

Użyj biblioteki klienta usługi QnA Maker, aby Node.js:

  • Tworzenie bazy wiedzy
  • Aktualizowanie bazy wiedzy
  • Publikowanie bazy wiedzy
  • Uzyskiwanie klucza punktu końcowego środowiska uruchomieniowego przewidywania
  • Poczekaj na długotrwałe zadanie
  • Pobieranie bazy wiedzy
  • Uzyskiwanie odpowiedzi z bazy wiedzy
  • Usuwanie baza wiedzy

Dokumentacja referencyjna | — przykłady pakietu (npm)Node.js |

Uwaga

Nowe zasoby utworzone po 1 lipca 2019 r. będą używać niestandardowych nazw domen podrzędnych. Aby uzyskać więcej informacji i pełną listę regionalnych punktów końcowych, zobacz Niestandardowe nazwy poddomeny dla usług Azure AI.

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz bezpłatnie
  • Bieżąca wersja platformy Node.js.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w witrynie Azure Portal, aby uzyskać klucz i zasób tworzenia. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Aby połączyć aplikację z interfejsem API usługi QnA Maker, potrzebny będzie klucz i nazwa zasobu z utworzonego zasobu. Wklej klucz i nazwę zasobu do poniższego kodu w dalszej części przewodnika Szybki start.
    • Możesz użyć warstwy cenowej bezpłatna (F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

Konfigurowanie

Tworzenie nowej aplikacji Node.js

W oknie konsoli (na przykład cmd, PowerShell lub Bash) utwórz nowy katalog dla aplikacji i przejdź do niego.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Uruchom polecenie npm init -y, aby utworzyć aplikację Node przy użyciu pliku package.json.

npm init -y

Instalowanie biblioteki klienta

Zainstaluj następujące pakiety NPM:

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

Plik aplikacji package.json jest aktualizowany przy użyciu zależności.

Utwórz plik o nazwie index.js i zaimportuj następujące biblioteki:

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

Utwórz zmienną dla klucza i nazwy zasobu.

  • Używamy klucza subskrypcji i klucza tworzenia zamiennie. Aby uzyskać więcej informacji na temat tworzenia klucza, zobacz Klucze w usłudze QnA Maker.

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Klucze i punkt końcowy w obszarze zarządzanie zasobami, aby zlokalizować klucz tworzenia (subskrypcja) i punkt końcowy usługi QnA Maker.

Punkt końcowy tworzenia usługi QnA Maker

  • Wartość QNA_MAKER_RUNTIME_ENDPOINT ma format https://YOUR-RESOURCE-NAME.azurewebsites.net. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Eksportuj szablon w obszarze Automatyzacja , aby zlokalizować punkt końcowy środowiska uruchomieniowego.

Punkt końcowy środowiska uruchomieniowego usługi QnA Maker

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Azure AI.

const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modele obiektów

Usługa QnA Maker używa dwóch różnych modeli obiektów:

  • QnAMakerClient to obiekt do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime to obiekt, który wysyła zapytanie do baza wiedzy przy użyciu interfejsu API GenerateAnswer i wysyła nowe sugerowane pytania przy użyciu interfejsu API trenowania (w ramach aktywnego uczenia).

Model obiektów QnAMakerClient

Tworzenie klienta usługi QnA Maker jest obiektem QnAMakerClient , który uwierzytelnia się na platformie Azure przy użyciu poświadczeń, które zawierają klucz.

Po utworzeniu klienta użyj bazy wiedzy, aby utworzyć i opublikować baza wiedzy oraz zarządzać nimi.

Zarządzanie baza wiedzy przez wysłanie obiektu JSON. W przypadku operacji natychmiastowych metoda zwykle zwraca obiekt JSON wskazujący stan. W przypadku długotrwałych operacji odpowiedź to identyfikator operacji. Wywołaj metodę client.operations.getDetails przy użyciu identyfikatora operacji, aby określić stan żądania.

Model obiektów QnAMakerRuntimeClient

Klient usługi QnA Maker przewidywania jest obiektem QnAMakerRuntimeClient, który uwierzytelnia się na platformie Azure przy użyciu elementu Microsoft.Rest.ServiceClientCredentials, który zawiera klucz środowiska uruchomieniowego przewidywania zwrócony z wywołania klienta tworzenia, klienta. EndpointKeys.getKeys po opublikowaniu bazy wiedzy.

Przykłady kodu

Te fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi QnA Maker dla platformy .NET:

Uwierzytelnianie klienta na potrzeby tworzenia baza wiedzy

Utwórz wystąpienie klienta przy użyciu punktu końcowego i klucza. Utwórz obiekt ServiceClientCredentials za pomocą klucza i użyj go z punktem końcowym, aby utworzyć obiekt 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);

Tworzenie bazy wiedzy

Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:

  • W przypadku zawartości redakcyjnej użyj obiektu QnADTO .
    • Aby użyć metadanych i monitów z monitami, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie poszczególnych par pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . Element FileDTO zawiera nazwę pliku i publiczny adres URL umożliwiający dotarcie do pliku.
  • W przypadku adresów URL użyj listy ciągów do reprezentowania publicznie dostępnych adresów URL.

Krok tworzenia zawiera również właściwości bazy wiedzy:

  • defaultAnswerUsedForExtraction - co jest zwracane, gdy nie znaleziono odpowiedzi
  • enableHierarchicalExtraction — automatyczne tworzenie relacji monitów między wyodrębnionych par pytań i odpowiedzi
  • language — podczas tworzenia pierwszej bazy wiedzy zasobu ustaw język, który ma być używany w indeksie usługi Azure Search.

Wywołaj metodę create przy użyciu informacji o baza wiedzy. Informacje o baza wiedzy są zasadniczo obiektem JSON.

Po powrocie metody create przekaż zwrócony identyfikator operacji do metody wait_for_operation , aby sondować stan. Metoda wait_for_operation jest zwracana po zakończeniu operacji. resourceLocation Przeanalizuj wartość nagłówka zwróconej operacji, aby uzyskać nowy identyfikator baza wiedzy.

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

Pamiętaj, aby uwzględnić wait_for_operation funkcję, do których odwołuje się powyższy kod, aby pomyślnie utworzyć baza wiedzy.

Aktualizowanie bazy wiedzy

Można zaktualizować baza wiedzy, przekazując identyfikator baza wiedzy i updateKbOperationDTO zawierające obiekty dodawania, aktualizowania i usuwania obiektów DTO do metody update. Obiekty DTO są również zasadniczo obiektami JSON. Użyj metody wait_for_operation, aby określić, czy aktualizacja zakończyła się pomyślnie.

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
}

Upewnij się, że funkcja includewait_for_operation, do których odwołuje się powyższy kod, w celu pomyślnego zaktualizowania baza wiedzy.

Pobieranie baza wiedzy

Użyj metody pobierania, aby pobrać bazę danych jako listę QnADocumentsDTO. Nie jest to odpowiednik eksportu portalu usługi QnA Maker ze strony Ustawienia, ponieważ wynik tej metody nie jest plikiem 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
}

Publikowanie bazy wiedzy

Opublikuj baza wiedzy przy użyciu metody publish. Spowoduje to utworzenie bieżącego zapisanego i wytrenowanego modelu, do którego odwołuje się identyfikator baza wiedzy, i opublikowanie go w punkcie końcowym. Sprawdź kod odpowiedzi HTTP, aby sprawdzić, czy publikowanie powiodło się.

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
}

Wykonywanie zapytań w bazie wiedzy

Pobieranie klucza środowiska uruchomieniowego zapytania

Po opublikowaniu bazy wiedzy potrzebny jest klucz środowiska uruchomieniowego zapytania, aby wykonać zapytanie względem środowiska uruchomieniowego. Nie jest to ten sam klucz używany do tworzenia oryginalnego obiektu klienta.

Użyj metody EndpointKeys.getKeys, aby uzyskać klasę EndpointKeysDTO.

Użyj jednej z właściwości klucza zwróconych w obiekcie, aby wysłać zapytanie do bazy wiedzy.

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
}

Uwierzytelnianie środowiska uruchomieniowego na potrzeby generowania odpowiedzi

Utwórz obiekt QnAMakerRuntimeClient, aby wysłać zapytanie do baza wiedzy w celu wygenerowania odpowiedzi lub szkolenia na podstawie aktywnej nauki.

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

Użyj klasy QnAMakerRuntimeClient, aby uzyskać odpowiedź z wiedzy lub wysłać nowe sugerowane pytania do baza wiedzy na potrzeby aktywnego uczenia.

Generowanie odpowiedzi na podstawie baza wiedzy

Wygeneruj odpowiedź na podstawie opublikowanej baza wiedzy przy użyciu metody RuntimeClient.runtime.generateAnswer. Ta metoda akceptuje identyfikator baza wiedzy i QueryDTO. Uzyskaj dostęp do dodatkowych właściwości obiektu QueryDTO, takich jak Top i Context do użycia w czatbotze.

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

}

Jest to prosty przykład wykonywania zapytań dotyczących baza wiedzy. Aby poznać zaawansowane scenariusze wykonywania zapytań, zapoznaj się z innymi przykładami zapytań.

Usuwanie bazy wiedzy

Usuń baza wiedzy przy użyciu metody delete z parametrem identyfikatora baza wiedzy.

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
}

Uzyskiwanie stanu operacji

Niektóre metody, takie jak tworzenie i aktualizowanie, mogą zająć wystarczająco dużo czasu, aby zamiast czekać na zakończenie procesu, zwracana jest operacja . Użyj identyfikatora operacji z operacji do sondowania (z logiką ponawiania prób), aby określić stan oryginalnej metody.

Wywołanie delayTimer w poniższym bloku kodu służy do symulowania logiki ponawiania prób. Zastąp to własną logiką ponawiania prób.

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

Uruchamianie aplikacji

Uruchom aplikację za pomocą node index.js polecenia z katalogu aplikacji.

node index.js

Kod źródłowy tego przykładu można znaleźć w usłudze GitHub.

Użyj biblioteki klienta usługi QnA Maker dla języka Python, aby:

  • Tworzenie bazy wiedzy
  • Aktualizowanie bazy wiedzy
  • Publikowanie bazy wiedzy
  • Uzyskiwanie klucza punktu końcowego środowiska uruchomieniowego przewidywania
  • Poczekaj na długotrwałe zadanie
  • Pobieranie bazy wiedzy
  • Uzyskiwanie odpowiedzi z bazy wiedzy
  • Usuwanie baza wiedzy

Dokumentacja — przykłady | kodu źródłowego biblioteki źródłowej | biblioteki (PyPi)Python |

Uwaga

Nowe zasoby utworzone po 1 lipca 2019 r. będą używać niestandardowych nazw domen podrzędnych. Aby uzyskać więcej informacji i pełną listę regionalnych punktów końcowych, zobacz Niestandardowe nazwy poddomeny dla usług Azure AI.

Wymagania wstępne

Uwaga

Ta dokumentacja nie ma zastosowania do najnowszej wersji. Aby dowiedzieć się więcej o korzystaniu z interfejsu API języka Python z najnowszą wersją, zapoznaj się z przewodnikiem Szybki start dotyczącym odpowiadania na pytania w języku Python.

  • Subskrypcja platformy Azure — utwórz bezpłatnie
  • Python 3.x
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy tworzenia. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Klucz i punkt końcowy będą potrzebne z utworzonego zasobu, aby połączyć aplikację z interfejsem API usługi QnA Maker. W dalszej części przewodnika Szybki start wklejesz klucz i punkt końcowy do poniższego kodu.
    • Możesz użyć warstwy cenowej bezpłatna (F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

Konfigurowanie

Instalowanie biblioteki klienta

Po zainstalowaniu środowiska Python możesz zainstalować bibliotekę klienta przy użyciu następującego polecenia:

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

Tworzenie nowej aplikacji w języku Python

Utwórz nowy plik języka Python o nazwie quickstart-file.py i zaimportuj następujące biblioteki.

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

Utwórz zmienne dla klucza i punktu końcowego platformy Azure zasobu.

  • Używamy klucza subskrypcji i klucza tworzenia zamiennie. Aby uzyskać więcej informacji na temat tworzenia klucza, zobacz Klucze w usłudze QnA Maker.

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Klucze i punkt końcowy w obszarze zarządzanie zasobami, aby zlokalizować klucz tworzenia (subskrypcja) i punkt końcowy usługi QnA Maker.

Punkt końcowy tworzenia usługi QnA Maker

  • Wartość QNA_MAKER_RUNTIME_ENDPOINT ma format https://YOUR-RESOURCE-NAME.azurewebsites.net. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Eksportuj szablon w obszarze Automatyzacja , aby zlokalizować punkt końcowy środowiska uruchomieniowego.

Punkt końcowy środowiska uruchomieniowego usługi QnA Maker

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Azure AI.

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'

authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'

runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

Modele obiektów

Usługa QnA Maker używa dwóch różnych modeli obiektów:

  • QnAMakerClient to obiekt do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime to obiekt, który wysyła zapytanie do baza wiedzy przy użyciu interfejsu API GenerateAnswer i wysyła nowe sugerowane pytania przy użyciu interfejsu API trenowania (w ramach aktywnego uczenia).

Przy użyciu tego przykładu baza wiedzy

Baza wiedzy w tym przewodniku Szybki start rozpoczyna się od 2 par pytań i odpowiedzi do konwersacji. W tym celu należy uprościć przykład i mieć wysoce przewidywalne identyfikatory do użycia w metodzie Update, kojarząc monity z monitami z pytaniami do nowych par. Zostało to zaplanowane i zaimplementowane w określonej kolejności dla tego przewodnika Szybki start.

Jeśli planujesz opracować baza wiedzy w miarę upływu czasu z monitami, które są zależne od istniejących par pytań i odpowiedzi, możesz wybrać następujące opcje:

  • W przypadku większych baz wiedzy zarządzaj baza wiedzy w edytorze tekstów lub narzędziem TSV obsługującym automatyzację, a następnie całkowicie zastąp baza wiedzy jednocześnie aktualizacją.
  • W przypadku mniejszych baz wiedzy zarządzaj monitami monitów w całości w portalu usługi QnA Maker.

Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:

  • Typy pary pytań i odpowiedzi — istnieją 2 typy par pytań i odpowiedzi w tym baza wiedzy po aktualizacji: chitchat i informacje specyficzne dla domeny. Jest to typowe, jeśli baza wiedzy jest powiązana z aplikacją konwersacji, taką jak czatbot.
  • Chociaż odpowiedzi bazy wiedzy można filtrować według metadanych lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj tych nieznistych przykładów generateAnswer języka.
  • Tekst odpowiedzi jest markdown i może zawierać szeroką gamę znaczników markdown , takich jak obrazy (publicznie dostępne obrazy internetowe), linki (do publicznie dostępnych adresów URL) i punktory, ten przewodnik Szybki start nie używa tej różnorodności.

Model obiektów QnAMakerClient

Tworzenie klienta usługi QnA Maker jest obiektem QnAMakerClient , który uwierzytelnia się na platformie Azure przy użyciu elementu Microsoft.Rest.ServiceClientCredentials, który zawiera klucz.

Po utworzeniu klienta użyj właściwości Bazy wiedzy, aby utworzyć, zarządzać i publikować baza wiedzy.

Zarządzanie baza wiedzy przez wysłanie obiektu JSON. W przypadku operacji natychmiastowych metoda zwykle zwraca obiekt JSON wskazujący stan. W przypadku długotrwałych operacji odpowiedź to identyfikator operacji. Wywołaj metodę operations.get_details z identyfikatorem operacji, aby określić stan żądania.

Model obiektów QnAMakerRuntimeClient

Klient przewidywania usługi QnA Maker jest obiektem QnAMakerRuntimeClient , który uwierzytelnia się na platformie Azure przy użyciu elementu Microsoft.Rest.ServiceClientCredentials, który zawiera klucz środowiska uruchomieniowego przewidywania zwrócony z wywołania klienta tworzenia, klienta. EndpointKeysOperations.get_keys po opublikowaniu bazy wiedzy.

generate_answer Użyj metody , aby uzyskać odpowiedź ze środowiska uruchomieniowego zapytania.

Uwierzytelnianie klienta na potrzeby tworzenia baza wiedzy

Utwórz wystąpienie klienta przy użyciu punktu końcowego i klucza. Utwórz obiekt CognitiveServicesCredentials za pomocą klucza i użyj go z punktem końcowym, aby utworzyć obiekt QnAMakerClient .

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

Tworzenie bazy wiedzy

Użyj obiektu klienta, aby uzyskać obiekt operacji baza wiedzy.

Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:

  • W przypadku zawartości redakcyjnej użyj obiektu QnADTO .
    • Aby użyć metadanych i monitów z monitami, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie poszczególnych par pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . Element FileDTO zawiera nazwę pliku i publiczny adres URL umożliwiający dotarcie do pliku.
  • W przypadku adresów URL użyj listy ciągów do reprezentowania publicznie dostępnych adresów URL.

Wywołaj metodę create , a następnie przekaż zwrócony identyfikator operacji do metody Operations.getDetails , aby sondować stan.

Ostatni wiersz poniższego kodu zwraca identyfikator baza wiedzy z odpowiedzi 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 pomyślnie utworzyć baza wiedzy, upewnij się, że funkcja uwzględnij _monitor_operation funkcję przywołyną w powyższym kodzie.

Aktualizowanie bazy wiedzy

Można zaktualizować baza wiedzy, przekazując identyfikator baza wiedzy i updateKbOperationDTO zawierające obiekty dodawania, aktualizowania i usuwania obiektów DTO do metody update. Użyj metody Operation.getDetail, aby określić, czy aktualizacja zakończyła się pomyślnie.

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

Upewnij się, że funkcja include_monitor_operation, do których odwołuje się powyższy kod, w celu pomyślnego zaktualizowania baza wiedzy.

Pobieranie baza wiedzy

Użyj metody pobierania, aby pobrać bazę danych jako listę QnADocumentsDTO. Nie jest to odpowiednik eksportu portalu usługi QnA Maker ze strony Ustawienia, ponieważ wynik tej metody nie jest plikiem 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)))

Publikowanie bazy wiedzy

Opublikuj baza wiedzy przy użyciu metody publish. Spowoduje to utworzenie bieżącego zapisanego i wytrenowanego modelu, do którego odwołuje się identyfikator baza wiedzy, i opublikowanie go w punkcie końcowym.

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

Wykonywanie zapytań w bazie wiedzy

Pobieranie klucza środowiska uruchomieniowego zapytania

Po opublikowaniu bazy wiedzy potrzebny jest klucz środowiska uruchomieniowego zapytania, aby wykonać zapytanie względem środowiska uruchomieniowego. Nie jest to ten sam klucz używany do tworzenia oryginalnego obiektu klienta.

Użyj metody EndpointKeysOperations.get_keys, aby uzyskać klasę EndpointKeysDTO.

Użyj jednej z właściwości klucza zwróconych w obiekcie, aby wysłać zapytanie do bazy wiedzy.

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

Uwierzytelnianie środowiska uruchomieniowego na potrzeby generowania odpowiedzi

Utwórz obiekt QnAMakerRuntimeClient, aby wysłać zapytanie do baza wiedzy w celu wygenerowania odpowiedzi lub szkolenia na podstawie aktywnej nauki.

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

Użyj klasy QnAMakerRuntimeClient, aby uzyskać odpowiedź z wiedzy lub wysłać nowe sugerowane pytania do baza wiedzy na potrzeby aktywnego uczenia.

Generowanie odpowiedzi na podstawie baza wiedzy

Wygeneruj odpowiedź na podstawie opublikowanej baza wiedzy przy użyciu metody QnAMakerRuntimeClient.runtime.generate_answer. Ta metoda akceptuje identyfikator baza wiedzy i QueryDTO. Uzyskaj dostęp do dodatkowych właściwości obiektu QueryDTO, takich jak Top i Context do użycia w czatbotze.

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

Jest to prosty przykład wykonywania zapytań dotyczących baza wiedzy. Aby poznać zaawansowane scenariusze wykonywania zapytań, zapoznaj się z innymi przykładami zapytań.

Usuwanie bazy wiedzy

Usuń baza wiedzy przy użyciu metody delete z parametrem identyfikatora baza wiedzy.

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

Uzyskiwanie stanu operacji

Niektóre metody, takie jak tworzenie i aktualizowanie, mogą zająć wystarczająco dużo czasu, aby zamiast czekać na zakończenie procesu, zwracana jest operacja . Użyj identyfikatora operacji z operacji do sondowania (z logiką ponawiania prób), aby określić stan oryginalnej metody.

Wywołanie setTimeout w poniższym bloku kodu służy do symulowania kodu asynchronicznego. Zastąp to logiką ponawiania prób.

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

Uruchamianie aplikacji

Uruchom aplikację za pomocą polecenia języka Python w pliku Szybki start.

python quickstart-file.py

Kod źródłowy tego przykładu można znaleźć w usłudze GitHub.

Użyj biblioteki klienta usługi QnA Maker dla języka Java, aby:

  • Tworzenie bazy wiedzy
  • Aktualizowanie bazy wiedzy
  • Publikowanie bazy wiedzy
  • Uzyskiwanie klucza punktu końcowego środowiska uruchomieniowego przewidywania
  • Poczekaj na długotrwałe zadanie
  • Pobieranie bazy wiedzy
  • Uzyskiwanie odpowiedzi z bazy wiedzy
  • Usuwanie baza wiedzy

Przykłady pakietów | kodu źródłowego | biblioteki

Uwaga

Nowe zasoby utworzone po 1 lipca 2019 r. będą używać niestandardowych nazw domen podrzędnych. Aby uzyskać więcej informacji i pełną listę regionalnych punktów końcowych, zobacz Niestandardowe nazwy poddomeny dla usług Azure AI.

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz bezpłatnie
  • Zestaw JDK.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy tworzenia. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Klucz i punkt końcowy będą potrzebne z utworzonego zasobu, aby połączyć aplikację z interfejsem API usługi QnA Maker. Wklej klucz i punkt końcowy do poniższego kodu w dalszej części przewodnika Szybki start.
    • Możesz użyć warstwy cenowej bezpłatna (F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.

Konfigurowanie

Instalowanie bibliotek klienckich

Po zainstalowaniu języka Java można zainstalować biblioteki klienckie przy użyciu narzędzia Maven z repozytorium MVN.

Tworzenie nowej aplikacji Java

Utwórz nowy plik o nazwie quickstart.java i zaimportuj następujące biblioteki.

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

Utwórz zmienne dla klucza i punktu końcowego platformy Azure zasobu.

  • Używamy klucza subskrypcji i klucza tworzenia zamiennie. Aby uzyskać więcej informacji na temat tworzenia klucza, zobacz Klucze w usłudze QnA Maker.

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Klucze i punkt końcowy w obszarze zarządzanie zasobami, aby zlokalizować klucz tworzenia (subskrypcja) i punkt końcowy usługi QnA Maker.

Punkt końcowy tworzenia usługi QnA Maker

  • Wartość QNA_MAKER_RUNTIME_ENDPOINT ma format https://YOUR-RESOURCE-NAME.azurewebsites.net. Przejdź do witryny Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz stronę Eksportuj szablon w obszarze Automatyzacja , aby zlokalizować punkt końcowy środowiska uruchomieniowego.

Punkt końcowy środowiska uruchomieniowego usługi QnA Maker

Ważne

Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Azure AI.

private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

Modele obiektów

Usługa QnA Maker używa dwóch różnych modeli obiektów:

  • QnAMakerClient to obiekt do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime to obiekt, który wysyła zapytanie do baza wiedzy przy użyciu interfejsu API GenerateAnswer i wysyła nowe sugerowane pytania przy użyciu interfejsu API trenowania (w ramach aktywnego uczenia).

Przy użyciu tego przykładu baza wiedzy

Baza wiedzy w tym przewodniku Szybki start rozpoczyna się od 2 par pytań i odpowiedzi do konwersacji. W tym celu należy uprościć przykład i mieć wysoce przewidywalne identyfikatory do użycia w metodzie Update, kojarząc monity z monitami z pytaniami do nowych par. Zostało to zaplanowane i zaimplementowane w określonej kolejności dla tego przewodnika Szybki start.

Jeśli planujesz opracować baza wiedzy w miarę upływu czasu z monitami, które są zależne od istniejących par pytań i odpowiedzi, możesz wybrać następujące opcje:

  • W przypadku większych baz wiedzy zarządzaj baza wiedzy w edytorze tekstów lub narzędziem TSV obsługującym automatyzację, a następnie całkowicie zastąp baza wiedzy jednocześnie aktualizacją.
  • W przypadku mniejszych baz wiedzy zarządzaj monitami monitów w całości w portalu usługi QnA Maker.

Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:

  • Typy pary pytań i odpowiedzi — istnieją 2 typy par pytań i odpowiedzi w tym baza wiedzy po aktualizacji: chitchat i informacje specyficzne dla domeny. Jest to typowe, jeśli baza wiedzy jest powiązana z aplikacją konwersacji, taką jak czatbot.
  • Chociaż odpowiedzi bazy wiedzy można filtrować według metadanych lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj tych nieznistych przykładów generateAnswer języka.
  • Tekst odpowiedzi jest markdown i może zawierać szeroką gamę znaczników markdown , takich jak obrazy (publicznie dostępne obrazy internetowe), linki (do publicznie dostępnych adresów URL) i punktory, ten przewodnik Szybki start nie używa tej różnorodności.

Model obiektów QnAMakerClient

Tworzenie klienta usługi QnA Maker jest obiektem QnAMakerClient , który uwierzytelnia się na platformie Azure przy użyciu biblioteki MsRest::ServiceClientCredentials, która zawiera klucz.

Po utworzeniu klienta użyj metod właściwości Knowledgebases klienta do tworzenia, zarządzania i publikowania baza wiedzy.

W przypadku operacji natychmiastowych metoda zwykle zwraca wynik, jeśli istnieje. W przypadku długotrwałych operacji odpowiedź jest obiektem Operation . Wywołaj metodę getDetails z wartością operation.operationId , aby określić stan żądania.

Model obiektów QnAMakerRuntimeClient

Klient usługi QnA Maker środowiska uruchomieniowego jest obiektem QnAMakerRuntimeClient .

Po opublikowaniu baza wiedzy przy użyciu klienta tworzenia użyj metody generateAnswer klienta środowiska uruchomieniowego, aby uzyskać odpowiedź z baza wiedzy.

Klient środowiska uruchomieniowego jest tworzony przez wywołanie metody QnAMakerRuntimeManager.authenticate i przekazanie klucza punktu końcowego środowiska uruchomieniowego. Aby uzyskać klucz punktu końcowego środowiska uruchomieniowego, użyj klienta tworzenia, aby wywołać metodę getKeys.

Uwierzytelnianie klienta na potrzeby tworzenia baza wiedzy

Utwórz wystąpienie klienta przy użyciu punktu końcowego tworzenia i klucza subskrypcji.

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

Tworzenie bazy wiedzy

Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:

  • W przypadku zawartości redakcyjnej użyj obiektu QnADTO .
    • Aby użyć metadanych i monitów z monitami, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie poszczególnych par pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . Element FileDTO zawiera nazwę pliku i publiczny adres URL umożliwiający dotarcie do pliku.
  • W przypadku adresów URL użyj listy ciągów do reprezentowania publicznie dostępnych adresów URL.

Wywołaj metodę create , a następnie przekaż operationId właściwość zwróconej operacji do metody getDetails w celu sondowania stanu.

Ostatni wiersz poniższego kodu zwraca identyfikator baza wiedzy.

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

Aktualizowanie bazy wiedzy

Można zaktualizować baza wiedzy, wywołując aktualizację i przekazując identyfikator baza wiedzy oraz obiekt UpdateKbOperationDTO. Ten obiekt może z kolei zawierać następujące elementy:

operationId Przekaż właściwość zwróconej operacji do metody getDetails w celu sondowania stanu.

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

Pobieranie baza wiedzy

Użyj metody pobierania, aby pobrać bazę danych jako listę QnADocumentsDTO. Nie jest to odpowiednik eksportu portalu usługi QnA Maker ze strony Ustawienia, ponieważ wynik tej metody nie jest plikiem 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");
}

Publikowanie bazy wiedzy

Opublikuj baza wiedzy przy użyciu metody publish. Spowoduje to utworzenie bieżącego zapisanego i wytrenowanego modelu, do którego odwołuje się identyfikator baza wiedzy, i opublikowanie go w punkcie końcowym.

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

Generowanie odpowiedzi na podstawie baza wiedzy

Po opublikowaniu baza wiedzy potrzebny jest klucz punktu końcowego środowiska uruchomieniowego, aby wykonać zapytanie dotyczące baza wiedzy. Nie jest to samo, co klucz subskrypcji użyty do utworzenia klienta tworzenia.

Użyj metody getKeys, aby uzyskać obiekt EndpointKeysDTO.

Utwórz klienta środowiska uruchomieniowego, wywołując element QnAMakerRuntimeManager.authenticate i przekazując klucz punktu końcowego środowiska uruchomieniowego z obiektu EndpointKeysDTO.

Wygeneruj odpowiedź na podstawie opublikowanej baza wiedzy przy użyciu metody generateAnswer. Ta metoda akceptuje identyfikator baza wiedzy i obiekt 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();
}

Jest to prosty przykład wykonywania zapytań dotyczących baza wiedzy. Aby poznać zaawansowane scenariusze wykonywania zapytań, zapoznaj się z innymi przykładami zapytań.

Usuwanie bazy wiedzy

Usuń baza wiedzy przy użyciu metody delete z parametrem identyfikatora baza wiedzy.

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

Uzyskiwanie stanu operacji

Niektóre metody, takie jak tworzenie i aktualizowanie, mogą zająć wystarczająco dużo czasu, aby zamiast czekać na zakończenie procesu, zwracana jest operacja . Użyj identyfikatora operacji z operacji do sondowania (z logiką ponawiania prób), aby określić stan oryginalnej 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;
}

Uruchamianie aplikacji

Oto główna metoda aplikacji.

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

Uruchom aplikację w następujący sposób. Zakłada się, że nazwa klasy to Quickstart , a zależności znajdują się w podfolderze o nazwie lib poniżej bieżącego folderu.

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

Kod źródłowy tego przykładu można znaleźć w usłudze GitHub.

Czyszczenie zasobów

Jeśli chcesz wyczyścić i usunąć subskrypcję usług Azure AI, możesz usunąć zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów.

Następne kroki

Samouczek: testowanie baza wiedzy przy użyciu pliku wsadowego