Импорт и экспорт данных из базы

Форматы хранения и представления данных

Через интерфейс чат-бота текущие данные проекта можно получить через выгрузку/export их в виде архивной копии. Эту операцию можно выполнить в разделе Настройки выбранного проекта и вкладке Импорт/Экспорт. Для каждого из проектов данные выгружаются отдельно.

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

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

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

• экспорт входящих высказываний - плагин позволяет экспортировать входящие высказывания в файл. После экспорта формируется zip-архив, содержащий пакет данных цифрового ассистента. Имя пакета имеет следующий формат. Сначала идет наименование проекта (например, проект Maria), затем идет дата/время формирования архива с данными 'yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffZ'. Внутри архива содержится следующая структура файлов и каталогов.

Рассмотрим более подробно структуру архива и назначение каждого их файлов.

Так, в папке чат-бота хранятся 4 файла формата yaml: analyticsconfig.yml, btconfig.yml, default-domen.yml, widgetsettings.yml, Analyticsconfig.yml содержит информацию о панели инструментов по умолчанию. Btconfig.yml содержит название проекта, язык по умолчанию, хост, ID проекта и его токен. Default-domain.yml включает в себя названия существующих слотов (slots), действий (actions) и сущностей (entities). Widgetsettings определяют тип данных и интерфейс для полей ввода.

В папке data существует еще две папки nlu и stories. В nlu видно, что есть еще 2 файла: en.json и ru.yml. En.json включает в себя модули, использованные для понимания естественного языка. Ru.yml содержит список намерений, которые можно редактировать прямо в файле и импортировать со всем проектом в чат-бот.

В разделе истории (stories) указаны примеры диалогов, на которых бот учится правильно реагировать в зависимости от предыстории разговора. Каждый диалог находится в отдельном файле формата yaml. История состоит из списка пронумерованных "токенов", фиксированного "словаря", состоящего из намерений (intent) человека и действий (action) бота.

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

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

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

Config-ru.yml, config-en.yml - файлы конфигурации определяют компоненты и политики, которые ваша модель будет использовать для прогнозирования на основе пользовательского ввода. Ключ рецепта позволяет использовать различные типы конфигурации и архитектуры модели. Ключи языка и конвейера определяют компоненты , используемые моделью для прогнозирования NLU. Ключ политик определяет политики, используемые моделью для прогнозирования следующего действия.

YAML

Rasa использует YAML(«Yet Another Markup Language» — «Ещё один язык разметки») как унифицированный и расширяемый способ управления всеми обучающими данными, включая данные NLU, истории и правила.

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

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

1. Rasa NLU или Natural language understanding (понимание естественного языка). Встроенные в Rasa алгоритмы NLU отвечают за определение намерения и извлечение сущностей. Как правило, для того, чтобы прописать намерения и все относящиеся к ним примеры, создается файл с названием "nlu.yml" (при инициализации бота такой файл создается автоматически и уже содержит примеры для обучения).

Пример nlu.yml:

version: "2.0"

nlu:
- intent: приветствие
  examples: |
    - привет
    - здравствуйте
    - добрый день
    - доброе утро
    - добрый вечер
    - приветствую
    - здарова
    - йо

- intent: прощание
  examples: |
    - пока
    - до свидания
    - до встречи
    - всего доброго

А что, бот понимает текст на русском? Не совсем. Вот что примерно происходит под капотом:

• Встроенный в Rasa алгоритм преобразует примеры для намерений в вектора через bag of words, они подаются на вход нейросетям:

Таким образом, после обучения каждому намерению будет поставлен в соответствие некий вектор.

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

2. Rasa stories: истории диалогов чат-бота с пользователями в виде намерение - действие.

Истории диалогов обычно фиксируются следующим образом:

stories:
 - story: Спрашивает как дела, если пользователь поздоровался
steps:
 - intent: приветствие
 - action: utter_приветствие
 - action: utter_как_дела

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

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

То, как именно должен ответить ассистент можно прописать в файле "domain.yml" или (что чуть-чуть сложнее) с помощью функции на python (actions.py). Рассмотрим первый вариант, определение реакции в DOMAIN с ключевым словом "utter":

responses:
  utter_приветствие:
  - text: "Привет, человек!"
  utter_как_дела:
  - text: "Как дела?"

Еще один пример типичной истории диалога с примерами выделенных ботом сущностей в квадратных скобках:

