Перейти к содержанию

Общая информация и основные понятия VK Assistant

Основные понятия

  • Скилсет (skillset) — набор умений, объединенных по общим бизнес признакам. Состоит из следующих элементов:
    • NLP инструменты:
      • NER-сервисы (системные и кастомные экстракторы) — это инструмент, предназначенный для извлечения информации из текстов пользователя с последующим использованием этой информации в рамках сессии.
      • NLP модели — математический модуль, который использует датасет для классификации текста.
    • Датасеты — хранилище данных для классификации, наборы данных в формате класс (ключ) / текст (значение).
    • Тесты — сохраненные эталонные сессии, которые облегчают рабoту разработчикам и бизнес-аналитикам при проверке функционирования перcептронов и скилсетов.
    • FAQs — блок ответов на часто задаваемые вопросы, которые вводит пользователь через usertext.
    • Факт (fact) — минимальная единица информации, которой оперирует система. Набор значений фактов — это контекст диалога (сессии).
    • Agent (агент) — внешняя или внутренняя программа, которая запускается при возникновении события. Есть три типа агентов:
      • Researcher — агент типа «исследователь». Результатом работы является найденный/не найденный ответ из базы знаний.
      • Solver — агент, который инициирует выполнение внешних задач, исполняет действия в целевых системах и возвращает результаты работы в виде кода и варианта.
      • Internal — это внутренние агенты, для использования которых не требуется подключение к внешней системе.
    • Персептрон (perceptron) — базовый элемент логики системы, простейшая нейронная сеть. Состоит из следующих элементов:
      • Sensor (сенсор) — это реагирующий нейрон, рецептор, который активируется от фактов.
      • Association (aссоциация) — логический нейрон персептрона.
      • Abstraction (абстракция) — вложенный персептрон.
      • Response (респонс) — реагирующий нейрон персептрона, реакция на логические выводы от ассоциации.
      • Knowledge (элемент базы знаний, ЭБЗ, КБ) — знание о необходимых действиях, желаемый результат диалога с пользователем.
  • Системный скилсет - такой же скилсет, только в нем находятся сущности, отвечающие за работоспособность самой системы, которые также доступны для использования в кастомных скилсетах.
    • Системные агенты — это агенты типа Internal, которые отвечают за процессы ведения сессии.
    • Системные факты — это факты, поставляемые, с системой, которые обеспечивают работоспособность процесса общения пользователя с системой VK Assistant.
    • Системные экстракторы — это комплекс сложных экстракторов для продвинутого извлечения информации из текстов пользователей, например, извлечение адресов, стран назначения, номеров документов и т.д.
  • Сессия — один диалог между пользователем и цифровым помощником, ведущий к определенной цели.
  • Событие — отчет о любом изменении состояния сессии.
  • Классификатор — инструмент классификации.
  • Классификация — номер или наименование класса, выдаваемый алгоритмом классификации в результате его применения к данному конкретному объекту.
  • Лемматизация — метод морфологического анализа, который сводится к приведению словоформы к ее первоначальной словарной форме (лемме).
  • Опечаточник — система коррекции орфографических ошибок в запросах пользователей, использующаяся для улучшения работы классификатора.
  • Препроцессинг — предварительная обработка данных.
  • Регулярное выражение — формальный язык поиска и осуществления манипуляций с подстроками в тексте, основанный на использовании метасимволов.
  • Токен — единица текстовой информации, используемая для классификации текста пользователя.
  • Репозиторий — хранилище пакетов скилсетов с тегами (документация для ознакомления — https://docs.npmjs.com/adding-dist-tags-to-packages) реализованный при помощи npm (документация для ознакомления — https://docs.npmjs.com/packages-and-modules/introduction-to-packages-and-modules) для транспортировки скилсетов с одного ландшафта на другой.

Скилсет (skillset)

Skillset (скилсет) — продукт решения определенной задачи, поставленной бизнесом, или результат улучшений для оптимизации работы системы.

С технической точки зрения скилсет — это функциональная единица VK Assistant, содержащая в себе средства решения конкретной диалоговой задачи или группы задач.

Каждый скилсет имеет уникальный идентификатор (ID), название, версию, флаг активности. Скилсету присвоен список ролей пользователей, для которых должны быть доступны сценарии диалогов, реализованных посредством данного скилсета.

Скилсет содержит следующие элементы:

  • Перcептроны — базовые элементы логики VK Assistant, содержащие алгоритм обработки событий и фактов в рамках диалога. Построены по принципу простейшей нейронной сети и состоят из элементов нескольких типов;
  • Агенты.
  • Факты.
  • Датасеты.
  • Тесты.
  • FAQs.
  • NLP инструменты — в частности, отвечающие за классификацию текстов, например, текстов запросов (пользовательских обращений):
    • NER-сервисы (системные и кастомные экстракторы) — это инструмент, предназначенный для извлечения информации из текстов пользователя с последующим использованием этой информации в рамках сессии.
    • NLP модели — математический модуль, который использует датасет для классификации текста.

Стартовый скилсет

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

Стартовый персептрон прописывается в параметре конфигурации farewell_perceptron.

В настоящий момент логика определения темы обращения пользователя для каждого сервера разнится и выбирается индивидуально под проект. Порядок разработки:

  1. Создание и утверждение архитектуры сценариев с учетом всех доступных методов платформы.
  2. Создание скилсетов с использованием всех доступных методов платформы.

CI/CD скилсета

CI/CD — процесс разработки, тестирования и передачи скилсетов между инстансами системы.

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

  • @latest — тег на последней публикации скилсета (данный тег не выбирается оператором, он ставится автоматически на версии, опубликованной последней);
  • @readyForTest — скилсет, доступный для тестирования (проставляется на инстансе DEV);
  • @tested — скилсет, прошедший тестирование (проставляется на инстансе TEST);
  • @stable — стабильный скилсет, доступный для наката на продуктивную зону (проставляется на инстансе PROD);
  • @lastStable — предыдущая стабильная версия, тег проставляется автоматически, когда ставиться тег @stable на новую стабильную версию прода, при условии, что новая версия будет больше старой.

Работа с репозиторием происходит следующим образом (нажмите на изображение, чтобы открыть его в новом окне браузера):

Особенности реализации

Фильтрация по ролям, статусам скилсетов и инстансе осуществляется по следующему алгоритму:

  • Проверяется наличие подключенного репозитория.
  • Если репозиторий подключен, то определяется инстанс и вычисляется статус скилсета.
  • В зависимости от статуса скилсета и типа инстанса определяются доступные команды для скилсета (взять в работу, опубликовать и т.п.).
  • Проверяется доступ к ресурсам по ролевой модели.

При отображении доступного обновления и расчете статусов скилсетов используется следующая логика:

  • На DEV отображаются и учитываются в расчете статусов все версии скилсетов из репозитория.
  • На TEST отображаются и учитываются в расчете статусов только те версии скилсетов из репозитория, которые имеют тег @readyForTest, @tested, @stable и @lastStable.
  • На PROD отображаются и учитываются в расчете статусов только те версии скилсетов из репозитория, которые имеют тег @tested, @stable и @lastStable.
  • Скилсет "system" нельзя публиковать в репозиторий на стендах DEV, TEST и PROD и нельзя редактировать на стендах TEST и PROD (для внесений изменений можно использовать импорт из файла измененного скилсета на стенде DEV).

Маппинги и соответствия для CI/CD скилсета

Ограничения по статусам скилсета не действуют на роль ADMIN.

Ниже представлен маппинг определения статуса скилсета в зависимости от комбинации его версий и подключенного репозитория (конкретные версии приведены для наглядности).

Важно

При отсутствии репозитория колонка статусов скилсетов не отображается на форме перечня скилсетов.

Английское наимено
вание статуса
Описание Локальная версия (Л) Базовая версия (Б) Версия в репозит
ории (Р)
Инстанс Комментарий
Отсутствует статус - - - DEV, TEST, PROD Репозиторий не подключен
Conflict Конфликт не пустая любая любая DEV, TEST, PROD Репозиторий подключен
Отсутствует или не заполнен параметр repoId у скилсета
New Новый не пустая - - DEV Р = null и репозиторий подключен
Latest Опубликованный 1.0.0 Не важна 1.0.0 DEV, TEST, PROD Л = Р
Obsolete Устаревший 1.0.0 Не важна 1.0.1 DEV, TEST, PROD Л < Р
In dev В разработке 1.0.1 Не важна 1.0.0 DEV Л > Р
In test В тестировании 1.0.1 Не важна 1.0.0 TEST, PROD Л > Р

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

Процесс Базовая версия Локальная Версия в репозитории Обязательные действия
1 Создать скилсет - = указанный номер (дефолтно 1.0.0) - Указать идентификатор
Указать название
2 Начать редактирование = базовая + N Поднять локальную версию
(больше версии репо)
3 Опубликовать новую = локальная = локальная Выбор репозиторий для публикации
Проставление тега (при необходимости)
Добавление комментария
4 Опубликовать изменение = локальная = локальная Проставление тега (при необходимости)
Добавление комментария
Репозиторий подставится автоматически
(перевыбрать при необходимости)
5 Импорт нового = из репозитория = из репозитория Выбор репозитория
Выбор скилсета
Выбор версии доступной в репозитории
6 Обновление до версии в репозитории = из репозитория = из репозитория Подтвердить обновление
7 Вернуть предыдущую = из репозитория = из репозитория Репозиторий подставится автоматически (перевыбрать при необходимости)
Наименование скилсета подставится автоматически
(перевыбрать при необходимости)
Выбрать версию на экране
8 Удалить скилсет Подтвердить удаление
9 Создать снапшот Вписать наименование снапшота

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

Статус скил
сета
Редакти
ровать мета
данные
Удалять Открыть список слепков Сделать слепок Скачать в файл (Экспорт) Взять в работу Опубли
ковать в репози
торий
Откат версии Работа с тегами Обнов
ление
DEV
-
Conflict ❌ (просмотр доступен)
Obsolete ❌ (просмотр доступен)
New
Latest ❌ (просмотр доступен)
TEST
-
Conflict ❌ (просмотр доступен)
Obsolete ❌ (просмотр доступен)
Latest ❌ (просмотр доступен)
PROD
-
Conflict ❌ (просмотр доступен)
Obsolete ❌ (просмотр доступен)
Latest ❌ (просмотр доступен)

NLP инструменты

В ходе каждой диалоговой сессии может использоваться множество NLP инструментов. Базовые операции на сенсорах персептрона, классификаторы на сенсорах, классификаторы в агентах и т.д.

Уникальной особенностью VK Assistant является возможность управлять моделями непосредственно в графическом интерфейсе административного приложения. NLP сервисы основаны на SyntaxNet (TensorFlow based NLU toolkit) и др.

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

К NLP инструментам относятся:

  • NLP модели;
  • NER-сервисы (экстракторы):

    • Системные экстракторы;
    • Кастомные экстракторы.

NLP модели (Natural Language Processing)

NLP модель — математический модуль, который использует датасет для классификации текста.

Решаемые задачи:

  • Классификация текстов

    Классификация текстов используется для определения намерения пользователя в диалоге при помощи определения класса (темы) запроса. Для решения задачи классификации текстов на основе размеченных датасетов создаются NLP-модели. Для этого используются методы предобработки текстов и методы машинного обучения. Модель интегрируется в диалог. Работа с датасетами подробно описана здесь.

  • Распознавание речи (speech recognition)

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

  • Морфологический анализ

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

  • Распознавание именованных сущностей

    Распознавание именованных сущностей (NER) используется для извлечения типовой информации из usertext. Извлеченную информацию можно устанавливать как факт в сессию или передавать моделям для последующей обработки.

NER-сервисы (экстракторы)

NER-сервисы (от англ. named entity recognition - распознавание именованных сущностей) — это инструмент, предназначенный для извлечения информации из текстов пользователя (особенно из usertext) с последующим использованием этой информации в рамках сессии (установка значений фактов). В рамках данной документации ner-сервисы также называются экстракторами (от англ. extract - извлекать). Экстракторы NER-сервисов созданы на базе библиотек Natasha и Yargy а также при помощи regexp.

NER-сервисы делятся на системные и кастомные экстракторы.

  • Системные экстракторы — это готовые инструменты для извлечения типовой информации.
  • Кастомные экстракторы — это набор инструментов в административной панели, предназначенный для создания новых экстракторов, а также созданные экстракторы.

Вызов экстрактора (системного или кастомного) осуществляется в js-агенте при помощи метода await helper.extract:

await helper.extract(fact.value, 'extractorID', 'RU')

Тесты

Тесты — это сохраненные эталонные сессии, которые облегчают рабoту разработчикам и бизнес-аналитикам при проверке функционирования перcептронов и скилсетов. Создание тестов является завершающим этапом разработки сценариев перед передачей его в пользование. Созданные тесты считаются результатом работы разработчика сценариев.

При переносе диалога из одного ландшафта в другой тесты должны быть созданы как завершение переноса. Каждый ландшафт должен содержать тесты ко всем сценариям. При любых изменениях в диалоге (сценарии) тесты должны быть актуализированы. Поддержание актуальности теста является задачей разработчика сценариев.

Чтобы создать тест:

  1. В своем скилсете во вкладке добавьте папку для сохранения тестов.

  2. В течение или после сессии включите debug-режим и нажмите на значок

  3. Выберите id скилсета, id персептрона, папку, введите название теста и сохраните его:

  4. Вернитесь в папку и поменяйте id персептрона на "root":

  5. Сэмулируйте работу сессии при помощи кнопки Выполнить.

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

FAQs

FAQ — это блок ответов на часто задаваемые вопросы, которые вводит пользователь через usertext.

В VK Assistant есть два типа FAQ:

  • Глобальный FAQ — включает в себя все FAQ с разных областей знаний (скилсетов).
  • Локальный FAQ — включает в себя вопросы и ответы на определенную область знаний.

Факт (Fact)

Fact (факт) — это минимальная единица информации, которой оперирует система. Логика будущего диалога (сессии) должна начинаться с перечня фактов, которые нужно собрать.

Факты бывают двух типов:

  • Системные — поставляются вместе с системой и их можно использовать в любом скилсете.
  • Кастомные — создаются в скилсете под нужды сценарной логики.

Факт можно получить одним из способов:

  • спросить его у пользователя при помощи Prompt;
  • задать значение при помощи действия Set Parameter в респонсе;
  • установить значение с помощью агента.

Первый Fact в сессии — это usertext, т.е. ответ пользователя на приветствие системы. На основе usertext система делает выводы и спрашивает следующие факты (задает вопросы).

В старой парадигме «факт» назывался «параметром». Это отразилось на названиях некоторых функций API: setParameter, getParameter и т.д.

Набор значений фактов — это контекст диалога (сессии). Логические выводы производятся только в контексте сессии, т.е. на основе набора значений фактов. После того, как факт получен, он влияет на сенсор.

Переход от факта к сенсору неявный, для него используется операция Stimulate.

Параметры и свойства факта

Свойства факта — это описание единичного «знания», которое позволяет системе понять: как обращаться с фактом, как спрашивать его у пользователя, как проверять на валидность.

Некоторые свойства являются системными. По умолчанию формулировка в чат: «введите $id факта$».

В expandParameter добавлена возможность доставать по ключу значение из JSON. Можно записать JSON с ключами (например, id и name) в факт, а потом достать значение по ключу. Например из факта test можно будет достать значения ${test}.id или ${test}.name

Форма создания факта

Элементы на форме:

  • id — обратная доменная нотация для уникальности в формате ".fact.<уникальный id факта в skillset>" (тип: String).
  • Имя — наименование (тип: String).
  • Тип — не используемый параметр.
  • Can Change Logic — реализация перехода в другой скилсет в рамках диалога.
  • NLP analysis — необходимость запуска NLP-анализатора.
  • Режим выбора значения — настроить выбор значения:
    • Классификатор или choice from classify — для выбора значения по классификации введенного текста пользователя по заданным вариантам.
    • Кнопки — для выбора значения по точному выбору из предлагаемого списка.
    • Дата — для выбора значения из календаря.
    • Агент — используется для запросов в целевые системы через встроенное веб приложение (создавалось для использования miniapp).
  • Зависимости — задать родительский факт из выпадающего списка.
  • Prompts — вопрос, который задает система, чтобы выяснить факт.
  • Hints — help prompt, пояснение факта для пользователю.
  • Валидация — проверка факта, список валидаторов (тип: Array).
  • Advanced mode — открыть блок кода для описания дополнительных свойств факта.

Немного подробнее про свойство NLP analysis

Факт с активным признаком "NLP analysis" при answer делаем разбор и сохраняем в факте дополнительные признаки (keywords и результат синтаксического разбора).

Например сообщение: «ну убираю снег с крыши» в usertext добавит в факт свойство nlpParsing типа:

{ "nlpParsing": { "syntax": {}, "keywords": [ "убирать", "снег", "крыша", "ну", "убираю", "с", "крыши" ], "language": "RU" }

Дополнительные свойства факта:

Свойство Тип Описание
properties Object Дополнительные свойства факта
properties.nlp Boolean TRUE значит, что при получении значения факта запускаются NLP анализаторы
properties.prompts Complex PROMPT
properties.hint Text пояснение о назначении факта для пользователя
properties.type_details Object Описание способа запрашивания факта у пользователя. Например, для "choice" - список вариантов

Зависимости (Depends)

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

Запрос (Prompts)

Prompts — это текст (вопрос или рекомендация), который система покажет пользователю, чтобы выяснить факт. По умолчанию формулировка в чат: “Введите $id факта$”.

Prompts представлен в виде JSON-объекта (ключ: целевой язык). Значение Prompts представлено в виде одной строки или массива строк. В случае наличия вариабельности (при значении "массив") вопрос выбирается случайным образом во избежание повторения одинаковых вопросов. Prompts могут использовать любой заданный язык.

В Prompts есть возможность реализации подстановок информации из уже известных фактов с помощью символа $, например: $имя пользователя$

Способы задания вопросов (text, choice, etc)

Способ запроса факта зависит от его типа:

  • text (по умолчанию) — факт спрашивается в виде текста, ответ сохраняется в виде строки;
  • choice — система предлагает пользователю несколько вариантов ответа на выбор.

Список готовых вариантов можно задать в Advanced mode.

При помощи Advanced mode можно:

  • добавить список готовых вариантов для Сhoice в Prompt.
{
    "nlp": false,
    "type": "choice",
    "type_details": {
        "RU": {
            "list": [{
                "title": "Первый сценарий",
                "value": "1"
            }, {
                "title": "Второй сценарий",
                "value": "2"
            }, {
                "title": "Третий сценарий",
                "value": "3"
            }],
            "disableNumbering": true
        }
    },
    "prompts": {
        "RU": "Выберите сценарий",
        "EN": "Please, choose the topic"
    },
    "canChangeLogic": "default"
}

Параметр disableNumbering отвечает за наличие нумерации элементов списка (true-нумерации нет, false или отсутствие параметра - нумерация есть).

Hints

Для поддержания user friendly интерфейса существует Help prompt, который прописывается в Hints. Он используется для того, чтобы дать пользователю подробную информацию о запрашиваемом факте: какой именно факт, зачем он нужен системе и где пользователь может найти этот факт. Таким образом Help prompt переспрашивает факт. Для вызова Help prompt пользователю нужно ввести знак вопроса.

Пример диалога:

— Введите номер расчетного счета

— ?

— Мы спрашиваем номер расчетного счета, потому что ... . Узнать номер расчетного счета можно ...

Валидация фактов (Validators)

Если у факта есть точные характеристики, то для него можно задать параметры валидации. В таком случае валидатор проверит факт в Целевой Системе (ЦС) и даст ответ TRUE/FALSE. Факт не устанавливается, пока валидатор не даст ответ TRUE.

Существуют стандартные валидаторы и валидаторы-агенты. Для создания агента-валидатора можно использовать https://regexr.com/. Валидацию нужно начинать с символа ^ и заканчивать $, например:

^([7]+[1]+\d{8}|[S]+[R]+\d{8})$

, где:

  • ^ — значит начало
  • $ — конец строки (т.е. после символа $ нельзя продолжать строку)

Также можно выбрать один из системных валидаторов:

  • contains — содержит;
  • equals — идентично;
  • isAlphanumeric — содержит буквы и цифры;
  • isCurrency — является валютой;
  • isEmail — является адресом email.

Укажите в поле Message сообщение, которое система покажет пользователю в случае несоблюдения валидации, например:

usertext: 222

system: Введите семизначный номер

Флаг Sanitizer необходим для случая valid, когда валидатор может вернуть и своё какое-то значение. Обработанное, более правильное и т.д.

Например, есть какой-то условный валидатор ОС, который каким-то своим особым образом обрабатывает ответ юзера на какой-то факт. Юзер пишет "робот", ответ обрабатывается, валидатор возвращает: {"code":"valid"}. В факт записывается "робот" — это ситуация, когда валидатор ничего не нашел.

В аналогичном же случае валидатор может вернуть и свой value: {"code":"valid", "value":"android"}. В таком случае, если у валидатора проставлено свойство sanitizer, хоть юзер и написал "дроид", в факт по итогу попадёт "android".

Агенты

Агент — это внутренняя или внешняя программа, которая запускается при возникновении события, на которое он подписан. Агент получает на вход состояние сессии, включая значения фактов, и возвращает статус и одно из действий. Если агент вернул действие "askParameter", то он автоматически подписывается на событие change этого факта и вызывается один раз при ответе.

В рамках системы используется 2 типа агентов:

  • системные (отвечающие за session flow).
  • функциональные (для выполнения специальных функций сценария):

    • Researcher (исследователь) — получает на вход состояние сессии (все собранные факты) и путь к целевой системе. Агент может вернуть Knowledge или выполнить определенные действия: установить/спросить факт, показать пользователю информацию и т.д.
    • Collector - researcher агент, который запускается по событию изменения факта. т.е. при появлении какой-то информации в сессии добыть на основании этого что-то ещё дополнительно. Может быть агентом типа JS, REST, Remout и т.д. (чаще всего JS).
    • Validator - researcher агент, который указывается в настройках факта и валидирует ответ пользователя на аск. Может быть агентом типа JS, REST, Remout и т.д. (чаще всего JS).
    • Solver — исполняет действия в целевых системах и возвращает результаты работы в виде кода и варианта. Solver имеет возможность устанавливать ЭБЗ и факты (не прямое назначение).

Персептрон (Perceptron)

Классический простейший персептрон — базовый элемент логики системы. Это простая нейронная сеть, состоящая из трех видов элементов:

  • сенсор (S), или рецептор, принимающий нейрон персептрона;
  • ассоциация (A), или логический вывод, ассоциативный нейрон персептрона;
  • респонс (R), или реакция на логический вывод, реагирующий нейрон персептрон.

Персептрон получает на входе значения фактов и выдает на выходе перечень действий в рамках одной сессии. Сигнал движется только по направлению стрелок: S → A, A → A, A → R.

Принцип действия персептрона:

  • факты активируют сенсор посредством операции Stimulate;
  • сигналы между нейронами имеют целочисленный вес (от -100 до 100);
  • уровень активации нейрона - это сумма входящих сигналов (stimulate);
  • исходящие сигналы имеют пороговый уровень:
    • если уровень активации нейрона выше (или равен) пороговому уровню, то сигнал идет дальше;
    • если уровень активации нейрона ниже порогового уровня, то сигнал не активирует дальнейшую ветку;
  • в том случае, если сигнал достиг реагирующего нейрона (Response), система получает руководство к действию и запускает КБ или агента.

Расчет персептронa

Стартом расчета персептрона занимается агент Dispatcher. Пересчет персептрона осуществляется после каждой смены состояния факта или фактов. Результатом расчета персептрона считается перечень активированных респонсов, где уровень активации больше 0:

  • рассчитываются все связи при проходе по графу (S - A - R)

  • респонсы сортируются по силе входящего сигнала;

  • запускается реакция в соответствии с очередностью.

Возможен другой способ реализации персептрона, при котором компилируется функция на JS. Выходами являются агенты типа Solver и Researcher:

  • агент Solver выводит Knowledge;
  • агент Researcher выводит actions.

При создании персептронов можно использовать факты, агенты, knowledge из Root skillset.

Жизненный цикл персептрона

  • Greet — приветствие.
  • Fact — единица знания.
  • Stimulate — правило, по которому факт активирует сенсор.
  • Sensor — реагирующий нейрон персептрона, рецептор.
  • Association — ассоциативный нейрон - логический вывод.
  • Signal — связь между сенсором и ассоциацией.
  • Associate — связь между ассоциациями.
  • Abstraction — вложенный персептрон.
  • Abstract — связь между результирующим респонсом вложенного персептрона и нейронами типа ассоциация, абстракция, респонс.
  • Activate — активация - связь между логическим выводом и реагирующим нейроном.
  • Response — реагирующий нейрон персептрона, реакция на логические выводы.
  • Researcher — агент-исследователь.
  • Research — процесс запуска агента.
  • Find — нахождение знания (Knowledge) в процессе исследования.
  • Guess — догадка о знании (Knowledge) в результате реакции персептрона.
  • Knowledge — знание (KB в старой версии).
  • Attempt — попытка выполнить действие, старт агента Solver.
  • Solver — агент-решатель проблемы.
  • FollowUp — настраиваемая ассоциация на продолжение подобных решений .
  • Farewell — прощание.
  • Command — краткая команда, которая должна выполняться без размышлений.
  • Require — для выполнения команда требует факты (параметры).
  • Set — установка знания (Knowledge) в результате выполнения команды.

Сенсор (Sensor)

Sensor (сенсор) — это реагирующий нейрон, рецептор, который активируется от фактов.

  • Факт (Fact) — параметр, единица знания.
  • Операция (Stimulate) — операция, правило, в соответствии с которым факт активирует сенсор.
  • Сенсор (Sensor) — реагирующий нейрон персептрона, рецептор. Это реакция на отработанную функцию. Имеет входящие и исходящие сигналы. Входящими сигналами являются только операции над фактами — сенсор получает «количественный коэффициент» операции. Каждый факт ведет к определенному сенсору. Если сумма входящих сигналов больше 0, то нейрон активируется и передает сигналы дальше. Каждый исходящий сигнал имеет собственный порог. Сигналы сенсора суммируются в ассоциациях.
Операции

Операция — это функция, которая на вход берет значение привязанного факта и аргументы самой операции и на выходе возвращает TRUE или FALSE. Если факт установлен, то на выходе операция возвращает TRUE, активируя следующий нейрон.

Каждая операция имеет id, имя, тип и value.

По типу различают встроенные (internal) и кастомные (custom) операции. Встроенные операции включены в ядро. Если для реализуемой логики требуется новая операция, то можно написать кастомную операцию. Кастомные операции написаны на языке JS в административной панели.

Пример встроенной операции equal, которая сравнивает факт со значением, которое указано в value:

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

Пример кастомной операции hasPartialNGramm, value которой представляет собой фразу, состоящую из корней слов:

Часто используемые операции:

Встроенные:

id name Назначение
1 equal equal Возвращает TRUE, когда факт равен указанному значению
2 hasBigram hasBigram Возвращает TRUE, когда введенный usertext имеет лексемы, указанные в value
3 hasKeyword hasKeyword Должна стоять галочка NLP analysis.
Возвращает TRUE, когда в предложении существует указанное слово (полное)
Пример:
указано: статус
предложение: Нужен статус заявки (вернет TRUE)
предложение: Нужен статус заявки (вернет FALSE)
4 hasKeywords hasKeywords Должна стоять галочка NLP analysis.
Возвращает TRUE, когда в предложении существует указанное словосочетание. Возможна запись нескольких слов в словосочетании через запятую, а несколько словосочетаний через точку с запятой.
5 hasMultipleSentences hasMultipleSentences Возвращает TRUE, когда введенный usertext состоит из нескольких предложений
6 isChanged isChanged Возвращает TRUE, когда факт изменяется в сессии
7 isChangedBtwnCalc isChangedBtwnCalc Возвращает TRUE, когда значение факта изменилось в процессе расчета персептрона
8 isInFaqWithProbability isInFaqWithProbability Возвращает TRUE, когда введенный usertext является вопросом из FAQs
9 isPresent Parameter is present in session Возвращает TRUE, когда факт уже установлен в сессии
10 isSet isSet Возвращает TRUE, когда факт известен
11 isUserInPlatform isUserInPlatform Вести операцию надо от факта system.fact.session.user_platforms Возвращает TRUE, когда Platform пользователя совпадает с указанной (например, SAP_S4)
12 isUserInPlatformType isUserInPlatformType Вести операцию надо от факта system.fact.session.user_platforms Возвращает TRUE, когда PlatformType пользователя совпадает с указанным (например, SAP )
13 isUserInRole isUserInRole Возвращает TRUE, когда Role пользователя совпадает с указанной (например, ADMIN)
14 nlpClassify nlpClassify Возвращает TRUE, когда введенный usertext с указанной вероятностью классифицирован моделью
15 nlpIsInFaqWithProbability nlpIsInFaqWithProbability Возвращает TRUE, когда введенный usertext c определенной вероятностью является вопросом из FAQs
16 receivedSignalFrom receivedSignalFrom Возвращает TRUE, когда сигнал получен от сущности, указанной в value
17 receivedSignalFromAbstraction receivedSignalFromAbstraction Возвращает TRUE, когда сигнал получен от абстракции, указанной в value
18 sentenceType sentenceType Возвращает TRUE, когда тип предложения в факте совпадает с нужным типом предложения. Пример:
нужно : assertive
предложение: Обычный текст
или
нужно : exclamatory
предложение : Обычный текст!

Кастомные:

id name Назначение
1 greaterThen greaterThan Возвращает TRUE, когда значение usertext больше указанного
2 isMonth isMonth Возвращает TRUE, когда usertext является месяцем
3 neq NotEqual Возвращает TRUE, когда usertext не равен значению, указанному в value
4 partialNGramm hasPartialNGramm Возвращает TRUE, когда usertext содержит корень, указанный в value
5 partialNGramms hasPartialNGramms Возвращает TRUE, когда usertext содержит корни, указанные в value

Пример использования операции isUserInRole в JS агенте

Ниже представлен пример использования операции isUserInRole посредством JS агента:

(() => { // Do not remove this line!

const user = _.find(sessionParameters, ["parameterId", "[gp]system.fact.quboUser"]);
return (async () => {
    try {
        if (user && user.value) {
            let userJson = JSON.parse(user.value);
            let isGuest = _.filter(userJson.roles, ["name", "GUEST"]);
                if (isGuest.length) {
                    <Какое-то действие>
                    }
            }
} catch (err) {
    await logger.write('generateIdeal text err', JSON.stringify(err));
    }
    return {}
})();

}); // Do not remove this line!
Операция Stimulate

Операция Stimulate определяет порог входящего сигнала (Input signal level), т.е. достаточен ли сигнал, полученный от факта, для перехода нейрона в активное состояние. Если сигнал достаточен, т.е. сумма входящих сигналов больше 0, то нейрон активируется

Параметры настройки:

Ассоциация (Association)

Association (Ассоциация) — логический нейрон персептрона. Принимает на вход сумму исходящих сигналов от сенсора или других ассоциаций и абстракций и активируется при сумме входящих сигналов больше 0. Ассоциация используется для того, чтобы продолжить цепочку действий, если накопленная сумма сигналов равна или выше порога выхода. Если накопленная сумма сигналов ниже порога выхода, ассоциация останавливает действие.

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

Абстракция

Абстракция — это ассоциация более высокого уровня, которая содержит в себе вложенный перcептрон. Является вложенным персептроном. Принцип работы абстракции схож с капсульной нейронной сетью.

Система рассчитывает вложенный перcептрон в том случае, когда уровень активации абстракции равен или выше установленного. Исходящий из абстракции сигнал связан напрямую с реагирующими нейронами внутри вложенного персептрона, т.е. можно узнать, сработала ли абстракция, только тогда, когда сработал респонс вложенного персептрона. Абстракция передаст сигнал дальше, если внутри встроенного персептрона реагирующий нейрон (указанный в сигнале) получит уровень активации больше 0.

В правильно построенном персептроне у абстракции нет выхода в КБ, только респонс, т.к. абстракция — это только логический вывод. Внутри абстракции можно создать несколько респонсов и добавить внутри перcептрона несколько действий для каждого из них.

На данный момент чаще используется переход в другой персептрон через респонс при помощи action setPerceptron.

Респонс (Response)

Response (Респонс) — это реагирующий нейрон перцептрона, реакция на логический вывод от ассоциации. Респонс активируется при сумме входящих сигналов больше 0. Входящие сигналы поступают от ассоциаций, абстракций и сенсоров. Не рекомендуется использовать непосредственную связь сенсор-респонс (такую логику сложно модифицировать).

Реакции, связанные с Response:

  • Reseacher — явный запуск агента исследователя.
  • Knowledge — явная установка KB.
  • Actions — переход к действиям.

Если после респонса выполняется любой агент или КB, этому агенту должна быть присвоена соответствующая платформа.

Если КБ не предполагает последующий вызов агента, устанавливается платформа internal.

Actions

Список действий:

id name Назначение
1 'askParameter' parameterId ID факта
2 Discover Aux Intents какой-то текст
3 Extract, Ectractor
"data": {
"source": "${system.fact.ui.usertext}",
"method": "extract",
"rule": {
"fact": "001.examples.fact.1",
"mode": "all",
"allow_repeat": false,
"extractor": "001.examples.RU.aux_intents",
"field": "entity_name"
}
},
Объект
4 Extract, Model
"data": {
"source": "${system.fact.ui.usertext}",
"method": "model",
"rule": {
"fact": "ai.fact.a",
"mode": "first",
"model": "FAQ-skill-set",
"threshold": 0.25
}
},
Объект
5 Extract, Preset
"data": {
"source": "${system.fact.ui.usertext}",
"method": "preset",
"rule": {
"fact": "ai.fact.a",
"mode": "single",
"allow_repeat": true,
"preset": {
"name": "datetime",
"options": {
"extrapolate_to": "future"{
}
}
}
},
Объект
6 'setParameter' parameterId ID факта
3 'setParameter PlatformId' platformId ID платформы
4 'setPerceptron' perceptronId ID перcептрона
5 'clearParameter' parameterId ID факта
6 showInfo какой-то текст ${ID факта} еще какой-то текст
7 type: "text" data: "Hello world!" строка
8 type: "table"
data: {
title: "Name",
table: [{
"numbers": numbs,
"date": dates,
"true symbols": symbols,
"work logic": logic,
"results of smth": res
}]
}
объект

Первичный вид:

return {
    actions: [{
                // используя choice
                action: "askParameter",
                parameterId: "[gp].payment_status.fact.num_contract",
                options: {
                    prompt: "Выберите интересующий договор по компании № ${[gp].payment_status.fact.compcode}",
                    type: "choice",
                    list: choice // массив элементов a = ['1', '2', '3', '4'];
                }
            }, {
                action: "setParameter",
                parameterId: '[gp].payment_status.fact.znp_number',
                value: number // значение let number = 1;
            }, {
                action: "setPerceptron",
                perceptronId:[gp].purchases.qualification.perceptron.faqRegisteredUsers'
            }, {
                action: "showInfo",
                type: "text",
                data: "Hello world!"
            }, {
                action: "clearParameter",
                parameterId: "[gp].payment_status.fact.num_contract"
            }, {
                action: "showInfo",
                type: "table",
                data: {
                        title: "Name",
                        table: [{
                            "numbers": numbs,
                            "date": dates,
                            "true symbols": symbols,
                            "work logic": logic,
                            "results of smth": res
                        }]
                    }
            }];
}

, где [gp] — нотация обратного доменного имени.

Элемент базы знаний (Knowledge)

Knowledge (элемент базы знаний) — знание о необходимых действиях, желаемый результат диалога с пользователем.

Цель сессии в классическом SessionFlow]— переход в Knowledge, т.е. система должна понять, что нужно пользователю, и подобрать подходящий Knowledge. Персептрон пересчитывается до тех пор, пока не появится выход в Knowledge. Если после расчета перcептрона появляются новые факты и Knowledge, то преимущество отдается Knowledge.

Если агент Dispatcher закончил работу выходом в Knowledge, то запускается агент SolverFinder. Агент SolverFinder запускает агент типа Solver.

Типы решения (solutionType)

  • url — перенаправить пользователя на нужную страницу;
  • none (он же agent) —запуск агента типа Solver;
  • text —показать текст пользователю;
  • html —показать пользователю HTML размеченный текст;
  • document —дать пользователю ссылку на документ (см. надстройка Документы). Ссылка на документ может формироваться двумя способами:
    • для работы с файлом в текущей вкладке;
    • для работы с файлом вне текущей вкладки (другое окно или вкладка).

В трех последних случаях стартует специальный агент типа Solver DocumentFinder.

Follow Up

Follow Up — предложение выполнить действие по связанным темам.

К одному элементу базы знаний (Knowledge) можно привязать до 10 follow up. В зависимости от результата работы агента Solver цепочки follow up могут быть бесконечными.

Системный скилсет (System skillset)

Системный скилсет содержит:

  • Системные факты, которые могут быть использованы в любом скилсете текущего инстанса.
  • Основные экстракторы.
  • Основные агенты.

Важно

Импортировать системный скилсет не рекомендуется.

Системные факты (System facts)

Список фактов, их ключи и значения:

ID Название Назначение Триггерит
событие
system.
change.
event
1 system.fact.
active_kb
ACTIVE_KB ЭБЗ для солвера

Пример возможного значения: ai.test.sage.test.case.knowledge.end
2 system.fact.calc_
snapshot
PERCEPTRON_CALC
_PARAMS
JSON фактов со значениями перед расчетом перcептрона. Содержит список всех фактов, участвующих в расчете персептрона
Пример возможного значения
{
    "parameterId": "system.fact.session.user_obj",
    "value":"{
      \"username\":\"a.grebenik\",
      \"email\":\"a.grebenik@mail.ru\",
      \"id\":\"6001b8215e6e710011c1c7fa\",
      \"isActive\":true,
      \"name\":\"Anna\",
      \"language\":\"RU\",
      \"lastPlatformsCheck\":\"03-02-2021 13:24:59\",
      \"roles\":[
        {
          \"id\":\"5ff8257adc60400018c88d8e\",
          \"name\":\"OPERATOR\",
          \"created\":\"2021-01-08T09:27:22.652Z\",
          \"modified\":\"2021-01-08T09:27:22.652Z\"},
        {
          \"id\":\"5ff8257adc60400018c88d8f\",
          \"name\":\"ADMIN\",
          \"created\":\"2021-01-08T09:27:22.653Z\",
          \"modified\":\"2021-01-08T09:27:22.653Z\"}
        ],
        \"lastSession\":\"2021-01-18T08:47:57.858Z\"}"
  },
{
    "parameterId": "system.fact.ui.usertext",
    "value": "создать СО заказа"
}
3 system.fact.custom_
fareweller_invoked
CUSTOM_FAREW
ELLER_INVOKED
Устанавливается, если был настроен каcтомный fareweller и он запустился вместо основного
4 system.fact.
endless_session
ENDLESS_SESSION Фаревеллер не завершает сессию, а рестартует если есть такой факт
5 system.fact.
faq_skillset
FAQ_SKILLSET FAQ SPECIFIC

Пример возможного значения: https://sandbox.dakub.ru/#/session/601c0de2055a4b001159a208
6 system.fact.
fareweller_done
FAREWELLER_DONE При установке в true указывает, что сессия завершена, и фаревеллер не работает больше

Пример возможного значения: true
7 system.fact.
is_faq_state
IS_FAQ_STATE Устанавливается в fareweller влияет на поведение сессии в режиме FAQ

Пример возможного значения: https://sandbox.dakub.ru/#/session/601c0de2055a4b001159a208
8 system.fact.md5hash MD5_FACT_HASH Хеш фактов при расчете перцептрона диспетчером

Пример возможного значения: закодированный контекст сессии
9 system.fact.
need_login
SOLVER_NEED_
LOGIN
Используется в solver finder для запроса логина при старте сессии
10 system.fact.
operator.mode
OPERATOR_MODE При работе с оператором принимает два значения ask или waterfall

Пример возможного значения: ask или waterfall (статус режима сообщений в чате с оператором)
11 system.fact.
operator.text
UI_OPERATOR Факт, через который ведется разговор с пользователем в режиме waterfall

Пример возможного значения: текст, который напишет оператор
12 system.fact.
session.channel
SESSION_CHANNEL Канал сессии (копия из свойства сессии uiChannel)

Пример возможного значения: web-chat<
13 system.fact.
session.context
CONTEXT Хранит информацию о контексте сессии
14 system.fact.session
.context.last
CONTEXT_LAST CONTEXT COLLECTOR AGENT

Пример возможного значения: факты, участвующие в сессии в текущий момент
15 system.fact.session.
dialog.agent
SESSION_DIALOG
_AGENT
Агент, с которым сейчас ведется диалог - ask от других агентов игнорируются

Пример возможного значения: system.agent.fareweller
16 system.fact.session.
domain
SESSION_DOMAIN Основная тема сессии (например skillsetId)

Пример возможного значения: 001.test-examples
17 system.fact.session.
full_name
LOCAL_NAME Имя пользователя для обращения

Пример возможного значения: user.name или user.username
18 system.fact.
session.id
SESSION_ID id сессии (копия из свойства сессии id)

Пример возможного значения: 01be2b1055a4b0011599c03
19 system.fact.
session.language
SESSION_LANGUAGE Язык сессии (копия из свойства сессии language)

Пример возможного значения: RU
20 system.fact.session.
platform_id
PLATFORM_ID Текущая целевая платформа. по умолчанию internal копия свойства сессии platformId

Пример возможного значения: internal
21 system.fact.session.
platform_username
PLATFORM_USER
_NAME
Проставляется после логина в платформу, если в свойствах UserPlatform есть username

Пример возможного значения: username
22 system.fact.session.
scope
SESSION_SCOPE Подтема сессии

Пример возможного значения: например faqTitle
23 system.fact.session.
sub.finish
SESSION_SUB_FINISH
  • установка в finish - создает и сохраняет новый инцидент если system.fact.session.sub.start не пустой
  • установка в cancel - очищает system.fact.session.sub.start сбрасывая инцидент

Пример возможного значения: finish или cancel
24 system.fact.session.
sub.result
SESSION_SUB_
RESULT
Хранит список инцидентов в виде JSON массива (по умолчанию):
  • skillSetId
  • domain
  • scope
  • duration
Пример возможного значения
[{
    "duration": 10,
    "skillSetId": "ai.app.root",
    "domain": "faq name",
    "scope":  "faq title"
}]
25 system.fact.session.
sub.start
SESSION_SUB_
START
Хранит время начала инцидента, если установить в start - начинает новый инцидент (ставит текущее время)

Пример возможного значения: start или время начала инцидента
26 system.fact.session.
user_obj
USER_OBJ json stringify(user)
Пример возможного значения
{
  "username": "a.grebenik",
  "email": "a.grebenik@mail.ru",
  "id": "6001b8215e6e710011c1c7fa",
  "isActive": true,
  "name": "Anna",
  "language": "RU",
  "lastPlatformsCheck": "дата последней проверки платформы",
  "roles": [список доступных ролей],
  "lastSession": "дата последней сессии через текущий канал"
}
27 system.fact.session.
user_platforms
USER_PLATFORMS Массив пользовательских платформ, список типов платформ, платформ и ролей, доступных пользователю
Пример возможного значения
{
  "platforms": [
    {
      "value": "internal",
      "title": "Internal"
    }
  ],
  "platformTypes": [
    {
      "value": "internal",
      "title": "Internal"
    }
  ],
  "roles": [
    "OPERATOR",
    "ADMIN",
    "NONSTUDY",
    "_ALL"
  ]
}
28 system.fact.session.
username
USER_NAME Значение user.username имя пользователя

Пример возможного значения: имя пользователя
29 system.fact.
skillset
SKILLSET Выбранный скиллсет

Пример возможного значения: ai.test.sage.test.case — текущий скилсет, который определил рутовый скилсет
30 system.fact.solver.
code
SOLVER_CODE Результаты работы солвера

Пример возможного значения: solved
31 system.fact.solver.
started
SOLVER_STARTED Признак что солвер начал работу

Пример возможного значения: system.agent.document_solver
32 system.fact.solver.
variant
SOLVER_VARIANT Результаты работы солвера

Пример возможного значения: default
33 system.fact.ui.
confirmstart
UI_CONFIRMSTART Если у солвера есть признак confirm_start, то этот факт запрашивается у пользователя
34 system.fact.ui.
fact.text
UI_FACT_TEXT Продолжение вопроса по FAQ - через endless в fareweller
35 system.fact.ui.
probleм_solved
UI_PROBLEM_
SOLVED
Факт, запрашиваемый у юзера в виде "Ваша проблема решена?"
36 system.fact.ui.
usertext
UI_USERTEXT Первый вопрос к пользователю при старте сессии

Пример возможного значения: текст пользователя
37 system.fact.vali
dation.error_count
VALIDATION_
ERROR_COUNT
Количество ошибок валидации на факте

Пример возможного значения: 2
38 system.fact.vali
dation.processing
VALIDATION_ERR
OR_PROCESSING
Поведение при провале валидации

Системные агенты (System agents)

Перечень системных агентов:

ID Тип Назначение
1 system.agent.command_finder internal Разбирает команды /add_budget <счет> <сумма>
2 system.agent.dispatcher internal Считает перцептроны и ведет сессию
3 system.agent.document_solver internal Обрабатывает KB - показывает документы или тексты
4 system.agent.fareweller internal Прощается и завершает или перезапускает сессию
5 system.agent.greeter internal Здоровается и начинает сессию
6 system.agent.solver_finder internal Обрабатывает KB если найдены
7 system.agent.session.sub.finish internal Подписки:
system.event.session.sub.finish:* сохраняет новый инцидент
system.event.fact.change:system.fact.solver.code - при отработке солвера это событие позволяет поймать код солвера
если solved - сохраняем новый инцидент
иначе отменяем текущий инцидент
system.event.fact.change:system.fact.session.sub.finish
если значение факта == finish - сохраняет новый инцидент
если значение факта == cancel - отменяет текущий инцидент
8 system.agent.session.sub.start internal Подписки:
system.event.session.sub.start - при старте события начинает отсчет инцидента
system.event.fact.change:system.fact.ui.usertext - при старте события начинает отсчет инцидента
system.event.fact.change:system.fact.session.sub.start - если значение факта == start - начинает отсчет времени инцидента
9 system.agent.task_dispatcher internal Координирует межсессионные взаимодействия и отложенные задачи.
10 system.agent.test.executor internal Прогоняет тесты - делает сессию, мониторит события, делает answer и тп
11 system.agent.timeouter internal По умолчанию запускается один раз в минуту, проверяет время и статус каждой сессии и делает вывод о закрытии сессии. Если в течение определенного времени внутри сессии не происходят события, сессия закрывается по time out

Системные экстракторы

Системные экстракторы (NER-сервисы) — это комплекс сложных экстракторов для продвинутого извлечения информации из текстов пользователей, например, извлечение адресов, стран назначения, номеров документов и т.д. Экстракторы NER-сервисов созданы на базе библиотек Natasha и Yargy или при помощи regexp.

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

Описание экстракторов

Идентификатор Описание и назначение
1 address Извлекает адреса.
Пример ответа при успешном извлечении данных

Текст для экстракции: улица Ленина 5

{
  "result": [
    {
      "extractor": "address",
      "entity_name": "улица",
      "entity_value": "Ленина",
      "__span": [
        0,
        14
      ]
    },
    {
      "extractor": "address",
      "entity_name": "name",
      "entity_value": "5",
      "__span": [
        0,
        14
      ]
    }
  ]
}
2 credit_card Извлекает номер кредитной карты. Примечание: извлекает 16 и 19 символьный номер карты.
Пример ответа при успешном извлечении данных

Текст для экстракции: 1234 5678 1234 5678

{
  "result": [
    {
      "entity_value": "1234 5678 1234 5678",
      "__span": [
        0,
        19
      ],
      "extractor": "credit_card",
      "entity_name": "credit_card"
    }
  ]
}
3 country Извлекает название страны.
> Пример ответа при успешном извлечении данных

Текст для экстракции: Россия

{
  "result": [
    {
      "extractor": "country",
      "entity_name": "country",
      "entity_value": "Россия",
      "__span": [
        0,
        6
      ]
    }
  ]
}
4 country_from Извлекает название страны по предлогам "из", "с".
Пример ответа при успешном извлечении данных

Текст для экстракции: из Москвы

{
  "result": [
    {
      "extractor": "country_from",
      "entity_name": "country_from",
      "entity_value": "Россия",
      "__span": [
        0,
        9
      ]
    }
  ]
}
5 country_in Извлекает название страны по предлогам "в", "на".
Пример ответа при успешном извлечении данных

Текст для экстракции: в Москву

{
  "result": [
    {
      "extractor": "country_in",
      "entity_name": "country_in",
      "entity_value": "Россия",
      "__span": [
        0,
        8
      ]
    }
  ]
}
6 dates Извлекает даты из следующих сущностей:
  • Числа
    • 1-31го; 1-31 го; 1-31-го
    • 1-31ого; 1-31 ого; 1-31-ого
    • 1-31е; 1-31 е; 1-31-е
    • первого - тридцать первого числа
    • первое - тридцать первое число
    • 01-31 числа; 1-31 числа
  • Число + Месяц (комбинации должны распознаваться со следующими разделителями: " " "." "-")
    • 01-31.01-12; 1-31.1-12
    • Любая комбинация из "Числа" + январь - декабрь (с правильным падежом)
    • 01-31 + январь - декабрь (с правильным падежом); 1-31 + январь - декабрь (с правильным падежом)
    • первого - тридцать + январь - декабрь (с правильным падежом)
    • первое - тридцать + январь - декабрь (с правильным падежом)
  • Число + Месяц + Год (комбинации должны распознаваться со следующими разделителями: " " "." "-")
    • 01-31.01.12.2022; 1-31.1-12.2022 - четырехзначный формат года
    • Любая комбинация из "Числа" + январь-декабрь + Любая комбинация из "Год"
    • 1-31 + январь - декабрь + Любая комбинация из "Год"
    • 01-31.01.12.22; 1-31.1-12.22 - двухзначный формат года
  • Год (если извлечен год от 0 до текущий год + 6, то добавляется в начало 20, если распознался текущий год + 7 до 99, то добавляется в начало 19)
    • 1- 3000 год или г
    • первого - трех тысячного года или г
Пример ответа при успешном извлечении данных

Текст для экстракции: 31 января 2021

{
  "result": [
    {
      "extractor": "dates",
      "entity_name": "year",
      "entity_value": 2021,
      "__span": [
        0,
        14
      ]
    },
    {
      "extractor": "dates",
      "entity_name": "month",
      "entity_value": 1,
      "__span": [
        0,
        14
      ]
    },
    {
      "extractor": "dates",
      "entity_name": "day",
      "entity_value": 31,
      "__span": [
        0,
        14
      ]
    }
  ]
}
7 digits Извлекает число (дробная часть числа распознается как отдельное число).
Пример ответа при успешном извлечении данных

Текст для экстракции: 10 раз к вам обращался

{
  "result": [
    {
      "entity_value": "10",
      "__span": [
        0,
        2
      ],
      "extractor": "digits",
      "entity_name": "digits"
    }
  ]
}
8 foreign_passport Извлекает номер иностранного паспорта.
Примечание: От 6 до 12 символов (в номере могут быть буквы).
Пример ответа при успешном извлечении данных

Текст для экстракции: 123456

{
  "result": [
    {
      "entity_value": "123456",
      "__span": [
        0,
        6
      ],
      "extractor": "foreign_passport",
      "entity_name": "foreign_passport"
    }
  ]
}
9 iccid Извлекает уникальный серийный номер SIM-карты.
Пример ответа при успешном извлечении данных

Текст для экстракции: номер 8901260232714958936

{
  "result": [
    {
      "entity_value": "8901260232714958936",
      "__span": [
        6,
        25
      ],
      "extractor": "iccid",
      "entity_name": "iccid"
    }
  ]
}
10 location Встроенный экстрактор в Natasha для извлечения объектов вроде "Швейцария" или "Академгородок".
Пример ответа при успешном извлечении данных

Текст для экстракции: я щас в академгородке

{
  "result": [
    {
      "extractor": "location",
      "entity_name": "name",
      "entity_value": "академгородок",
      "__span": [
        0,
        13
      ]
    }
  ]
}
11 military_id Извлекает номер военного билета.
Пример ответа при успешном извлечении данных

Текст для экстракции:

{
  "result": [
    {
      "entity_value": "0999999",
      "__span": [
        0,
        7
      ],
      "extractor": "military_id",
      "entity_name": "military_id"
    }
  ]
}
12 money_range Извлекает разброс стоимости (вместе с валютой).
Пример ответа при успешном извлечении данных

Текст для экстракции: от 100 до 200 рублей

{
  "result": [
    {
      "extractor": "money_range",
      "entity_name": "min_integer",
      "entity_value": "100",
      "__span": [
        0,
        20
      ]
    },
    {
      "extractor": "money_range",
      "entity_name": "max_integer",
      "entity_value": "200",
      "__span": [
        0,
        20
      ]
    },
    {
      "extractor": "money_range",
      "entity_name": "max_currency",
      "entity_value": "RUB",
      "__span": [
        0,
        20
      ]
    }
  ]
}
13 money_rate Извлекает сумму в период.
Пример ответа при успешном извлечении данных

Текст для экстракции: 1000р в день

{
  "result": [
    {
      "extractor": "money_rate",
      "entity_name": "money_integer",
      "entity_value": "1000",
      "__span": [
        0,
        12
      ]
    },
    {
      "extractor": "money_rate",
      "entity_name": "money_currency",
      "entity_value": "RUB",
      "__span": [
        0,
        12
      ]
    },
    {
      "extractor": "money_rate",
      "entity_name": "period",
      "entity_value": "DAY",
      "__span": [
        0,
        12
      ]
    }
  ]
}
14 money Извлекает количество денег и валюту (рубли, доллары и евро при условии, что валюта написана словами).
Пример ответа при успешном извлечении данных

Текст для экстракции: 100 долларов

{
  "result": [
    {
      "extractor": "money",
      "entity_name": "integer",
      "entity_value": "100",
      "__span": [
        0,
        12
      ]
    },
    {
      "extractor": "money",
      "entity_name": "currency",
      "entity_value": "USD",
      "__span": [
        0,
        12
      ]
    }
  ]
}
15 msisdn Извлекает номер сотового телефона.
Примечания:
  • Извлекает номера телефона, которые начинаются на +7, 7 и 8
  • Извлекает номера телефона, которые написаны через " " и "-"
Пример ответа при успешном извлечении данных

Текст для экстракции: 7 926 426 0224

{
  "result": [
    {
      "entity_value": "7 926 426 0224",
      "__span": [
        0,
        14
      ],
      "extractor": "msisdn",
      "entity_name": "msisdn"
    }
  ]
}
16 names Извлекает имена и фамилии.
Примечания:
  • Экстрактор Извлекает двойную фамилию, если она написана через "-". Через проблем берется только первое значение.
  • Фамилии и Имена ищутся в словаре. Если значения нет или оно ошибочно находится в словаре, то необходимо корректировать словарь.
Пример ответа при успешном извлечении данных

Текст для экстракции: Иванов-Петров Андрей

{
  "result": [
    {
      "extractor": "names",
      "entity_name": "last",
      "entity_value": "иванов-петров",
      "__span": [
        0,
        20
      ]
    },
    {
      "extractor": "names",
      "entity_name": "first",
      "entity_value": "андрей",
      "__span": [
        0,
        20
      ]
    }
  ]
}
17 numbers Извлекает числа.
Пример ответа при успешном извлечении данных

Текст для экстракции: 1 10 или 15 3

{
  "result": [
    {
      "extractor": "numbers",
      "entity_name": "numbers",
      "entity_value": "1 10",
      "__span": [
        0,
        4
      ]
    },
    {
      "extractor": "numbers",
      "entity_name": "numbers",
      "entity_value": "15 3",
      "__span": [
        9,
        13
      ]
    }
  ]
}
18 order Извлекает значения "по убыванию" или "по возрастанию".
Пример ответа при успешном извлечении данных

Текст для экстракции: расположить 1 4 7 2 по убыванию и возрастанию

{
  "result": [
    {
      "extractor": "order",
      "entity_name": "order",
      "entity_value": "по убыванию",
      "__span": [
        20,
        31
      ]
    },
    {
      "extractor": "order",
      "entity_name": "order",
      "entity_value": "по возрастанию",
      "__span": [
        34,
        45
      ]
    }
  ]
}
19 organisation Извлекает названия организаций (аббревиатуры и полные слова).
Пример ответа при успешном извлечении данных

Текст для экстракции: МГУ

{
  "result": [
    {
      "extractor": "organisation",
      "entity_name": "name",
      "entity_value": "МГУ",
      "__span": [
        0,
        3
      ]
    }
  ]
}
20 period Извлекает значение, через которое будет что-то выполнено.
Пример ответа при успешном извлечении данных

Текст для экстракции: с 1 по 10 буду в отпуске

{
  "result": [
    {
      "extractor": "period",
      "entity_name": "period",
      "entity_value": "10",
      "__span": [
        7,
        9
      ]
    }
  ]
}
21 person Извлекает должность и имя (нуждается в доработке).
Пример ответа при успешном извлечении данных

Текст для экстракции: Президент России Путин

{
  "result": [
    {
      "extractor": "person",
      "entity_name": "position",
      "entity_value": "Президент России",
      "__span": [
        0,
        22
      ]
    },
    {
      "extractor": "person",
      "entity_name": "name_last",
      "entity_value": "Путин",
      "__span": [
        0,
        22
      ]
    }
  ]
}
22 persons Комбинация из экстрактора "names" и нейросетевого экстрактора от natasha.
Используются следующие этапы экстракции:
  • допустим, на входе имеем text = "обошлось Юлия"
    • если names находит в тексте имена, он делат слова данного имени с большой буквы
  • names отработал так себе и теперь имеем text = "Обошлось Юлия"
    • полученный текст попадает в нейронку natasha. Даже если слово написано с большой буквы, natasha скорее всего поймет что это все-таки не имя
  • получаем результат: [] (пустой массив сущностей, сущности не обнаружены)
Пример ответа при успешном извлечении данных

Текст для экстракции: ИваноВ пЕтр

{
  "result": [
    {
      "extractor": "nn_person",
      "entity_name": "person",
      "entity_value": "ИваноВ пЕтр",
      "__span": [
        0,
        11
      ]
    }
  ]
}
23 region Извлекает название региона (только РФ).
Пример ответа при успешном извлечении данных

Текст для экстракции: Тверская область

{
  "result": [
    {
      "extractor": "region",
      "entity_name": "region",
      "entity_value": "Тверская область",
      "__span": [
        0,
        16
      ]
    }
  ]
}
24 region_from Извлекает название региона (только РФ) по предлогам "из", "с".
Пример ответа при успешном извлечении данных

Текст для экстракции: из Москвы

{
  "result": [
    {
      "extractor": "region_from",
      "entity_name": "region_from",
      "entity_value": "Москва",
      "__span": [
        0,
        9
      ]
    }
  ]
}
25 region_in Извлекает название региона (только РФ) по предлогам "в", "на".
Пример ответа при успешном извлечении данных

Текст для экстракции: в Питер

{
  "result": [
    {
      "extractor": "region_in",
      "entity_name": "region_in",
      "entity_value": "Санкт-Петербург",
      "__span": [
        0,
        7
      ]
    }
  ]
}
26 residence Извлекает номер вида на жительство. От 7 цифр до 12.
Пример ответа при успешном извлечении данных

Текст для экстракции: серия 82 номер 1234567

{
  "result": [
    {
      "entity_value": "1234567",
      "__span": [
        15,
        22
      ],
      "extractor": "residence",
      "entity_name": "residence"
    }
  ]
}
27 russian_passport Извлекает серию и номер российского паспорта.
Пример ответа при успешном извлечении данных

Текст для экстракции: 4615 123123

{
  "result": [
    {
      "entity_value": "4615 123123",
      "__span": [
        0,
        11
      ],
      "extractor": "ai.app.extractors.extractor.RU.russian_passport",
      "entity_name": "ai.app.extractors.extractor.RU.russian_passport"
    }
  ]
}
28 seafarer_id Извлекает номер удостоверения личности моряка.
Пример ответа при успешном извлечении данных

Текст для экстракции: 0999999

{
  "result": [
    {
      "entity_value": "0999999",
      "__span": [
        2,
        9
      ],
      "extractor": "seafarer_id",
      "entity_name": "seafarer_id"
    }
  ]
}
29 units Извлекает единицу измерения.
Пример ответа при успешном извлечении данных

Текст для экстракции: 105 дм

{
  "result": [
    {
      "extractor": "units",
      "entity_name": "standard_unit",
      "entity_value": "дециметр",
      "__span": [
        4,
        6
      ]
    }
  ]
}
30 words Извлекает отдельные слова из текста.
Пример ответа при успешном извлечении данных

Текст для экстракции: Здесь три слова

{
  "result": [
    {
      "entity_value": "Здесь",
      "__span": [
        0,
        5
      ],
      "extractor": "words",
      "entity_name": "words"
    },
    {
      "entity_value": "три",
      "__span": [
        6,
        9
      ],
      "extractor": "words",
      "entity_name": "words"
    },
    {
      "entity_value": "слова",
      "__span": [
        10,
        15
      ],
      "extractor": "words",
      "entity_name": "words"
    }
  ]
}

Экстракторы NER-сервисов подключаются к сценарию аналогично простым экстракторам, т.е. вызываются методом agentHelper в коде JavaScript-агента:

await helper.extract(fact.value, 'extractorID', 'RU')

(() => { // Do not remove this line!

const country = _.find(sessionParameters, ["parameterId", "ai.app.country.fact.country"]);

return (async () => {
    try {
        let country_ext = await helper.extract(country.value, 'country', "RU") // вызов экстрактора country
        let country_from = await helper.extract(country.value, 'country_from', "RU") // вызов экстрактора country_from
        let country_in = await helper.extract(country.value, 'country_in', "RU") // вызов экстрактора country_in

        await logger.write('country_ext', `${JSON.stringify(country_ext)}`) // для просмотра в логах

        return {
            actions: [{
                action: "setParameter",
                parameterId: "ai.app.country.fact.result",
                value: "Ваш регион - " + country_ext
            }]
        }
    } catch (err) {
        await logger.write('error', JSON.stringify(err))
    }
})();

}); // Do not remove this line!

Вызов больше одного экстрактора

Для того, чтобы прогнать текст пользователя через несколько экстракторов сразу, используется используется метод run_many.

Сессия

Сессия рассматривается как один диалог между пользователем и цифровым помощником, ведущий к определенной цели. Если цель достигнута — диалог считается успешно завершенным, если нет — неудачно завершенным. Контекстом диалога в любой момент является набор значений фактов, собранных в одной сессии.

Каждая сессия имеет:

  • userId — уникальное имя пользователя, запустившего сессию;
  • uiChannel — канал, который пользователь использует для обращения к системе (веб, чат, VK Teams, Skype и т.д.);
  • platformId — платформа/ы, которую в данный момент использует сессия;
  • language — язык сессии;
  • perceptronId — уникальное имя активного персептрона;
  • debugLevel — уровень прохождения сессии (по умолчанию 0);
  • ttl — таймаут сессии (значение конфига сервера);
  • state — состояние сессии (описаны ниже);
  • title — автоматически присваивается первый пользовательский текст (usertext);
  • operatorId — id назначенного оператора (если есть);
  • id сессии — уникальный номер сессии.
  • summary — это объект свободной формы, в который можно в ходе сессии что-то складывать в зависимости от требований и нужд проекта. Для этого можно использовать доступные из js методы helper.getSessionSummary и helper.setSessionSummary. Агент просто использует это как временный буфер для своей внутренней логики. При желании summary также можно пользоваться для разных целей в рамках проекта.

Состояния сессии

  • asking parameter — система запрашивает факт у пользователя;
  • closed — сессия закрыта;
  • opened — сессия активна;
  • operator ask — оператор ждет ответа пользователя;
  • waiting — сессия ждет назначения оператору.

Этапы сессии

  • Приветствие и первичный вопрос.
  • Определение намерения пользователя: одному намерению соответствует один набор умений (скилсет).
  • Сбор фактов, необходимых для реализации цели в рамках определенного набора умений.
  • Исполнение цели пользователя, т.е. получение информации или выполнение действия.
  • follow up — предложение выполнить действие по связанным темам (опционально).
  • Завершение сессии (оценка работы и прощание).

Завершение сессии

Для завершения сессии существует агент timeouter. Агент timeouter по умолчанию запускается один раз в минуту, проверяет время и статус каждой сессии и делает вывод о закрытии сессии. Если в течение определенного времени внутри сессии не происходят события, сессия закрывается по time out.

Endless сессия Сессия не всегда прямолинейна и имеет возможности возврата к любому моменту сессии с полным или частичным сохранением контекста диалога. Для этого в сессии устанавливается факт endless (setParameter - endless).

Сессия хранится в БД и содержит подчиненные списки сущностей:

  • sessionParameter — значения фактов сессии;
  • sessionEvent — события в сессии;
  • sessionAgent — вызовы агентов;
  • sessionListener — подписка на события;
  • sessionResult — найденные KB;
  • sessionAskedParameter — очередь вопросов (запросов фактов);
  • sessionUI — UI история чата сессии.

Сбор метрик сессии (инциденты)

Это возможность отслеживать количество решенных вопросов (инцидентов) в рамках сессии.

Детали реализации

Новые факты:

  • system.fact.session.sub.start — хранит время начала инцидента, если установить в start - начинает новый инцидент (ставит текущее время);
  • system.fact.session.sub.finish — отвечает за очистку старта инцидента и создание нового;
  • system.fact.session.sub.result — хранит список инцидентов в виде JSON массива (по умолчанию);
  • system.fact.session.domain — основная тема сессии (например skillsetId);
  • system.fact.session.scope - под тема сессии (например faqTitle).

При формировании записи system.fact.session.sub.result берем значения фактов из конфига sessionSubConfig (см. ниже) + duration это разница между временем в system.fact.session.sub.start и текущим временем в секундах.

Пример:

[
{ "duration": 10, "skillSetId": "ai.app.root", "domain": "faq name", "scope":  "faq title"}
]

Новые конфиги:

  • statisticIncludeSubs
  • sessionSubConfig

Новые события:

  • system.event.session.sub.start
  • system.event.session.sub.finish

Новые системные агенты:

  • system.agent.session.sub.start
  • system.agent.session.sub.finish

Новые методы AgentHelper:

  • sessionSubStart()
  • sessionSubFinish()
  • sessionSubCancel()

Процессы:

  1. Варианты начать новый инцидент:

    • system.event.fact.change usertext — при изменении usertext;
    • создать событие system.event.session.sub.start (await helper.triggerEvent или из дебага);
    • записывает в факт system.fact.session.sub.start значение «start» (можно setParameter на Response);
    • await helper.sessionSubStart().
  2. Варианты завершить начатый инцидент:

    • создать событие system.event.session.sub.finish (await helper.triggerEvent или из дебага)
    • отработал solver и вернул result.code == solved (в том числе documentSolver);
    • записывает в факт system.fact.session.sub.finish значение «finish» (можно setParameter на Response);
    • await helper.sessionSubFinish().
  3. Варианты отменить начатый инцидент:

    • записать в факт system.fact.session.sub.finish значение «cancel» (можно setParameter на Response);
    • await helper.sessionSubCancel();
    • clearParameter system.fact.session.sub.start (можно clearParameter на Response).
  4. Варианты посмотреть инциденты:

    • Новое поле в статистике.
    • При экспорте статистики (новая закладка Subs в Excel).

Событие (Event)

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

При возникновении события в сессии:

  1. Событие записывается в сессионный флоу (sessionEvent);
  2. Запускаются агенты, подписанные на событие (sessionListener);
  3. Обрабатываются результаты работы агентов.

Подписать агента на событие можно через форму в агентах или в подписках агентов.

При подписке можно указать следующие свойства:

  • agentId — идентификатор агента;
  • eventId — идентификатор события (например: system.fact.change)
  • eventSuffix — конкретика по событию, при возникновении которого срабатывает агент;
    • подписка на system.fact.change:* запускает подписанного агента при изменении любого факта;
    • подписка на system.fact.change:fact1 запускает подписанного агента при изменении факта fact1;
  • params.sync — агент реагирует каждый раз при возникновении события. Возможные значения : true/false;
  • params.once — агент реагирует на данное событие, возникшее впервые. Возможные значения : true/false;
  • params.keepOnChangeContext — агент реагирует на смену контента. Возможные значения : true/false;
  • onlyForUiChannels — добавляются UI каналы, на которые необходимо подписываться. Если указан не валидный канал или канал не указан, то подписка не сработает.