Вопросы

Вопросы choice, score и probability — структурированные инструкции и критерии, что API возвращает для каждого, взвешенные уровни, зарезервированный вариант other и минимальная уверенность.

Вопросы — это то, на что решение отвечает о state. В решении от 1 до 64 вопросов, и на все отвечает один вызов движка: Jev оценивает каждый из них независимо и параллельно по одному и тому же state. Каждый вопрос становится ключом в объектах result и confidence ответа, в том порядке, в каком вы их задали.

ТипДля чегоresult[key]Пример
choiceВыбор одного варианта: команды, категории, инструментаОдно из значений ваших вариантов (string)"sales"
scoreРазмещение state на упорядоченной шкалеПодпись наиболее вероятного уровня (string)"high"
probabilityВопрос да/нетВероятность yes, от 0 до 10.9412

Общие свойства

СвойствоТипОбязательноеОписание
keystringДаsnake_case, уникальный в решении. Становится ключом JSON в ответе.
typestringДаchoice, score или probability.
instructionsstring, object или arrayДаВопрос, на который отвечает движок: текст или структурированный JSON. До 8 000 символов (для JSON считается длина в сериализованном виде).
minConfidencenumberНетОт 0 до 1. Ниже этого значения решение применяет действие fallback — см. ниже.

Choice

{
  "key": "route",
  "type": "choice",
  "instructions": "Which team should receive this lead?",
  "options": [
    { "value": "sales", "description": "high intent, ready to talk to sales" },
    { "value": "sdr", "description": "some intent, needs qualification" },
    { "value": "nurture", "description": "early stage, send content" }
  ]
}
  • В options нужно не меньше 2 и не больше 254 вариантов, плюс other — всего 255, максимум Jev.
  • value следует правилам для ключей и должно быть уникальным внутри вопроса.
  • description сообщает движку, когда вариант подходит: текст или JSON, до 2 000 символов. Оно необязательно — опустите его или задайте null, когда значение говорит само за себя ("yes_refund"). Описания определяют точность: противопоставляйте похожие варианты и добавляйте исключения вроде «не для существующих клиентов».
  • Порядок важен. Jev может склоняться к варианту, указанному первым. Проверяйте важные вопросы в Playground с переставленными вариантами и убеждайтесь, что ответ не меняется.

Зарезервированный вариант other

У каждого вопроса choice есть вариант other. Dcision добавляет его автоматически последним вариантом с описанием none of the options above. Удалить его нельзя, но можно описать самостоятельно, включив в options, — куда бы вы его ни поставили, он переносится в конец:

{ "value": "other", "description": "not about our product, or a language we don't support" }

Без other движок вынужден выбирать наименее неверный вариант. С ним «ничего из этого» становится явным ответом: когда вопрос choice отвечает other и ни одна политика не сработала раньше, решение применяет действие fallback с action_reason.type = "other_option". См. Политики и действия.

Что возвращает API

  • result.route — выбранный вариант, например "sales" (или "other").
  • confidence.route — насколько выбранный вариант возвышается над равномерным распределением между всеми вариантами, от 0 до 1, — см. Уверенность.
  • С ?include=probabilities поле probabilities.route содержит по одной вероятности на вариант, включая other.

Политики по ответу choice могут использовать только eq и neq. Сравнение игнорирует регистр и пробелы по краям.

Score

{
  "key": "priority",
  "type": "score",
  "instructions": "How urgent is it to answer this lead?",
  "scale": ["low", "medium", "high", "critical"]
}
  • scale перечисляет от 2 до 10 уровней от низшего к высшему. Уровень — это подпись (до 2 000 символов) или структурированная рубрика с label. Подписи должны быть уникальными.
  • result.priority — подпись наиболее вероятного уровня, а не среднее, а confidence.priority показывает, насколько распределение сосредоточено вокруг него.
  • scores.priority — взвешенный уровень: среднее уровней, взвешенное по вероятности, считая с 1. На шкале выше 2.81 находится между medium (2) и high (3), ближе к high. Используйте его, чтобы действовать между уровнями.
  • С ?include=probabilities поле probabilities.priority содержит по одной вероятности на подпись, в порядке шкалы.

Политики сравнивают уровни, пронумерованные с 1: на шкале выше low — это 1, а critical — 4.

  • По ответу ("on": "output") правило использует номер уровня ("value": 3) или подпись ("value": "high") с любым оператором: { "field": "priority", "operator": "gte", "value": "high", "action": "escalate" } совпадает с high и critical. Подпись, которой нет на шкале, никогда не совпадает.
  • По взвешенному уровню ("on": "score") правило сравнивает scores.priority с числом: { "field": "priority", "on": "score", "operator": "gte", "value": 3.5, "action": "escalate" } срабатывает, когда вес смещается к critical, даже если наиболее вероятный уровень — high.

Probability

