Разработка с расширенным мышлением

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

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

Расширенное мышление поддерживается в следующих моделях:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (устарела)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Как работает расширенное мышление

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

Ответ API будет включать блоки содержимого thinking, за которыми следуют блоки содержимого text.

Вот пример формата ответа по умолчанию:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Для получения дополнительной информации о формате ответа расширенного мышления см. Справочник API Messages.

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

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "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?"
        }
    ]
}'

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

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

budget_tokens должен быть установлен на значение меньше, чем max_tokens. Однако при использовании чередующегося мышления с инструментами вы можете превысить это ограничение, так как лимит токенов становится вашим полным контекстным окном (200k токенов).

Суммированное мышление

С включённым расширенным мышлением Messages API для моделей Claude 4 возвращает сводку полного процесса мышления Claude. Суммированное мышление обеспечивает полные преимущества интеллекта расширенного мышления, предотвращая неправомерное использование.

Вот некоторые важные соображения для суммированного мышления:

• Вам выставляется счёт за полные токены мышления, созданные исходным запросом, а не за токены сводки.
• Количество выставленных токенов вывода не будет совпадать с количеством токенов, которые вы видите в ответе.
• Первые несколько строк вывода мышления более подробны, предоставляя детальное рассуждение, которое особенно полезно для целей инженерии подсказок.
• По мере того как Anthropic стремится улучшить функцию расширенного мышления, поведение суммирования может измениться.
• Суммирование сохраняет ключевые идеи процесса мышления Claude с минимальной добавленной задержкой, обеспечивая потоковый пользовательский опыт и простую миграцию с Claude Sonnet 3.7 на модели Claude 4.
• Суммирование обрабатывается другой моделью, чем та, которую вы указываете в своих запросах. Модель мышления не видит суммированный вывод.

Потоковое мышление

Вы можете передавать ответы расширенного мышления потоком, используя события, отправляемые сервером (SSE).

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

Для получения дополнительной документации по потоковой передаче через Messages API см. Потоковая передача сообщений.

Вот как обрабатывать потоковую передачу с мышлением:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

Пример вывода потоковой передачи:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-5", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Расширенное мышление с использованием инструментов

Расширенное мышление можно использовать наряду с использованием инструментов, позволяя Claude рассуждать о выборе инструмента и обработке результатов.

При использовании расширенного мышления с использованием инструментов помните о следующих ограничениях:

1. Ограничение выбора инструмента: Использование инструментов с мышлением поддерживает только tool_choice: {"type": "auto"} (по умолчанию) или tool_choice: {"type": "none"}. Использование tool_choice: {"type": "any"} или tool_choice: {"type": "tool", "name": "..."} приведёт к ошибке, потому что эти опции принуждают использование инструментов, что несовместимо с расширенным мышлением.

2. Сохранение блоков мышления: Во время использования инструментов вы должны передать блоки thinking обратно в API для последнего сообщения помощника. Включите полный неизменённый блок обратно в API для сохранения непрерывности рассуждения.

Переключение режимов мышления в разговорах

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

• Если мышление включено, последний ход помощника должен начинаться с блока мышления.
• Если мышление отключено, последний ход помощника не должен содержать никаких блоков мышления

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

Например, эта последовательность является частью одного хода помощника:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

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

Распространённые сценарии ошибок

Вы можете столкнуться с этой ошибкой:

Expected `thinking` or `redacted_thinking`, but found `tool_use`.
When `thinking` is enabled, a final `assistant` message must start
with a thinking block (preceding the lastmost set of `tool_use` and
`tool_result` blocks).

Это обычно происходит, когда:

1. У вас было мышление отключено во время последовательности использования инструментов
2. Вы хотите включить мышление снова
3. Ваше последнее сообщение помощника содержит блоки использования инструментов, но нет блока мышления

Практическое руководство

✗ Неправильно: Переключение мышления сразу после использования инструмента

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
// Cannot enable thinking here - still in the same assistant turn

✓ Правильно: Сначала завершите ход помощника

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"] 
User: "What about tomorrow?" (thinking disabled)
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

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

Сохранение блоков мышления

