Szybki start: biblioteka klienta usługi QnA Maker

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 wycofana 31 marca 2025 r. Nowsza wersja możliwości pytań i odpowiedzi jest teraz dostępna w ramach usługi Azure Cognitive Service for Language. Aby uzyskać możliwości 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 baz 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 w najnowszej wersji, zapoznaj się z przewodnikiem Szybki start dotyczącym odpowiedzi na pytania dotyczące interfejsu API REST

  • Bieżąca wersja biblioteki 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 utworzono klucz. Nazwa zasobu jest używana jako poddomena punktu końcowego. Aby pobrać klucz i nazwę zasobu, wybierz pozycję Szybki start dla zasobu w Azure Portal. Nazwa zasobu to pierwsza poddomena adresu URL punktu końcowego:

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

Przestroga

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

Tworzenie bazy wiedzy

Aby utworzyć baza wiedzy za pomocą interfejsów API REST i biblioteki cURL, musisz mieć następujące informacje:

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

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/cognitive-services/qnamaker/faqs"]}'

Odpowiedź cURL z usługi QnA Maker zawiera element operationId , 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 asynchroniona, odpowiedź zawiera informacje określające stan.

Informacje Konfiguracja biblioteki cURL Przeznaczenie
Nazwa zasobu usługi QnA Maker Adres 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 -h param dla Ocp-Apim-Subscription-Key nagłówka 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.

Informacje Konfiguracja biblioteki cURL Przeznaczenie
Nazwa zasobu usługi QnA Maker Adres URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -h param dla Ocp-Apim-Subscription-Key nagłówka 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 wiersza polecenia, -v 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 baz wiedzy korzystających z zasobu usługi QnA Maker.

Informacje Konfiguracja biblioteki cURL Przeznaczenie
Nazwa zasobu usługi QnA Maker Adres URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -h param dla Ocp-Apim-Subscription-Key nagłówka 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 opublikowanego 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.

Informacje Konfiguracja biblioteki cURL Przeznaczenie
Nazwa zasobu usługi QnA Maker Adres URL służy do konstruowania adresu URL
Klucz środowiska uruchomieniowego usługi QnA Maker -h param dla Authorization nagłówka Klucz jest częścią ciągu, który zawiera 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 -h param dla Content-Size nagłówka

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 odpowiedź u góry wraz z innymi informacjami, które aplikacja kliencka, taka jak czatbot, musi wyświetlić odpowiedź użytkownikowi.

Usuwanie baza wiedzy

Po zakończeniu pracy z baza wiedzy usuń go.

Informacje Konfiguracja biblioteki cURL Przeznaczenie
Nazwa zasobu usługi QnA Maker Adres URL służy do konstruowania adresu URL
Klucz zasobu usługi QnA Maker -h param dla Ocp-Apim-Subscription-Key nagłówka 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 wiersza polecenia, -v 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 referencyjna | Kod | źródłowy bibliotekiPakiet (NuGet) | Przykłady w języku C#

Uwaga

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

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 odpowiedzi na pytania w języku C#.

  • Subskrypcja platformy Azure — utwórz jedną 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 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, potrzebna będzie nazwa klucza i 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

Porada

Chcesz wyświetlić cały plik kodu Szybkiego startu jednocześnie? Możesz go znaleźć w witrynie GitHub, która zawiera przykłady kodu w tym przewodniku 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 klucza tworzenia, zobacz Klucze w usłudze QnA Maker.

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do 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 Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz pozycję Eksportuj szablon strony 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 Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Cognitive Services.

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 jest obiektem do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime jest obiektem do wykonywania zapytań dotyczących baza wiedzy za pomocą interfejsu API GenerateAnswer i wysyłania nowych sugerowanych pytań 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 QnA konwersacji. Jest to wykonywane specjalnie, aby 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 czasie z monitami, które są zależne od istniejących par QnA, możesz wybrać:

  • 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 dotyczącymi kontynuacji 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 QnA — istnieją 2 typy par QnA w tej 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 mogą być filtrowane przez metadane lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj przykładów generacyjnych generowania elementów generacyjnych w języku.
  • 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 punkty punktacji, ten przewodnik Szybki start nie używa tej odmiany.

Model obiektu QnAMakerClient

