Конфигурационный файл chatbot.yaml

chatbot.yaml — конфигурационный файл чат-бота. Файл содержит основную информацию о конфигурации проекта, например:

• имя главного файла сценария;
• данные о подключаемых зависимостях;
• конфигурацию NLU;
• перечень файлов с тестами.

В данном разделе перечислены настройки, которые можно задать в chatbot.yaml, и их назначение.

Подробнее о синтаксисе YAML

Точка входа в сценарий

entryPoint: main.sc

Поле используется для указания файла, с которого начинается загрузка сценария чат-бота при публикации. Файл должен находиться в папке src и обычно называется main.sc или entryPoint.sc.

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

entryPoint — обязательное поле.

Имя бота

name: zb-cailapub

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

Настройки NLU

Диалоговый движок

botEngine: v2

Поле задает версию диалогового движка бота.

Движок второй версии v2 позволяет использовать для понимания естественного языка (NLU) сервис CAILA. Это рекомендуемое значение поля для всех новых проектов.

Если поле отсутствует или значение поля отличается от v2, будет использован движок первой версии v1. NLU на этом движке возможен только при помощи паттернов и групп примеров.

Язык бота

language: ru

Поле задает язык, на котором общается бот. Значение поля должно быть ISO-кодом нужного языка.

На второй версии диалогового движка поле является обязательным.

Пороговые значения классификатора

sts:
  noMatchThreshold: 0.2
caila:
  noMatchThreshold: 0.2

Поля noMatchThreshold используются только на второй версии диалогового движка и задают пороговое значение для гипотез классификатора. Рассмотрим его поведение:

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

Таким образом, noMatchThreshold задает минимальную похожесть запроса на один из классов. Чем ближе его значение к 1, тем строже классификатор и тем более точные требуются совпадения.

Было эмпирически определено, что оптимальное значение этого параметра — 0.2.

Поле noMatchThreshold в секции sts задает пороговое значение для классификатора на примерах, а в секции caila — для NLU-сервиса CAILA.

Длина $context.nBest

nlp:
  nbest: 3
  nbestPatterns: 1
  nbestIntents: 2
  nbestExamples: 3

Поля семейства nlp.nbest задают число правил активации, к которым можно получить доступ из сценария через объект $context.

• Поле nbest задает длину $context.nBest — массива сработавших для запроса правил активации всех типов: паттернов, интентов и примеров. Значение по умолчанию — 1.
• Поле nbestPatterns задает длину $context.nBestPatterns — массива правил активации, сработавших только при помощи паттернов. Если поле не указано, то этот массив недоступен.

nbestIntents и nbestExamples работают аналогично для интентов и примеров.

Подробнее об использовании $context.nBest

Ограничения при обработке запроса

Ограничение на длину запроса

nlp:
  lengthLimit:
    enabled: true
    symbols: 100
    words: -1

Секция nlp.lengthLimit задает ограничение на длину запросов, которые принимает бот:

• enabled включает или выключает проверку.
• symbols — максимальное количество символов в запросе.
• words — максимальное количество слов в запросе. Если указано -1, эта проверка не производится.

По умолчанию включено ограничение на 400 символов, ограничение на количество слов отключено.

Если запрос превысит одно из ограничений, в сценарии возникнет событие lengthLimit.

Ограничение на время обработки запроса

nlp:
  timeLimit:
    enabled: true
    timeout: 500

Секция nlp.timeLimit задает ограничение на общее время, в течение которого будет обработан запрос:

• enabled включает или выключает проверку.
• timeout — максимальное время обработки запроса в миллисекундах.

По умолчанию ограничение включено со значением таймаута 10000 (10 секунд).

Если запрос превысит ограничение, в сценарии возникнет событие timeLimit.

XML-тесты

tests:
  include:
    - "authorization.xml"
    - "integration-tests/*.xml"
  exclude:
    - "broken.xml"
  caseSensitive: false

XML-тесты сценариев позволяют проверить логику чат-бота, эмулируя запросы клиента и проверяя ответы от бота. Тесты выполняются автоматически при публикации.

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

По умолчанию выполняются все тесты из файлов в папке проекта test. Это поведение можно переопределить в секции tests, задав значения для подсекций include и/или exclude:

• include — будут выполнены тесты только из тех файлов, которые попадают под шаблоны, перечисленные в этой подсекции.
• exclude — из выполнения будут исключены все файлы, которые попадают под шаблоны, перечисленные в этой подсекции.

Шаблоны используют синтаксис Apache Ant.

Поле caseSensitive определяет, должны ли шаблоны учитывать регистр названий файлов. Значение по умолчанию — true.

Зависимости

dependencies:
  - name: common
    type: git
    url: https://<repository>
    version: heads/master

Секция dependencies позволяет задать список зависимостей проекта.

Подробнее о зависимостях

Сообщения об ошибках

messages:
  onError:
    locales:
      ru: Что-то пошло не так.
      en: Failed on request processing.
    defaultMessage: Что-то пошло не так.
    # defaultMessages:
    #   - Извините, что-то сломалось.
    #   - Произошла ошибка при обработке запроса.

Секция messages.onError позволяет задать текст сообщения, которое бот отправит при возникновении какой-либо ошибки.

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

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

Если секция messages.onError не заполнена, то в случае возникновения ошибки бот не ответит клиенту.

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

Injector

injector:
  catchAllLimit: 10
  api:
    protocol: https
    host: example.com
    port: 443

Секция injector позволяет задать параметры конфигурации чат-бота. Заданные параметры будут доступны в скриптах чат-бота через переменную $injector.

Подробнее об $injector

Другие настройки

Возможность изменения запроса

nlp:
  modifyRequestInPreMatch: true

Поле nlp.modifyRequestInPreMatch включает возможность изменять содержимое запроса в обработчике preMatch — например, редактировать текст запроса.

Токенизация слов в паттернах

tokenizeWordsInPatterns: true

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

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

Порядок загрузки файлов

scenarioLoadStrategy: v2

Поле scenarioLoadStrategy задает порядок загрузки файлов в сценарий, состоящий из множества файлов. Поле имеет два возможных значения: v1 (значение по умолчанию) и v2. При стратегии v1 загрузка производится в порядке сверху вниз по дереву импортируемых файлов, а при v2 — снизу вверх.

Рассмотрим пример. В файл main.sc при помощи тега require импортируются файлы r1.sc, r2.sc и r3.sc, в файлы r1.sc и r2.sc также импортируются по два файла. При публикации сценария файлы будут загружены в порядке, приведенном на изображении.