Расширенное мышление предоставляет 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)
Поведение API отличается между моделями Claude Sonnet 3.7 и Claude 4, но формы API остаются точно такими же.Для получения дополнительной информации см. Различия в мышлении между версиями моделей.

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

Когда расширенное мышление включено, 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.
  • Суммирование обрабатывается другой моделью, чем та, которую вы указываете в своих запросах. Модель мышления не видит суммированный вывод.
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)
Лучшая практика: Планируйте вашу стратегию мышления в начале каждого хода, а не пытайтесь переключаться в середине хода.
Переключение режимов мышления также делает недействительным кэширование подсказок для истории сообщений. Для получения дополнительной информации см. раздел Расширенное мышление с кэшированием подсказок.
Вот практический пример, показывающий, как сохранить блоки мышления при предоставлении результатов инструментов:
weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
}

# First request - Claude responds with thinking and tool request
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)
Ответ API будет включать блоки мышления, текста и tool_use:
{
    "content": [
        {
            "type": "thinking",
            "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "I can help you get the current weather information for Paris. Let me check that for you"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}
Теперь давайте продолжим разговор и используем инструмент
# Extract thinking block and tool use block
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Call your actual weather API, here is where your actual API call would go
# let's pretend this is what we get back
weather_data = {"temperature": 88}

# Second request - Include thinking block and tool result
# No new thinking blocks will be generated in the response
continuation = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # notice that the thinking_block is passed in as well as the tool_use_block
        # if this is not passed in, an error is raised
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Current temperature: {weather_data['temperature']}°F"
        }]}
    ]
)
Ответ API теперь будет только включать текст
{
    "content": [
        {
            "type": "text",
            "text": "Currently in Paris, the temperature is 88°F (31°C)"
        }
    ]
}

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

Во время использования инструментов вы должны передать блоки thinking обратно в API, и вы должны включить полный неизменённый блок обратно в API. Это критично для сохранения потока рассуждений модели и целостности разговора.
Хотя вы можете опустить блоки thinking из предыдущих ходов assistant, мы предлагаем всегда передавать все блоки мышления обратно в API для любого многоходового разговора. API будет:
  • Автоматически фильтровать предоставленные блоки мышления
  • Использовать релевантные блоки мышления, необходимые для сохранения рассуждений модели
  • Выставлять счёт только за входные токены для блоков, показанных Claude
При переключении режимов мышления во время разговора помните, что весь ход помощника (включая циклы использования инструментов) должен работать в одном режиме мышления. Для получения дополнительной информации см. Переключение режимов мышления в разговорах.
Когда 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, ваш запрос не пройдёт.
import anthropic

client = anthropic.Anthropic()

# Define tools
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request - Claude thinks once before all tool calls
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

# Response includes thinking followed by tool uses
# Note: Claude thinks once at the beginning, then makes all tool decisions
print("First response:")
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking (summarized): {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# You would execute the tools and return results...
# After getting both tool results back, Claude directly responds without additional thinking
В этом примере без чередующегося мышления:
  1. Claude думает один раз в начале, чтобы понять задачу
  2. Принимает все решения об использовании инструментов заранее
  3. Когда возвращаются результаты инструментов, Claude сразу же предоставляет ответ без дополнительного мышления
import anthropic

client = anthropic.Anthropic()

# Same tool definitions as before
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request with interleaved thinking enabled
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

print("Initial response:")
thinking_blocks = []
tool_use_blocks = []

for block in response.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# First tool result (calculator)
calculator_result = "7500"  # 150 * 50

# Continue with first tool result
response2 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        }
    ]
)

print("\nAfter calculator result:")
# With interleaved thinking, Claude can think about the calculator result
# before deciding to query the database
for block in response2.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Interleaved thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")

# Second tool result (database)
database_result = "5200"  # Example average monthly revenue

# Continue with second tool result
response3 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        },
        {
            "role": "assistant",
            "content": thinking_blocks[1:] + tool_use_blocks[1:]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[1].id,
                "content": database_result
            }]
        }
    ]
)

print("\nAfter database result:")
# With interleaved thinking, Claude can think about both results
# before formulating the final response
for block in response3.content:
    if block.type == "thinking":
        print(f"Final thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Final response: {block.text}")
В этом примере с чередующимся мышлением:
  1. Claude думает о задаче изначально
  2. После получения результата калькулятора Claude может снова подумать о том, что означает этот результат
  3. Claude затем решает, как запросить базу данных на основе первого результата
  4. После получения результата базы данных Claude ещё раз думает о обоих результатах перед формулировкой окончательного ответа
  5. Бюджет мышления распределяется по всем блокам мышления в пределах хода
Этот паттерн позволяет более сложные цепочки рассуждений, где выход каждого инструмента информирует следующее решение.

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

Кэширование подсказок с мышлением имеет несколько важных соображений:
Задачи расширенного мышления часто занимают более 5 минут. Рассмотрите использование кэша на 1 час для сохранения попаданий кэша в течение более длительных сеансов мышления и многошаговых рабочих процессов.
Удаление контекста блока мышления
  • Блоки мышления из предыдущих ходов удаляются из контекста, что может повлиять на точки разрыва кэша
  • При продолжении разговоров с использованием инструментов блоки мышления кэшируются и считаются входными токенами при чтении из кэша
  • Это создаёт компромисс: хотя блоки мышления не потребляют пространство контекстного окна визуально, они всё ещё считаются в вашем использовании входных токенов при кэшировании
  • Если мышление становится отключённым, запросы не пройдут, если вы передаёте содержимое мышления в текущем ходе использования инструментов. В других контекстах содержимое мышления, переданное в 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
  • Это поведение согласуется независимо от использования обычного мышления или чередующегося мышления
