Полное руководство по разговорному ИИ с Dialogflow и Google Cloud

14 апреля 2025 г. 13:05

Глава 11: Создание пользовательской интеграции с SDK Dialogflow

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

Dialogflow также предоставляет SDK, и это удобно, когда вы хотите создать свои собственные интеграции вместо использования готовых интеграций в Dialogflow. Примеры включают реализацию чат-бота в вашем собственном мобильном приложении, на вашем собственном оборудовании и интеграцию его в ваш собственный веб-сайт. Это означает, что вам нужно будет вручную вызывать/предоставлять следующие шаги (см. Рисунок 11-1):

Реализация пользовательского интерфейса для интеграции (фронтенд) обычно включает поле textarea для отображения ответов и поле ввода для ввода высказываний.
Реализация бэкэнда, которая интегрирует SDK Dialogflow для:
- Управления сеансами
- Аутентификации
- Обнаружения намерений (detectIntent)
- Возврата ответов
Расширенные ответы в пользовательском интерфейсе реализации.

Рисунок 11-1. Архитектура пользовательской интеграции. От реализации пользовательского интерфейса к бэкэнд-приложению, которое взаимодействует с SDK Dialogflow

Ваш пользователь разговаривает с пользовательским интерфейсом вашей интеграции (например, фронтендом вашего веб-сайта).

Пользовательский интерфейс передает введенные сообщения чат-бота (или входящие аудиопотоки) в бэкэнд-интеграцию. Бэкэнд-интеграция разговаривает с SDK Dialogflow.

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

Реализация пользовательского чат-бота на фронтенде вашего веб-сайта, Настройка

Для реализации пользовательской интеграции, например, на веб-сайте, вам нужно будет убедиться, что у вас включен API Dialogflow:

gcloud services enable dialogflow.googleapis.com

Также требуется загрузить сервисный аккаунт Dialogflow Integrations на ваш жесткий диск и назначить его переменной среды GOOGLE_APPLICATION_CREDENTIALS.

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

gcloud init

Если вы не выполните эти шаги, вы получите эту ошибку:

(node:95119) UnhandledPromiseRejectionWarning:
Error: 7 PERMISSION_DENIED: IAM permission 'dialogflow.sessions.detectIntent' on 'projects/project-id/agent' denied.

Просмотрите Главу 2 о том, как настроить ваш проект Dialogflow для получения дополнительной информации.

Реализация пользовательского интерфейса

Листинг 11-1 показывает пример HTML-страницы, которая включает пользовательский интерфейс чат-бота Dialogflow. В реальном мире вы, вероятно, захотите использовать клиентский фреймворк, такой как Angular, но чтобы сделать этот пример простым, давайте оставим его красивым и компактным.

Листинг 11-1. Пример пользовательского интерфейса чат-бота в HTML

<!DOCTYPE html>
<html>
<head>
 <meta charset="utf-8" />
 <title>Custom Web Chat</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
 <link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.indigo-pink.min.css">
 <!-- //1 -->
 <script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.3.0/socket.io.js"></script>
 <!-- //2 Найдите таблицу стилей в Git-репозитории этой книги-->
 <link rel="stylesheet" href="style.css">
</head>
<body>
 <!-- //3-->
 <form id="chatbox" autocomplete="off">
  <h1 style="font-size: 18px;">Custom Web Chat</h1>
  <div class="chatarea" id="ca">
   <ul id="messages" class="history"></ul>
  </div>
  <div class="chatfooter">
   <!-- //4-->
   <div class="chatinput">
    <input id="queryText" class="chatinput" placeholder="Reply to chatbot...">
   </div>
   <button type="submit" id="submit">Send</button>
  </div>
 </form>
 <script>
  //a) Загрузить socket io
  const socketio = io();

  //b) Как только socket.io установит соединение с серверным приложением,
  // выполнить этот блок
  const socket = socketio.on('connect', function() {
   console.log('connected');

   //c) Запустить этот блок, когда сервер ответит выполнением
   socketio.on('returnResults', function (data) {
    var objDiv = document.getElementById("ca");
    console.log(data);

    //d) Если есть queryResults, то динамически
    // создать элементы списка для добавления к списку сообщений.
    if(data[0].queryResult){
     var agent = document.createElement("li");
     agent.className = 'balloon agent';
     agent.innerHTML = data[0].queryResult.fulfillmentText;
     messages.appendChild(agent);
     objDiv.scrollTop = objDiv.scrollHeight;
    }
   });

   //welcome
   socketio.emit('welcome');
  });

  //e) Создать несколько указателей на другие HTML-элементы
  // const textarea = document.getElementById('textarea'); // Этот элемент не используется в предоставленном коде
  const textInput = document.getElementById('queryText');
  const submitBtn = document.getElementById('submit');
  const messages = document.getElementById('messages');

  //f) При отправке высказывания пользователя,
  // создать элементы списка для добавления к списку сообщений.
  submitBtn.onclick = function(e) {
   e.preventDefault();
   socketio.emit('message', textInput.value);
   var user = document.createElement("li");
   user.className = 'balloon user';
   user.innerHTML = textInput.value;
   messages.appendChild(user);
   textInput.value = ""; // Очистить поле ввода
   objDiv.scrollTop = objDiv.scrollHeight; // Прокрутить вниз
  }
 </script>
</body>
</html>

При просмотре этого кода следует обратить внимание на пару ключевых моментов:

