Перейти к содержимому

Модели принятия решений ​

jev-latest, clef и clef-flash нужны, когда программе требуется решение в заданном формате, а не текстовый ответ. Например: определить тему обращения, проверить наличие просьбы о возврате или оценить срочность заявки.

Вы передаёте данные и вопросы. Модель возвращает выбранный вариант, вероятность «да» или числовую оценку. Дальше ваш код решает, куда направить заявку, какой шаг запустить или когда запросить проверку человеком.

Это не обычный чат

Для этих моделей используйте POST /v1/systemone с полями model, state и questions. Маршрут /v1/chat/completions и массив messages для них не подходят.

Если клиент умеет только общаться с чат-моделями, замены Model ID недостаточно. Нужна поддержка System One либо прямой HTTP-запрос из вашего приложения, скрипта или инструмента автоматизации.

Зачем нужны такие модели ​

ЗадачаЧто спроситьТип вопроса
Классификация обращенийЭто вопрос об оплате, техническая проблема или другая тема?choice
Проверка условияКлиент явно просит вернуть деньги?noul
Оценка по критериямНасколько срочно нужно обработать заявку?score
Проверка ответа другой моделиПодтверждается ли утверждение приложенным документом?noul
Маршрутизация в автоматизацииКакой из известных обработчиков подходит запросу?choice

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

Как это работает ​

  1. В state передайте материал для оценки: текст, JSON-объект или массив. Например, обращение клиента и условия возврата.
  2. В questions задайте именованные вопросы. Каждый содержит type, instructions и, при необходимости, criteria.
  3. Отправьте запрос. Ответ приходит в том же HTTP-вызове: отдельный опрос статуса задачи не нужен.
  4. Прочитайте answers: ключи ответов совпадают с именами вопросов. Проверьте значения, прежде чем выполнять действие.

Несколько вопросов можно задать в одном запросе к одному state. Не рассчитывайте, что один вопрос увидит ответ на другой: зависимые шаги выполняйте отдельными запросами через свой код.

Модель оценивает переданные данные. Она не выполняет возврат средств, не вызывает ваши функции и не проверяет внешнюю базу сама по себе. Если для решения нужен документ или факт, добавьте его в state.

Как выбрать модель ​

Model ID в 1APPИздатель в каталогеГруппа токена
jev-latestTypeSafeTypeSafe или auto
clefCloudflareCloudflare или auto
clef-flashCloudflareCloudflare или auto

Все три модели подключаются через один маршрут и описанные ниже типы вопросов. Для перехода между ними измените model и проверьте доступ группы токена. Токен группы TypeSafe не даёт доступ к Clef, а группы Cloudflare — к Jev. Подробнее — группы токенов.

Jev — модель принятия решений TypeSafe; jev-latest является обновляемым именем модели, а не закреплённой версией. clef и clef-flash — отдельные модели, доступные в 1APP через тот же интерфейс. Само слово flash не гарантирует конкретную задержку или качество: сравните модели на одинаковых примерах из своей задачи. Измеряйте правильность решений и время ответа, а не только уверенность.

Точные имена, доступность и текущие тарифы смотрите в каталоге моделей. Не используйте неподключённые псевдонимы вроде clef:free.

Подключение к 1APP ​

НастройкаЗначение
Полный URL прямого запросаhttps://1app.ru/v1/systemone
HTTP-методPOST
АвторизацияAuthorization: Bearer <ВАШ_API_KEY>
Формат телаContent-Type: application/json

Используйте ключ API 1APP, а не ключ TypeSafe или Cloudflare. Если токен ограничен списком моделей, добавьте нужное имя. Для вызовов всех трёх моделей удобно использовать группу auto, если соответствующие группы доступны вашему аккаунту.

Полный URL выше предназначен для прямого HTTP-запроса. В клиенте, который сам добавляет /systemone, Base URL будет https://1app.ru/v1. Сначала проверьте, как клиент собирает адрес: не допускайте повторения /v1 или /systemone.

Первый запрос ​

Пример проверяет, просит ли клиент возврат. Замените <ВАШ_API_KEY> своим ключом. Не публикуйте ключ: команда с подставленным значением может сохраниться в истории терминала и быть видна в списке процессов.

bash
curl --silent --show-error --fail-with-body --max-time 120 \
  'https://1app.ru/v1/systemone' \
  -H 'Authorization: Bearer <ВАШ_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"jev-latest","state":"С меня дважды списали оплату. Верните лишний платёж.","questions":{"refund_requested":{"type":"noul","instructions":"Клиент явно просит вернуть деньги?"}}}'

Результат ищите в answers.refund_requested.noul. Это число от 0 до 1, а не true или false. Для вызова Clef замените jev-latest на clef или clef-flash и используйте подходящую группу токена.

Три типа вопросов ​

Noul: вероятность «да» ​

noul отвечает на один вопрос с вариантами «да» и «нет». Обязательны type: "noul" и instructions. Поле criteria необязательно; в нём можно уточнить смысл вариантов ключами "true" и "false".

Ответ noul: 0.98 означает оценённую моделью вероятность «да» в 98%. Значение около 0 означает «нет», около 0.5 — неопределённость. Проверка if (answer.noul) неверна: даже 0.01 является ненулевым числом. Сравнивайте результат с порогом, выбранным для вашей задачи.

Choice: выбор из заданных вариантов ​

В criteria передайте объект: ключи — машинные имена вариантов, значения — их описания или null. Ответ содержит choice, распределение probabilities и показатель confidence.

