Краткое руководство. Клиентская библиотека QnA Maker

Предварительные требования

• Текущая версия cURL. В этом кратком руководстве используются несколько параметров командной строки, которые указаны в документации cURL.

• Для использования ключа и имени ресурса необходимо иметь QnA Maker ресурса. Вы указали имя ресурса во время его создания, после чего был создан ключ. Имя ресурса используется в качестве поддомена для конечной точки. Чтобы получить ключ и имя ресурса, на портале Azure для своего ресурса выберите Быстрое начало. Имя ресурса является первым поддоменом в URL-адресе конечной точки:

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

Создание базы знаний

Чтобы создать базу знаний с помощью REST API и cURL, необходимо иметь следующие сведения:

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав собственные имя ресурса, ключ ресурса, значения и размер 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://video2.skills-academy.com/azure/ai-services/qnamaker/faqs"]}'

Ответ cURL от QnA Maker содержит operationId, необходимый для получения состояния операции.

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

Получение состояния операции

При создании базы знаний, так как операция является асинхронной, ответ содержит сведения для определения состояния.

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав имя ресурса, ключ ресурса и идентификатор операции.

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"

Ответ cURL содержит состояние. Если состояние операции — "выполнено успешно", resourceLocation содержит идентификатор базы знаний.

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

Публикация базы знаний

Перед отправкиой запроса в базу знаний необходимо выполнить следующие действия:

• Публикация базы знаний
• Получение ключа конечной точки среды выполнения

Эта задача публикует базу знаний. Получение ключа конечной точки среды выполнения — это отдельная задача.

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав имя ресурса, ключ ресурса и идентификатор базы знаний.

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

Состояние ответа имеет значение 204 (без результатов). Используйте параметр командной строки -v, чтобы просмотреть подробные выходные данные для команды cURL. Они включают в себя состояние HTTP.

Получение ключа конечной точки среды выполнения для опубликованной базы знаний

Перед отправкиой запроса в базу знаний необходимо выполнить следующие действия:

• Публикация базы знаний
• Получение ключа конечной точки среды выполнения

Эта задача получает ключ конечной точки среды выполнения. Публикация базы знаний — это отдельная задача.

Ключ конечной точки среды выполнения — это один и тот же ключ для всех баз знаний, использующих ресурс QnA Maker.

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав собственное имя ресурса и ключ ресурса.

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"

В ответе cURL содержатся ключи конечной точки среды выполнения. Используйте только один из ключей при отправке запроса, чтобы получить ответ от базы знаний.

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

Запрос ответа из опубликованной базы знаний

Получение ответа из базы знаний выполняется из отдельной среды выполнения, которая не управляет базой знаний. Так как это отдельная среда выполнения, необходимо пройти проверку подлинности с помощью ключа среды выполнения.

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав имя ресурса, ключ ресурса и идентификатор базы знаний.

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

Успешный ответ включает в себя наиболее подходящий ответ, а также другие сведения, которые клиентское приложение (например, чат-бот) должно отображать в качестве ответа пользователю.

Удаление базы знаний

После завершения использования базы знаний удалите ее.

Команда cURL выполняется из оболочки BASH. Измените эту команду, указав имя ресурса, ключ ресурса и идентификатор базы знаний.

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"

Состояние ответа имеет значение 204 (без результатов). Используйте параметр командной строки -v, чтобы просмотреть подробные выходные данные для команды cURL. Они включают в себя состояние HTTP.

Дополнительные ресурсы

• Справочная документация по разработке.
• Справочная документация по среде выполнения.
• Примеры скриптов BASH с использованием cURL.

Клиентская библиотека QnA Maker для .NET:

• Создание базы знаний
• Обновление базы знаний
• Публикация базы знаний
• Получение ключа конечной точки среды выполнения прогнозирования
• Ожидание долго выполняющейся задачи
• Скачивание базы знаний
• Получение ответа из базы знаний
• Удаление базы знаний