stories:
- story: A basic story test
 steps:
 - user: |
    привет
   intent: приветствие
 - action: utter_определение_местоположения
 - user: |
    в [Paris]{"entity": "location"}
   intent: информирование
 - action: utter_спрашивание_цены

3. Rasa actions: набор действий, которые может предпринимать бот, например, вызов API, отправка изображения или текстовый ответ. Есть ряд дефолтных действий для чат-бота, например, вернуться в начальную точку диалога, на каком шаге не находился бы бот или ожидать пользовательского сообщения. Действие также можно кастомизировать в виде функций на python.

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

- rule: Всегда прощаться, если пользователь прощается
 steps:
 - intent: прощание
  action: utter_прощание

В RASA существует два формата данных для обучения: JSON и Markdown. Во многих учебниках описывается JSON формат, но с этим форматом не удобно работать без дополнительных программных средств. С увеличением обучаемых данных будет все сложнее вносить изменения в JSON файл, поэтому мы будем работать с форматом markdown.

Сейчас нам необходимо решить что наш бот будет делать и что он будет понимать.

Преобразовать формат данных

Markdown - это, пожалуй, самый безопасный выбор для начинающих при создании данных. Однако может быть случай, когда обучающие данные автоматизированы или получены из другого источника, такого как формат данных LUIS, формат данных WIT, формат данных Dialogflow и json. Rasa также предоставляет вам способ для преобразования формата данных. Убедитесь, что виртуальная среда активирована, и выполните следующую команду (она преобразует md в json):

rasa data convert nlu --data data/nlu.md --out data/nlu.json -f json

1. --данные путь к файлу или каталогу, содержащему RLA NLU данные.

2. --вне Имя файла для сохранения тренировочных данных в формате Rasa.

3. -f является выходным форматом, данные обучения должны быть преобразованы. Принимает либо JSON или MD.

Когда у вас есть все необходимые данные, переместите их в данные папку и удалите все существующие.

Импорт/экспорт данных через интерфейс

Импорт проекта Rasa или Rasa X

Вы можете легко импортировать проект Rasa или Rasa X в Bot.Kloud.One. Перейдите в меню "Настройки" (левая боковая панель), выберите "Импорт/экспорт", "Импорт" и загрузите необходимые файлы.

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

Экспорт в Rasa или Rasa X

Вы можете экспортировать диалоги, созданные с помощью чат-бота, в существующий проект Rasa / Rasa X. Перейдите в меню "Настройки", выберите "Импорт/экспорт", затем "Экспорт".

Когда вы экспортируете проект, ссылки и ветви сохраняются в файлах 'md', поэтому вы можете повторно импортировать эти файлы и сохранить.

Вы получите zip-файл, содержащий все необходимые файлы:

awesome-project
|- data/
|--- nlu.md
|--- stories.md
|- config.yml
|- credentials.yml
|- domains.yml
|- endpoints.yml

Взаимодействие с GitHub

Управление версиями в Bot.Kloud.One обрабатывается git. Каждый проект может быть подключен к ветви репозитория git, что позволяет отправлять изменения и возвращаться к предыдущим версиям.

Устанавливаем и настраиваем Git

Windows. Скачайте Git для Windows, запустите exe-файл, следуйте инструкциям.

macOS. Скачайте Git для macOS и запустите dmg-файл. Если он не запускается, зайдите в Системные настройки — Безопасность и нажмите кнопку Open anyway (Всё равно открыть).

Linux. Установите Git через встроенный менеджер пакетов. Если у вас Ubuntu, используйте команду sudo apt-get install git. Команды для других дистрибутивов можно посмотреть здесь.

Как проверить, что Git установился

Откройте терминал и введите команду

git --version

Если Git установлен, то вы увидите номер версии, например, 2.35.1.

Настраиваем Git

Теперь нужно ввести имя и адрес электронной почты, чтобы ваши действия в Git были подписаны, а ещё для привязки к GitHub.

Добавить имя (введите его внутри кавычек): git config --global user.name "ваше имя"

Добавить электронную почту (замените email@example.com на вашу почту): git config --global user.email email@example.com

Опция --global значит, что имя и почта будут использоваться для всех ваших действий в Git. Если вы хотите менять эту информацию для разных проектов, то вводите эти же команды, только без опции --global.

Регистрируемся на GitHub

GitHub (или Гитхаб) — веб-сервис на основе Git, который помогает совместно разрабатывать IT-проекты. На Гитхабе разработчики публикуют свой и редактируют чужой код, комментируют проекты и следят за новостями других пользователей.

