Добавление возможности распознавания естественного языка в функционал ботаAdd natural language understanding to your bot

применимо к: Пакет SDK v4APPLIES TO: SDK v4

Возможность понимать, что пользователь хочет сказать и какой вкладывает контекст, может быть сложной задачей, но также может способствовать более естественной беседе с ботом.The ability to understand what your user means conversationally and contextually can be a difficult task, but can provide your bot a more natural conversation feel. API распознавания речи — это облачная служба API, которая позволяет сделать так, чтобы бот мог распознавать намерения пользовательских сообщений, использовать более естественный язык пользователя и лучше направлять поток общения.Language Understanding (LUIS) is a cloud-based API service that enables you to do just that so that your bot can recognize the intent of user messages, allow for more natural language from your user, and better direct the conversation flow.

В этом разделе рассматривается добавление LUIS в приложение для бронирования авиабилетов, чтобы распознавать намерения и сущности в введенных пользователем данных.This topic walks you through adding LUIS to a flight booking application to recognize different intents and entities contained within user input.

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

Об этом примереAbout this sample

Этот пример основного бота реализует логику приложения для бронирования авиабилетов.This core bot sample shows an example of an airport flight booking application. С помощью службы LUIS он распознает пользовательский ввод и возвращает наиболее вероятное из обнаруженных LUIS намерений.It uses a LUIS service to recognize the user input and return the top recognized LUIS intent.

Языковая модель содержит три намерения: Book Flight, Cancel и None.The language model contains three intents: Book Flight, Cancel, and None. Служба LUIS будет использовать эти намерения для распознавания желаний пользователя в полученном от него сообщении.LUIS will use these intents to understand what the user meant when they send a message to the bot. Языковая модель также определяет сущности, которые LUIS может извлекать из входных данных пользователя, таких как аэропорты вылета или назначения.The language model also defines entities that LUIS can extract from the user's input, such as the origin or destination airport.

После каждой обработки введенных пользователем данных DialogBot сохраняет текущее состояние UserState и ConversationState.After each processing of user input, DialogBot saves the current state of both UserState and ConversationState. После сбора всех необходимых сведений в этом примере кода создается демонстрационное резервирование авиабилетов.Once all the required information has been gathered the coding sample creates a demo flight booking reservation. В этой статье мы будем рассматривать те элементы примера, которые имеют отношение к LUIS.In this article we'll be covering the LUIS aspects of this sample. Но в целом поток логических действий в примере выглядит примерно так.However, the general flow of the sample is shown below:

  • Когда подключается новый пользователь, вызывается OnMembersAddedAsync и отображается приветственная карточка.OnMembersAddedAsync is called when a new user is connected and displays a welcome card.
  • OnMessageActivityAsync вызывается для каждого полученного блока данных, введенных пользователем.OnMessageActivityAsync is called for each user input received.

Поток логических действий в примере LUIS

Модуль OnMessageActivityAsync запускает соответствующий диалог с помощью метода расширения диалога Run.The OnMessageActivityAsync module runs the appropriate dialog through the Run dialog extension method. Затем главный диалог вызывает вспомогательный метод LUIS для поиска самого вероятного намерения пользователя.Then the main dialog calls the LUIS helper to find the the top scoring user intent. Если таким намерением является BookFlight (бронирование авиабилетов), вспомогательный метод сохраняет полученные от LUIS данные пользователя.If the top intent for the user input returns "BookFlight", the helper fills out information from the user that LUIS returned. Затем главный диалог запускает BookingDialog для сбора требуемых дополнительных сведений от пользователя, например:After that, the main dialog starts the BookingDialog, which acquires additional information as needed from the user such as:

  • Origin — город вылета;Origin the originating city
  • TravelDate — дата для бронирования авиабилетов;TravelDate the date to book the flight
  • Destination — город прилета;Destination the destination city

В этой статье описывается добавление LUIS в бот.This article covers how to add LUIS to a bot. Дополнительные сведения об использовании диалогов или состояния можно получить, ознакомившись со сбором данных, которые вводит пользователь, с помощью запроса в диалоге или сохранением данных пользователя и диалога.For information about using dialogs or state, see how to gather user input using a dialog prompt or save user and conversation data, respectively.

Создание приложения LUIS на портале LUISCreate a LUIS app in the LUIS portal

  1. Войдите на портал LUIS.Sign in to the LUIS portal.

    • Создайте учетную запись, если у вас ее еще нет.If you don't already have an account, create one.
    • Если у вас еще нет ресурса разработки, создайте его.If you don't already have an authoring resource, create one.
    • Дополнительные сведения см. в документации LUIS о том, как войти на портал LUIS.For more information, see the LUIS documentation on how to sign in to the LUIS portal.
  2. На странице My Apps (Мои приложения) выберите + New app for conversation (Создать приложение для беседы), а затем выберите Import as JSON (Импортировать как JSON).On the My Apps page, click New app for conversation and select Import as JSON.

  3. В диалоговом окне Import new app (Импорт нового приложения) сделайте следующее.In the Import new app dialog:

    1. Выберите файл FlightBooking.json в папке CognitiveModels примера.Choose the FlightBooking.json file in the CognitiveModels folder of the sample.
    2. Введите FlightBooking в качестве необязательного имени приложения и нажмите кнопку Done (Готово).Enter FlightBooking as the optional name of the app, and click Done.
  4. Возможно, вам будет предложено обновить составные сущности.You may be prompted to upgrade your composite entities. Можно проигнорировать это и нажать кнопку напомнить позже.You can ignore this and click Remind me later:

    игнорировать-составные сущности

  5. Обучите и опубликуйте свое приложение.Train and publish your app. Дополнительные сведения см. в документации LUIS по обучению и публикации приложения в рабочей среде.For more information, see the LUIS documentation on how to train and publish an app to the production environment.