Справочная документация | Исходный код библиотеки | Пакет (NuGet) | Образцы кода (C#)

Предварительные требования

• Подписка Azure — создайте бесплатную учетную запись.
• IDE Visual Studio или текущая версия .NET Core.
• Получив подписку Azure, создайте ресурс QnA Maker на портале Azure, чтобы получить ключ разработки и имя ресурса. После развертывания ресурса выберите элемент Перейти к ресурсу.
  • Для подключения приложения к API QnA Maker потребуется ключ и имя созданного ресурса. Ключ и имя ресурса вы вставите в приведенный ниже код на следующих шагах в рамках этого краткого руководства.
  • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Установка

CLI

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем qna-maker-quickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода: program.cs.

dotnet new console -n qna-maker-quickstart

Измените каталог на созданную папку приложения. Чтобы создать приложение, выполните следующую команду:

dotnet build

Выходные данные сборки не должны содержать предупреждений или ошибок.

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

В каталоге приложения установите клиентскую библиотеку QnA Maker для .NET с помощью следующей команды:

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

Директивы using

В каталоге проекта откройте файл program.cs и с помощью using добавьте следующие директивы:

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

Ключ подписки и конечные точки ресурсов

Чтобы использовать общие задачи из этого краткого руководства, в методе Main приложения добавьте переменные и код из приведенного ниже раздела.

• Ключ подписки и ключ разработки являются взаимозаменяемыми. Дополнительные сведения о ключе разработки см. в разделе Ключи в QnA Maker.

• Формат значения QNA_MAKER_ENDPOINT: https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Ключи и конечная точка в разделе Управление ресурсами, чтобы найти ключ разработки (подписка) и конечную точку QnA Maker.

• Формат значения QNA_MAKER_RUNTIME_ENDPOINT: https://YOUR-RESOURCE-NAME.azurewebsites.net. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Экспорт шаблона в разделе Автоматизация, чтобы найти конечную точку среды выполнения.

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

Объектные модели

В QnA Maker используются две разные объектные модели:

• QnAMakerClient — это объект для создания, публикации и скачивания базы знаний, а также управления ею.
• QnAMakerRuntime — это объект для отправки запроса в базу знаний с помощью API GenerateAnswer и новых предложенных вопросов с помощью API обучения (в рамках активного обучения).

Использование этого примера базы знаний

База знаний, используемая в этом кратком руководстве, начинается с двух пар разговорных вопросов и ответов. Это сделано, чтобы упростить пример и обеспечить строго предсказуемые идентификаторы, используемые в методе Update, который сопоставляет дальнейшие запросы, содержащие вопросы, с новыми парами. Такой подход был запланирован и реализован в определенном порядке для целей данного краткого руководства.

Если вы планируете со временем разработать базу знаний с дальнейшими запросами, которые зависят от имеющихся пар вопросов и ответов, вы можете воспользоваться одним из следующих вариантов.

• Для управления более крупными базами знаний следует воспользоваться текстовым редактором или поддерживающим автоматизацию средством TSV, а затем полностью заменить всю базу знаний обновленной версией.
• Для небольших баз знаний дальнейшими запросами можно полностью управлять на портале QnA Maker.

Ниже приведены сведения о парах вопросов и ответов, используемых в этом кратком руководстве.

• Типы пар вопросов и ответов. После обновления в этой базе знаний содержатся пары вопросов и ответов двух типов: для беседы и по предметной области. Это типичное содержание для баз знаний, привязанных к приложению для общения, например чат-боту.
• Хотя можно фильтровать ответы из базы знаний по метаданным или использовать дальнейшие запросы, в этом кратком руководстве эти возможности не рассматриваются. Такие независящие от языка примеры generateAnswer можно найти здесь.
• Текст ответа — это данные на языке Markdown, которые могут содержать широкий спектр элементов Markdown, например изображения (общедоступные изображения из Интернета), ссылки (на общедоступные URL-адреса) и пункты маркированного списка. Все это многообразие в данном кратком руководстве не используется.

Объектная модель QnAMakerClient

Клиент разработки QnA Maker — это объект QnAMakerClient, который проходит проверку подлинности в Azure с помощью объекта Microsoft.Rest.ServiceClientCredentials, содержащего ваш ключ.

После создания клиента используйте свойство QnAMakerClient.Knowledgebase для создания и публикации своей базы знаний, а также управления ею.

Управляйте своей базой знаний, отправляя объект JSON. Для немедленных операций метод обычно возвращает объект JSON, указав статус. Ответ для длительных операций — ИД операции. Вызовите метод OperationsExtensions.GetDetailsAsync(IOperations, String, CancellationToken) с ИД операции, чтобы определить класс OperationStateType.

Объектная модель QnAMakerRuntimeClient

Клиент прогнозирования QnA Maker — это объект QnAMakerRuntimeClient, который проходит проверку подлинности в Azure с помощью объекта Microsoft.Rest.ServiceClientCredentials, содержащего ключ среды выполнения прогнозирования, возвращенный из вызова клиента разработки client.EndpointKeys.GetKeys после публикации базы знаний.

Метод GenerateAnswer используется для получения ответа от среды выполнения запроса.

Примеры кода

Эти фрагменты кода показывают, как выполнить следующие действия с помощью клиентской библиотеки QnA Maker для .NET:

• Проверка подлинности клиента разработки
• Создание базы знаний
• Обновление базы знаний
• Скачивание базы знаний
• Публикация базы знаний
• Удаление базы знаний
• Получение ключа среды выполнения запроса
• Получение состояния операции
• Проверка подлинности клиента среды выполнения запросов
• Создание ответа из базы знаний

Проверка подлинности клиента для создания базы знаний

Создайте экземпляр клиентского объекта с использованием ключа. С помощью этого экземпляра и ресурса сформируйте конечную точку. Применяя эту конечную точку и ключ, создайте QnAMakerClient. Создайте объект ServiceClientCredentials.

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

Создание базы знаний

База знаний хранит пары вопросов и ответов для объекта Класс CreateKbDTO из трех источников:

• Для редакционного содержимого используйте объект Класс QnADTO.
  • Чтобы использовать метаданные и запросы дальнейших действий, используйте редакционный контекст, так как эти данные добавляются на уровне отдельных пар вопросов и ответов.
• Для файлов используйте объект Класс FileDTO. Он включает в себя имя и общедоступный URL-адрес, указывающие на файл.
• В качестве значения для параметра URL-адреса используйте список строк, представляющих общедоступные URL-адреса.

На этапе создания также задаются свойства базы знаний:

• defaultAnswerUsedForExtraction — то, что возвращается, если ответ не найден;
• enableHierarchicalExtraction — автоматическое создание связей запросов между извлеченными парами вопросов и ответов;
• language — при создании первой базы данных ресурса задайте язык для использования в индексе Поиска Azure.

Вызовите методKnowledgebaseExtensions.CreateAsync(IKnowledgebase, CreateKbDTO, CancellationToken), а затем передайте возвращенный ИД операции методу Get status of an operation (Получение статуса операции) для опроса состояния.

Последняя строка следующего кода возвращает ИД базы знаний из ответа от MonitorOoperation.

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

Чтобы создать базу знаний, добавьте функцию MonitorOperation из предыдущего примера кода.

Обновление базы знаний

Базу знаний можно обновить, передав ИД базы знаний и объекты DTO Класс UpdateKbOperationDTO, содержащий класс UpdateKbOperationDTOAdd, класс UpdateKbOperationDTOUpdate и класс UpdateKbOperationDTODelete в метод KnowledgebaseExtensions.UpdateAsync(IKnowledgebase, String, UpdateKbOperationDTO, CancellationToken). Используйте метод Get status of an operation (Получение состояния операции), чтобы определить, успешно ли выполнено обновление.

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

Чтобы обновить базу знаний, добавьте функцию MonitorOperation из предыдущего примера кода.

Скачивание базы знаний

Используйте метод KnowledgebaseExtensions.DownloadAsync(IKnowledgebase, String, String, CancellationToken), чтобы загрузить базу данных в виде списка Класс QnADocumentsDTO. Это не эквивалентно экспорту портала QnA Maker со страницы настроек, так как результатом этого метода не является файл.

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
}

