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 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 | -h parametr 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 | -h parametr 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 | -h parametr 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 | -h parametr 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 | -h parametr 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 | -h parametr 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 | -h parametr 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 | -h parametr 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
CLI
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.
- 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.
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 tworzenia
- Tworzenie bazy wiedzy
- Aktualizowanie bazy wiedzy
- Pobieranie baza wiedzy
- Publikowanie bazy wiedzy
- Usuwanie baza wiedzy
- Pobieranie klucza środowiska uruchomieniowego zapytania
- Uzyskiwanie stanu operacji
- Uwierzytelnianie klienta środowiska uruchomieniowego zapytań
- Generowanie odpowiedzi na podstawie baza wiedzy
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 odpowiedzienableHierarchicalExtraction
— automatyczne tworzenie relacji monitów między wyodrębnionych par pytań i odpowiedzilanguage
— 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.
- 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.
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 tworzenia
- Tworzenie bazy wiedzy
- Aktualizowanie bazy wiedzy
- Pobieranie baza wiedzy
- Publikowanie bazy wiedzy
- Usuwanie baza wiedzy
- Pobieranie klucza środowiska uruchomieniowego zapytania
- Uzyskiwanie stanu operacji
- Uwierzytelnianie klienta środowiska uruchomieniowego zapytań
- Generowanie odpowiedzi na podstawie baza wiedzy
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 odpowiedzienableHierarchicalExtraction
— automatyczne tworzenie relacji monitów między wyodrębnionych par pytań i odpowiedzilanguage
— 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.
- 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.
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.
- 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.
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.