Как создать выполнение (Dialogflow)

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

Подробнее о создании ответов…

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

Определите стиль общения

Примечание. Подробную информацию о том, как работать с намерениями, можно найти в документации Dialogflow.

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

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

Как создавать намерения

Нажмите на значок + рядом с пунктом меню Intents (Намерения) на панели навигации слева. Откроется редактор намерений, в котором можно указать следующую информацию:

• Intent name (Название намерения) – название намерения, которое показывается в IDE.
• Контексты позволяют ограничить активацию намерения определенными случаями. Дополнительную информацию можно найти в документации Dialogflow по контекстам.
• События активируют намерения без необходимости что-либо говорить. Примером такого события является GOOGLE_ASSISTANT_WELCOME, которое позволяет Google Ассистенту вызвать ваше действие. Это событие используется для действия по умолчанию. Дополнительную информацию о встроенных вспомогательных намерениях можно найти в документации.
• Обучающие фразы определяют, что пользователи должны сказать (грамматика), чтобы активировать намерение. Введите несколько фраз (5–10), которые пользователи могут сказать, чтобы активировать намерение. Dialogflow автоматически обрабатывает естественные вариации фраз, которые вы указываете в качестве примеров.

• Действие и параметры определяют, какие данные передавать в выполнение, если оно включено для этого намерения. Это включает данные, проанализированные на основе пользовательского ввода, и имя, которое вы можете использовать в своем выполнении, чтобы определить, какое намерение было запущено. Это название будет использоваться для сопоставления намерения с соответствующей логикой выполнения. Дополнительную информацию об определении действий можно найти в разделе Действия и параметры документации Dialogflow.

  Примечание. В данном случае "действие" – это компонент намерения Dialogflow, а не действие на платформе Actions on Google.

• Responses (Ответы) – это конструктор ответов Dialogflow, в котором можно определить ответ на это намерение непосредственно в Dialogflow, не вызывая выполнение. Эта функция полезна для статических ответов, которые не требуют выполнения. Например, вы можете использовать его для простых приветствий или прощаний. Однако для большинства намерений вы, скорее всего, будете использовать фулфилмент.

• Fulfillment (Выполнение) – укажите, нужно ли вызывать выполнение при активации намерения. Скорее всего, вы включите эту функцию для большинства намерений в агенте Dialogflow. Чтобы увидеть этот пункт в намерении, необходимо включить выполнение для агента в меню Fulfillment (Выполнение).

Создание ответов в Dialogflow

Для некоторых намерений может не потребоваться, чтобы выполнение возвращало ответ. В таких случаях вы можете использовать конструктор ответов в Dialogflow.

В разделе Responses (Ответы) укажите текстовый ответ, который будет возвращаться пользователям. Текстовые ответы по умолчанию – это простые текстовые ответы TTS, которые можно использовать в нескольких интеграциях Dialogflow. Ответы для Google Ассистента описаны на странице Ответы.

Как создавать ответы на запросы

Код выполнения размещается в логике выполнения вебхука для действия. Например, в примере Silly Name Maker эта логика находится в файле index.js для Cloud Functions for Firebase.

Когда активируется намерение, использующее выполнение, вы получаете от Dialogflow запрос, содержащий информацию о намерении. Затем вы отвечаете на запрос, обрабатывая намерение и возвращая ответ. Этот запрос и ответ определяются вебхуком Dialogflow.

Мы настоятельно рекомендуем использовать клиентскую библиотеку Node.js для обработки запросов и возврата ответов. В общих чертах процедура использования клиентской библиотеки выглядит следующим образом:

1. Инициализируйте объект Dialogflow. Этот объект автоматически обрабатывает прослушивание запросов и их синтаксический анализ, чтобы вы могли обрабатывать их при выполнении.
2. Создание функций для обработки запросов Эти функции обрабатывают пользовательский ввод и другие компоненты намерения и создают ответ, который возвращается в Dialogflow.

Инициализируйте объект Dialogflow

Следующий код создает экземпляр Dialogflow и выполняет стандартную настройку Node.js для Google Cloud Functions:

Node.js

'use strict';

const {dialogflow} = require('actions-on-google');
const functions = require('firebase-functions');

const app = dialogflow({debug: true});

app.intent('Default Welcome Intent', (conv) => {
  // Do things
});
exports.yourAction = functions.https.onRequest(app);

Java

public class DfFulfillment extends DialogflowApp {
  private static final Logger LOGGER = LoggerFactory.getLogger(DfFulfillment.class);