Публикация базы знаний

Опубликуйте базу знаний, используя метод KnowledgebaseExtensions.PublishAsync(IKnowledgebase, String, CancellationToken). При этом берется текущая сохраненная и обученная модель, на которую ссылается ИД базы знаний, и публикуется в конечной точке. Это необходимо для подачи запросов к базе знаний.

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

Получение ключа среды выполнения запроса

После публикации базы знаний необходимо получить ключ среды выполнения запроса, чтобы отправить в нее запрос. Этот ключ отличается о того, который использовался для создания исходного объекта клиента.

Используйте метод EndpointKeys, чтобы получить класс EndpointKeysDTO.

Для запроса к базе знаний используйте любое свойство ключа, возвращаемое в объекте.

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

    return endpointKeysObject.PrimaryEndpointKey;
}

Ключ среды выполнения требуется для отправки запросов к базе знаний.

Проверка подлинности среды выполнения для создания ответа

Создайте QnAMakerRuntimeClient, чтобы отправить в базу знаний запрос для создания ответа или выполнять обучение по методу активного обучения.

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

QnAMakerRuntimeClient позволяет:

• получать ответы из базы знаний;
• отправлять новые предложенные вопросы в базу знаний для активного обучения.

Создание ответа из базы знаний

Создайте ответ от опубликованной базы знаний с использованием метода RuntimeClient.GenerateAnswerAsync. Этот метод принимает идентификатор базы знаний и QueryDTO. Перейдите к дополнительным свойствам QueryDTO, таким как Top и Context, для использования в вашем чат-боте.

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
}

Это простой пример отправки запроса в базу знаний. Чтобы ознакомиться с расширенными сценариями запросов, см. другие примеры запросов.

Удаление базы знаний

Удалите базу знаний, используя метод DeleteAsync с параметром ИД базы знаний.

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

Получение состояния операции

Некоторые методы, такие как "create" и "update", могут занять достаточно времени, чтобы вместо ожидания завершения процесса был возвращен класс операции. Используйте свойство Operation.OperationId из операции для опроса (с логикой повторных попыток), чтобы определить состояние исходного метода.

loop и Task.Delay в следующем блоке кода используются для имитации логики повторных попыток. Они должны быть заменены собственной логикой повторных попыток.

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

Выполнение приложения

Запустите приложение с помощью команды dotnet run из каталога приложения.

dotnet run

Исходный код для этого шаблона можно найти на портале GitHub.

Клиентская библиотека QnA Maker для Node.js:

• Создание базы знаний
• Обновление базы знаний
• Публикация базы знаний
• Получение ключа конечной точки среды выполнения прогнозирования
• Ожидание долго выполняющейся задачи
• Скачивание базы знаний
• Получение ответа из базы знаний
• Удаление базы знаний

