Расширенные размышления

«Extended thinking» (расширенные размышления) в ручном режиме дают вам прямой контроль над тем, сколько Claude думает. Вы задаёте бюджет токенов размышлений в каждом запросе с помощью thinking: {type: "enabled", budget_tokens: N}, и Claude думает в рамках этого бюджета, прежде чем приступить к окончательному ответу. Ручной режим остаётся полезным, когда ваша рабочая нагрузка требует предсказуемой задержки или точного контроля над затратами на размышления. На этой странице рассказывается, как задавать и настраивать бюджет, как ручной режим взаимодействует с чередующимися размышлениями и «prompt caching» (кэшированием подсказок), а также как перейти на адаптивные размышления.

Чтобы узнать, как работают сами размышления, включая блоки размышлений и форму ответа, параметр display, «streaming» (потоковую передачу), размышления с «tool use» (использованием инструментов) и шифрование, см. обзор размышлений.

Поддерживаемые модели

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

Как использовать расширенные размышления

Вот пример использования расширенных размышлений в Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# Ответ содержит блоки с кратким изложением размышлений и текстовые блоки
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Чтобы включить ручные расширенные размышления, добавьте объект thinking с параметром type, установленным в enabled, и значением budget_tokens.

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

Правила и настройка бюджета

budget_tokens должен удовлетворять следующим ограничениям:

• Минимум 1 024 токена. API отклоняет меньшие значения.
• Меньше, чем max_tokens. Токены размышлений учитываются в лимите max_tokens для хода, поэтому бюджет должен оставлять место для окончательного ответа. Единственное исключение — чередующиеся размышления, где budget_tokens может превышать max_tokens, поскольку бюджет распространяется на все блоки размышлений в рамках одного хода ассистента.
• Без предварительного прогрева кэша. Поскольку budget_tokens должен быть меньше max_tokens, расширенные размышления нельзя сочетать с max_tokens: 0 (предварительный прогрев кэша).

Бюджет — это целевое значение, а не строгий предел. Фактическое использование токенов зависит от задачи, и Claude может прекратить рассуждение задолго до исчерпания бюджета; max_tokens остаётся жёстким потолком для общего объёма вывода.

На Claude Opus 4.5, единственной модели только с расширенными размышлениями, которая поддерживает effort, effort формирует общий ответ, а budget_tokens задаёт глубину размышлений; задавайте оба параметра.

Чтобы настроить бюджет:

• Подбирайте отправную точку под задачу. Для простых задач начинайте вблизи минимума в 1 024 токена и постепенно увеличивайте, чтобы найти оптимальный диапазон для вашего сценария использования. Для сложных задач начинайте с большего бюджета в 16 000 токенов или более и корректируйте в соответствии с вашими требованиями к задержке и качеству. Более высокие бюджеты позволяют проводить более всестороннее рассуждение с убывающей отдачей, зависящей от задачи, и ценой увеличенной задержки. Для критически важных задач протестируйте разные настройки, чтобы найти правильный баланс.
• Для бюджетов размышлений свыше 32k используйте пакетную обработку, чтобы избежать сетевых проблем. Принуждение модели думать более чем на 32k токенов порождает длительные запросы, которые могут столкнуться с системными тайм-аутами и лимитами открытых соединений.

Чтобы отслеживать, во что вам фактически обходится бюджет, следите за полем usage.output_tokens_details.thinking_tokens в ответе, которое сообщает, сколько из оплачиваемых выходных токенов пришлось на внутреннее рассуждение. При потоковой передаче эта разбивка появляется только в финальном событии message_delta.

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

Чередующиеся размышления в ручном режиме

«Interleaved thinking» (чередующиеся размышления) позволяют Claude думать между вызовами инструментов в рамках одного хода ассистента, рассуждая о каждом результате инструмента, прежде чем решить, что делать дальше. О самой концепции, структуре хода и о том, как они ведут себя на моделях с адаптивными размышлениями, см. чередующиеся размышления в обзоре размышлений. В этом разделе рассказывается, как включить их при использовании ручных размышлений type: "enabled".

В Claude Opus 4.5, Claude Sonnet 4.5 и более ранних моделях Claude 4 добавьте «beta header» (бета-заголовок) interleaved-thinking-2025-05-14 в ваш запрос к API.

Поколение 4.6 в ручном режиме разделяется:

• Claude Sonnet 4.6: бета-заголовок с ручным type: "enabled" по-прежнему работает, но объявлен устаревшим. Предпочитайте адаптивные размышления, которые чередуются автоматически без заголовка.
• Claude Opus 4.6: в ручном режиме чередующихся размышлений нет вообще. Чередуется только его адаптивный режим, поэтому переключитесь на thinking: {type: "adaptive"}, если вам нужно рассуждение между вызовами инструментов на этой модели.

Claude Haiku 4.5 не поддерживает чередующиеся размышления. В Claude API бета-заголовок принимается, но игнорируется.

Ещё два соображения для чередующихся размышлений в ручном режиме:

• budget_tokens здесь может превышать max_tokens; правила бюджета объясняют это исключение.
• Чередующиеся размышления поддерживаются только для инструментов, используемых через Messages API.

Платформы обрабатывают бета-заголовок по-разному. Claude API и Claude Platform на AWS принимают interleaved-thinking-2025-05-14 на любой модели и игнорируют его там, где он не поддерживается. Принятие — не то же самое, что эффект: на моделях, которые отклоняют type: "enabled" (4.7 и новее) или не имеют чередования в ручном режиме (Claude Opus 4.6), заголовок не оказывает эффекта в ручном режиме; адаптивные размышления там чередуются автоматически.

Платформы, управляемые партнёрами (Amazon Bedrock и Google Cloud), аналогично принимают заголовок на любой модели, не возвращая ошибку, и игнорируют его на моделях, которые не поддерживают чередующиеся размышления.

Структура хода в ручном режиме

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

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

Кэширование подсказок в ручном режиме

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

На практике выберите бюджет и держите его стабильным на протяжении всей жизни кэшированного разговора. Запуск многоходового разговора с кэшированием на уровне сообщений на Claude Sonnet 4.6 и изменение бюджета в третьем запросе с 4 000 до 8 000 токенов наглядно показывает инвалидацию:

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

Третий запрос заново создаёт кэш (cache_creation_input_tokens=1370, cache_read_input_tokens=0), поскольку бюджет изменился между запросами. Запускаемую версию того же эксперимента в адаптивном режиме, где уровень effort играет ту же роль для кэша, что и budget_tokens здесь, см. в разделе Кэширование подсказок на странице управления размышлениями.

Общая механика

Большая часть поведения размышлений не зависит от режима и документирована один раз на странице Размышления. Всё, что там описано, применимо и в ручном режиме:

• Управление отображением размышлений
• Потоковая передача размышлений
• Размышления при использовании инструментов, включая сохранение блоков размышлений
• Размышления и кэширование подсказок
• Размышления и контекстное окно
• Шифрование размышлений
• Цены (на странице Управление размышлениями)

Переход на адаптивные размышления

Если ваша модель поддерживает только расширенные размышления (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 и более ранние модели Claude 4), сейчас никаких действий не требуется: адаптивные размышления там недоступны, и type: "adaptive" возвращает ошибку 400. Сохраняйте budget_tokens, пока не перейдёте на модель, поддерживающую адаптивные размышления, а затем примените приведённое ниже сопоставление.

Вам необходимо отказаться от type: "enabled", если:

• Вы используете Claude Opus 4.6 или Claude Sonnet 4.6, где budget_tokens устарел.
• Вы используете Claude 4.7 или более позднюю модель, например Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5 или Claude Fable 5.1, где type: "enabled" возвращает ошибку 400.

Сопоставление простое: удалите budget_tokens, задайте thinking: {type: "adaptive"} и управляйте глубиной рассуждения с помощью output_config: {effort: ...} вместо бюджета токенов.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

превращается в:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" совпадает со значением API по умолчанию: он указан здесь только для того, чтобы показать, где теперь задаётся глубина рассуждения, а если его опустить, поведение не изменится.

Ожидайте изменения поведения, а не только синтаксиса. При фиксированном бюджете Claude думает в каждом запросе. При адаптивных размышлениях Claude сам решает, думать ли и сколько думать в каждом запросе, а при более низких настройках effort может полностью пропускать размышления для простых входных данных. После перехода вы также можете удалить бета-заголовок interleaved-thinking-2025-05-14: адаптивные размышления чередуются автоматически, а Claude API игнорирует этот заголовок на этих моделях. Меняется и сохранение блоков размышлений: Claude Opus 4.5 и модели с номером 4.6 и выше сохраняют блоки размышлений предыдущих ходов в контексте и тарифицируют их как входные данные, тогда как Claude Sonnet 4.5, Claude Haiku 4.5 и более ранние модели их удаляли; см. сохранение блоков размышлений по моделям.

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

Полное руководство см. в разделах адаптивные размышления, effort и в руководстве по миграции моделей.

Следующие шаги