В заголовке я загружаю файл JavaScript из CDN: socket.io.js Socket.IO обеспечивает двунаправленную связь в реальном времени на основе событий. Он работает на любой платформе, в браузере или на устройстве, одинаково уделяя внимание надежности и скорости.
Таблица стилей style.css загрузит несколько приятных стилей, чтобы текст пользователя и агента выглядел как текстовые шарики.
В теле HTML-документа я создаю элемент формы. Этот элемент формы будет содержать список сообщений чат-бота. Это сообщения пользователя и сообщения агента Dialogflow.
Форма также содержит поле ввода текста с кнопкой отправки; это позволяет пользователю вводить вопросы чат-боту.
Теперь есть некоторый клиентский JavaScript для запуска:
1. Сначала загрузите объект JavaScript Socket.IO.
2. Как только Socket.IO установит соединение с серверным приложением, выполните этот блок кода.
3. Запустите этот блок, когда сервер ответит выполнением.
4. Если есть queryResults, то динамически создайте элементы списка для добавления к списку сообщений.
5. Создайте несколько указателей на другие HTML-элементы.
6. При отправке высказывания пользователя создайте элементы списка для добавления к списку сообщений.

Реализация бэкэнда

Теперь перейдем к бэкэнд-коду. Это приложение Node.js Express.

Для этого проекта мы будем использовать библиотеки npm из Листинга 11-2.

Листинг 11-2. Бэкэнд package.json, содержащий все библиотеки

{
 "name": "dialogflow-custom-integration",
 "version": "1.0.0",
 "author": "Lee Boonstra",
 "license": "Apache-2.0",
 "description": "Custom Web integration with the Dialogflow SDK",
 "engines": {
  "node": ">=10.9.0 <13.0.0", // Уточненные версии Node.js
  "yarn": ">=1.17.3 <=1.19.1" // Версии Yarn, если используется
 },
 "scripts": {
  "start": "node app.js"
 },
 "private": true,
 "dependencies": {
  "cors": "^2.8.5",
  "dialogflow": "^0.14.1", // Уточненная версия, может потребоваться обновление
  "dotenv": "^8.2.0",
  "express": "^4.17.1",
  "socket.io": "^2.3.0", // Уточненная версия
  "uuid": "^3.3.3" // Или более новая версия
 }
}

Вот код, который будет запускать бэкэнд-интеграцию чат-бота.

Листинг 11-3. Код бэкэнд-интеграции, который взаимодействует с SDK Dialogflow

//1) Эти системные переменные можно установить из командной строки с помощью --PROJECT_ID, --PORT и --LANGUAGE
const projectId = process.env.npm_config_PROJECT_ID;
const port = ( process.env.npm_config_PORT || 3000 );
const languageCode = (process.env.npm_config_LANGUAGE || 'en-US');

//2) Загрузить все библиотеки, необходимые для этого приложения
const socketIo = require('socket.io');
const http = require('http');
const cors = require('cors');
const express = require('express');
const path = require('path');
// Это специфично для Dialogflow
const uuid = require('uuid');
const df = require('dialogflow').v2beta1; // Используем v2beta1

//3) Создать приложение express
const app = express();

//4) Настроить Express и загрузить статические файлы и HTML-страницу
app.use(cors());
app.use(express.static(path.join(__dirname, '/../ui/'))); // Убедитесь, что путь правильный
app.get('/', function(req, res) {
 res.sendFile(path.join(__dirname, '/../ui/index.html')); // Убедитесь, что путь правильный
});

//5) Создать сервер и слушать переменную PORT
const server = http.createServer(app); // Передаем приложение Express
let io; // Объявляем io здесь

// Глобальные переменные для Dialogflow
let sessionClient;
let sessionPath;
let request = {}; // Инициализируем объект request

//6) Слушатель Socket.io, как только клиент подключится к сокету сервера
// затем выполнить этот блок.
io = socketIo(server); // Инициализируем Socket.IO с сервером
io.on('connect', (client) => {
 console.log(`Client connected [id=${client.id}]`);
 client.emit('server_setup', `Server connected [id=${client.id}]`);

 //7) Когда клиент отправляет события 'message'
 // затем выполнить этот блок
 client.on('message', async function(msg) {
  //console.log(msg);
  //8) Обещание выполнить сопоставление намерений
  const results = await detectIntent(msg);
  console.log(results);
  //9) Вернуть Dialogflow после сопоставления намерений в пользовательский интерфейс клиента.
  client.emit('returnResults', results);
 });

 // Обработка события 'welcome' от клиента
 client.on('welcome', async function() {
    const welcomeResults = await detectIntentByEventName('WELCOME'); // Используем событие WELCOME по умолчанию
    client.emit('returnResults', welcomeResults);
 });

});

/**
 * Настройка интеграции Dialogflow
 */
function setupDialogflow(){
 //10) Dialogflow понадобится идентификатор сеанса
 const sessionId = uuid.v4(); // Генерируем уникальный sessionId при настройке

 //11) Dialogflow понадобится клиент сеанса DF
 // Таким образом, каждый сеанс DF уникален
 sessionClient = new df.SessionsClient(); // Инициализируем sessionClient

 //12) Создать путь сеанса из клиента сеанса,
 // который является комбинацией projectId и sessionId.
 sessionPath = sessionClient.sessionPath(projectId, sessionId); // Используем глобальный projectId

 //13) Эти объекты находятся в запросе Dialogflow
 request = {
  session: sessionPath,
  queryInput: {}
 };
}