Примеры пакета справочной документации | (npm)Node.js |

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Текущая версия Node.js.
• Получив подписку Azure, создайте ресурс QnA Maker на портале Azure, чтобы получить ключ разработки и ресурс. После развертывания ресурса выберите элемент Перейти к ресурсу.
  • Для подключения приложения к API QnA Maker потребуется ключ и имя созданного ресурса. Ключ и имя ресурса вы вставите в приведенный ниже код на следующих шагах в рамках этого краткого руководства.
  • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Установка

Создание нового приложения Node.js

В окне консоли (например, cmd, PowerShell или Bash) создайте новый каталог для приложения и перейдите в него.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

Выполните команду npm init -y, чтобы создать приложение узла с помощью файла package.json.

npm init -y

Установка клиентской библиотеки

Установите следующие пакеты npm:

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

Файл package.json приложения обновлен с учетом зависимостей.

Создайте файл с именем index.js, откройте его и импортируйте следующие библиотеки:

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

Создайте переменную для ключа Azure и имени ресурса.

• Ключ подписки и ключ разработки являются взаимозаменяемыми. Дополнительные сведения о ключе разработки см. в разделе Ключи в QnA Maker.

• Формат значения QNA_MAKER_ENDPOINT: https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Ключи и конечная точка в разделе Управление ресурсами, чтобы найти ключ разработки (подписка) и конечную точку QnA Maker.

• Формат значения QNA_MAKER_RUNTIME_ENDPOINT: https://YOUR-RESOURCE-NAME.azurewebsites.net. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Экспорт шаблона в разделе Автоматизация, чтобы найти конечную точку среды выполнения.

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

Объектные модели

В QnA Maker используются две разные объектные модели:

• QnAMakerClient — это объект для создания, публикации и скачивания базы знаний, а также управления ею.
• QnAMakerRuntime — это объект для отправки запроса в базу знаний с помощью API GenerateAnswer и новых предложенных вопросов с помощью API обучения (в рамках активного обучения).

Объектная модель QnAMakerClient

Клиент разработки QnA Maker — это объект QnAMakerClient, который проходит проверку подлинности в Azure с учетными данными, включающими ваш ключ.

После создания клиента используйте Базу знаний для создания, управления и публикации своей базы знаний.

Управляйте своей базой знаний, отправляя объект JSON. Для немедленных операций метод обычно возвращает объект JSON, указав статус. Ответ для длительных операций — ИД операции. Вызовите метод client.operations.getDetails с идентификатором операции, чтобы определить состояние запроса.

Объектная модель QnAMakerRuntimeClient

Клиент прогнозирования QnA Maker — это объект QnAMakerRuntimeClient, который проходит проверку подлинности в Azure с помощью объекта Microsoft.Rest.ServiceClientCredentials, содержащего ключ среды выполнения прогнозирования, полученный из вызова client.EndpointKeys.getKeys к клиенту разработки после публикации базы знаний.

Примеры кода

Эти фрагменты кода показывают, как выполнить следующие действия с помощью клиентской библиотеки QnA Maker для .NET:

• Проверка подлинности клиента разработки
• Создание базы знаний
• Обновление базы знаний
• Скачивание базы знаний
• Публикация базы знаний
• Удаление базы знаний
• Получение ключа среды выполнения запроса
• Получение состояния операции
• Проверка подлинности клиента среды выполнения запросов
• Создание ответа из базы знаний

Проверка подлинности клиента для создания базы знаний

Создайте экземпляр клиента с конечной точкой и ключом. Создайте объект ServiceClientCredentials с ключом и используйте его с конечной точкой, чтобы создать объект 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);

Создание базы знаний

База знаний хранит пары вопросов и ответов для объекта Класс CreateKbDTO из трех источников:

• Для редакционного содержимого используйте объект Класс QnADTO.
  • Чтобы использовать метаданные и запросы дальнейших действий, используйте редакционный контекст, так как эти данные добавляются на уровне отдельных пар вопросов и ответов.
• Для файлов используйте объект Класс FileDTO. Он включает в себя имя и общедоступный URL-адрес, указывающие на файл.
• В качестве значения для параметра URL-адреса используйте список строк, представляющих общедоступные URL-адреса.

На этапе создания также задаются свойства базы знаний:

• defaultAnswerUsedForExtraction — то, что возвращается, если ответ не найден;
• enableHierarchicalExtraction — автоматическое создание связей запросов между извлеченными парами вопросов и ответов;
• language — при создании первой базы данных ресурса задайте язык для использования в индексе Поиска Azure.

Вызовите метод "Создать" со сведениями о базе знаний. Сведения о базе знаний по сути представляют собой объект JSON.

После возвращения метода "Создать" передайте возвращенный идентификатор операции методу wait_for_operation для опроса состояния. Метод "wait_for_operation" возвращает значение после завершения операции. Проанализируйте значение заголовка resourceLocation возвращенной операции, чтобы получить новый идентификатор базы знаний.

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

Чтобы создать базу знаний, добавьте функцию wait_for_operation из предыдущего примера кода.

