Ta przeglądarka nie jest już obsługiwana.
Przejdź na przeglądarkę Microsoft Edge, aby korzystać z najnowszych funkcji, aktualizacji zabezpieczeń i pomocy technicznej.
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.
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
Przestroga
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.
Aby utworzyć baza wiedzy przy użyciu interfejsów API REST i biblioteki cURL, musisz mieć następujące informacje:
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Klucz zasobu usługi QnA Maker | -hparametr dla nagłówka Ocp-Apim-Subscription-Key |
Uwierzytelnianie w usłudze QnA Maker |
| Kod JSON opisujący baza wiedzy | -d Param |
Przykłady kodu JSON |
| Rozmiar kodu JSON w bajtach | -hparametr dla nagłówka Content-Size |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i wartości JSON oraz rozmiaru kodu JSON.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'
Odpowiedź cURL z usługi QnA Maker zawiera operationId element , który jest wymagany do uzyskania stanu operacji.
{
"operationState": "NotStarted",
"createdTimestamp": "2020-02-27T04:11:22Z",
"lastActionTimestamp": "2020-02-27T04:11:22Z",
"userId": "9596077b3e0441eb93d5080d6a15c64b",
"operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}
Podczas tworzenia baza wiedzy, ponieważ operacja jest asynchronizuj, odpowiedź zawiera informacje określające stan.
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Identyfikator operacji | Trasa adresu URL | /operations/REPLACE-WITH-YOUR-OPERATION-ID |
| Klucz zasobu usługi QnA Maker | -hparametr dla nagłówka Ocp-Apim-Subscription-Key |
Uwierzytelnianie w usłudze QnA Maker |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora operacji.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
Odpowiedź cURL zawiera stan. Jeśli stan operacji zakończył się pomyślnie, resourceLocation element zawiera identyfikator baza wiedzy.
{
"operationState": "Succeeded",
"createdTimestamp": "2020-02-27T04:54:07Z",
"lastActionTimestamp": "2020-02-27T04:54:19Z",
"resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
"userId": "f596077b3e0441eb93d5080d6a15c64b",
"operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}
Przed wykonaniem zapytania o baza wiedzy należy wykonać następujące kroki:
To zadanie publikuje baza wiedzy. Pobieranie klucza punktu końcowego środowiska uruchomieniowego jest osobnym zadaniem.
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Klucz zasobu usługi QnA Maker | -hparametr dla nagłówka Ocp-Apim-Subscription-Key |
Uwierzytelnianie w usłudze QnA Maker |
| Identyfikator bazy wiedzy | Trasa adresu URL | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''
Stan odpowiedzi to 204 bez wyników. Użyj parametru -v wiersza polecenia, aby wyświetlić pełne dane wyjściowe polecenia cURL. Będzie to obejmować stan HTTP.
Przed wykonaniem zapytania o baza wiedzy należy wykonać następujące kroki:
To zadanie pobiera klucz punktu końcowego środowiska uruchomieniowego. Publikowanie baza wiedzy jest osobnym zadaniem.
Klucz punktu końcowego środowiska uruchomieniowego jest tym samym kluczem dla wszystkich baza wiedzy przy użyciu zasobu usługi QnA Maker.
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Klucz zasobu usługi QnA Maker | -hparametr dla nagłówka Ocp-Apim-Subscription-Key |
Uwierzytelnianie w usłudze QnA Maker |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
Odpowiedź cURL zawiera klucze punktu końcowego środowiska uruchomieniowego. Użyj tylko jednego z kluczy podczas wykonywania zapytań, aby uzyskać odpowiedź z baza wiedzy.
{
"primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
"secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
"installedVersion": "4.0.5",
"lastStableVersion": "4.0.6"
}
Uzyskanie odpowiedzi na podstawie wiedzy odbywa się z oddzielnego środowiska uruchomieniowego niż zarządzanie baza wiedzy. Ponieważ jest to oddzielne środowisko uruchomieniowe, należy uwierzytelnić się przy użyciu klucza środowiska uruchomieniowego.
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Klucz środowiska uruchomieniowego usługi QnA Maker | -hparametr dla nagłówka Authorization |
Klucz jest częścią ciągu zawierającego wyraz Endpointkey . Uwierzytelnianie w usłudze QnA Maker |
| Identyfikator bazy wiedzy | Trasa adresu URL | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
| Kod JSON opisujący zapytanie | -d Param |
Parametry treści żądania i przykłady kodu JSON |
| Rozmiar kodu JSON w bajtach | -hparametr dla nagłówka Content-Size |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true, "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'
Pomyślna odpowiedź zawiera górną odpowiedź wraz z innymi informacjami, które aplikacja kliencka, taka jak czatbot, musi wyświetlić odpowiedź użytkownikowi.
Gdy skończysz z baza wiedzy, usuń go.
| Informacja | Konfiguracja programu cURL | Purpose |
|---|---|---|
| Nazwa zasobu usługi QnA Maker | URL | służy do konstruowania adresu URL |
| Klucz zasobu usługi QnA Maker | -hparametr dla nagłówka Ocp-Apim-Subscription-Key |
Uwierzytelnianie w usłudze QnA Maker |
| Identyfikator bazy wiedzy | Trasa adresu URL | /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID |
Polecenie cURL jest wykonywane z powłoki BASH. Edytuj to polecenie przy użyciu własnej nazwy zasobu, klucza zasobu i identyfikatora baza wiedzy.
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
Stan odpowiedzi to 204 bez wyników. Użyj parametru -v wiersza polecenia, aby wyświetlić pełne dane wyjściowe polecenia cURL. Będzie to obejmować stan HTTP.
Użyj biblioteki klienta usługi QnA Maker dla platformy .NET, aby:
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.
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#.
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.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.
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;
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.
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";
Usługa QnA Maker używa dwóch różnych modeli obiektów:
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:
Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:
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.
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.
Te fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi QnA Maker dla platformy .NET:
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 };
Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:
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.
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.
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
}
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);
}
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.
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:
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ń.
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);
}
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;
}
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:
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.
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.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
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.
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";
Usługa QnA Maker używa dwóch różnych modeli obiektów:
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.
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.
Te fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi QnA Maker dla platformy .NET:
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);
Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:
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.
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.
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
}
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
}
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
}
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.
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ń.
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
}
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);
});
}
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:
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.
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.
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.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
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.
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'
Usługa QnA Maker używa dwóch różnych modeli obiektów:
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:
Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:
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.
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.
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))
Użyj obiektu klienta, aby uzyskać obiekt operacji baza wiedzy.
Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:
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.
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.
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)))
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.")
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
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.
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ń.
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.")
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
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:
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.
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.Po zainstalowaniu języka Java można zainstalować biblioteki klienckie przy użyciu narzędzia Maven z repozytorium MVN.
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.
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";
Usługa QnA Maker używa dwóch różnych modeli obiektów:
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:
Szczegółowe informacje o parach pytań i odpowiedzi używanych w tym przewodniku Szybki start:
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.
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.
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();
Baza wiedzy przechowuje pary pytań i odpowiedzi dla obiektu CreateKbDTO z trzech źródeł:
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;
}
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.");
}
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");
}
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");
}
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ń.
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");
}
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;
}
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.
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.
Szkolenie
Moduł
Tworzenie rozwiązań do odpowiadania na pytania przy użyciu języka sztucznej inteligencji platformy Azure
Certyfikacja
Certyfikat firmy Microsoft: Specjalność dla deweloperów usługi Azure Cosmos DB - Certifications
Pisanie wydajnych zapytań, tworzenie zasad indeksowania, zarządzanie zasobami i aprowizowanie ich w interfejsie API SQL i zestawie SDK za pomocą usługi Microsoft Azure Cosmos DB.