{
  "key": "purchase_intent",
  "type": "probability",
  "instructions": "Does this lead have real intent to buy in the next 30 days?",
  "criteria": {
    "yes": "asks for pricing, a demo, a quote or a start date",
    "no": "just browsing, student, vendor or spam"
  }
}
  • criteria.yes и criteria.no необязательны — текст или JSON, до 2 000 символов каждое — и говорят, что считается «да» и что «нет». Согласуйте их с инструкциями: yes должно описывать случай «да».
  • result.purchase_intent — вероятность «да», от 0 до 1, округлённая до 4 знаков после запятой.
  • confidence.purchase_intent равно |2p − 1|: расстоянию от подбрасывания монеты. У 0.03 (уверенное no) и 0.97 (уверенное yes) уверенность одинаковая — 0.94; у 0.5 — 0.
  • С ?include=probabilities поле probabilities.purchase_intent равно { "yes": p, "no": 1 − p }.

Политики сравнивают вероятность с числом, например { "field": "purchase_intent", "operator": "gte", "value": 0.8, "action": "continue" }.

Структурированные инструкции и критерии

Jev изначально понимает структуру. Везде, где у вопроса есть текст — instructions, description варианта, уровни score, criteria.yes и criteria.no, — вместо него можно отправить JSON-объект или массив. Структура помогает, когда у вопроса несколько частей или когда ему нужны вспомогательные данные — таксономия, схема или строка из базы данных: ключи подписывают каждую часть.

{
  "key": "duplicate_candidate",
  "type": "probability",
  "instructions": {
    "potential_duplicate": { "name": "John Smith", "location": "Oakland, California", "last_employer": "Google" },
    "question": "Is the resume in `resume` for the same person as `potential_duplicate`?"
  }
}
  • Указывайте на данные обратными кавычками. Называйте поля state и ключи инструкции в обратных кавычках — `resume`, `ticket.messages[0].text`, — чтобы точно сказать движку, на что смотреть.
  • Дайте вариантам рубрику. Описание варианта вроде { "what": "Charges, invoices, refunds", "not_for": "Order tracking", "examples": ["I was charged twice"] } уточняет границу между соседями.
  • Лимиты те же, что для текста, и измеряются по сериализованному JSON: 8 000 символов для инструкций, 2 000 для описания варианта, уровня score или критерия. Объекты и массивы не могут быть пустыми.
  • В редакторе вставьте JSON-объект или массив в поле: он сохраняется как структура и помечается как структурированный. Всё, что не является корректным JSON, остаётся текстом.

Структурированные уровни score

Уровень score может быть объектом с label — подпись возвращается в result и сравнивается политиками, а весь объект читает движок:

{
  "key": "bug_severity",
  "type": "score",
  "instructions": "If this describes a bug, how severe is it for the customer?",
  "scale": ["cosmetic", "minor", "major", { "label": "critical", "rubric": "outage, data loss, security issue or money at risk" }]
}

Подпись — от 1 до 255 символов; весь уровень в сериализованном виде — до 2 000. Простые и структурированные уровни можно смешивать на одной шкале. Редактор добавляет уровни как простые подписи и показывает структурированные со значком фигурных скобок — шаблон Сортировка тикетов поддержки начинается с одного такого.

Минимальная уверенность

У любого вопроса можно задать minConfidence от 0 до 1. Когда уверенность ответа ниже этого значения и ни одна политика не сработала раньше, решение применяет действие fallback с action_reason.type = "low_confidence":

{ "type": "low_confidence", "question": "route", "confidence": 0.52, "minConfidence": 0.8 }

В редакторе переключатель Минимальная уверенность начинается с 80%. Без него ответы с низкой уверенностью всё равно получают continue.

Для вопроса probability уверенность равна |2p − 1|, поэтому минимальная уверенность отмечает полосу вероятностей вокруг 0.5: 0.8 отмечает любое p между 0.1 и 0.9, 0.6 — любое p между 0.2 и 0.8. Редактор показывает полосу рядом с ползунком. См. Уверенность и вероятности и Низкая уверенность и other.

Советы

  • Спрашивайте об одном в каждом вопросе. Разделите «это срочный спам?» на probability (spam) и score (urgency) — в любом случае это один вызов.
  • Формулируйте инструкции как буквальный вопрос о state: «Какая команда должна получить этот лид?».
  • Для да/нет предпочитайте probability — к числу проще применить порог, чем к choice из двух вариантов.
  • Для упорядоченных уровней предпочитайте score — тогда политики могут использовать gte/lte по уровню и пороги по взвешенному уровню.
  • Пишите описания вариантов как критерии, а не как подписи, и делайте соседние варианты взаимоисключающими. Если Playground отмечает почти ничью, описания пересекаются.
  • Помещайте бизнес-факты в context, а не в каждую инструкцию.
  • Держите вычисления, подсчёты и даты в коде и отправляйте результаты в state.
  • Порядок важен: когда несколько вопросов отвечают other или оказываются ниже своей минимальной уверенности, в action_reason попадает первый в порядке вопросов.

Подробнее — в разделе Как писать хорошие вопросы.

На этой странице