Обновление базы знаний

Базу знаний можно обновить, передав идентификатор базы знаний и метод UpdateKbOperationDTO, содержащий добавить, обновить и удалить объекты DTO в метод обновить. DTO также являются объектами JSON. Используйте метод wait_for_operation, чтобы определить, успешно ли выполнено обновление.

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
}

Чтобы обновить базу знаний, добавьте функцию wait_for_operation из предыдущего примера кода.

Скачивание базы знаний

Используйте метод загрузить, чтобы загрузить базу данных в виде списка QnADocumentsDTO. Это не эквивалентно экспорту портала QnA Maker со страницы настроек, поскольку результатом этого метода не является файл 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
}

Публикация базы знаний

Опубликуйте базу знаний, используя метод опубликовать. При этом берется текущая сохраненная и обученная модель, на которую ссылается ИД базы знаний, и публикуется ее в конечной точке. Проверьте код ответа HTTP, чтобы убедиться, что публикация прошла удачно.

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
}

Запрос к базе знаний

Получение ключа среды выполнения запроса

После публикации базы знаний необходимо получить ключ среды выполнения запроса, чтобы отправить в нее запрос. Этот ключ отличается о того, который использовался для создания исходного объекта клиента.

Используйте метод EndpointKeys.getKeys, чтобы получить класс EndpointKeysDTO.

Для запроса к базе знаний используйте любое свойство ключа, возвращаемое в объекте.

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
}

Проверка подлинности среды выполнения для создания ответа

Создайте QnAMakerRuntimeClient, чтобы отправить в базу знаний запрос для создания ответа или обучения по методу активного обучения.

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

Используйте QnAMakerRuntimeClient, чтобы получить ответ от базы знаний или отправить в нее новые предложенные вопросы для активного обучения.

Создание ответа из базы знаний

Создайте ответ из опубликованной базы знаний с помощью метода RuntimeClient.runtime.generateAnswer. Этот метод принимает идентификатор базы знаний и QueryDTO. Получите дополнительные свойства QueryDTO, например Top и Context, чтобы использовать их в чат-боте.

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

}

Это простой пример отправки запроса в базу знаний. Чтобы ознакомиться с расширенными сценариями запросов, см. другие примеры запросов.

Удаление базы знаний

Удалите базу знаний с помощью метода удалить с параметром идентификатора базы знаний.

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
}

Получение состояния операции

Некоторые методы, такие как "create" и "update", могут занять достаточно времени, чтобы вместо ожидания завершения процесса был возвращен класс операции. Используйте свойство Operation.OperationId из операции для опроса (с логикой повторных попыток), чтобы определить состояние исходного метода.

Вызов delayTimer в следующем блоке кода используется для имитации логики повторных попыток. Замените его на собственную логику повторных попыток.

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

Выполнение приложения

Запустите приложение с командой node index.js из каталога приложения.

node index.js

Исходный код для этого шаблона можно найти на портале GitHub.

Клиентская библиотека QnA Maker для Python позволяет выполнить следующие задачи:

• Создание базы знаний
• Обновление базы знаний
• Публикация базы знаний
• Получение ключа конечной точки среды выполнения прогнозирования
• Ожидание долго выполняющейся задачи
• Скачивание базы знаний
• Получение ответа из базы знаний
• Удаление базы знаний

Справочная документация | Исходный код библиотеки | Пакет (PyPi) | Примеры Python

Предварительные требования

• Подписка Azure — создайте бесплатную учетную запись.
• Python 3.x
• Получив подписку Azure, создайте ресурс QnA Maker на портале Azure, чтобы получить ключ разработки и конечную точку. После развертывания ресурса выберите элемент Перейти к ресурсу.
  • Для подключения приложения к API QnA Maker потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
  • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Установка

Установка клиентской библиотеки

После установки Python вы можете установить клиентскую библиотеку с помощью следующей команды:

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

Создание приложения Python

Создайте файл Python с именем quickstart-file.py и импортируйте следующие библиотеки.

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

Создайте переменные для конечной точки Azure и ключа ресурса.

• Ключ подписки и ключ разработки являются взаимозаменяемыми. Дополнительные сведения о ключе разработки см. в разделе Ключи в QnA Maker.

• Формат значения QNA_MAKER_ENDPOINT: https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Ключи и конечная точка в разделе Управление ресурсами, чтобы найти ключ разработки (подписка) и конечную точку QnA Maker.

• Формат значения QNA_MAKER_RUNTIME_ENDPOINT: https://YOUR-RESOURCE-NAME.azurewebsites.net. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Экспорт шаблона в разделе Автоматизация, чтобы найти конечную точку среды выполнения.

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'

Объектные модели

В QnA Maker используются две разные объектные модели:

• QnAMakerClient — это объект для создания, публикации и скачивания базы знаний, а также управления ею.
• QnAMakerRuntime — это объект для отправки запроса в базу знаний с помощью API GenerateAnswer и новых предложенных вопросов с помощью API обучения (в рамках активного обучения).