/*
 * Обнаружение намерения Dialogflow на основе текста
 * @param text - строка
 * @return обещание ответа
 */
async function detectIntent(text){
 //14) Получить высказывание пользователя из пользовательского интерфейса
 request.queryInput.text = {
  languageCode: languageCode,
  text: text
 };
 console.log(request);
 //15) Метод SDK Dialogflow для обнаружения намерений.
 // Он возвращает обещание, которое будет разрешено, как только
 // данные выполнения поступят.
 const responses = await sessionClient.detectIntent(request);
 return responses;
}

/*
 * Обнаружение намерения Dialogflow на основе события
 * @param eventName - строка
 * @return обещание ответа
 */
async function detectIntentByEventName(eventName){
 request.queryInput.event = {
  languageCode: languageCode,
  name: eventName
 };
 console.log(request);
 const responses = await sessionClient.detectIntent(request);
 // Удалить событие, чтобы событие приветствия не вызывалось снова
 delete request.queryInput.event;
 return responses;
}

// Запустить этот код.
setupDialogflow(); // Вызываем функцию настройки Dialogflow

server.listen(port, () => { // Запускаем сервер Express
 console.log('Running server on port %s', port);
});

Эти системные переменные можно установить из командной строки с помощью --PROJECT_ID, --PORT и --LANGUAGE.
Загрузите все библиотеки, необходимые для этого приложения, причем последние специфичны для Dialogflow.
Создайте приложение Express.
Настройте Express и загрузите статические файлы и HTML-страницу.
Создайте сервер и слушайте переменную PORT.
Слушатель Socket.IO, как только клиент подключится к сокету сервера, выполните этот блок.
Когда клиент отправляет события ‘message’, выполните этот блок.
Это содержит функцию для выполнения сопоставления намерений.
Как только результаты поступят, верните их в пользовательский интерфейс клиента.
Dialogflow понадобится уникальный идентификатор сеанса:
sessionId = uuid.v4();
Dialogflow понадобится клиент сеанса Dialogflow, чтобы сделать этот сеанс уникальным для своего пользователя:
sessionClient = new df.SessionsClient();
Создайте путь сеанса из клиента сеанса, комбинацию projectId и sessionId. Теперь сеанс будет принадлежать только вашему агенту Dialogflow.
sessionPath = sessionClient.sessionPath(projectId, sessionId);

Эти объекты находятся в запросе Dialogflow:

request = {
 session: sessionPath,
 queryInput: {
  text: { // Или event: {}
   languageCode: languageCode
   // text: text_input или name: event_name
  }
 }
}

Получите высказывание пользователя из пользовательского интерфейса.
Это метод SDK Dialogflow для обнаружения намерений. Он возвращает обещание, которое будет разрешено, как только данные выполнения поступят:
await sessionClient.detectIntent(request);

Рисунок 11-2 показывает, как это будет выглядеть.

Рисунок 11-2. Рабочая пользовательская интеграция чата в веб-браузере

Чтобы запустить этот пример из репозитория GitHub, который принадлежит этой книге, вам нужно будет перейти в папку back-end.

Оттуда установите необходимые библиотеки:

npm install

Запустите приложение Node:

npm --PROJECT_ID=[ваш-id-проекта-google-cloud] run start

Перейдите в браузере по адресу http://localhost:3000.

Приветственное сообщение

Частый вопрос, который я постоянно получаю от людей, реализующих свои собственные интеграции: как я могу убедиться, что мой чат-бот приветствует пользователя при открытии чата? Это не так уж сложно; мы можем вызывать события в Dialogflow, и мы сделаем это, как только Socket.IO установит правильное соединение с клиентом (что происходит после загрузки страницы). Обратите внимание на Листинг 11-4.

Добавьте в index.html внутри слушателя connect:

socketio.emit('welcome');

Затем в вашем бэкэнд-файле app.js, внутри слушателя connect, мы будем слушать сообщения welcome, отправленные из пользовательского интерфейса.

Листинг 11-4. Прослушивание приветственного сообщения

client.on('welcome', async function() {
 const welcomeResults = await detectIntentByEventName('welcome'); // Используем имя события 'welcome', можно изменить
 client.emit('returnResults', welcomeResults);
});

Следующая новая функция в Листинге 11-5 работает довольно похоже на вызов detectIntent из Листинга 11-3, но вместо передачи текстового ввода запроса мы будем использовать имя события.

Листинг 11-5. Обнаружение намерения по имени события

async function detectIntentByEventName(eventName){
 request.queryInput.event = {
  languageCode: languageCode,
  name: eventName
 };
 const responses = await sessionClient.detectIntent(request);
 //удалить событие, чтобы событие приветствия не вызывалось снова
 delete request.queryInput.event;
 return responses;
}

Какое имя события? Событие приветствия, так как наше намерение приветствия имеет это событие, прикрепленное к нему, что вы можете видеть на Рисунке 11-3.

Рисунок 11-3. Событие Welcome в Dialogflow

Создание расширенных ответов в вашей интеграции чат-бота

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

Давайте создадим несколько ответов с расширенными сообщениями в нашей интеграции.

Компонент гиперссылки, карта Google и компонент изображения

Сначала создайте новое намерение с обучающими фразами типа «У вас есть веб-адрес?»