Для чего нужны сущностиWhy use entities

Сущности LUIS позволяют боту лучше понимать некоторые факты или события, которые отличаются от стандартных намерений.LUIS entities allow your bot to intelligently understand certain things or events that are different than the standard intents. Это позволяет получить от пользователя дополнительную информацию, которая позволит боту точнее реагировать на действия пользователя или пропустить некоторые вопросы, в которых от пользователя запрашивается уже полученная информация.This enables you to gather extra information from the user, which lets your bot respond more intelligently or possibly skip certain questions where it asks the user for that information. В файле FlightBooking.json определены не только три намерения LUIS (Book Flight, Cancel и None), но и набор дополнительных сущностей, таких как From.Airport и To.Airport.Along with definitions for the three LUIS intents 'Book Flight', 'Cancel', and 'None' the FlightBooking.json file also contains a set of entities such as 'From.Airport' and 'To.Airport'. Эти сущности позволяют LUIS обнаруживать и возвращать дополнительные сведения из данных, которые пользователь предоставляет при запросе нового бронирования.These entities allow LUIS to detect and return additional information contained within the user's original input when they request a new travel booking.

Получение значений для подключения к приложению LUISObtain values to connect to your LUIS app

После публикации приложения LUIS ваш бот сможет обратиться к нему.Once your LUIS app is published, you can access it from your bot. Для доступа к приложению LUIS из кода бота потребуется записать несколько значений.You will need to record several values to access your LUIS app from within your bot. Нужные сведения можно получить с помощью портала LUIS.You can retrieve that information using the LUIS portal.

Получение сведений о приложении на портале LUIS.aiRetrieve application information from the LUIS.ai portal

Файл параметров (appsettings.json, .env или config.py) используется, чтобы собрать в одном расположении ссылки на все службы.The settings file (appsettings.json, .env or config.py) acts as the place to bring all service references together in one place. Полученные данные будут добавлены в этот файл в следующем разделе.The information you retrieve will be added to this file in the next section.

  1. Выберите опубликованное приложение LUIS на сайте luis.ai.Select your published LUIS app from luis.ai.
  2. Открыв опубликованное приложение LUIS, выберите в нем вкладку MANAGE (Управление).With your published LUIS app open, select the MANAGE tab.
  3. Перейдите на вкладку Параметры в левой части экрана и запишите значение, показанное в поле идентификатор приложения как <YOUR_APP_ID> .Select the Settings tab on the left side and record the value shown for Application ID as <YOUR_APP_ID>.

    Управление приложением LUIS — сведения о приложенииManage LUIS app - Application Information

  4. Перейдите на вкладку Azure Resources (Ресурсы Azure) в левой части страницы и выберите группу Authoring Resource (Ресурс разработки).Select the Azure Resources tab on the left side and select the Authoring Resource group. Запишите значение Location (Расположение) как <YOUR_REGION>, а значение Primary Key (Первичный ключ) — как <YOUR_AUTHORING_KEY>.Record the value shown for Location as <YOUR_REGION> and Primary Key as <YOUR_AUTHORING_KEY>.

    Управление информацией о разработке приложений LUISManage LUIS app - Authoring Information

Обновление файла параметровUpdate the settings file

Добавьте в файл appsettings.json необходимые сведения для доступа к приложению LUIS, включая идентификатор приложения, ключ разработки и регион.Add the information required to access your LUIS app including application id, authoring key, and region into the appsettings.json file. Все эти данные вы ранее сохранили из опубликованного приложения LUIS.These are the values you saved previously from your published LUIS app. Обратите внимание, что имя узла API должно иметь формат <your region>.api.cognitive.microsoft.com.Note that the API host name should be in the format <your region>.api.cognitive.microsoft.com.

appsetting.jsonappsetting.json

{
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "LuisAppId": "",
  "LuisAPIKey": "",
  "LuisAPIHostName": ""
}

Настройка бота для работы с приложением LUISConfigure your bot to use your LUIS app

Убедитесь, что для вашего проекта установлен пакет NuGet Microsoft.Bot.Builder.AI.Luis.Be sure that the Microsoft.Bot.Builder.AI.Luis NuGet package is installed for your project.