  @ForIntent("Default Welcome Intent")
  public ActionResponse welcome(ActionRequest request) {
    // Do things
    // ...
  }

Примечание. Если вы развертываете приведенный выше код с помощью встроенного редактора Dialogflow, замените exports.yourAction на exports.dialogflowFirebaseFulfillment.

Создание функций для обработки запросов

Когда пользователь произносит фразу, которая активирует намерение, вы получаете запрос от Dialogflow, который обрабатывается функцией в дополнении. В этой функции вы обычно делаете следующее:

1. Выполните логику, необходимую для обработки пользовательского ввода.
2. Создайте ответы на намерения. Учитывайте, на каком устройстве пользователи будут видеть ответы. Подробнее о том, как адаптировать ответы для разных платформ, читайте в разделе Возможности платформ.
3. Вызовите функцию ask() с вашим ответом.

Примечание. При использовании Cloud Functions for Firebase глобальные переменные могут кешироваться между выполнениями функций. Дополнительную информацию вы можете найти в разделе Жизненный цикл экземпляра функции документации Google Cloud.

В приведенном ниже коде показано, как создать два ответа TTS, которые обрабатывают намерение вызова (input.welcome) и намерение диалога (input.number), которое приветствует пользователя в вашем действии и повторяет число, которое пользователь произнес для намерения Dialogflow с именем:

Node.js

const app = dialogflow();
app.intent('Default Welcome Intent', (conv) => {
conv.ask('Welcome to number echo! Say a number.');
});
app.intent('Input Number', (conv, {num}) => {
// extract the num parameter as a local string variable
conv.close(`You said ${num}`);
});

Java

@ForIntent("Default Welcome Intent")
public ActionResponse defaultWelcome(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  rb.add("Welcome to number echo! Say a number.");
  return rb.build();
}

@ForIntent("Input Number")
public ActionResponse inputNumber(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  Integer number = (Integer) request.getParameter("num");
  rb.add("You said " + number.toString());
  return rb.endConversation().build();
}

Особое намерение Input Number, которое сопровождает приведенный выше код, использует объект @sys.number для извлечения числа из высказываний пользователя. Затем намерение отправляет параметр num, содержащий число, указанное пользователем, в функцию выполнения.

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

Node.js

const WELCOME_INTENT = 'Default Welcome Intent';
const NUMBER_INTENT = 'Input Number';
const NUMBER_PARAMETER = 'num';
// you can add a fallback function instead of a function for individual intents
app.fallback((conv) => {
 // intent contains the name of the intent
 // you defined in the Intents area of Dialogflow
 const intent = conv.intent;
 switch (intent) {
   case WELCOME_INTENT:
     conv.ask('Welcome! Say a number.');
     break;
   case NUMBER_INTENT:
     const num = conv.parameters[NUMBER_PARAMETER];
     conv.close(`You said ${num}`);
     break;
 }
});

Java

// you can add a fallback function instead of a function for individual intents
@ForIntent("Default Fallback Intent")
public ActionResponse fallback(ActionRequest request) {
  final String WELCOME_INTENT = "Default Welcome Intent";
  final String NUMBER_INTENT = "Input Number";
  final String NUMBER_ARGUMENT = "num";
  // intent contains the name of the intent
  // you defined in the Intents area of Dialogflow
  ResponseBuilder rb = getResponseBuilder(request);
  String intent = request.getIntent();
  switch (intent) {
    case WELCOME_INTENT:
      rb.add("Welcome! Say a number.");
      break;
    case NUMBER_INTENT:
      Integer num = (Integer) request.getParameter(NUMBER_ARGUMENT);
      rb.add("You said " + num).endConversation();
      break;
  }
  return rb.build();
}

Повторный запрос при отсутствии совпадений

Если Dialogflow не может сопоставить ни одну из грамматик ввода, определенных в обучающих фразах намерений, активируется резервное намерение. Обычно в таких случаях пользователю предлагается повторно ввести данные, необходимые для работы Действия. Вы можете указать фразы для повторного запроса в разделе Response (Ответ) резервного намерения или использовать вебхук.

Если ответ пользователя не соответствует обучающим фразам вашего действия, Google Ассистент пытается обработать ввод. Это позволяет пользователям переключаться между действиями в процессе разговора. Например, пользователь спрашивает: "Какие фильмы идут в кинотеатрах на этой неделе?", а затем меняет тему: "Какая завтра будет погода?" В этом примере фраза "Какая завтра погода?" не является допустимым ответом в разговоре, начатом исходным запросом. Поэтому Ассистент автоматически пытается обработать совпадение и перевести пользователя в подходящий разговор.

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

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

Примечание. По умолчанию Dialogflow автоматически создает стандартное резервное намерение для каждого агента. Вы можете изменить ответы, предоставляемые этим намерением, или удалить его и создать собственные резервные намерения, чтобы правильно обрабатывать случаи, когда совпадений нет. Ответы по умолчанию в стандартном резервном намерении в большинстве случаев слишком общие.

Внимание! Не используйте резервные намерения для выполнения запросов пользователей. Резервные намерения и обработка несоответствий должны использоваться только для повторного запроса пользователя. Вместо этого определите действие, которое использует объект @sys.any.

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

1. В меню навигации Dialogflow нажмите Intents (Намерения).
2. Нажмите на значок ⋮ рядом с кнопкой Create Intent (Создать намерение) и выберите Create Fallback Intent (Создать резервное намерение). Вы также можете нажать Default Fallback Intent (Резервное намерение по умолчанию), чтобы изменить его.

3. Укажите фразы, которые будут произноситься пользователям. Эти фразы должны быть разговорными и максимально полезными для текущего контекста пользователя.

