Рассуждающие модели reasoning_effort Расширенное мышление OpenAI API Claude API

Параметры API рассуждающих моделей: сравнение по провайдерам

reasoning_effort у OpenAI, thinking у Anthropic и thinkingBudget у Gemini — все управляют скрытыми токенами рассуждения, оплачиваемыми как вывод. Как работает каждая ручка и чем они различаются.

AveMujica API 15 июл. 2026 г. 8 мин чтения

Рассуждающие модели добавляют шаг, который вы не видите: прежде чем написать ответ, модель производит скрытые токены рассуждения, и эти токены стоят денег, потребляют контекстное окно и добавляют задержку. Каждый провайдер даёт вам циферблат для управления тем, сколько этого происходит, но три циферблата имеют разные имена, разные шкалы значений и разные значения по умолчанию — reasoning_effort у OpenAI, thinking у Anthropic, thinkingConfig у Gemini. Правильно обращаться с рассуждающими моделями — это в основном про понимание этих трёх ручек и одного общего факта: токены рассуждения выставляются как выходные токены, хотя вы их никогда не читаете. Эта статья проходит по параметрам каждого провайдера, полям использования, которые раскрывают скрытую стоимость, и по местам, где абстракции перестают совпадать.

Общая ментальная модель

Независимо от провайдера, у рассуждающего запроса одна и та же анатомия. Ваши входные токены идут внутрь. Модель генерирует два вида вывода: скрытые токены рассуждения и видимые токены ответа. Оба выставляются по ставке за выход, оба считаются против контекстного окна модели, и только видимые возвращаются вам (опционально в сопровождении сводки рассуждения, но никогда сырого рассуждения на большинстве моделей). Циферблат, который предоставляет каждый провайдер, меняет то, сколько скрытых токенов модель готова потратить. Выкрутите его вверх для трудных задач и многошаговых агентных циклов; выкрутите вниз для чувствительных к задержке, неглубоких задач. Всё, что ниже, — вариация на эту тему.

OpenAI: `reasoning_effort` и объект `reasoning`

На рассуждающих моделях OpenAI вы задаёте усилие. Chat Completions принимает строку reasoning_effort верхнего уровня; Responses API принимает объект reasoning, чьё поле effort делает ту же работу и добавляет место для сводки и контролов контекста.

from openai import OpenAI
client = OpenAI(base_url="https://your-gateway.example.com/v1", api_key="AVE_GATEWAY_API_KEY")

# Responses API
resp = client.responses.create(
    model="gpt-5.6",
    input="Prove there are infinitely many primes p with p mod 4 == 3.",
    reasoning={"effort": "high", "summary": "auto"},
)

Значения усилия зависят от модели и могут включать none, minimal, low, medium, high и xhigh; значение по умолчанию варьируется по модели. Меньшее усилие приоритезирует скорость и меньше токенов, большее усилие даёт более тщательный вывод по большей стоимости. Скрытая работа замеряется: токены рассуждения появляются в usage под output_tokens_details как reasoning_tokens, так что вы можете наблюдать невидимые траты, хотя сами токены удерживаются. Чтобы увидеть, почему модель что-то заключила, запросите сводку (summary: "auto" или "detailed"), которая возвращает сводный след рассуждения в элементе вывода reasoning — вы должны подписаться на это; он не включён по умолчанию.

Две фичи важны для stateless- и агентных сетапов. Для работы с нулевым удержанием отправьте store: false и добавьте reasoning.encrypted_content в массив include; API возвращает зашифрованное рассуждение, которое вы передаёте обратно на следующем ходу, чтобы сохранить непрерывность без хранения сервером чего-либо. А reasoning.context (auto, current_turn или all_turns) управляет тем, на какие предыдущие элементы рассуждения модель может опираться в цепочечной беседе.

