Обработка данных и доступ к контексту

Платформа предоставляет механизм извлечения сущностей (entities) для распознавания и обработки структурированных данных из пользовательского ввода. Этот функционал позволяет работать с различными типами данных, такими как номера телефонов, даты, адреса и другие.

Принцип работы

1. Распознавание: При поступлении сообщения NLU-модель автоматически извлекает сущности, соответствующие настроенным шаблонам.
2. Сохранение в контекст: Извлеченные данные сохраняются в объекте context, становясь доступными для использования в сценарии.
3. Доступ к данным: Доступ к значению сущности осуществляется через следующие поля:
   • context.имя_сущности.str: Отформатированное строковое представление.
   • context.имя_сущности.raw: Оригинальное значение, как оно было введено пользователем.

Данные из контекста можно использовать как декларативно в блоке Текст, так и программно в Сниппетах.

Практическое руководство

Рассмотрим пример извлечения номера телефона и его использования в сценарии.

Шаг 1. Конфигурация сущности

Перейдите в раздел Сущности и создайте новую сущность с типом Phone number. Присвойте ей имя, например, Phone.

Шаг 2. Создание сниппета

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

getPhoneNumber.js

async function snippet (core = new Core(), context = new Context()) {
  // Прямой доступ к сущности, извлеченной из последнего сообщения
  core.sendText("Получаю доступ из контекста к сущности 'Phone': " + context.Phone.str);
}

Шаг 3. Построение и тестирование сценария

1. Перейдите в раздел Сценарии и создайте новый сценарий.
2. В качестве триггера (первого шага) установите блок Сущность и выберите созданную ранее сущность Phone.
3. Добавьте два шага-реакции:
   • Сниппет: Выберите созданный сниппет getPhoneNumber.
   • Текст: Введите Указан телефон: {{Phone.str}} для демонстрации прямого доступа к данным сущности.
4. Сохраните сценарий.

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

Продвинутые техники работы с контекстом

Обработка нескольких сущностей

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

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

multiple-phones.js

async function snippet (core = new Core(), context = new Context()) {
    if (context.Phone) {
        core.sendText('Основной номер: ' + context.Phone.str);
        if(context.Phone.others && context.Phone.others.length > 0) {
            // Проходим по массиву остальных найденных номеров
            context.Phone.others.forEach((phoneEntity, index) => {
                 core.sendText(`Дополнительный номер ${index + 1}: ${phoneEntity.str}`);
            });
        } else {
            core.sendText('Дополнительные номера не обнаружены.');
        }
    } else {
        core.sendText('Номер не обнаружен.');
    }
}

Доступ к истории контекста

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

• context.current.meta.entities: Сущности, извлеченные из текущего сообщения.
• context.events: Массив всех событий в диалоге. Для доступа к последнему событию используется context.events[context.events.length - 1].

Пример сниппета для демонстрации различных способов доступа:

entity-access-methods.js

async function snippet (core = new Core(), context = new Context()) {
  // Способ 1: Прямой доступ к сущности из последнего сообщения
  if (context.Phone) {
    core.sendText('Способ 1 (прямой доступ): ' + context.Phone.str);
  }

  // Способ 2: Доступ через метаданные текущего события
  if (context.current && context.current.meta && context.current.meta.entities && context.current.meta.entities.Phone) {
    core.sendText('Способ 2 (из context.current): ' + context.current.meta.entities.Phone.str);
  }

  // Способ 3: Доступ через историю событий
  const lastEvent = context.events[context.events.length - 1];
  if (lastEvent && lastEvent.meta && lastEvent.meta.entities && lastEvent.meta.entities.Phone) {
    core.sendText('Способ 3 (из истории событий): ' + lastEvent.meta.entities.Phone.str);
  }
}