Reasoning Tokens

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

В примерах ниже $TEXT_MODEL — переменная окружения с идентификатором модели из GET /api/v1/models. Идентификаторы не зашивают в код: состав каталога меняется. Разбор — в разделе Модели и цены.

Что это такое

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

Время до первого токена заметно больше, чем у обычной модели. При stream: true это нормально, а не зависание.
Текст рассуждений не обязателен в ответе — см. раздел ниже.
Стоимость растёт вместе с глубиной рассуждения, иногда в разы относительно обычного ответа той же длины.

Включение: `reasoning_effort`

Есть два равнозначных способа задать глубину. Значение effort, отличное от none, включает рассуждение.

{ "reasoning_effort": "medium" }

{ "reasoning": { "effort": "medium" } }

Уровни:

`effort`	Когда подходит
`none`	Рассуждение выключено
`minimal`	Короткое уточнение входа, почти без развёрнутого хода
`low`	Простая задача с парой шагов: перевод, короткий расчёт, классификация с логикой
`medium`	Задача с несколькими зависимыми шагами, разбор условия, типовой рабочий запрос
`high`	Сложный вывод: математика, многошаговый план, противоречия в условии, код с неочевидной логикой

Полная форма объекта reasoning:

{
  "reasoning": {
    "enabled": true,
    "effort": "high",
    "max_tokens": 4000,
    "summary": "auto",
    "display": "collapsed"
  }
}

Поле	Что делает
`enabled`	Явное включение рассуждения
`effort`	Уровень глубины, см. таблицу выше
`max_tokens`	Потолок токенов рассуждения
`summary`	Нужна ли сводка рассуждений
`display`	Как показывать рассуждение в интерфейсе

reasoning_effort и reasoning.effort задавать одновременно нельзя — придёт 400 invalid_request. Это две записи одного параметра, и API считает их конфликтом, а не повторением. Пользуйтесь чем-то одним; краткая форма удобнее.

Ответ

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "reasoning_effort": "medium",
    "messages": [{"role": "user", "content": "Верни 100 граммов воды при 25 °C. Объясни ход."}]
  }' | jq '{
    reasoning: .choices[0].message.reasoning,
    answer: .choices[0].message.content,
    reasoning_tokens: .usage.completion_tokens_details.reasoning_tokens,
    cost: .usage.cost.total_cost
  }'

{
  "message": {
    "role": "assistant",
    "reasoning": "Плотность воды при 25 °C около 0,997 г/мл. V = 100 / 0,997 ≈ 100,3 мл.",
    "reasoning_content": "Плотность воды при 25 °C около 0,997 г/мл. V = 100 / 0,997 ≈ 100,3 мл.",
    "content": "При 25 °C это примерно 100,3 мл."
  },
  "usage": {
    "completion_tokens": 180,
    "completion_tokens_details": { "reasoning_tokens": 142 },
    "cost": { "total_cost": 0.0047 }
  }
}

Где	Поле
Текст рассуждений	`choices[0].message.reasoning`
То же самое, второй ключ	`choices[0].message.reasoning_content`
В потоке	`delta.reasoning` и `delta.reasoning_content`
Объём	`usage.completion_tokens_details.reasoning_tokens`

reasoning и reasoning_content — один и тот же текст под двумя именами. Дублирование сделано для совместимости с разными SDK: часть читает reasoning, часть — reasoning_content. Берите любое, но не складывайте.

Сколько токенов ушло на рассуждение

usage.completion_tokens_details.reasoning_tokens — объём рассуждения. Это подмножество completion_tokens, а не отдельная категория сверх него.

Python

usage = response["usage"]
reasoning = usage["completion_tokens_details"]["reasoning_tokens"]
completion = usage["completion_tokens"]

# сложение здесь не нужно — reasoning_tokens уже входит в completion_tokens
assert reasoning <= completion

Прибавлять reasoning_tokens к completion_tokens при расчёте объёма нельзя: получите двойной счёт. Рассуждение — часть выхода.

Стоимость