Для подключения к службе LUIS бот извлекает сведения, которые вы ранее добавили в файл appsetting.json.To connect to the LUIS service, the bot pulls the information you added above from the appsetting.json file. Класс FlightBookingRecognizer содержит код с параметрами из файла appsetting.json и отправляет запрос к службе LUIS, вызывая метод RecognizeAsync.The FlightBookingRecognizer class contains code with your settings from the appsetting.json file and queries the LUIS service by calling RecognizeAsync method.

FlightBookingRecognizer.csFlightBookingRecognizer.cs

public class FlightBookingRecognizer : IRecognizer
{
    private readonly LuisRecognizer _recognizer;

    public FlightBookingRecognizer(IConfiguration configuration)
    {
        var luisIsConfigured = !string.IsNullOrEmpty(configuration["LuisAppId"]) && !string.IsNullOrEmpty(configuration["LuisAPIKey"]) && !string.IsNullOrEmpty(configuration["LuisAPIHostName"]);
        if (luisIsConfigured)
        {
            var luisApplication = new LuisApplication(
                configuration["LuisAppId"],
                configuration["LuisAPIKey"],
                "https://" + configuration["LuisAPIHostName"]);
            // Set the recognizer options depending on which endpoint version you want to use.
            // More details can be found in https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3
            var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
            {
                PredictionOptions = new Bot.Builder.AI.LuisV3.LuisPredictionOptions
                {
                    IncludeInstanceData = true,
                }
            };

            _recognizer = new LuisRecognizer(recognizerOptions);
        }
    }

    // Returns true if luis is configured in the appsettings.json and initialized.
    public virtual bool IsConfigured => _recognizer != null;

    public virtual async Task<RecognizerResult> RecognizeAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        => await _recognizer.RecognizeAsync(turnContext, cancellationToken);

    public virtual async Task<T> RecognizeAsync<T>(ITurnContext turnContext, CancellationToken cancellationToken)
        where T : IRecognizerConvert, new()
        => await _recognizer.RecognizeAsync<T>(turnContext, cancellationToken);
}

FlightBookingEx.cs содержит логику для извлечения From, To и TravelDate. Это расширение разделяемого класса FlightBooking.cs, используемого для хранения результатов LUIS при вызове FlightBookingRecognizer.RecognizeAsync<FlightBooking> из MainDialog.cs.The FlightBookingEx.cs contains the logic to extract From, To and TravelDate; it extends the partial class FlightBooking.cs used to store LUIS results when calling FlightBookingRecognizer.RecognizeAsync<FlightBooking> from the MainDialog.cs.

CognitiveModels\FlightBookingEx.csCognitiveModels\FlightBookingEx.cs

// Extends the partial FlightBooking class with methods and properties that simplify accessing entities in the luis results
public partial class FlightBooking
{
    public (string From, string Airport) FromEntities
    {
        get
        {
            var fromValue = Entities?._instance?.From?.FirstOrDefault()?.Text;
            var fromAirportValue = Entities?.From?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (fromValue, fromAirportValue);
        }
    }

    public (string To, string Airport) ToEntities
    {
        get
        {
            var toValue = Entities?._instance?.To?.FirstOrDefault()?.Text;
            var toAirportValue = Entities?.To?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (toValue, toAirportValue);
        }
    }

    // This value will be a TIMEX. And we are only interested in a Date so grab the first result and drop the Time part.
    // TIMEX is a format that represents DateTime expressions that include some ambiguity. e.g. missing a Year.
    public string TravelDate
        => Entities.datetime?.FirstOrDefault()?.Expressions.FirstOrDefault()?.Split('T')[0];
}

Теперь служба LUIS для бота полностью настроена и подключена.LUIS is now configured and connected for your bot.

Тестирование ботаTest the bot

Скачайте и установите последнюю версию Bot Framework Emulator.Download and install the latest Bot Framework Emulator

  1. Выполните этот пример на локальном компьютере.Run the sample locally on your machine. Дополнительные инструкции, включая примеры для C#, JS или Python, см. в файле README.If you need instructions, refer to the readme file for the C# Sample, JS Sample or Python Sample.

  2. В эмуляторе введите сообщение, например "Путешествие в Париж" или "переход от Париж к Берлин".In the Emulator, type a message such as "travel to paris" or "going from paris to berlin". Используйте все речевые фрагменты, включенные в файл FlightBooking.json, для обучения намерения Book flight (Бронирование авиабилетов).Use any utterance found in the file FlightBooking.json for training the intent "Book flight".

Входные данные LUIS для бронирования

Если наиболее вероятное намерение LUIS соответствует элементу Book flight (Бронирование авиабилетов), бот будет задавать дополнительные вопросы, пока не получит достаточно сохраненных сведений для создания бронирования.If the top intent returned from LUIS resolves to "Book flight" your bot will ask additional questions until it has enough information stored to create a travel booking. После этого он возвращает всю собранную информацию о бронировании пользователю.At that point it will return this booking information back to your user.

Результат LUIS для бронирования

На этом этапе логика кода обнуляет состояние бота, и вы можете создать новое резервирование.At this point the code bot logic will reset and you can continue to create additional bookings.

Дополнительные сведенияAdditional information

Дополнительные сведения о LUIS см. в документации по LUIS:For more about LUIS, see the LUIS documentation:

Дальнейшие действияNext steps