Сущности

Сущность — единица NLU-ядра CAILA. Представляет собой последовательность слов, объединенных некоторым смыслом или правилом. Например: имена, дата и время, местоположение и пр.

CAILA предоставляет для работы:

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

Подробнее о редакторе сущностей

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

Напрямую

Все сущности, найденные во фразе будут доступны в сценарии через переменную $jsapi.context().entities или $entities.

Например:

    state:
        q!: Информация по продукту *
        a: Информация по продукту: {{ $entities[0].value }}

В интентах

Сущности можно использовать в интентах.

Подробнее о заполнении слотов в интентах и процессе Slot filling

При активации интента данные по соответствующему слоту попадут в переменную $parseTree._<имя слота>.

В этой переменной будет записан исходный текст, по которому найдено совпадение, либо данные DATA, заданные для данной сущности в редакторе сущностей.

Например:

    state:
        intent: /купить
        a: Action: {{ $parseTree._Action }}, Product: {{ $parseTree._Product }}

    state:
        intent: /продать
        a: Action: {{ $parseTree._Action }}, Product: {{ $parseTree._Product }}

В паттернах

Сущности можно использовать в паттернах, ссылаясь на них как @<имя сущности> или @<имя сущности>::<имя слота>.

Для сущности, указанной в паттерне, автоматически создается слот, и она попадает в дерево разбора $parseTree. Значение сущности будет доступно в сценарии как $parseTree._<имя слота>.

Например:

    state:
        q!: * @Product::p1 *
        a: Информация по продукту: {{ $parseTree._p1 }}

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

patterns:
    $four = @four || converter = function() {return 4}

В этом примере мы создали сущность @four, в которой объявили конвертер converter. Функция конвертера вернет значение 4.

В примерах фраз классификатора STS

Сущности можно использовать в примерах фраз классификатора STS, ссылаясь на них как @<имя сущности> или @<имя сущности>::<имя слота>.

Для сущности, указанной в примере, автоматически создается слот, и она попадает в дерево разбора $parseTree.

Значение сущности будет доступно в сценарии как $parseTree._<имя слота>.

Например:

    state:
        e!: @Pizza::p2
        a: Информация о пицце: {{ $parseTree._p2 }}

В сущностях

В JAICP сущности могут ссылаться на другие сущности.

Рассмотрим поведение сущностей при:

заполнении поля Значение;
заполнении поля DATA.

Заполнение поля Значение

Рассмотрим пример заполнения адреса клиента. Адрес состоит из двух составных частей: улица и номер дома.

В меню проекта перейдите на вкладку CAILA > Сущности > Мои сущности и создайте сущности:

street_name с паттернами:

Ленина
Школьная
Центральная

street с паттерном:

Улица @street_name

Теперь создадим сущность address, которая будет ссылаться на сущность street и на системную сущность @duckling.number:

@street дом @duckling.number

Теперь допустим, что клиент вводит сообщение Улица Ленина. Поле Значение будет заполнено следующим образом:

Ленина у сущности street_name;
Улица Ленина у сущности street.

Если клиент вводит сообщение Улица Школьная дом 15, то Значение будет заполнено так:

Школьная у сущности street_name;
Улица Школьная у сущности street;
Улица Школьная дом 15 у сущности address.

Заполнение поля DATA

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

В меню проекта перейдите на вкладку CAILA > Сущности > Мои сущности и создайте сущности:

fruit с паттернами:

(яблок*|ренет*)
(банан*)
(лимон*)

vegetable с паттернами:

(картошк*|картох*|картофель)
(томат*|помидор*)

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

Например, для паттерна (банан*) укажите:

{
    "name": "banana",
    "type": "fruit"
}

Сделайте то же самое для каждого паттерна сущности vegetable. Например:

{
    "name": "potato",
    "type": "vegetable"
}

Теперь объединим эти сущности в сущность grocery. Создайте сущность grocery и в поле Справочник укажите паттерны @vegetable и @fruit.

Сущность grocery

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

state: Start
    q!: $regex</start>
    a: Здравствуйте! В нашем магазине представлен широкий ассортимент овощей и фруктов. Что вы хотите?

    state: Grocery
        q!: * @grocery *
        script:
            $reactions.answer("Название продукта: {{ $parseTree._grocery.name }}");
            $reactions.answer("Тип продукта: {{ $parseTree._grocery.type }}");

Таким образом, если клиент напишет сообщение Картошку, то это сообщение будет распознано сущностью vegetable, на которую ссылается сущность grocery. Поле DATA у сущности grocery заполнится содержимым поля DATA сущности vegetable. Бот выведет сообщения:

Название продукта: potato
Тип продукта: vegetable

Заполнение массива $entities

Рассмотрим пример наличия нескольких вариантов совпадения при поиске сущности.

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

Для этого необходимо, чтобы в массив $entities попали все значения сущности.

При помощи метода CAILA API:

PUT    /cailapub/api/caila/p/{accessToken}/entities/{entityId}

Добавим параметр для сущности @City:

{
  "fuzzySearch": true    // позволяет находить и помещать в массив несколько значений
}

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