Параметр, о котором нельзя забывать, — max_output_tokens. Он ограничивает общее число сгенерированных токенов — рассуждение плюс видимый ответ, — так что если вы установите его слишком низко, бюджет может быть целиком поглощён скрытым рассуждением и вы получите status равный incomplete (с incomplete_details, ссылающимися на max_output_tokens) и никакого видимого текста, при этом всё равно платя за входные токены и токены рассуждения. OpenAI рекомендует резервировать щедрый запас (порядка десятков тысяч токенов) под рассуждение плюс вывод, когда вы начинаете. Бюджетирование этого запаса — та же дисциплина, что описана в управлении контекстным окном LLM.

Anthropic: от `budget_tokens` к адаптивному мышлению

Расширенное мышление Anthropic исторически использовало явный бюджет токенов. Вы включаете его объектом thinking с type: "enabled" и пределом budget_tokens:

import anthropic
client = anthropic.Anthropic(base_url="https://your-gateway.example.com", api_key="AVE_GATEWAY_API_KEY")

msg = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "Are there infinitely many primes p with p mod 4 == 3?"}],
)

Три правила управляют budget_tokens. Он задаёт максимум токенов для внутреннего рассуждения и должен быть меньше max_tokens (кроме случая, когда чередующееся мышление с инструментами позволяет пределу стать всем контекстным окном). Модель может не использовать весь бюджет, особенно при больших значениях. И рассуждение всплывает как блоки контента thinking — каждый несёт текст thinking и signature — перед блоками text; вам выставляют счёт за полные сгенерированные токены мышления, а не за более короткую сводку, так что оплаченное число выходных токенов не совпадёт с тем, что вы видите визуально.

Есть важное разделение по версиям, которое стоит планировать. budget_tokens уходит на пенсию: он объявлен устаревшим на некоторых текущих моделях и возвращает 400 на новейших (например, поколение Opus 4.8/4.7 и Sonnet 5), которые вместо этого используют адаптивное мышление — объект thinking с type: "adaptive" в паре с настройкой усилия, концептуально приближая Anthropic к циферблату усилия OpenAI. Когда вы строите, ветвитесь по модели: отправляйте budget_tokens моделям, которые его ещё принимают, и адаптивную форму / форму усилия тем, которые её требуют. Шлюз может частично это скрыть, как показывает следующий раздел.

Одно правило использования инструментов не подлежит обсуждению: во время цикла инструментов вы должны передать блоки thinking модели обратно неизменёнными в следующем сообщении ассистента, или API отклонит запрос с 400. Блоки кодируют рассуждение, приведшее к вызову инструмента, и переупорядочивание или редактирование их ломает непрерывность. Это зеркалит совет OpenAI возвращать элементы рассуждения с вызовами функций, и именно поэтому переносимый вызов инструментов между провайдерами трактует сохранение блоков рассуждения как часть корректного цикла инструментов.

Gemini: `thinkingConfig` и `thinkingBudget`

Gemini управляет рассуждением через thinkingConfig внутри generationConfig. Ключевое поле — thinkingBudget, допуск токенов на мышление, с двумя специальными значениями: -1 позволяет модели решать динамически, а (на моделях, допускающих отключение) 0 выключает мышление. Флаг includeThoughts просит API вернуть сводку мыслей. Израсходованное рассуждение появляется в usageMetadata как счётчик токенов мыслей, снова выставляемый как вывод.

from google import genai
from google.genai import types

client = genai.Client()
resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Are there infinitely many primes p with p mod 4 == 3?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=-1, include_thoughts=True),
    ),
)

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

Что нормализует шлюз и где он останавливается

За одним OpenAI-совместимым эндпоинтом шлюз пробрасывает параметры рассуждения каждого провайдера той вышестоящей стороне, что их понимает: reasoning_effort и объект reasoning — в OpenAI, thinking — в Anthropic, thinkingConfig — в Gemini. Он также сворачивает три разных счётчика скрытых токенов в единый взгляд на использование, поэтому реальная стоимость вывода рассуждающего запроса видна в ваших журналах независимо от того, какой вендор его обслужил.