Использование этого примера базы знаний

База знаний, используемая в этом кратком руководстве, начинается с двух пар разговорных вопросов и ответов. Это сделано, чтобы упростить пример и обеспечить строго предсказуемые идентификаторы, используемые в методе Update, который сопоставляет дальнейшие запросы, содержащие вопросы, с новыми парами. Такой подход был запланирован и реализован в определенном порядке для целей данного краткого руководства.

Если вы планируете со временем разработать базу знаний с дальнейшими запросами, которые зависят от имеющихся пар вопросов и ответов, вы можете воспользоваться одним из следующих вариантов.

• Для управления более крупными базами знаний следует воспользоваться текстовым редактором или поддерживающим автоматизацию средством TSV, а затем полностью заменить всю базу знаний обновленной версией.
• Для небольших баз знаний дальнейшими запросами можно полностью управлять на портале QnA Maker.

Ниже приведены сведения о парах вопросов и ответов, используемых в этом кратком руководстве.

• Типы пар вопросов и ответов. После обновления в этой базе знаний содержатся пары вопросов и ответов двух типов: для беседы и по предметной области. Это типичное содержание для баз знаний, привязанных к приложению для общения, например чат-боту.
• Хотя можно фильтровать ответы из базы знаний по метаданным или использовать дальнейшие запросы, в этом кратком руководстве эти возможности не рассматриваются. Такие независящие от языка примеры generateAnswer можно найти здесь.
• Текст ответа — это данные на языке Markdown, которые могут содержать широкий спектр элементов Markdown, например изображения (общедоступные изображения из Интернета), ссылки (на общедоступные URL-адреса) и пункты маркированного списка. Все это многообразие в данном кратком руководстве не используется.

Объектная модель QnAMakerClient

Клиент разработки QnA Maker — это объект QnAMakerClient, который проходит проверку подлинности в Azure с помощью объекта Microsoft.Rest.ServiceClientCredentials, содержащего ваш ключ.

После создания клиента используйте свойство QnAMakerClient.Knowledgebase для создания и публикации своей базы знаний, а также управления ею.

Управляйте своей базой знаний, отправляя объект JSON. Для немедленных операций метод обычно возвращает объект JSON, указав статус. Ответ для длительных операций — ИД операции. Вызовите метод operations.get_details с идентификатором операции, чтобы определить состояние запроса.

Объектная модель QnAMakerRuntimeClient

Клиент QnA Maker прогнозирования — это QnAMakerRuntimeClient объект, который проходит проверку подлинности в Azure с помощью Microsoft.Rest.ServiceClientCredentials, который содержит ключ среды выполнения прогнозирования, возвращенный из вызова клиента разработки, клиента. EndpointKeysOperations.get_keys после публикации базы знаний.

generate_answer Используйте метод, чтобы получить ответ из среды выполнения запроса.

Проверка подлинности клиента для создания базы знаний

Создайте экземпляр клиента с конечной точкой и ключом. Создайте объект CognitiveServicesCredentials с ключом и используйте его с конечной точкой для создания объекта QnAMakerClient .

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

Создание базы знаний

Используйте объект клиента, чтобы получить объект операций базы знаний.

База знаний хранит пары вопросов и ответов для объекта Класс CreateKbDTO из трех источников:

• Для редакционного содержимого используйте объект Класс QnADTO.
  • Чтобы использовать метаданные и запросы дальнейших действий, используйте редакционный контекст, так как эти данные добавляются на уровне отдельных пар вопросов и ответов.
• Для файлов используйте объект Класс FileDTO. Он включает в себя имя и общедоступный URL-адрес, указывающие на файл.
• В качестве значения для параметра URL-адреса используйте список строк, представляющих общедоступные URL-адреса.

Вызовите методСоздать, а затем передайте возвращенный идентификатор операции методу Operations.getDetails для опроса состояния.

Последняя строка следующего кода возвращает ИД базы знаний из ответа от MonitorOoperation.

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

Чтобы создать базу знаний, добавьте функцию _monitor_operation из предыдущего примера кода.

Обновление базы знаний

Базу знаний можно обновить, передав идентификатор базы знаний и метод UpdateKbOperationDTO, содержащий добавить, обновить и удалить объекты DTO в метод обновить. Используйте метод Operation.getDetail, чтобы определить, успешно ли выполнено обновление.

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

Чтобы обновить базу знаний, добавьте функцию _monitor_operation из предыдущего примера кода.

Скачивание базы знаний

Используйте метод загрузить, чтобы загрузить базу данных в виде списка QnADocumentsDTO. Это не эквивалентно экспорту портала QnA Maker со страницы настроек, поскольку результатом этого метода не является файл 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)))

Публикация базы знаний

Опубликуйте базу знаний, используя метод опубликовать. При этом берется текущая сохраненная и обученная модель, на которую ссылается ИД базы знаний, и публикуется ее в конечной точке.

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

Запрос к базе знаний

Получение ключа среды выполнения запроса

