Клиентские сущности

подсказка

Клиентские сущности — сущности, которые может персонализировать сам клиент во время диалога с ботом. При этом содержание сущности будет доступно только для самого клиента.

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

Использование клиентских сущностей доступно в сценарии бота, интентах и слот-филлинге.

подсказка

Подробнее о работе с сущностями в сценарии

Быстрый старт

Рассмотрим работу с клиентскими сущностями на примере сценария со слот-филлингом. Бот будет добавлять контакты клиента в записную книжку и назначать встречи. При этом у каждого клиента бота будет персонализированная записная книжка.

Заполнение сущности

Создайте сущность @Contact. Нажмите клиентская под названием сущности для того, чтобы её значения были уникальны для каждого клиента. Заполнение сущности будет происходить в ходе диалога.

Заполнение интентов

Далее перейдем к созданию интентов. Создайте и заполните интент добавления контакта в записную книжку AddContact следующими образом:

Интент AddContact активируется, когда клиент хочет создать новую запись в записной книжке. Здесь мы используем слот-филлинг для заполнения слотов номера телефона и имени контакта.

Слоты будут заполняться при помощи системных сущностей @duckling.phone-number и @pymorphy.name. Проверьте, что эти сущности активны.

Создайте и заполните интент добавления контакта в записную книжку Meeting следующим образом:

Интент Meeting активируется, когда клиент хочет назначить встречу с уже созданным контактом. Обратите внимание, что в тренировочных фразах мы добавляем ссылку на клиентскую сущность @Contact, созданную ранее.

Сценарий

Сценарий бота:

require: slotfilling/slotFilling.sc
  module = sys.zb-common
theme: /

    state: Start                                            # старт сценария
        q!: $regex</start>
        a: Я умею добавлять контакты в записную книжку

    state: AddContact                                       # добавление контакта
        intent!: /AddContact
        script:
            $caila.addClientEntityRecords("Contact", [{"type": "synonyms", "rule": [$parseTree._Имя], "value": $parseTree._Номер}]);
        a: Отлично, добавил контакт {{$parseTree._Имя}} с номером {{$parseTree._Номер}}

    state: Meeting                                         # создание встречи с добавленным контактом
        intent!: /Meeting
        a: Окей, назначаю встречу {{$parseTree._Contact}}

    state: NoMatch
        event!: noMatch
        a: Я не понял. Вы сказали: {{$request.query}}

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

После того, как все слоты были заполнены, управление передается в основной сценарий со всеми заполненными слотами в $parseTree.

подсказка

При помощи метода $caila.addClientEntityRecords запись сущности будет добавлена в справочник для текущего клиента.

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

Тестирование

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

При обращении к контактам не из своей записной книжки сценарий переходит в стейт NoMatch.

Работа с записями

Метод	Описание
$caila.addClientEntityRecords	Добавляет запись для определенного клиента к текущим записям сущности.
$caila.deleteClientEntityRecords	Удаляет записи с заданными идентификаторами id для определенного клиента.
$caila.getClientEntityRecords	Возвращает список записей сущности для определенного клиента.
$caila.setClientEntityRecords	Перезаписывает все записи сущности для определенного клиента.
$caila.setClientEntityRecord	Переопределяет запись сущности для определенного клиента.
$caila.setClientNerId	Устанавливает кастомный идентификатор клиента сlientId, который будет в дальнейшем использоваться при анализе текста.
$caila.clearClientNerId	Удаляет кастомный идентификатор клиента сlientId, который был установлен методом $caila.setClientNerId.

подсказка

У клиентских сущностей, помимо уникальных записей, могут быть общие записи для всех клиентов. Их можно заполнить при создании Сущности или при помощи CAILA API.

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

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

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

Идентификатор пользователя

По умолчанию как уникальный идентификатор пользователя используется $request.channelUserId.

При помощи метода $caila.setClientNerId вы можете установить кастомный сlientId, который будет в дальнейшем использоваться при анализе текста.