Вам не нужно указывать текстовый ответ. Вместо этого вы создадите новую пользовательскую полезную нагрузку (custom payload), которая использует наш пользовательский JSON, как показано на Рисунке 11-4:

{
 "web": {
  "type": "hyperlink",
  "text": "Check My Website",
  "link": "http://www.leeboonstra.com"
 }
}

Рисунок 11-4. Пользовательская полезная нагрузка для пользовательского расширенного сообщения с гиперссылкой

В вашей бэкэнд-интеграции, после запуска метода detectIntent, вам нужно будет пройтись по массиву queryResult.fulfillmentMessages. Он должен содержать объект с сообщением, установленным в полезную нагрузку.

fulfillmentMessages: Array(1)
 0:
  message: "payload"
  payload:
   fields:
    platform: {stringValue: "custom-web", kind: "stringValue"}
    web: {structValue: {...}, kind: "structValue"}
    __proto__: Object
   __proto__: Object
  platform: "PLATFORM_UNSPECIFIED"
  __proto__: Object
 length: 1
 __proto__: Array(0)
fulfillmentText: ""

Совет: Вы заметили, что с объектом полезной нагрузки что-то странное? Он не содержит того же объекта JSON, что и введенный вами в консоли Dialogflow.

Это потому, что Google gRPC API использует буферы протокола (google.protobuf.Struct). Буферы протокола — это языково-нейтральный, платформенно-нейтральный, расширяемый механизм Google для сериализации структурированных данных.

Вам нужно будет преобразовать protobuf в JSON. В моем GitHub для этого примера я включил простой скрипт-конвертер.

Ваш бэкэнд-код должен вернуть результаты в пользовательский интерфейс. Ваш клиентский JavaScript будет проходить по всем результатам и представлять результаты на экране с пользовательским стилем. Рисунок 11-5 показывает, как это будет выглядеть.

Рисунок 11-5. Пример пользовательской интеграции с поддержкой расширенных сообщений

Реализация

Давайте рассмотрим полную реализацию расширенных сообщений для гиперссылок, Google Maps и изображений. Мы уже видели пример пользовательской полезной нагрузки с гиперссылкой; Листинг 11-6 показывает некоторые примеры изображения и Google Map.

Листинг 11-6. Пользовательская полезная нагрузка в консоли Dialogflow

{
 "web": {
  "type": "image",
  "alt": "Lee Boonstra",
  "src": "https://www.leeboonstra.com/images/profile.jpg"
 }
}
{
 "web": {
  "link": "https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d2437.7995043017927!2d4.869772751476948!3d52.33778327968087!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x47c60a05af168f5b%3A0x3e5bfe6e0b2ce441!2sGoogle+Amsterdam!5e0!3m2!1sen!2snl!4v1520965060384",
  "type": "map"
 }
}

Сразу после обещания detectIntent вы можете вызвать новый метод под названием getRichContent(), который передает в него разрешенные ответы обещания.

const responses = await sessionClient.detectIntent(request);
let data = getRichContent(responses);
return data;

Метод getRichContent выглядит так; см. Листинг 11-7.

Листинг 11-7. Метод getRichContent получает объект из protobuf

function getRichContent(responses){
 const result = responses[0].queryResult;
 let messages = [];
 if(result.fulfillmentMessages.length > 0) {
  for (let index = 0; index < result.fulfillmentMessages.length; index++) {
   const msg = result.fulfillmentMessages[index];
   if (msg.payload){
    // Преобразование protobuf Struct в JSON
    let data = structJson.structProtoToJson(msg.payload);
    // Предполагаем, что полезная нагрузка имеет ключ 'web'
    if (data && data.web) {
        messages.push(data.web);
    } else {
        // Обработка случая, когда 'web' отсутствует или data null/undefined
        console.log("Payload structure is not as expected or 'web' key is missing", data);
        // Можно добавить текстовое сообщение по умолчанию или пропустить
         if (msg.text && msg.text.text) {
             messages.push(msg.text.text[0]); // Добавляем первый текстовый ответ, если он есть
         }
    }
   } else {
    // Если нет полезной нагрузки, добавляем текстовое сообщение
    if (msg.text && msg.text.text) {
        messages.push(msg.text.text[0]); // Добавляем первый текстовый ответ
    }
   }
  }
  return messages;
 }
 return []; // Возвращаем пустой массив, если нет сообщений
}

Сначала он проверяет, содержит ли fulfillmentMessages массив, имеющий хотя бы один элемент. Возможно иметь несколько сообщений выполнения, например, текстовое сообщение и два расширенных сообщения, поэтому нам нужно будет пройтись по ним в цикле. Если сообщение содержит пользовательскую полезную нагрузку, нам нужно будет получить данные и преобразовать protobuf в JSON. В противном случае мы можем добавить текстовую версию в новый массив сообщений. Этот массив будет отправлен в пользовательский интерфейс. Технически, вы также могли бы создать HTML-разметку на этом месте, но будет лучше сделать это на фронтенде, чтобы ваш код фронтенд-интерфейса был хорошо отделен от вашего бэкэнд-кода.

Я использую этот небольшой скрипт-конвертер для работы с буферами протокола. Я могу конвертировать из JSON в Struct или из Struct в JSON. Вы можете найти этот скрипт в репозитории GitHub из этой книги. Последнее, что нам нужно: structProtoToJson(data.web);

Не забудьте включить файл в верхнюю часть вашего бэкэнд-кода app.js:

const structJson = require('../back-end/structToJson');

Вот код, который мы будем использовать в пользовательском интерфейсе. Мой index.html будет содержать следующий блок, как только данные будут получены Socket.IO. Посмотрите на Листинг 11-8.

Листинг 11-8. Проход по результатам для поиска типа пользовательской полезной нагрузки и отображения его прямо на экране

socketio.on('returnResults', function (data) {
 console.log(data);
 var objDiv = document.getElementById("ca"); // Получаем контейнер чата

 //d) Если есть результаты, то динамически
 // создать элементы списка для добавления к списку сообщений.
 if (data && data.length > 0) { // Проверяем, что data не пустой массив
  for (let index = 0; index < data.length; index++) {
   var e = data[index];
   var balloon = document.createElement("li"); // Создаем элемент li для каждого сообщения
   balloon.className = 'balloon agent'; // Присваиваем класс

   // Проверяем тип сообщения и создаем соответствующий HTML
   if (typeof e === 'object' && e !== null) { // Убедимся, что e - это объект
        if (e.type == 'hyperlink'){
         balloon.innerHTML = `<a href="${e.link}" target="_blank">${e.text}</a>`; // Добавляем target="_blank" для открытия в новой вкладке
        } else if (e.type == 'map') {
         balloon.innerHTML = `<iframe src="${e.link}" width="300" height="200" frameborder="0" style="border:0;" allowfullscreen="" aria-hidden="false" tabindex="0"></iframe>`; // Уменьшил размер для мобильных
        } else if (e.type == 'image') {
         balloon.innerHTML = `<img src="${e.src}" alt="${e.alt || 'Image'}" style="max-width: 100%; height: auto;" />`; // Добавил стили для адаптивности
        } else {
         // Если тип неизвестен, отображаем как текст (или JSON)
         balloon.innerHTML = JSON.stringify(e);
        }
   } else {
        // Если e - это просто строка (текстовое сообщение)
        balloon.innerHTML = e;
   }
   messages.appendChild(balloon); // Добавляем элемент в список сообщений
  }
  objDiv.scrollTop = objDiv.scrollHeight; // Прокручиваем вниз
 }
});

Он проверяет типы сообщений. Если тип — гиперссылка, то мы создадим тег anchor со ссылкой и текстом ссылки, предоставленными пользовательской полезной нагрузкой в консоли Dialogflow. Если тип — изображение, вы создадите тег image с src изображения и тегом alt, предоставленными пользовательской полезной нагрузкой в консоли Dialogflow. А когда это карта, то он будет использовать iframe с URL-адресом Google Maps, который был предоставлен пользовательской полезной нагрузкой в консоли Dialogflow.

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

Использование синтаксиса Markdown и условных шаблонов в ваших ответах Dialogflow

При работе с большими командами UX-дизайнер или копирайтер часто поддерживает разговор в консоли Dialogflow. Они хотят иметь контроль над стилем текста, не используя HTML-разметку в тексте, например, чтобы выделить определенные слова или отобразить гиперссылки.

При создании собственной интеграции интеграция поддержки markdown на самом деле очень проста.

Просто убедитесь, что ваш пользовательский интерфейс index.html включает библиотеку markdown, такую как Marked.

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

Ваши ответы на намерения теперь могут содержать синтаксис markdown, как показано на Рисунке 11-6:

**Ли** - *Адвокат разработчиков разговорного ИИ* в Google. В этой роли она фокусируется на *Dialogflow*, *Contact Center AI* и технологии *Speech*. Вот ее [веб-сайт](https://www.leeboonstra.com)

Рисунок 11-6. Использование текста markdown в текстовых полях ответа Dialogflow

Рисунок 11-7 показывает, как это будет отображаться на экране.

Рисунок 11-7. Пользовательская интеграция может обрабатывать markdown после импорта библиотеки Marked

Ветвление разговора

Помимо markdown, также возможно использовать шаблоны и условное ветвление из консоли Dialogflow.

Подумайте о Jinja (для разработчиков Python или Java), Smarty (PHP) или Jade/Pug, Handlebars и Mustache (для разработчиков JavaScript). Вот пример с библиотекой Pug.js (ранее известной как Jade). Она работает очень хорошо.

Хитрость здесь заключается в использовании настройки ответа с пользовательской полезной нагрузкой и использовании библиотеки шаблонизации, чтобы вы могли предоставлять читаемые шаблоны и переменные, которые могут быть вставлены. Обратите внимание на Листинг 11-9.

Листинг 11-9. Пример ветвления в консоли Dialogflow в виде пользовательской полезной нагрузки

{ "custom":
 {
  "locals": {
   "username": "$username"
  },
  "pug": [ "if username\n", " | Hello $username\n", "else\n", " | Hello stranger" ]
 }
}

Обучающая фраза, которая относится к этому примеру:

Меня зовут: Ли

Значения объекта locals — это значения параметров, которые были переданы как имя пользователя. В объекте pug я написал многострочный строковый шаблон с веткой if-else. При использовании Pug отступы строк имеют важное значение. Обратите внимание на код новой строки \n и | для использования обычного текста.

Мой бэкэнд-код интеграции должен будет включить библиотеку pub:

const pug = require('pug');

Пользовательская функция, которая может получить шаблон из пользовательской полезной нагрузки для компиляции его с переданными переменными. См. Листинг 11-10.

Листинг 11-10. Вспомогательная функция шаблона для компиляции для Pug

function templateHelper(payload) {
 var str = payload.custom.pug;
 if(Array.isArray(payload.custom.pug)) {
  str = payload.custom.pug.join("");
 };
 var fn = pug.compile(str);
 var text = fn(payload.custom.locals);
 return text;
}

После обнаружения намерения вам нужно будет только вызвать метод templateHelper с полезной нагрузкой. См. Листинг 11-11.

Листинг 11-11. Вызов метода templateHelper

io.on('connect', (client) => {
 console.log(`Client connected [id=${client.id}]`);
 client.emit('server_setup', `Server connected [id=${client.id}]`);

 client.on('message', async function(msg) {
  const results = await detectIntent(msg);
  var responseMsg = results[0].queryResult.fulfillmentText;

  // Проверяем, есть ли полезная нагрузка и содержит ли она 'custom'
  var payload = results[0].queryResult.fulfillmentMessages[0].payload;
  let data;
  if (payload) {
      data = structJson.structProtoToJson(payload); // Преобразуем protobuf в JSON
      console.log("Payload data:", data);
  }


  if (data && data.custom){ // Если есть пользовательская полезная нагрузка
   client.emit('returnResults', [templateHelper(data)]); // Используем templateHelper
  } else {
   // Если нет пользовательской полезной нагрузки или она не содержит 'custom', отправляем стандартный текст
   client.emit('returnResults', [responseMsg || ' ']); // Отправляем fulfillmentText или пустую строку
  }
 });
});

Как только придет сообщение, мы обнаружим намерение как обычно, но нам нужно будет проверить, содержат ли данные сопоставленного намерения полезную нагрузку, которая является пользовательской. Обратите внимание, что это protobuf, который сначала нужно будет преобразовать в объект JSON. Скрипт для этого можно найти в репозитории GitHub, который принадлежит этой книге. На основе этой пользовательской полезной нагрузки мы вызовем templateHelper и передадим данные полезной нагрузки. В противном случае мы просто вернем fulfillmentText в качестве ответного сообщения. См. результат на Рисунке 11-8.

Рисунок 11-8. Ветвление разговора в пользовательском интерфейсе через консоль Dialogflow

Создание интеграции для запуска агента Dialogflow в нативном мобильном приложении Android или iOS с помощью Flutter

Предыдущие разделы показали вам, как интегрировать Dialogflow в ваш веб-сайт или веб-приложение, создав фронтенд-интерфейс и бэкэнд-сервер. Если бы вы сделали этот веб-сайт адаптивным для мобильных устройств, он мог бы работать на мобильном устройстве. Однако, возможно, вы заинтересованы в интеграции агента Dialogflow в нативное мобильное приложение. Именно здесь на помощь приходит технология Google, Flutter.

Flutter — это набор средств разработки пользовательского интерфейса с открытым исходным кодом, созданный Google. Он используется для разработки приложений для Android, iOS, Linux, Mac, Windows и веба из единой кодовой базы (Dart). С помощью Flutter вы можете быстро разрабатывать приложения, так как он может выполнять горячую перезагрузку изменений при сохранении кода. Flutter поставляется с богатым набором настраиваемых виджетов для создания нативных пользовательских интерфейсов с нативной производительностью, так как он компилируется в нативный машинный код ARM с использованием нативных компиляторов Dart. Как и npm для Node.js, Dart и Flutter имеют свой собственный менеджер пакетов, управление пакетами pub.dev, позволяющее вам загружать предварительно созданные пакеты Flutter и интегрировать их в ваше приложение.

Две техники интеграции Dialogflow в приложение Flutter

Существует две техники интеграции агента Dialogflow в приложение Flutter. Оба решения будут иметь свои плюсы и минусы, и вам решать, какое решение лучше всего подходит для вашего бизнеса.

Первое решение самое очевидное: использование пакета Dialogflow, интеграция SDK Dialogflow непосредственно в ваш (мобильное приложение) клиент. Другое решение — включить SDK Dialogflow в бэкэнд-серверное приложение и позволить вашему (мобильному приложению) клиенту разговаривать с бэкэндом по HTTP(s).

Создавая его непосредственно во Flutter, вам нужно будет написать кодовую базу только один раз. Как предприятие, у вас либо будет опыт работы с Dart/Flutter внутри компании, либо вы наймете фрилансера или агентство для создания приложения для вас. С Flutter 2 вы даже можете поддерживать настольные и веб-приложения вместо только приложений для Android и iOS. Однако вам нужно будет разработать решение для безопасного обслуживания и хранения сервисных аккаунтов и ключей API Google Cloud.

Внимание: Хранение сервисного аккаунта в папке ресурсов клиента (или даже в безопасном хранилище ключей клиента) может быть опасным, если с этим не обращаться должным образом. Прежде всего, вам нужно быть очень осторожным с вашими сервисными аккаунтами. Какие права на чтение и доступ вы предоставите своим компонентам? Когда вы предоставляете права администратора вычислительному движку Google Cloud, вы можете представить, что злоумышленники могут взломать и декомпилировать ваше приложение. Когда они получат доступ к вашему вычислительному движку, они могут привести вас к расходам, например, майня биткойны для них. Теперь, даже когда вы не предоставляете права доступа к вычислениям вашим сервисным аккаунтам Google Cloud, вы все равно не будете раскрывать свои ключи. Даже если для Dialogflow это дает доступ только к вашему чат-боту в вашем проекте, злоумышленники могут прочитать данные PII из истории чата, если ваши конечные пользователи делились данными PII в чате. Это может быть огромной проблемой.

Кроме того, не так просто изменить ключи сервисного аккаунта в приложениях, так как вы не хотите, чтобы приложение перестало работать для текущих пользователей. Так как же можно безопасно обслуживать сервисные аккаунты и ключи в мобильных клиентах? Например, создав механизм для ротации (второго набора) ключей. Например, работая с веб-токенами JSON (JWT), интернет-предлагаемым стандартом для создания данных с необязательной подписью и необязательным шифрованием, полезная нагрузка которого содержит JSON, утверждающий некоторое количество утверждений. Токены подписываются либо с помощью частного секрета, либо с помощью открытого/закрытого ключа. Или вы можете запускать части вашей интеграции на сервере.

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

Еще одним существенным преимуществом такого подхода является то, что вы хотите создать платформу чата/голосовой связи, которая должна поддерживать различные каналы интеграции. Для создания многоканального или омниканального опыта это правильный подход, так как вам нужно поддерживать интеграцию Dialogflow только в одном месте, рассматривая каждую интеграцию как свой собственный канал. При желании вы даже можете построить его так, чтобы можно было переключаться между агентами Dialogflow Essentials и Dialogflow CX. Давайте рассмотрим оба решения.

Интеграция SDK Dialogflow непосредственно в ваше приложение Flutter

При поиске Dialogflow на pub.dev вы найдете много пакетов Dialogflow Flutter с открытым исходным кодом, включая мой: dialogflow_grpc. Пакет Dialogflow gRPC использует библиотеку gRPC для Dialogflow. Только с библиотекой gRPC возможно выполнять потоковую передачу, если вы хотите использовать встроенные возможности Dialogflow Speech to Text и Text to Speech. Кстати, базовый API gRPC также быстрее, чем REST API, который часто используется для интеграции Dialogflow с Dart и Flutter.

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

Отредактируйте файл pubspec.yaml с зависимостью dialogflow_grpc. И укажите на ваш сервисный аккаунт (например, assets/credentials.json), как показано в Листинге 11-12.

Листинг 11-12. pubspec.yaml

dependencies:
 flutter:
  sdk: flutter
 dialogflow_grpc: any # Укажите конкретную версию или 'any' для последней

# Следующий раздел специфичен для Flutter.
flutter:
 uses-material-design: true
 assets:
  - assets/credentials.json # Убедитесь, что путь правильный

Импортируйте этот пакет в свой код. Загрузите свой сервисный аккаунт и создайте экземпляр DialogflowGrpc; см. Листинг 11-13.

Листинг 11-13. Загрузка сервисного аккаунта

import 'package:dialogflow_grpc/v2beta1.dart';
// import 'package:dialogflow_grpc/generated/google/cloud/dialogflow/v2beta1/session.pb.dart'; // Не используется напрямую в этом примере
import 'package:dialogflow_grpc/dialogflow_auth.dart';
import 'package:flutter/services.dart' show rootBundle; // Для загрузки из assets

// ... внутри вашего виджета или класса состояния ...

DialogflowGrpc? dialogflow; // Сделайте nullable или инициализируйте позже

@override
void initState() {
  super.initState();
  _initDialogflow(); // Вызов асинхронной инициализации
}

Future<void> _initDialogflow() async {
  // Загрузка сервисного аккаунта из assets
  final serviceAccountJson = await rootBundle.loadString('assets/credentials.json');
  final serviceAccount = ServiceAccount.fromString(serviceAccountJson);

  // Создание экземпляра DialogflowGrpc
  dialogflow = DialogflowGrpc.viaServiceAccount(serviceAccount);
  // Теперь dialogflow готов к использованию
}

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

var data = await dialogflow.detectIntent(text, 'en-US');
print(data.queryResult.fulfillmentText);

Листинг 11-14 показывает, как вы можете обнаружить намерение на основе аудиопотока. Интеграция потоковой передачи аудио требует работы с компонентом микрофона в вашем приложении Flutter. Обычно на pub.dev будет доступно несколько компонентов микрофона с открытым исходным кодом. Имейте в виду, что библиотеки микрофонов Flutter являются обертками вокруг нативных аппаратных компонентов. Таким образом, реализации могут отличаться на разных устройствах (Android, iOS, Web, macOS или Windows).

Листинг 11-14. Потоковая передача аудио в Dialogflow

// 1) Создаем список смещения для распознавания речи
var biasList = SpeechContextV2Beta1(
 phrases: [
  'Dialogflow CX',
  'Dialogflow Essentials',
  'Action Builder',
  'HIPAA'
 ],
 boost: 20.0
);

// 2) Настраиваем конфигурацию аудиовхода
var config = InputConfigV2beta1(
 encoding: 'AUDIO_ENCODING_LINEAR_16', // Убедитесь, что кодировка соответствует вашему источнику аудио
 languageCode: 'en-US',
 sampleRateHertz: 16000, // Убедитесь, что частота дискретизации соответствует вашему источнику аудио
 singleUtterance: false, // false для потоковой передачи
 speechContexts: [biasList] // Применяем список смещения
);

// 3) Выполняем вызов потокового обнаружения намерения
// _audioStream должен быть Stream<List<int>> из вашего компонента микрофона
final responseStream = dialogflow!.streamingDetectIntent(config, _audioStream); // Используем non-null assertion operator (!) после проверки

// Слушаем поток ответов
responseStream.listen((data) {
 // Обрабатываем данные ответа от Dialogflow
 print(data);
 // Например, отображаем промежуточную транскрипцию или результат намерения
 if (data.recognitionResult != null) {
  print('Intermediate transcript: ${data.recognitionResult.transcript}');
 }
 if (data.queryResult != null) {
  print('Detected intent: ${data.queryResult.intent.displayName}');
  print('Fulfillment text: ${data.queryResult.fulfillmentText}');
 }
});

Вы можете создать список смещения распознавания речи, чтобы придать определенным словам усиление. Это имеет смысл в тех случаях, когда ваша модель речи, кажется, не понимает вас. (См. Главу 7 для получения более подробной информации об адаптации речи.)
Здесь вы аннотируете вашу конфигурацию аудио, и это зависит от оборудования устройства, которое вы используете. Например, ваш телефон может использовать кодировку AUDIO_ENCODING_LINEAR_16 и 16000 герц. Вам также нужно будет указать язык, который вы перечисляете, и хотите ли вы обнаружить одно высказывание. По умолчанию (что установлено на false), распознавание не прекращается до тех пор, пока клиент не закроет поток. Если true, распознаватель обнаружит одно произнесенное высказывание во входном аудио. Наконец, вы хотите указать список смещения.
Сделайте вызов streamingDetectIntent с указанным InputConfig и аудиопотоком. Такой аудиопоток вы можете получить из компонента микрофона.

Следующая глава подробнее расскажет о потоковой передаче аудио в Dialogflow.

Рисунок 11-9 показывает пример приложения Flutter с компонентами Flutter UI, которое интегрирует пакет Dialogflow gRPC в ваше приложение. Пакет Flutter gRPC поставляется с полнофункциональным демо-приложением потоковой передачи аудио для мобильных устройств.

Рисунок 11-9. Демо-приложение, интегрирующее пакет Dialogflow gRPC в приложение Flutter UI

Приложение Flutter, которое взаимодействует с бэкэнд-приложением SDK Dialogflow

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

Рисунок 11-10. Пример архитектуры для создания платформы ботов, поддерживающей несколько каналов

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

Бэкэнд-сервер существует как серверный компонент. Например, в приложении Node.js сервер может использовать библиотеку Express npm. Google Assistant может отправлять POST-запросы на https://www.example.com/app/googleassistant; приложение Flutter может отправлять POST-запросы на https://www.example.com/app/mobile; и так далее.

Сервер может маршрутизировать все входящие (Ajax) сообщения посреднику канала. Это промежуточное ПО заботится об интеграции различных SDK. Например, промежуточное ПО Google Assistant будет интегрироваться с Actions on Google, промежуточное ПО телефона и WhatsApp будет интегрироваться с Twilio, веб-сайт Angular и приложение Flutter будут создавать представления для возврата вручную.

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

При построении такой архитектуры не забудьте создать архитектуру конвейера данных аналитики. Глава 13 описывает, как это сделать.

Резюме

Эта глава содержит информацию о создании ваших собственных интеграций. Вы узнаете следующие задачи:

Вы хотите создать чат-бота на своем собственном веб-сайте с помощью SDK Dialogflow и WebSockets.
Вы хотите интегрировать расширенные ответы, такие как карточки, изображения, гиперссылки или Google Maps, в вашу пользовательскую интеграцию веб-чата.
Вы хотите использовать синтаксис markdown в вашей интеграции чат-бота и выполнять ветвление.
Вы хотите интегрировать SDK Dialogflow в мобильное приложение с помощью Flutter для создания нативных приложений для Android, iOS, Windows, MacOS или веб-чатов.
Вы хотите создать многоканальную платформу ботов, создав бэкэнд-интеграцию.

Если вы хотите создать этот пример, исходный код для этой книги доступен на GitHub через страницу продукта книги, расположенную по адресу www.apress.com/978-1-4842-7013-4. Ищите папки custom-integration-web, custom-integration-markdown и custom-integration-rich-messages.

Дополнительные материалы

Метод SDK Dialogflow для обнаружения намерения
https://cloud.google.com/dialogflow/es/docs/reference/rest/v2/projects.agent.sessions/detectIntent
SDK Dialogflow по QueryInput выглядит так
https://cloud.google.com/dialogflow/es/docs/reference/rest/v2/QueryInput
Пример реального подхода к чат-боту, интегрированному в веб-сайт
https://github.com/savelee/kube-django-ng
Документация SDK по QueryResults
https://cloud.google.com/dialogflow/es/docs/reference/rest/v2/DetectIntentResponse#queryresult
Дополнительная информация о буферах протокола
https://developers.google.com/protocol-buffers
Библиотека MarkedJS для разрешения синтаксиса markdown в вашей пользовательской веб-интеграции
https://github.com/markedjs/marked
Библиотека Pug.js для поддержки условных шаблонов в вашей пользовательской веб-интеграции
https://www.npmjs.com/package/pug
Flutter
https://flutter.dev
Пакет Dialogflow gRPC
https://pub.dev/packages/dialogflow_grpc
Узнайте больше об интеграции gRPC и создании вашего собственного пакета Flutter
https://www.leeboonstra.dev/apis/dialogflow_flutter_grpc/

Предыдущая глава Следующая глава