После публикации базы знаний необходимо получить ключ среды выполнения запроса, чтобы отправить в нее запрос. Этот ключ отличается о того, который использовался для создания исходного объекта клиента.

Используйте метод EndpointKeysOperations.get_keys, чтобы получить класс EndpointKeysDTO.

Для запроса к базе знаний используйте любое свойство ключа, возвращаемое в объекте.

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

Проверка подлинности среды выполнения для создания ответа

Создайте QnAMakerRuntimeClient, чтобы отправить в базу знаний запрос для создания ответа или выполнять обучение по методу активного обучения.

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

Используйте QnAMakerRuntimeClient, чтобы получить ответ от базы знаний или отправить в нее новые предложенные вопросы для активного обучения.

Создание ответа из базы знаний

Сгенерируйте ответ из опубликованной базы знаний с помощью метода QnAMakerRuntimeClient.runtime.generate_answer. Этот метод принимает идентификатор базы знаний и QueryDTO. Получите дополнительные свойства QueryDTO, например Top и Context, чтобы использовать их в чат-боте.

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

Это простой пример отправки запроса в базу знаний. Чтобы ознакомиться с расширенными сценариями запросов, см. другие примеры запросов.

Удаление базы знаний

Удалите базу знаний с помощью метода удалить с параметром идентификатора базы знаний.

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

Получение состояния операции

Некоторые методы, такие как "create" и "update", могут занять достаточно времени, чтобы вместо ожидания завершения процесса был возвращен класс операции. Используйте идентификатор операции из операции для опроса (с логикой повторных попыток), чтобы определить состояние исходного метода.

Вызов setTimeout в следующем блоке кода используется для имитации асинхронного кода. Замените это на логику повторных попыток.

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

Выполнение приложения

Запустите приложение, выполнив команду Python в файле краткого руководства.

python quickstart-file.py

Исходный код для этого шаблона можно найти на портале GitHub.

Клиентская библиотека QnA Maker для Java позволяет выполнить указанные ниже задачи.

• Создание базы знаний
• Обновление базы знаний
• Публикация базы знаний
• Получение ключа конечной точки среды выполнения прогнозирования
• Ожидание долго выполняющейся задачи
• Скачивание базы знаний
• Получение ответа из базы знаний
• Удаление базы знаний

Исходный код библиотеки | Пакет | Примеры

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• JDK.
• Получив подписку Azure, создайте ресурс QnA Maker на портале Azure, чтобы получить ключ разработки и конечную точку. После развертывания ресурса выберите элемент Перейти к ресурсу.
  • Для подключения приложения к API QnA Maker потребуется ключ и конечная точка из созданного ресурса. Вставьте ключ и конечную точку в код, приведенный ниже в этом кратком руководстве.
  • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Установка

Установка клиентских библиотек

После установки Java можно установить клиентские библиотеки с помощью Maven из репозитория MVN.

Создание нового приложения Java

Создайте файл с именем quickstart.java и импортируйте указанные ниже библиотеки.

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

Создайте переменные для конечной точки Azure и ключа ресурса.

• Ключ подписки и ключ разработки являются взаимозаменяемыми. Дополнительные сведения о ключе разработки см. в разделе Ключи в QnA Maker.

• Формат значения QNA_MAKER_ENDPOINT: https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Ключи и конечная точка в разделе Управление ресурсами, чтобы найти ключ разработки (подписка) и конечную точку QnA Maker.

• Формат значения QNA_MAKER_RUNTIME_ENDPOINT: https://YOUR-RESOURCE-NAME.azurewebsites.net. Перейдите на портал Azure и найдите ресурс QnA Maker, созданный в рамках выполнения предварительных требований. Откройте страницу Экспорт шаблона в разделе Автоматизация, чтобы найти конечную точку среды выполнения.

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

Объектные модели

В QnA Maker используются две разные объектные модели:

• QnAMakerClient — это объект для создания, публикации и скачивания базы знаний, а также управления ею.
• QnAMakerRuntime — это объект для отправки запроса в базу знаний с помощью API GenerateAnswer и новых предложенных вопросов с помощью API обучения (в рамках активного обучения).

Использование этого примера базы знаний

База знаний, используемая в этом кратком руководстве, начинается с двух пар разговорных вопросов и ответов. Это сделано, чтобы упростить пример и обеспечить строго предсказуемые идентификаторы, используемые в методе Update, который сопоставляет дальнейшие запросы, содержащие вопросы, с новыми парами. Такой подход был запланирован и реализован в определенном порядке для целей данного краткого руководства.

Если вы планируете со временем разработать базу знаний с дальнейшими запросами, которые зависят от имеющихся пар вопросов и ответов, вы можете воспользоваться одним из следующих вариантов.

• Для управления более крупными базами знаний следует воспользоваться текстовым редактором или поддерживающим автоматизацию средством TSV, а затем полностью заменить всю базу знаний обновленной версией.
• Для небольших баз знаний дальнейшими запросами можно полностью управлять на портале QnA Maker.

Ниже приведены сведения о парах вопросов и ответов, используемых в этом кратком руководстве.

