Как пользоваться Jev — пошаговая инструкция

Шаг 1. Выберите, откуда подключаться

Модель одна, а входов несколько. Они отличаются ключами, оплатой и названием модели в запросе:

Где	Модель в запросе	Особенности
TypeSafe напрямую	jev-latest	Ранний доступ по листу ожидания, оплата в долларах
OpenRouter	typesafe/jev-1.13	Отдельный Decisions API, оплата с баланса OpenRouter
Vercel AI Gateway	typesafe-ai/jev	Оплата кредитами Vercel
Cloudflare Workers AI	typesafe/jev	Вызов через ai/run из кода Workers
Polza.AI	typesafe/jev	Без VPN, карта РФ, СБП или счёт для юрлиц

Прямой доступ у TypeSafe пока ранний: заявку оставляют на сайте, ключ выдают после одобрения. У OpenRouter есть нюанс: Jev работает через отдельный Decisions API, а не через привычный чат-эндпоинт, поэтому SDK для chat completions с ней не работают. Как подключиться из России без VPN, рассказываем в статье о доступе к Jev из России, а все варианты с плюсами и минусами сравниваем в статье о том, как получить доступ к Jev.

Шаг 2. Получите API-ключ

На любой площадке порядок одинаковый: регистрация, пополнение баланса, создание ключа в личном кабинете. У TypeSafe ключи создаются в консоли console.typesafe.ai, когда вас пропустят из листа ожидания.

Сохраните ключ в переменную окружения и не публикуйте его в коде. Официальные SDK сами читают переменную TYPESAFE_API_KEY. Если работаете через агрегатор, в SDK понадобятся ещё его базовый адрес и название модели. Для Polza.AI это https://polza.ai/api без /v1 и модель typesafe/jev.

Шаг 3. Попробуйте запрос без кода

В консоли TypeSafe есть песочница (Playground). Вставьте текст в поле состояния, добавьте вопрос, например «Выражает ли сообщение срочность?», и посмотрите ответ. Затем добавьте ещё пару вопросов разных типов: все ответы придут одновременно.

Если прямого доступа нет, соберите запрос в нашем конструкторе. Он выдаст готовый код на curl, Python или JavaScript, останется подставить ключ.

Шаг 4. Отправьте первый запрос

Самый простой способ — curl. Запрос состоит из трёх частей: модель, состояние и вопросы.

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Помогите! Выплаты не проходят уже третий день.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Это срочное обращение?"
      }
    }
  }'

is_urgent — идентификатор, который вы придумали сами. По документации TypeSafe он нужен только вашему коду и в модель не передаётся. Поэтому вопрос целиком пишите в instructions, даже если название ключа кажется понятным.

Если подключаетесь через агрегатор, замените адрес, ключ и название модели на выданные площадкой. У Polza.AI путь тот же: https://polza.ai/api/v1/systemone.

Шаг 5. Разберите ответ

Ответ на запрос выше выглядит так (числа для примера):

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": { "type": "noul", "noul": 0.95 }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

noul: 0.95 означает, что модель оценивает вероятность ответа «да» в 95%. Порог выбираете вы. Например: больше 0,8 — сразу в работу, от 0,4 до 0,8 — на проверку человеку, ниже 0,4 — в обычную очередь.

Поле model показывает, какая версия ответила. Алиас jev-latest сейчас указывает на jev-1.13.0, но при следующем релизе переключится. Если вы подобрали пороги под конкретную версию, указывайте в запросе её, а не алиас.

Обратите внимание на input_tokens: даже короткий запрос тянет около 280 служебных токенов. Учитывайте это в расчётах, в чём поможет наш калькулятор стоимости.

Шаг 6. Задайте несколько вопросов сразу

В одном запросе можно смешивать вопросы всех трёх типов. Они считаются параллельно, поэтому время ответа почти не растёт, а состояние и служебные токены оплачиваются один раз. Вот тот же тикет с тремя вопросами:

{
  "model": "jev-latest",
  "state": "Помогите! Выплаты не проходят уже третий день.",
  "questions": {
    "is_urgent": { "type": "noul", "instructions": "Клиент сообщает о срочной проблеме?" },
    "department": {
      "type": "choice",
      "instructions": "Какая команда должна заняться обращением?",
      "criteria": {
        "billing": "Платежи, счета, возвраты",
        "technical": "Ошибки, сбои, интеграции",
        "other": null
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "Насколько раздражён клиент?",
      "criteria": ["Спокоен", "Раздражён, но вежлив", "Очень зол"]
    }
  }
}

Как читать ответ на Choice и Score

Для Choice модель возвращает choice — вариант с наибольшей вероятностью, probabilities — вероятности всех вариантов (в сумме 1) и confidence — насколько лидер оторвался от остальных. Для Score приходит score — положение на шкале, которое может оказаться между уровнями, например 1,4. Поле legend напоминает, что означает каждый уровень, а probabilities показывает распределение по уровням.

У Noul отдельного confidence нет: само значение noul и есть вероятность ответа «да». Практическое правило для всех трёх типов: действуйте автоматически, только когда модель уверена, а сомнительные ответы отправляйте на проверку. Как выбрать тип вопроса под задачу, разбираем в статье о примитивах Jev.

Шаг 7. Подключите SDK

Для рабочего кода удобнее официальные библиотеки:

• Python (версия 3.10 и новее): pip install typesafe-sdk, синхронный клиент TypeSafeClient и асинхронный AsyncTypeSafeClient.
• JavaScript и TypeScript (Node.js 20 и новее): npm install @typesafe-ai/sdk, типы ответов выводятся из вопросов автоматически.

Минимальный пример на Python:

from typesafe_sdk import Noul, TypeSafeClient

client = TypeSafeClient()  # ключ берётся из TYPESAFE_API_KEY
response = client.system_one(
    state="Помогите! Выплаты не проходят уже третий день.",
    questions={"is_urgent": Noul(instructions="Это срочное обращение?")},
)
print(response.nouls["is_urgent"].noul)

SDK по умолчанию обращаются к jev-latest и сами повторяют запрос с растущей задержкой, если упёрлись в лимит. Подробности — в руководстве по Jev на Python.

Если что-то пошло не так

Код	Что значит	Что делать
401	Ключа нет или он неверный	Проверьте заголовок Authorization и переменную окружения
422	Запрос не прошёл проверку	Прочитайте тело ответа: там указано поле с ошибкой
429	Превышен лимит запросов	Повторите запрос с экспоненциальной задержкой
529	Сервис перегружен	Повторите позже, тоже с растущей задержкой

Лимиты TypeSafe сейчас — 1200 запросов в минуту и 250 тысяч токенов в секунду, но компания предупреждает, что может менять их без уведомления. Разбор ошибок с примерами кода — в статье об ошибках API Jev.

Как сформулировать вопрос

Модель читает инструкции буквально, поэтому формулировка влияет на результат сильнее, чем кажется. Несколько примеров:

Плохо	Лучше	Почему
«Это важное письмо?»	«Письмо требует ответа сегодня?»	«Важное» каждый понимает по-своему
«Это срочная жалоба на оплату?»	Три вопроса: срочность, жалоба, оплата	Один ответ скрывает три суждения
«Клиент не против возврата?»	«Клиент просит вернуть деньги?»	Отрицания и косвенные вопросы снижают точность
«Сколько товаров в заказе?»	Посчитать в коде	Jev ненадёжно считает
«Оцени тон» без уровней	Score с уровнями «спокоен», «раздражён», «очень зол»	Описанные уровни дают стабильную оценку

Если варианты Choice похожи, опишите в criteria, чем каждый отличается от соседнего. Документация TypeSafe советует указать для каждого варианта, что он охватывает, что к нему не относится, и привести пару примеров.

Советы для начала

• Добавляйте в Choice вариант «другое», если список может не покрыть все случаи.
• Отправляйте в state только то, что нужно для решения. Посторонний текст, по данным TypeSafe, снижает точность.
• Считайте в коде: арифметику, даты и подсчёт элементов модель выполняет ненадёжно.
• Пишите на удобном языке, но проверяйте качество на своих данных: основной язык обучения Jev — английский.
• Сразу решите, что делать при низкой уверенности. Об этом — в статье об уверенности Jev.
• Прогоните 100–200 реальных примеров и сравните ответы с ручной разметкой, прежде чем выпускать в продакшн.

Перед запуском в продакшн

Когда первые запросы заработали, проверьте ещё пять вещей:

1. Логи. Сохраняйте поле model, вопросы и вероятности каждого ответа. По ним потом видно, на каких входах модель ошибается.
2. Версия. Закрепите версию, под которую подбирали пороги, и переходите на новую осознанно, после повторной проверки.
3. Мониторинг уверенности. Следите за долей ответов с низкой уверенностью. Её рост — сигнал, что поток изменился или инструкция устарела.
4. Запасной путь. На случай ошибок 429 и 529 предусмотрите очередь, повтор или обработку простым правилом.
5. Данные. Не отправляйте персональные данные без обезличивания: запросы уходят на серверы за рубежом.