Работа с клиентскими сущностями

Обновлено 15 декабря 2023

Code

Brain

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

Вы можете использовать клиентские сущности в сценарии смартапа, интентах и слот-филлинге.

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

Создадим сценарий смартапа записной книжки. Смартап будет уметь:

• сохранять контакты с помощью клиентской сущности @Contact и интента AddContact.

• создавать встречи с помощью интента Meeting.

  Для назначения встречи интент будет обращаться к клиентской сущности @Contact

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

Для корректной работы смартапа нужно включить системные сущности @duckling.phone-number и @pymorphy.name.

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

Создайте сущность @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

У клиентских сущностей, помимо уникальных записей, могут быть общие записи для всех пользователей смартапов. Например, в телефонном справочнике это могут быть номера экстренных служб. Их можно заполнить при создании сущности или при помощи SmartApp Brain Direct API.

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

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