Klient usługi QnA Maker tworzenia to obiekt QnAMakerClient, który uwierzytelnia się na platformie Azure przy użyciu Microsoft. Rest.ServiceClientCredentials, który zawiera klucz.

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

Zarządzaj baza wiedzy, wysyłając obiekt 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.

QnAMakerRuntimeClient, model obiektu

Klient usługi QnA Maker przewidywania to obiekt QnAMakerRuntimeClient, który uwierzytelnia się na platformie Azure przy użyciu 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 obiektu 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 dotyczących kolejnych kroków, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie indywidualnej pary pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . PlikDTO 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 QnA
  • language — podczas tworzenia pierwszej bazy wiedzy zasobu ustaw język do użycia 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.

Końcowy 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ę, przywołyną w powyższym kodzie, 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ę, przywołyną w powyższym kodzie, 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. Pobiera bieżący zapisany i wytrenowany model, do którego odwołuje się identyfikator baza wiedzy, i publikuje go w punkcie końcowym. Jest to niezbędny krok w celu wykonywania zapytań względem bazy wiedzy.

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

Uzyskiwanie klucza środowiska uruchomieniowego zapytań

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
  • aby wysłać nowe sugerowane pytania 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, na przykład 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 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, aby sondować (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. Powinny one zostać zastąpione 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 | Kod | źródłowy bibliotekiPakiet (npm) | przykładyNode.js

Uwaga

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

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz bezpłatnie
  • Bieżąca wersja Node.js.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w 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ć bezpłatnej warstwy cenowej (F0), aby wypróbować usługę, a następnie uaktualnić usługę do warstwy płatnej dla środowiska produkcyjnego.

Konfigurowanie

Tworzenie nowej aplikacji Node.js

W oknie konsoli (takim jak 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ę węzła z plikiem 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 zostanie zaktualizowany package.json o 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 platformy Azure i nazwy zasobu zasobu.

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

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do 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 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 azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Cognitive Services.

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 za pomocą interfejsu API GenerateAnswer i wysyła nowe sugerowane pytania przy użyciu interfejsu API trenowania (w ramach aktywnej nauki).

Model obiektów QnAMakerClient

Klient usługi QnA Maker do tworzenia 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 z identyfikatorem operacji, aby określić stan żądania.

Model obiektu QnAMakerRuntimeClient

Klient przewidywania usługi QnA Maker jest obiektem QnAMakerRuntimeClient, który uwierzytelnia się na platformie Azure przy użyciu 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 monitów, 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 obejmuje również właściwości bazy wiedzy:

  • defaultAnswerUsedForExtraction - co jest zwracane, gdy nie znaleziono odpowiedzi
  • enableHierarchicalExtraction - automatycznie twórz relacje monitów między wyodrębnionych par pytań i odpowiedzi
  • language — podczas tworzenia pierwszej bazy wiedzy zasobu ustaw język do użycia w indeksie usługi Azure Search.

Wywołaj metodę create przy użyciu informacji o baza wiedzy. Informacje 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 o dołączeniu wait_for_operation funkcji, 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 oraz obiekt UpdateKbOperationDTO zawierający 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, przywoływająca w powyższym kodzie, aby pomyślnie zaktualizować 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 zakończyło się pomyślnie.

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 aktywnej nauki.

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, na przykład 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 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, aby sondować (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 referencyjna | Kod | źródłowy bibliotekiPakiet (PyPi) | Przykłady języka Python

Uwaga

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

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 Python z najnowszą wersją, zapoznaj się z przewodnikiem Szybki start dotyczącym odpowiadania na pytania w języku Python.

  • Subskrypcja platformy Azure — utwórz jedną bezpłatnie
  • Python 3.x
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w Azure Portal, aby uzyskać klucz tworzenia i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Będziesz potrzebować klucza i punktu końcowego 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 języka Python możesz zainstalować bibliotekę klienta przy użyciu następujących elementów:

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 punktu końcowego i klucza platformy Azure zasobu.

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

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do 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 Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz pozycję Eksportuj szablon strony 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 Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Cognitive Services.

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 jest obiektem do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime jest obiektem do wykonywania zapytań dotyczących baza wiedzy za pomocą interfejsu API GenerateAnswer i wysyłania nowych sugerowanych pytań 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 QnA konwersacji. Jest to wykonywane specjalnie, aby 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 czasie z monitami, które są zależne od istniejących par QnA, możesz wybrać:

  • 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 dotyczącymi kontynuacji 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 QnA — istnieją 2 typy par QnA w tej 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 mogą być filtrowane przez metadane lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj przykładów generacyjnych generowania elementów generacyjnych w języku.
  • 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 punkty punktacji, ten przewodnik Szybki start nie używa tej odmiany.

Model obiektu QnAMakerClient

Klient usługi QnA Maker tworzenia to obiekt QnAMakerClient, który uwierzytelnia się na platformie Azure przy użyciu Microsoft. Rest.ServiceClientCredentials, który zawiera klucz.

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

Zarządzaj baza wiedzy, wysyłając obiekt 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.

QnAMakerRuntimeClient, model obiektu

Klient usługi QnA Maker przewidywania jest obiektem uwierzytelnianym QnAMakerRuntimeClient na platformie Azure przy użyciu 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 za pomocą punktu końcowego i klucza. Utwórz obiekt CognitiveServicesCredentials przy użyciu 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 dotyczących kolejnych kroków, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie indywidualnej pary pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . PlikDTO 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 w celu sondowania stanu.

Końcowy 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

Upewnij się, że funkcja uwzględnij_monitor_operation, przywołyną w powyższym kodzie, 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 aktualizacji. 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 uwzględnij_monitor_operation, przywołyną w powyższym kodzie, aby pomyślnie zaktualizować 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. Pobiera bieżący zapisany i wytrenowany model, do którego odwołuje się identyfikator baza wiedzy, i publikuje 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

Uzyskiwanie klucza środowiska uruchomieniowego zapytań

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 aktywnej nauki.

Generowanie odpowiedzi na podstawie baza wiedzy

Wygeneruj odpowiedź na podstawie opublikowanego 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, na przykład 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 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, aby sondować (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

Kod | źródłowy bibliotekiPakiet | Próbki

Uwaga

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

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz jedną bezpłatnie
  • Zestaw JDK.
  • Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi QnA Maker w Azure Portal, aby uzyskać klucz tworzenia i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
    • Będziesz potrzebować klucza i punktu końcowego 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 punktu końcowego i klucza platformy Azure zasobu.

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

  • Wartość QNA_MAKER_ENDPOINT ma format https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Przejdź do 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 Azure Portal i znajdź zasób usługi QnA Maker utworzony w wymaganiach wstępnych. Wybierz pozycję Eksportuj szablon strony 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 Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Cognitive Services.

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 jest obiektem do tworzenia, zarządzania, publikowania i pobierania bazy wiedzy.
  • QnAMakerRuntime jest obiektem do wykonywania zapytań dotyczących baza wiedzy za pomocą interfejsu API GenerateAnswer i wysyłania nowych sugerowanych pytań 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 QnA konwersacji. Jest to wykonywane specjalnie, aby 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 czasie z monitami, które są zależne od istniejących par QnA, możesz wybrać:

  • 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 dotyczącymi kontynuacji 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 QnA — istnieją 2 typy par QnA w tej 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 mogą być filtrowane przez metadane lub używać monitów z monitami, ten przewodnik Szybki start nie pokazuje tego. Poszukaj tutaj przykładów generacyjnych generowania elementów generacyjnych w języku.
  • 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 punkty punktacji, ten przewodnik Szybki start nie używa tej odmiany.

Model obiektu QnAMakerClient

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

Po utworzeniu klienta użyj metod właściwości Knowledgebases klienta, aby utworzyć, zarządzać i publikować 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.

QnAMakerRuntimeClient, model obiektu

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 funkcji QnAMakerRuntimeManager.authenticate i przekazanie klucza punktu końcowego środowiska uruchomieniowego. Aby uzyskać klucz punktu końcowego środowiska uruchomieniowego, użyj klienta tworzenia w celu wywołania klawiszy 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 dotyczących kolejnych kroków, użyj kontekstu redakcyjnego, ponieważ te dane są dodawane na poziomie indywidualnej pary pytań i odpowiedzi.
  • W przypadku plików użyj obiektu FileDTO . PlikDTO 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.

Końcowy 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 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. Pobiera bieżący zapisany i wytrenowany model, do którego odwołuje się identyfikator baza wiedzy, i publikuje 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 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, aby sondować (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 i 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 Cognitive Services, 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