Этот шлюз дополнительно предлагает удобство, о котором стоит знать: он может распарсить суффикс усилия в имени модели и перевести его в собственный параметр рассуждения провайдера. Добавление -high, -medium, -low, -minimal, -xhigh или -max к id модели (например, claude-opus-4-8-high или вариант -thinking) позволяет клиенту, который может задать только строку модели, всё же выбрать уровень усилия, и шлюз отображает этот суффикс на правильную ручку для целевого провайдера. Зарегистрированные варианты моделей и усилий вместе с их тарифами опубликованы на открытой странице тарифов.

Говорите прямо о пределах, потому что абстракции по-настоящему не совпадают:

Шкалы разные. effort у OpenAI — перечисление, устаревший budget_tokens у Anthropic — абсолютный счётчик токенов, а thinkingBudget у Gemini — счётчик токенов со значениями-часовыми. «Высокое усилие» и «10 000 бюджетных токенов» не являются переводами друг друга; отображение одного на другое — эвристика, а не эквивалентность.
Значения по умолчанию различаются. Некоторые модели рассуждают по умолчанию, некоторые нет, и усилие по умолчанию специфично для модели. Не предполагайте, что молчание означает «нет рассуждения».
Покрытие фич различается. Непрерывность зашифрованного рассуждения, сводки мыслей и отключение мышления поддерживаются неравномерно у разных провайдеров. Шлюз может пробросить поле, но не может заставить провайдера чтить возможность, которую он не предлагает.

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

Практические значения по умолчанию

Несколько стартовых правил экономят деньги и задержку:

Сопоставляйте усилие с глубиной задачи, а не с важностью. Трудному извлечению нужно больше рассуждения, чем длинному, но неглубокому суммированию. Усилие — про структуру проблемы, а не про ставки.
Всегда резервируйте запас под вывод. С любой рассуждающей моделью устанавливайте предел max-output достаточно высоким, чтобы скрытое рассуждение не могло заморить видимый ответ, иначе вы заплатите за рассуждение и получите ничего.
Измеряйте скрытые токены. Наблюдайте за reasoning_tokens / токенами мышления в ваших логах использования; задача, чьи токены рассуждения затмевают токены ответа, — кандидат на меньшее усилие или нерассуждающую модель, решение, рассмотренное в выборе правильной LLM-модели.

FAQ

Оплачиваются ли токены рассуждения, хотя я их никогда не вижу?

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

Почему я получил пустой или неполный ответ от рассуждающей модели?

Обычно предел вывода был слишком низким и рассуждение поглотило весь бюджет. OpenAI возвращает status равный incomplete со ссылкой на max_output_tokens; Anthropic требует, чтобы budget_tokens был меньше max_tokens. Поднимите общий предел вывода, чтобы скрытое рассуждение не могло заморить видимый ответ, и резервируйте щедрый запас на рассуждающих маршрутах.

`budget_tokens` у Anthropic — то же, что `reasoning_effort` у OpenAI?

Они служат одной цели, но не эквивалентны. reasoning_effort — это перечисление (low/medium/high и связанные значения); budget_tokens — абсолютный счётчик токенов. На новейших моделях Anthropic budget_tokens не поддерживается, и его заменяет адаптивное мышление с настройкой усилия. Шлюз может отобразить метку усилия на параметр провайдера, но отображение приблизительно, а не перевод один-к-одному.

Как задать уровень рассуждения, если мой клиент может отправить только имя модели?

Используйте суффикс усилия шлюза. Добавьте -high, -medium, -low, -minimal, -xhigh или -max к id модели, и шлюз распарсит его и применит подходящий параметр рассуждения для целевого провайдера. Это позволяет тонким клиентам выбрать уровень усилия, не отправляя специфичное для провайдера поле самим.

Найдите точку перегиба усилия на своей задаче

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