Например, choice: "billing" направляет обращение в отдел оплаты. Добавляйте вариант other с понятным описанием, если ни одна известная категория может не подойти. Иначе модель всё равно должна выбирать из предложенного набора.

Score: оценка по шкале ​

В criteria передайте массив минимум из двух описаний, расположенных по порядку. Нумерация начинается с 0: три описания задают уровни 0, 1 и 2, а не 1, 2 и 3.

score — среднее номеров уровней с учётом их вероятностей. Значение может быть дробным. Ответ также содержит probabilities, confidence и legend — соответствие номеров описаниям. Это не произвольная шкала «от 1 до 10»: диапазон определяется числом переданных уровней.

Пример: разбор обращения тремя вопросами ​

Такое JSON-тело можно отправить тем же запросом, например сохранить в request.json и заменить -d '…' на --data-binary @request.json:

json
{
  "model": "clef-flash",
  "state": {
    "message": "С меня дважды списали оплату. Верните лишний платёж сегодня, пожалуйста."
  },
  "questions": {
    "refund_requested": {
      "type": "noul",
      "instructions": "Клиент явно просит вернуть деньги?"
    },
    "department": {
      "type": "choice",
      "instructions": "Выберите отдел для обработки обращения.",
      "criteria": {
        "billing": "Оплата, списания и возвраты",
        "technical": "Технические ошибки подключения и работы API",
        "other": "Любые другие темы"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "Оцените срочность по тексту обращения.",
      "criteria": [
        "Нет признаков срочности",
        "Клиент просит решить вопрос скоро, без конкретного срока",
        "Клиент явно просит решить вопрос сегодня или немедленно"
      ]
    }
  }
}

Как прочитать ответ ​

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

json
{
  "model": "clef-flash",
  "answers": {
    "refund_requested": {
      "type": "noul",
      "noul": 0.98
    },
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1.0,
      "probabilities": {
        "billing": 1.0,
        "technical": 0.0,
        "other": 0.0
      }
    },
    "urgency": {
      "type": "score",
      "score": 1.8,
      "confidence": 0.7,
      "legend": {
        "0": "Нет признаков срочности",
        "1": "Клиент просит решить вопрос скоро, без конкретного срока",
        "2": "Клиент явно просит решить вопрос сегодня или немедленно"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.2,
        "2": 0.8
      }
    }
  },
  "usage": {
    "input_tokens": 250,
    "output_tokens": 40
  }
}
  • answers.refund_requested.noul: модель оценила вероятность просьбы о возврате в 0.98.
  • answers.department.choice: выбрана категория billing.
  • answers.urgency.score: оценка 1.8 по шкале 0–2. Здесь 0 × 0 + 1 × 0.2 + 2 × 0.8 = 1.8.
  • probabilities: распределение по вариантам или уровням; сумма вероятностей равна 1 с учётом округления.
  • confidence: показатель определённости распределения от 0 до 1. Это не гарантия правильности и не то же самое, что вероятность выбранного варианта.
  • usage: учёт использования модели. Если провайдер возвращает usage.cost, не считайте его суммой списания 1APP. Проверяйте фактическое списание в журнале использования 1APP и текущую цену в каталоге.

В примере программа может поставить заявку в очередь оплаты с повышенным приоритетом. Сам возврат требует отдельной проверки платежа и разрешения на операцию. Ответ модели не заменяет эти проверки.

Как получать полезные решения ​

  • Задавайте узкие вопросы с однозначными критериями. «Есть ли явная просьба вернуть деньги?» понятнее, чем «Что делать с клиентом?».
  • Передавайте нужные факты в state, а правила оценки — в instructions и criteria. Текст клиента считайте данными, а не доверенными командами.
  • Для шкалы описывайте каждый уровень словами. Различия между соседними уровнями должны быть понятны.
  • Проверяйте наличие нужных ответов, их типы и допустимые диапазоны. При HTTP-ошибке или поле error не запускайте действие как при успешном решении.
  • Подбирайте пороги на размеченных примерах своей задачи. Для сомнительных случаев предусмотрите ручную проверку или дополнительный шаг.
  • Не отправляйте API-ключи и лишние персональные данные в state. Высокая уверенность не делает решение безопасным автоматически.

Почему не работает ​

СимптомЧто проверить
Клиент отправляет messages или получает ошибку интерфейсаНужен System One: POST /v1/systemone, state и questions, а не Chat API
404Полный URL, метод, повторный /v1; поддерживает ли клиент нужный маршрут
Нет доступного канала / 503Точное имя модели, группу токена, ограничения списка моделей и доступность провайдера
Ошибка формата запросаstate — строка, объект или массив; questions — непустой объект именованных вопросов; choice.criteria — объект, score.criteria — массив
Вместо true пришло числоЭто нормально для noul: результат — вероятность «да»
Оценка не попадает в ожидаемую шкалу 1–10score использует уровни от 0 до число критериев − 1
401 или ошибка квотыКлюч API 1APP, срок действия и лимит токена, баланс аккаунта

Поддержка дополнительных возможностей upstream, включая тип box, передачу изображений и параметры чат-генерации, этой справкой не заявляется. Для описанного подключения используйте три типа вопросов и поля запроса из примеров.

Если нужна помощь, отправьте поддержке модель, HTTP-метод и путь, время запроса, статус и текст ошибки. Удалите ключи и приватные данные. Общая справка — Ошибки.

Подробнее о протоколе ​

Это документация TypeSafe. При работе через 1APP используйте адрес, ключ и доступные модели 1APP, указанные выше.