from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

SYSTEM_PROMPT=[
    {
        "type": "text",
        "text": "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.",
    },
    {
        "type": "text",
        "text": LARGE_TEXT,
        "cache_control": {"type": "ephemeral"}
    }
]

MESSAGES = [
    {
        "role": "user",
        "content": "Analyze the tone of this passage."
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

# Third request - different thinking parameters (cache miss for messages)
print("\nThird request - different thinking parameters (cache miss for messages)")
response3 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Changed thinking budget
    },
    system=SYSTEM_PROMPT,  # System prompt remains cached
    messages=MESSAGES  # Messages cache is invalidated
)

print(f"Third response usage: {response3.usage}")
from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

# No system prompt - caching in messages instead
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {
                "type": "text",
                "text": "Analyze the tone of this passage."
            }
        ]
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000  # Same thinking budget
    },
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response2.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the setting in this passage."
})

# Third request - different thinking budget (cache miss expected)
print("\nThird request - different thinking budget (cache miss expected)")
response3 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Different thinking budget breaks cache
    },
    messages=MESSAGES
)

print(f"Third response usage: {response3.usage}")
Вот вывод скрипта (вы можете видеть немного другие числа)
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 }
Этот пример демонстрирует, что когда кэширование установлено в массиве сообщений, изменение параметров мышления (budget_tokens увеличен с 4000 на 8000) делает кэш недействительным. Третий запрос показывает отсутствие попадания кэша с cache_creation_input_tokens=1370 и cache_read_input_tokens=0, доказывая, что кэширование на основе сообщений делается недействительным при изменении параметров мышления.

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

В более старых моделях 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.
Строго необходимо отправлять блоки мышления только при использовании инструментов с расширенным мышлением. В противном случае вы можете опустить блоки мышления из предыдущих ходов или позволить 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..."
    }
  ]
}
Видение редактированных блоков мышления в вашем выводе - это ожидаемое поведение. Модель всё ещё может использовать это редактированное рассуждение для информирования своих ответов при сохранении защитных ограждений безопасности.Если вам нужно протестировать обработку редактированного мышления в вашем приложении, вы можете использовать эту специальную тестовую строку как вашу подсказку: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
При передаче блоков thinking и redacted_thinking обратно в API в многоходовом разговоре вы должны включить полный неизменённый блок обратно в API для последнего хода помощника. Это критично для сохранения потока рассуждений модели. Мы предлагаем всегда передавать все блоки мышления обратно в API. Для получения дополнительной информации см. раздел Сохранение блоков мышления выше.
Этот пример демонстрирует, как обрабатывать блоки redacted_thinking, которые могут появиться в ответах, когда внутреннее рассуждение Claude содержит содержимое, отмеченное системами безопасности:
import anthropic

client = anthropic.Anthropic()

# Using a special prompt that triggers redacted thinking (for demonstration purposes only)
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identify redacted thinking blocks
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("Response contains redacted thinking blocks")
    # These blocks are still usable in subsequent requests

    # Extract all blocks (both redacted and non-redacted)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # When passing to subsequent requests, include all blocks without modification
    # This preserves the integrity of Claude's reasoning

    print(f"Found {len(all_thinking_blocks)} thinking blocks total")
    print(f"These blocks are still billable as output tokens")

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

Messages API обрабатывает мышление по-разному в моделях Claude Sonnet 3.7 и Claude 4, в основном в поведении редакции и суммирования. См. таблицу ниже для сокращённого сравнения:
ФункцияClaude Sonnet 3.7Модели Claude 4
Вывод мышленияВозвращает полный вывод мышленияВозвращает суммированное мышление
Чередующееся мышлениеНе поддерживаетсяПоддерживается с заголовком бета-версии interleaved-thinking-2025-05-14

Цены

Расширенное мышление использует стандартную схему ценообразования токенов:
МодельБазовые входные токеныЗаписи кэшаПопадания кэшаВыходные токены
Claude Opus 4.1$15 / MTok$18.75 / MTok$1.50 / MTok$75 / MTok
Claude Opus 4$15 / MTok$18.75 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4.5$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Процесс мышления влечёт за собой расходы на:
  • Токены, используемые во время мышления (выходные токены)
  • Блоки мышления из последнего хода помощника, включённые в последующие запросы (входные токены)
  • Стандартные выходные токены текста
Когда расширенное мышление включено, специализированная системная подсказка автоматически включается для поддержки этой функции.
При использовании суммированного мышления:
  • Входные токены: Токены в вашем исходном запросе (исключает токены мышления из предыдущих ходов)
  • Выходные токены (выставлены счётом): Исходные токены мышления, которые Claude создал внутренне
  • Выходные токены (видимые): Суммированные токены мышления, которые вы видите в ответе
  • Без расходов: Токены, используемые для создания сводки
Количество выставленных токенов вывода не будет совпадать с видимым количеством токенов в ответе. Вам выставляется счёт за полный процесс мышления, а не за сводку, которую вы видите.

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

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

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

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

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

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

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

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

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

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