Во время использования инструментов вы должны передать блоки thinking обратно в API, и вы должны включить полный неизменённый блок обратно в API. Это критично для сохранения потока рассуждений модели и целостности разговора.

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

1. Непрерывность рассуждения: Блоки мышления захватывают пошаговое рассуждение Claude, которое привело к запросам инструментов. Когда вы отправляете результаты инструментов, включение исходного мышления гарантирует, что Claude может продолжить своё рассуждение с того места, где оно остановилось.

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

Важно: При предоставлении блоков thinking вся последовательность последовательных блоков thinking должна соответствовать выводам, созданным моделью во время исходного запроса; вы не можете переставлять или изменять последовательность этих блоков.

Чередующееся мышление

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

С чередующимся мышлением Claude может:

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

Чтобы включить чередующееся мышление, добавьте заголовок бета-версии interleaved-thinking-2025-05-14 в ваш запрос API.

Вот некоторые важные соображения для чередующегося мышления:

• С чередующимся мышлением budget_tokens может превышать параметр max_tokens, так как он представляет общий бюджет для всех блоков мышления в одном ходе помощника.
• Чередующееся мышление поддерживается только для инструментов, используемых через Messages API.
• Чередующееся мышление поддерживается только для моделей Claude 4 с заголовком бета-версии interleaved-thinking-2025-05-14.
• Прямые вызовы Claude API позволяют вам передавать interleaved-thinking-2025-05-14 в запросах к любой модели без эффекта.
• На платформах третьих сторон (например, Amazon Bedrock и Vertex AI), если вы передаёте interleaved-thinking-2025-05-14 к любой модели, кроме Claude Opus 4.1, Opus 4 или Sonnet 4, ваш запрос не пройдёт.

Расширенное мышление с кэшированием подсказок

Кэширование подсказок с мышлением имеет несколько важных соображений:

Удаление контекста блока мышления

• Блоки мышления из предыдущих ходов удаляются из контекста, что может повлиять на точки разрыва кэша
• При продолжении разговоров с использованием инструментов блоки мышления кэшируются и считаются входными токенами при чтении из кэша
• Это создаёт компромисс: хотя блоки мышления не потребляют пространство контекстного окна визуально, они всё ещё считаются в вашем использовании входных токенов при кэшировании
• Если мышление становится отключённым, запросы не пройдут, если вы передаёте содержимое мышления в текущем ходе использования инструментов. В других контекстах содержимое мышления, переданное в API, просто игнорируется

Паттерны инвалидации кэша

• Изменения параметров мышления (включено/отключено или распределение бюджета) делают недействительными точки разрыва кэша сообщений
• Чередующееся мышление усиливает инвалидацию кэша, так как блоки мышления могут возникать между несколькими вызовами инструментов
• Системные подсказки и инструменты остаются кэшированными несмотря на изменения параметров мышления или удаление блоков

Понимание поведения кэширования блока мышления

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

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

1. Кэширование происходит только при выполнении последующего запроса, который включает результаты инструментов
2. Когда выполняется последующий запрос, предыдущая история разговора (включая блоки мышления) может быть кэширована
3. Эти кэшированные блоки мышления считаются входными токенами в ваших метриках использования при чтении из кэша
4. Когда включен блок результата пользователя, не являющийся результатом инструмента, все предыдущие блоки мышления игнорируются и удаляются из контекста

Подробный пример потока:

Запрос 1:

User: "What's the weather in Paris?"

Ответ 1:

[thinking_block_1] + [tool_use block 1]

Запрос 2:

User: ["What's the weather in Paris?"], 
Assistant: [thinking_block_1] + [tool_use block 1], 
User: [tool_result_1, cache=True]

Ответ 2:

[thinking_block_2] + [text block 2]

Запрос 2 записывает кэш содержимого запроса (не ответа). Кэш включает исходное сообщение пользователя, первый блок мышления, блок использования инструмента и результат инструмента.

Запрос 3:

User: ["What's the weather in Paris?"], 
Assistant: [thinking_block_1] + [tool_use block 1], 
User: [tool_result_1, cache=True], 
Assistant: [thinking_block_2] + [text block 2], 
User: [Text response, cache=True]

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