   Без выполнения. Укажите фразы в области Response (Ответ) намерения. Dialogflow случайным образом выбирает фразы из этого списка, чтобы отвечать пользователям, пока не будет активировано более конкретное намерение.

   Чтобы сделать это с помощью фулфилмента:

   1. В разделе Fulfillment (Выполнение) нужного намерения установите переключатель Enable webhook call for this intent (Включить вызов вебхука для этого намерения) в положение "включено".
   2. В логике выполнения обработайте резервное намерение так же, как и любое другое, как описано в разделе Создание функций для обработки запросов.

   Например, следующая функция использует объект conv.data (произвольный набор данных, который можно использовать для сохранения состояния) из клиентской библиотеки Node.js, чтобы хранить счетчик, отслеживающий, сколько раз активируется резервное намерение. Если оно сработает несколько раз, действие будет прекращено. Хотя это не показано в коде, вы должны сделать так, чтобы другие намерения сбрасывали этот счетчик на 0, когда срабатывает намерение, не являющееся резервным. Подробнее о том, как это сделать, рассказывается в примере Number Genie.

   Node.js

   app.intent('Default Fallback Intent', (conv) => {
    conv.data.fallbackCount++;
    // Provide two prompts before ending game
    if (conv.data.fallbackCount === 1) {
      conv.contexts.set(DONE_YES_NO_CONTEXT, 5);
      conv.ask('Are you done playing Number Genie?');
    } else {
      conv.close(`Since I'm still having trouble, so I'll stop here. ` +
        `Let's play again soon.`);
    }
   });

   Java

   @ForIntent("Default Fallback Intent")
   public ActionResponse defaultFallback(ActionRequest request) {
     final String DONE_YES_NO_CONTEXT = "done_yes_no_context";
     ResponseBuilder rb = getResponseBuilder(request);
   
     int fallbackCount =
         request.getConversationData().get("fallbackCount") == null
             ? 0
             : (Integer) request.getConversationData().get("fallbackCount");
     fallbackCount++;
     request.getConversationData().put("fallbackCount", fallbackCount);
   
     if (fallbackCount == 1) {
       rb.add(new ActionContext(DONE_YES_NO_CONTEXT, 5));
       rb.add("Are you done playing Number Genie?");
     } else {
       rb.add("Since I'm still having trouble, so I'll stop here. Let's play again soon")
           .endConversation();
     }
     return rb.build();
   }

Использование контекстов

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

• Если вы не зададите контексты для резервного намерения, оно будет считаться глобальным резервным намерением, которое Dialogflow активирует, когда не удается сопоставить никакое другое намерение. Если вы решите использовать один из них, то он должен быть единственным.

• Если вы зададите входные контексты для резервного намерения, Dialogflow активирует его при соблюдении следующих условий:

  • Текущие контексты пользователя являются надмножеством контекстов, определенных в намерении.
  • Других совпадений по намерениям нет.

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

• Если вы зададите контекст вывода для стандартного намерения, то после его активации и обработки пользователь останется в том же контексте.

Подробнее о контекстах Dialogflow…

Повторный запрос при отсутствии ввода

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