Документация / Виды шагов маршрута и их поля
Виды шагов маршрута и их поля
Для администратораСправочникЧитается по месту
Это справочник к редактору, в котором собирается порядок работы задачи. Здесь по каждому виду шага перечислено, что он делает, какие поля у него есть, какие из них обязательны и что означает каждое значение выбора. Читать подряд не обязательно, обычно сюда приходят с открытым редактором и конкретным вопросом.
Термины этой страницы. Шаг - это одно действие маршрута. Ключ результата - это имя, под которым шаг записывает свой результат в дело, чтобы следующие шаги могли его прочитать. Набор полей - это объявленный задачей список полей с типами, он же схема данных. Задание для модели - это текст инструкции, который уходит языковой модели.
Экран, о котором идет речь, называется редактором маршрутов и открывается со «Сборки задач». Как собрать маршрут целиком, разобрано на странице создания агента с нуля. Здесь только справка по полям.
Как читать панель шага
Щелчок по шагу открывает правую панель. Сверху стоит значок и вид шага, под ним поля в трех уровнях подробности.
- Основные поля показаны сразу. Обязательные помечены словом «обязательно» красным. У пустого обязательного поля платформа пишет «Заполните» с названием поля и не дает записать правку.
- Блок «Дополнительно» раскрывается щелчком. Там поля, у которых есть разумное умолчание.
- Блок «Служебное» виден в режиме «для инженера». Там служебные имена, пути к данным и тонкая настройка качества ответа.
Внизу панели стоят три действия шага, это «Сделать началом», «Сделать копию» и «Заменить на другой вид…». Замена вида сбрасывает настройки шага под новый вид, а переходы и название остаются, и платформа предупреждает об этом до замены.
Общие поля любого шага
| Поле | Что это | Обязательное |
|---|---|---|
| Название | Слово, которым шаг подписан на холсте, в журнале и в замечаниях проверки | Да |
| Какие данные нужны шагу | Отметки на входе маршрута и на предыдущих шагах | Нет |
| Поля результата | Набор полей, который шаг записывает в дело | Нет |
| Предел времени, секунд | Сколько шаг вправе работать до того, как считаться сбойным | Нет |
| Повторов при сбое | Сколько раз повторять шаг, если он не удался | Нет |
| Паузы между повторами, секунд | Через запятую, по одному числу на повтор | Нет |
| Если шаг дал сбой, перейти к | Куда уходит дело, когда повторы кончились | Нет |
У шагов «подтверждение человеком» и «передача человеку» нет собственного действия, они только ждут человека. Поэтому предел времени и повторы к ним не относятся, и платформа пишет об этом прямо в панели.
Шаг ИИ
Языковая модель читает данные и отдает текст или набор полей.
| Поле | Что это |
|---|---|
| Что делает модель (обязательное) | Одно из семи значений, см. таблицу ниже |
| Задание для модели | Выбор из заданий задачи и ваших. Рядом кнопка «Новое задание…» |
| Что передать на вход | Пары вида «переменная задания и откуда взять значение». Переменные берутся из выбранного задания |
| База знаний | Профиль поиска по документам. Обязателен для поиска и для записи в базу знаний |
| Поля результата | Набор полей, куда ляжет ответ модели |
| Какая языковая модель нужна | Класс модели, см. таблицу ниже |
| Какие данные попадут в модель | Класс данных не ниже фактического |
| Сколько документов взять (дополнительно) | Предел числа найденных документов для одного ответа |
Что делает модель
| Значение | Что происходит |
|---|---|
| сформировать текст | Модель пишет ответ по заданию и данным |
| найти в базе знаний | Поиск по вашим документам, ответ со ссылками на источники |
| положить в базу знаний | Документ разбирается и кладется в корпус для поиска |
| извлечь данные из документа | Из письма, счета или заявки собираются поля |
| отнести к категории | Модель выбирает одну категорию из заданных |
| кратко пересказать | Модель сжимает длинный текст |
| вызвать действие подключения | Модель обращается к системе через объявленное действие |
Классы языковых моделей
| Класс | Когда его берут |
|---|---|
| сильная модель | Разбор сложного текста, ответ клиенту, решение с последствиями |
| обычная модель | Большинство шагов |
| легкая модель | Простая классификация, короткие подсказки, массовый поток |
| модель с картинками | Фотографии, сканы, изображения документов |
Какие классы разрешены на вашей установке, задается конфигурацией и видно на экране моделей. Класс, не разрешенный установкой, проверка отклонит и назовет допустимые.
Классы данных
| Класс | Что это |
|---|---|
| открытые | Данные, которые и так публичны |
| внутренние | Рабочие данные компании без персональных сведений |
| персональные данные | Сведения о конкретном человеке |
| особые персональные данные | Здоровье, убеждения и прочие особые категории |
| банковская тайна | Сведения о счетах и операциях |
| коммерческая тайна | Сведения, охраняемые режимом коммерческой тайны |
Указанный класс должен быть не ниже фактического. Если в модель попадут данные класса выше, проверка скажет об этом и назовет оба класса. Куда данные каждого класса вообще разрешено передавать, задается в разделе правил задачи, и эта проверка работает уже во время работы задачи, а не только при сборке.
Расчет моделью
Обученная на ваших данных ML-модель считает оценку или класс, без языковой модели. Так делают скоринг, оценку риска, предсказание по числовым признакам.
| Поле | Что это |
|---|---|
| Модель (обязательное) | Выбор из обученных моделей задачи |
| Что передать на вход | Пары вида «поле модели и откуда взять значение» |
| Поля результата | Набор полей, куда ляжет оценка |
Если у задачи обученных моделей нет, вид закрыт в окне выбора с причиной «В этом техническом решении нет обученных моделей».
Обращение к системе
Читает или пишет через подключение к внешней системе.
| Поле | Что это |
|---|---|
| Подключение (обязательное) | Выбор из подключений, объявленных задачей |
| Действие подключения (обязательное) | Выбор из действий этого подключения. Рядом с каждым написано, читает оно или пишет |
| Что передать на вход | Пары вида «поле действия и откуда взять значение». Обязательные поля действия помечены |
| Поля результата | Набор полей, куда ляжет ответ системы |
Новое подключение из редактора не заводится. Оно объявляется в разделе подключений задачи, и там же сверяется класс данных. Подключение, задачей не объявленное, проверка отклонит.
У пометки «пишет» есть последствие. Правка, после которой становятся достижимы пишущие шаги, требует подтверждения второго человека.
Подтверждение человеком
Маршрут ждет решения сотрудника из очереди.
| Поле | Что это |
|---|---|
| Очередь (обязательное) | В какой очереди дело ждет сотрудника. Выбор из очередей задачи |
| Варианты решения | Что сотрудник может выбрать. По умолчанию их три, это подтвердить, вернуть на доработку и отклонить |
| Если подтверждение не требуется, считать решением | Каким вариантом платформа считает дело, когда подтверждение по правилам не нужно |
| Кто может подтвердить | Роли задачи, у которых есть право подтверждать |
| Срок, часов | Через сколько дело считается просроченным |
У каждого варианта решения должен быть свой переход. Вариант без перехода проверка назовет поименно. Убрать вариант, у которого переход есть, платформа предложит вместе с переходом и спросит подтверждение.
Название варианта вы пишете своими словами, а служебный ключ платформа порождает сама и при переименовании не меняет. Поэтому переименование варианта переходов не ломает.
Значение «считать решением» обязано быть одним из вариантов решения этого же шага, иначе проверка скажет об этом.
У шага, приехавшего в поставке, очередь и срок задает задача, и на экране они только читаются. У вашего шага их задаете вы.
Передача человеку
Маршрут передает дело сотруднику и ждет. От подтверждения человеком отличается смыслом. Подтверждение - это решение по существу дела, а передача - это «автомат не справился, разберите руками». Поля те же, что у подтверждения.
Преобразование данных
Перекладывает и считает поля без модели. Шаг состоит из правил, и каждое правило записывает одно поле. Правило собирается формой, а не формулой.
| Форма правила | Что делает |
|---|---|
| Взять из поля | Копирует значение другого поля |
| Взять ключ из поля по имени | Достает из набора полей значение по названию ключа |
| Сравнить | Записывает «да» или «нет» по условию |
| Выбрать из списка по значению | Находит в списке элемент, у которого нужное поле совпадает с другим значением |
| В зависимости от условия | Несколько ветвей «если, то» и одна ветвь «иначе» |
| Собрать текст по шаблону | Склеивает строку из текста и подставленных полей |
| Выражение | Произвольное выражение, правится в режиме «для инженера» |
Правило, которое формами не раскладывается, платформа показывает как выражение с пометкой «Это правило нельзя показать формой. Его правят в режиме «для инженера»». Работать оно при этом будет.
Пустой список правил проверка не пропустит, она попросит добавить хотя бы одно.
Ветвление и слияние ветвей
Ветвление пускает несколько ветвей одновременно, слияние ждет все ветви и идет дальше. Это пара, и порознь они не работают.
- Условие на переходе из ветвления не работает, потому что ветвление пускает все ветви разом.
- Переход из ветвления прямо в конец маршрута недопустим, сначала ветви надо слить.
- Своих полей у этих двух видов нет, кроме общих. Смысл им задают переходы.
Вложенный маршрут
Вызывает другой маршрут как шаг.
| Поле | Что это |
|---|---|
| Какой маршрут вызвать (обязательное) | Выбор из других маршрутов этой задачи. Сам себя маршрут вызвать не может |
| Что передать на вход | Пары вида «поле входа вызываемого маршрута и откуда взять значение» |
Вложенность ограничена десятью уровнями. Маршруты, вызывающие друг друга по кругу, проверка назовет и покажет весь круг.
Вложенный маршрут - это место, где путь мимо остановки на человеке проще всего появляется незаметно, поэтому проверка разбирает его отдельно и в замечании называет и вложенный маршрут, и шаги, ставшие достижимыми.
Агентный цикл
Языковая модель сама выбирает действия, пока не решит задачу. Это самый свободный вид шага, и ставят его там, где число обращений заранее неизвестно.
| Поле | Что это |
|---|---|
| Задание для модели | Инструкция, по которой модель работает в цикле |
| Что спросить у модели | Поле дела, содержимое которого становится вопросом |
| Действия | Флажками отмечается, какие действия каких подключений модели разрешены |
| Предел шагов (обязательное) | Сколько обращений модель вправе сделать, прежде чем цикл прервется |
| Какая языковая модель нужна | Класс модели |
| Какие данные попадут в модель | Класс данных не ниже фактического |
| Поля результата | Набор полей, куда ляжет итог |
Свобода здесь ограничена двумя вещами. Первая - это список действий, модель выбирает только из того, что вы отметили. Вторая - это предел шагов, и когда проходы кончились, а результата нет, дело уходит человеку, а не пропадает.
Конструктор условий
Условие перехода собирается списком сравнений. Сверху выбирается, как сравнения объединять.
| Правило объединения | Когда условие верно |
|---|---|
| все сравнения | Когда верны все |
| хотя бы одно | Когда верно любое |
| не все | Когда хотя бы одно неверно |
| ни одно | Когда неверны все |
| Сравнение | Что проверяет |
|---|---|
| равно, не равно | Совпадение значения с текстом, числом или порогом настройки |
| больше, не меньше, меньше, не больше | Числовые границы |
| да, нет | Значение вида «да-нет» |
| есть, нет | Заполнено поле или нет |
| пусто, не пусто | Пустая строка или список |
| содержит текст | Вхождение куска текста |
| в списке, не в списке | Принадлежность значения перечню |
Значение сравнения берется из поля дела, из введенного вами текста или числа, либо из порога настройки задачи. Последнее удобнее всего, потому что порог потом двигается на экране настройки, а маршрут при этом не трогают и второй человек не нужен.
Собранное условие платформа пишет на переходе словами, например «если сумма больше порога» или «если категория не «спам»». Длинное условие сокращается многоточием, полное видно в панели.
Поля самого маршрута
Если на холсте ничего не выбрано, правая панель показывает поля всего маршрута.
| Поле | Что это |
|---|---|
| Название | Как маршрут называется в перечне и в журнале |
| Как работает | Два значения, «идет шагами, может ждать решения людей» и «выдает ответ одним вызовом, людей не ждет» |
| Что приходит на вход маршрута (обязательное) | Набор полей, с которым дело начинается |
| Что отменить, если маршрут сорвался | Пары вида «какой шаг и чем его отменить». Это компенсирующие действия |
| Что вернуть в ответ | Набор полей ответа. Имеет смысл для маршрута, выдающего ответ одним вызовом |
| Добавлено вами в этой правке | Ваши новые наборы полей и задания, заведенные прямо в редакторе |
В маршруте, который выдает ответ одним вызовом, остановки на человеке недоступны, потому что ждать решения сотрудника такому маршруту негде. Окно выбора показывает эти виды бледными и называет причину.
Компенсирующие действия нужны там, где маршрут успел записать что-то в вашу систему и сорвался дальше по пути. При пробном запуске они не выполняются.
Замечания проверки
Проверка идет на сервере тем же кодом, который судит задачу при установке. Каждое замечание показано на своем шаге и в общем списке на вкладке «Проверка». Ниже разобраны те, что встречаются чаще других.
Порядок и связность
| Что говорит платформа | Что делать |
|---|---|
| Шаг читает данные, которые к этому месту еще не записаны | Переставить шаг после того, который эти данные записывает |
| Условие или шаг ссылается на данные, которых в маршруте нет | Проверить название поля или добавить шаг, который его записывает |
| До шага теперь нельзя дойти ни по одному переходу | Дорисовать переход или убрать шаг |
| Не выбрано начало маршрута | Щелкнуть по первому шагу правой кнопкой и выбрать «Сделать началом» |
| У шага не для каждого варианта решения есть переход | Дорисовать переход каждому названному варианту |
| Вложенные маршруты вызывают друг друга по кругу | Разорвать круг, он показан целиком |
| Вложенность маршрутов больше десяти | Сократить цепочку вызовов |
Человек в маршруте
| Что говорит платформа | Что делать |
|---|---|
| Правка открыла путь мимо шага, где решает человек | Убрать обходной переход. В замечании названы шаги, ставшие достижимыми |
| Путь мимо подтверждения открылся через вложенный маршрут | То же, но проверить надо вызываемый маршрут |
| Шаг ждет решения человека, но очередь не выбрана | Выбрать очередь в панели шага |
| Очередь задачей не объявлена | Выбрать очередь из списка, своя очередь в редакторе не заводится |
| Не выбрано, кто может подтвердить | Отметить роли в панели шага |
| У перехода после подтверждения человеком условия не бывает | Выбрать вариант решения вместо условия |
| Вариант «если подтверждение не требуется» должен быть одним из вариантов решения | Исправить значение поля |
| Поле несет данные класса, который нельзя показывать в очереди | Убрать поле из карточки очереди |
Данные и модели
| Что говорит платформа | Что делать |
|---|---|
| В модель попадут данные класса выше указанного | Поднять класс в поле «какие данные попадут в модель» |
| Данные этого класса нельзя передавать в такое-то назначение | Поменять маршрут данных в правилах задачи или убрать шаг |
| Языковая модель в этой задаче не разрешена | Выбрать класс из названных допустимых |
| В тексте задания найдены персональные данные | Заменить их примером без данных |
| Задание для модели не найдено | Выбрать задание или завести новое кнопкой в панели |
| Задача не разрешает добавлять свои задания для модели | Пользоваться заданиями задачи |
Подключения и размер правки
| Что говорит платформа | Что делать |
|---|---|
| Подключение задачей не объявлено | Объявить подключение в разделе подключений задачи |
| У подключения нет такого действия | Выбрать действие из списка |
| Действию переданы не те поля | Заполнить обязательные поля действия, они помечены |
| Правка больше допустимого | Разбить правку на несколько. В замечании названо, чего и сколько |
| Проверка не уложилась в отведенное время | Повторить, а если повторяется, звать администратора установки |
| Часть проверок платформа выполнить не смогла | Записывать правку нельзя, сообщить администратору установки |
Режим для инженера
Режим включается в меню «Файл» и делает следующее:
- Показывает служебные поля.
- Печатает под русским текстом замечания сырое сообщение проверки.
- Дает править выражения, пути к данным и настройку проверки качества ответа.
Обычной сборке он не нужен. Включают его в двух случаях. Первый случай наступает, когда замечание непонятно и нужен исходный текст для обращения в поддержку. Второй наступает, когда правило или условие сложнее того, что показывает форма.
Там же лежит вкладка «Текст маршрута», где весь маршрут показан одним документом, в том виде, в каком его читает платформа. Этот же документ скачивается и загружается через меню «Файл».