User: ["What's the weather in Paris?"], 
Assistant: [tool_use block 1], 
User: [tool_result_1, cache=True], 
Assistant: [text block 2], 
User: [Text response, cache=True]

Ключевые моменты:

• Это поведение кэширования происходит автоматически, даже без явных маркеров cache_control
• Это поведение согласуется независимо от использования обычного мышления или чередующегося мышления

Максимальные токены и размер контекстного окна с расширенным мышлением

В более старых моделях Claude (до Claude Sonnet 3.7), если сумма токенов подсказки и max_tokens превышала контекстное окно модели, система автоматически регулировала max_tokens для соответствия ограничению контекста. Это означало, что вы могли установить большое значение max_tokens, и система молча уменьшала бы его по мере необходимости.

С моделями Claude 3.7 и 4 max_tokens (который включает ваш бюджет мышления при включённом мышлении) применяется как строгое ограничение. Система теперь вернёт ошибку валидации, если токены подсказки + max_tokens превышает размер контекстного окна.

Контекстное окно с расширенным мышлением

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

• Блоки мышления из предыдущих ходов удаляются и не считаются в вашем контекстном окне
• Мышление текущего хода считается в вашем лимите max_tokens для этого хода

Диаграмма ниже демонстрирует специализированное управление токенами при включённом расширенном мышлении:

Эффективное контекстное окно рассчитывается как:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

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

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

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

Расчёт эффективного контекстного окна для расширенного мышления с использованием инструментов становится:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Диаграмма ниже иллюстрирует управление токенами для расширенного мышления с использованием инструментов:

Управление токенами с расширенным мышлением

Учитывая поведение контекстного окна и max_tokens с расширенным мышлением моделей Claude 3.7 и 4, вам может потребоваться:

• Более активно отслеживать и управлять использованием токенов
• Регулировать значения max_tokens по мере изменения длины подсказки
• Потенциально использовать конечные точки подсчёта токенов более часто
• Помнить, что предыдущие блоки мышления не накапливаются в вашем контекстном окне

Это изменение было сделано для обеспечения более предсказуемого и прозрачного поведения, особенно поскольку максимальные лимиты токенов значительно увеличились.

Шифрование мышления

Полное содержимое мышления зашифровано и возвращено в поле signature. Это поле используется для проверки того, что блоки мышления были созданы Claude при передаче обратно в API.

Вот некоторые важные соображения по шифрованию мышления:

• При потоковой передаче ответов подпись добавляется через signature_delta внутри события content_block_delta непосредственно перед событием content_block_stop.
• Значения signature значительно длиннее в моделях Claude 4, чем в предыдущих моделях.
• Поле signature является непрозрачным полем и не должно интерпретироваться или анализироваться - оно существует исключительно в целях проверки.
• Значения signature совместимы между платформами (Claude APIs, Amazon Bedrock и Vertex AI). Значения, созданные на одной платформе, будут совместимы с другой.

Редакция мышления

Иногда внутреннее рассуждение Claude будет отмечено нашими системами безопасности. Когда это происходит, мы шифруем часть или всё содержимое блока thinking и возвращаем его вам как блок redacted_thinking. Блоки redacted_thinking расшифровываются при передаче обратно в API, позволяя Claude продолжить свой ответ без потери контекста.

При разработке приложений, ориентированных на клиентов, которые используют расширенное мышление:

• Помните, что блоки редактированного мышления содержат зашифрованное содержимое, которое не читается человеком
• Рассмотрите предоставление простого объяснения, такого как: "Часть внутреннего рассуждения Claude была автоматически зашифрована в целях безопасности. Это не влияет на качество ответов."
• Если показываете блоки мышления пользователям, вы можете отфильтровать редактированные блоки, сохраняя обычные блоки мышления
• Будьте прозрачны в том, что использование функций расширенного мышления может иногда привести к шифрованию некоторого рассуждения
• Реализуйте надлежащую обработку ошибок для корректного управления редактированным мышлением без нарушения вашего пользовательского интерфейса