Рассуждение тарифицируется по ставке выходных токенов, а у рассуждающих моделей выход обычно дороже всего. Механика простая: поднимаете effort — платите больше, потому что модель производит больше выходных токенов. Иллюстрация без конкретных цен: при cost_completion из каталога и ответе, где 150 из 400 выходных токенов пришлись на рассуждение, в счёт уйдут все 400 по выходной ставке. Поднятие effort с low до high на одной и той же задаче обычно даёт рост выхода в разы при практически неизменном входе.

Python

# доля рассуждения в выходе — полезная метрика при выборе effort
usage = response["usage"]
out = usage["completion_tokens"]
reasoning = usage["completion_tokens_details"]["reasoning_tokens"]
print(f"рассуждение: {reasoning}/{out} = {reasoning / out:.0%} выхода")

Практический вывод: эффективность определяется не максимальным effort, а минимальным, который решает задачу. На большинстве запросов low или medium дают тот же итоговый ответ, что и high, за в разы меньшую цену. Замерьте на своей выборке запросов долю рассуждения и итоговое качество — вместе.

Выбор уровня по классу задачи

Класс задачи	Разумный старт	Комментарий
Классификация, извлечение полей, перевод, пересказ	`low` или `minimal`	Рассуждение почти не помогает, а токены тратятся
Ответ по документу, суммаризация с выводами	`low`	Хватает пробега по структуре
Многошаговый расчёт, план, разбор условия	`medium`	Рабочая точка большинства задач
Формальная математика, сложный код, поиск противоречий	`high`	Здесь разница в качестве обычно видна
Творческий текст, переписывание	`none`	Рассуждение часто ухудшает результат

Высокий effort не делает модель «умнее в целом» — он даёт ей больше места на вывод. Если задача не выигрывает от развёрнутого хода мысли, вы платите за пустые токены.

Рассуждение может не вернуться

Текст рассуждений приходит не всегда, даже при явно заданном effort. Часть моделей возвращает только итоговый ответ, часть — сокращённую сводку, часть — ничего. Поле reasoning_tokens при этом может быть ненулевым, то есть токены потрачены, а текст вам не показан.

Поэтому:

не стройте продукт, который показывает ход мысли пользователю — можете получить пустой блок;
не рассчитывайте стоимость по видимому тексту: сверяйтесь с usage;
для отладки используйте usage.completion_tokens_details.reasoning_tokens как признак того, что рассуждение шло.

В потоке

for line in response.iter_lines():
    if not line or not line.startswith(b"data: "):
        continue
    payload = line[len(b"data: "):]
    if payload == b"[DONE]":
        break
    chunk = json.loads(payload)
    if "error" in chunk:
        raise RuntimeError(chunk["error"]["message"])

    for choice in chunk.get("choices", []):
        delta = choice.get("delta", {})
        if delta.get("reasoning"):
            print(delta["reasoning"], end="", flush=True)   # ход мысли
        elif delta.get("content"):
            print(delta["content"], end="", flush=True)     # ответ

Разбор потока целиком — на странице Потоковая передача.

Что дальше

Модели и цены

Ставка за выход и контекстное окно

Учёт средств

Как читать usage и cost

Кэширование

Снижение цены длинного стабильного префикса

Запрос чату

Поля reasoning и reasoning_effort

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Что это такое

Включение: `reasoning_effort`

Ответ

Сколько токенов ушло на рассуждение

Стоимость

Выбор уровня по классу задачи

Рассуждение может не вернуться

В потоке

Что дальше

Модели и цены

Учёт средств

Кэширование

Запрос чату

​Что это такое

​Включение: reasoning_effort

​Ответ

​Сколько токенов ушло на рассуждение

​Стоимость

​Выбор уровня по классу задачи

​Рассуждение может не вернуться

​В потоке

​Что дальше

Модели и цены

Учёт средств

Кэширование

Запрос чату

Что это такое

Включение: `reasoning_effort`

Ответ

Сколько токенов ушло на рассуждение

Стоимость

Выбор уровня по классу задачи

Рассуждение может не вернуться

В потоке

Что дальше