• Типы пар вопросов и ответов. После обновления в этой базе знаний содержатся пары вопросов и ответов двух типов: для беседы и по предметной области. Это типичное содержание для баз знаний, привязанных к приложению для общения, например чат-боту.
• Хотя можно фильтровать ответы из базы знаний по метаданным или использовать дальнейшие запросы, в этом кратком руководстве эти возможности не рассматриваются. Такие независящие от языка примеры generateAnswer можно найти здесь.
• Текст ответа — это данные на языке Markdown, которые могут содержать широкий спектр элементов Markdown, например изображения (общедоступные изображения из Интернета), ссылки (на общедоступные URL-адреса) и пункты маркированного списка. Все это многообразие в данном кратком руководстве не используется.

Объектная модель QnAMakerClient

Клиент разработки QnA Maker — это объект QnAMakerClient, который проходит проверку подлинности в Azure с помощью объекта MsRest::ServiceClientCredentials, содержащего ваш ключ.

После создания клиента используйте методы свойства Knowledgebases клиента для создания и публикации своей базы знаний, а также управления ею.

Для немедленных операций метод обычно возвращает результат, если таковой имеется. Ответ для длительных операций — объект Operation. Вызовите метод getDetails со значением operation.operationId, чтобы определить состояние запроса.

Объектная модель QnAMakerRuntimeClient

Клиент QnA Maker среды выполнения — объект QnAMakerRuntimeClient.

После публикации базы знаний с помощью клиента разработки используйте метод generateAnswer клиента среды выполнения, чтобы получить ответ от базы знаний.

Чтобы создать клиент среды выполнения, вызовите метод QnAMakerRuntimeManager.authenticate и передайте ключ конечной точки среды выполнения. Чтобы получить ключ конечной точки среды выполнения, вызовите getKeys с помощью клиента разработки.

Проверка подлинности клиента для создания базы знаний

Создайте экземпляр клиента с помощью конечной точки разработки и ключа подписки.

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

Создание базы знаний

База знаний хранит пары вопросов и ответов для объекта Класс CreateKbDTO из трех источников:

• Для редакционного содержимого используйте объект Класс QnADTO.
  • Чтобы использовать метаданные и запросы дальнейших действий, используйте редакционный контекст, так как эти данные добавляются на уровне отдельных пар вопросов и ответов.
• Для файлов используйте объект Класс FileDTO. Он включает в себя имя и общедоступный URL-адрес, указывающие на файл.
• В качестве значения для параметра URL-адреса используйте список строк, представляющих общедоступные URL-адреса.

Вызовите метод create, затем передайте свойство operationId возвращенной операции в метод getDetails для опроса состояния.

Последняя строка указанного ниже кода возвращает идентификатор базы знаний.

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

Обновление базы знаний

Вы можете обновить базу знаний, вызвав метод update, а затем передав ее идентификатор и объект UpdateKbOperationDTO. Этот объект, в свою очередь, может содержать следующие методы:

• добавление
• обновить
• Удаление

Передайте свойство operationId возвращенной операции в метод getDetails для опроса состояния.

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

Скачивание базы знаний

Используйте метод загрузить, чтобы загрузить базу данных в виде списка QnADocumentsDTO. Это не эквивалентно экспорту портала QnA Maker со страницы настроек, поскольку результатом этого метода не является файл 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");
}

Публикация базы знаний

Опубликуйте базу знаний, используя метод опубликовать. При этом берется текущая сохраненная и обученная модель, на которую ссылается ИД базы знаний, и публикуется ее в конечной точке.

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

Создание ответа из базы знаний

После публикации базы знаний необходимо получить ключ конечной точки среды выполнения, чтобы отправить в нее запрос. Он отличается от ключа подписки, используемого для создания клиента разработки.

Используйте метод getKeys, чтобы получить объект EndpointKeysDTO.

Создайте клиент среды выполнения, вызвав QnAMakerRuntimeManager.authenticate, и передайте ключ конечной точки среды выполнения из объекта EndpointKeysDTO.

Создайте ответ из опубликованной базы знаний с помощью метода generateAnswer. Этот метод принимает идентификатор базы знаний и объект 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();
}

Это простой пример отправки запроса в базу знаний. Чтобы ознакомиться с расширенными сценариями запросов, см. другие примеры запросов.

Удаление базы знаний

Удалите базу знаний с помощью метода удалить с параметром идентификатора базы знаний.

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

Получение состояния операции

Некоторые методы, такие как "create" и "update", могут занять достаточно времени, чтобы вместо ожидания завершения процесса был возвращен класс операции. Используйте идентификатор операции из операции для опроса (с логикой повторных попыток), чтобы определить состояние исходного метода.

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

Выполнение приложения

Ниже приведен метод Main для приложения.

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

Запустите приложение следующим образом: Предполагается, что имя класса — Quickstart, а зависимости находятся во вложенной папке с именем lib под текущей папкой.

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

Исходный код для этого шаблона можно найти на портале GitHub.