Вот пример, показывающий как обычные, так и редактированные блоки мышления:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

При передаче блоков thinking и redacted_thinking обратно в API в многоходовом разговоре вы должны включить полный неизменённый блок обратно в API для последнего хода помощника. Это критично для сохранения потока рассуждений модели. Мы предлагаем всегда передавать все блоки мышления обратно в API. Для получения дополнительной информации см. раздел Сохранение блоков мышления выше.

Различия в мышлении между версиями моделей

Messages API обрабатывает мышление по-разному в моделях Claude Sonnet 3.7 и Claude 4, в основном в поведении редакции и суммирования.

См. таблицу ниже для сокращённого сравнения:

Цены

Расширенное мышление использует стандартную схему ценообразования токенов:

Процесс мышления влечёт за собой расходы на:

• Токены, используемые во время мышления (выходные токены)
• Блоки мышления из последнего хода помощника, включённые в последующие запросы (входные токены)
• Стандартные выходные токены текста

При использовании суммированного мышления:

• Входные токены: Токены в вашем исходном запросе (исключает токены мышления из предыдущих ходов)
• Выходные токены (выставлены счётом): Исходные токены мышления, которые Claude создал внутренне
• Выходные токены (видимые): Суммированные токены мышления, которые вы видите в ответе
• Без расходов: Токены, используемые для создания сводки

Лучшие практики и соображения для расширенного мышления

Работа с бюджетами мышления

• Оптимизация бюджета: Минимальный бюджет составляет 1024 токена. Мы предлагаем начать с минимума и постепенно увеличивать бюджет мышления, чтобы найти оптимальный диапазон для вашего случая использования. Более высокие количества токенов позволяют более комплексное рассуждение, но с убывающей отдачей в зависимости от задачи. Увеличение бюджета может улучшить качество ответа в обмен на повышенную задержку. Для критических задач протестируйте различные параметры, чтобы найти оптимальный баланс. Обратите внимание, что бюджет мышления является целевым, а не строгим ограничением — фактическое использование токенов может варьироваться в зависимости от задачи.
• Начальные точки: Начните с больших бюджетов мышления (16k+ токенов) для сложных задач и регулируйте в зависимости от ваших потребностей.
• Большие бюджеты: Для бюджетов мышления выше 32k мы рекомендуем использовать пакетную обработку для избежания проблем с сетью. Запросы, которые толкают модель думать выше 32k токенов, вызывают долгоживущие запросы, которые могут столкнуться с тайм-аутами системы и ограничениями открытых соединений.
• Отслеживание использования токенов: Отслеживайте использование токенов мышления для оптимизации затрат и производительности.

Соображения производительности

• Время ответа: Будьте готовы к потенциально более длительному времени ответа из-за дополнительной обработки, необходимой для процесса рассуждения. Учитывайте, что создание блоков мышления может увеличить общее время ответа.
• Требования потоковой передачи: Потоковая передача требуется, когда max_tokens больше 21333. При потоковой передаче будьте готовы обрабатывать как блоки мышления, так и текстовое содержимое по мере их поступления.

Совместимость функций

• Мышление несовместимо с модификациями temperature или top_k, а также с принудительным использованием инструментов.
• Когда мышление включено, вы можете установить top_p на значения между 1 и 0.95.
• Вы не можете предварительно заполнить ответы, когда мышление включено.
• Изменения бюджета мышления делают недействительными кэшированные префиксы подсказок, которые включают сообщения. Однако кэшированные системные подсказки и определения инструментов продолжат работать при изменении параметров мышления.

Руководства по использованию

• Выбор задачи: Используйте расширенное мышление для особенно сложных задач, которые выигрывают от пошагового рассуждения, таких как математика, кодирование и анализ.
• Обработка контекста: Вам не нужно самостоятельно удалять предыдущие блоки мышления. Claude API автоматически игнорирует блоки мышления из предыдущих ходов, и они не включаются при расчёте использования контекста.
• Инженерия подсказок: Просмотрите наши советы по инженерии подсказок расширенного мышления, если вы хотите максимизировать возможности мышления Claude.

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