Профиль на Гитхабе и все проекты в нём — ваше публичное портфолио разработчика, поэтому нужно завести профиль, если у вас его ещё нет.

1. Зайдите на сайт https://github.com и нажмите кнопку Sign up.

2. Введите имя пользователя (понадобится в дальнейшей работе), адрес электронной почты (такой же, как при настройке Git) и пароль.

3. На почту придёт код активации — введите на сайте.

4. Появится окно с выбором тарифного плана. Если вы пользуетесь Гитхабом для учёбы, то укажите, что профиль нужен только для вас и вы студент.

5. Опросы и выбор интересов можно пропустить.

На этом всё — вы зарегистрировались и у вас есть собственный профиль.

Создание репозитория

1. Нажмите на кнопку Create repository(Создать репозиторий)
2. Введите название репозитория в поле ввода Repository name(Название репозитория) и нажмите кнопку "Create repository".

Настройка репозитория

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

Обратите внимание, что ключи SSH, хранящиеся в Bot.Kloud.One, не шифруются и видны любому пользователю с разрешением git-credentials:r в области проекта.

Устанавливаем SSH-ключи

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

SSH — протокол для безопасного соединения между компьютерами.

SSH-ключ состоит из двух частей — открытого и закрытого ключа. Открытый ключ мы отправляем на сервер. Его можно не прятать от всех и не переживать, что кто-то его украдёт, потому что без закрытого ключа он бесполезен. А вот закрытый ключ — секретная часть, доступ к нему должен быть только у вас. Это важно.

Мы будем подключаться к GitHub по SSH. Это работает так:

1. Вы отправляете какую-то информацию на GitHub, который знает ваш открытый ключ.
2. GitHub по открытому ключу понимает, что вы это вы, и отправляет что-то в ответ.
3. Только вы можете расшифровать этот ответ, потому что только у вас есть подходящий закрытый ключ.

А чтобы подключиться к GitHub с помощью SSH-ключа, сначала нужно его создать.

Создание ключа SSH

Для создания ключа SSH для linux/macOS откройте окно терминала на компьютере и введите команду. Команда -C позволяет добавить комментарий, который поможет отслеживать ваши ключи.

ssh-keygen -C "Comment"

При появлении запроса введите имя файла и нажмите клавишу Enter.

Затем введите и повторно введите парольную фразу.

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

В каталоге, где вы создали свои ключи, появятся два новых файла: key-name и key-name.pub. Первый файл содержит закрытый ключ, а второй — открытый ключ.

В результате создаётся новый SSH-ключ, привязанный к вашей электронной почте.

Создание ключа по шагам:

Добавление ключа SSH в репозиторий Github

Откройте репозиторий git в Github.

Перейдите в раздел Параметры -> Развернуть ключи.

Щелкните Добавить ключ развертывания.

Введите заголовок и скопируйте открытый ключ из ФАЙЛА .pub в текстовое поле Ключ.

Убедитесь, что установлен флажок Разрешить доступ на запис, чтобы чат-бот мог отправлять данные.

Нажмите кнопку Сохранить, чтобы добавить этот ключ в репозиторий.

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

Подключение чат-бота к git

Откройте проект в чат-боте и перейдите в раздел Настройки -> учетные данные Git.

Скопируйте строку подключения git в поле репозитория git, а затем где — имя существующей ветви в репозитории, которую чат-бот будет использовать для хранения текущего проекта. #<branch-name><branch-name>

Ключ SSH состоит из двух файлов, один с открытым ключом, а другой с закрытым ключом. Скопируйте текст из PUB-файла в открытое поле, а текст из другого файла — в закрытое поле.

Нажмите кнопку Сохранить, чтобы сохранить свои учетные данные. Вид после сохранения:

Чтобы убедиться, что вы подключены к git, вернитесь на экран историй и убедитесь, что кнопка git видна на верхней панели.

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

Использование интеграции git

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

Фиксация и отправка

Чтобы сохранить изменения в подключенном репозитории, нажмите на опцию Фиксировать и применить в выпадающем списке git button.

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

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

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

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

Возврат к предыдущему

Чтобы вернуться к предыдущей версии вашего проекта, нажмите на опцию Вернуться к предыдущему в раскрывающемся списке кнопки git.

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

Если проект содержит какие-либо несохраненные изменения, он сохранит их с сообщением фиксации перед возвратом к выбранной фиксации. Project state before revert to <commitId>