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

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

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

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

Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)

Поведение API различается в моделях Claude 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 сообщений.

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

Вот пример использования расширенного мышления в 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-20250514",
    "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, установив параметр thinking на enabled и budget_tokens на указанный бюджет токенов для расширенного мышления.

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

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

Сокращенное мышление

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

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

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

Claude Sonnet 3.7 продолжает возвращать полный вывод мышления.

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

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

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

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

Для получения дополнительной документации о потоковой передаче через 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-20250514",
    "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-20250514", "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 рассуждать о выборе инструментов и обработке результатов.

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

Ограничение выбора инструмента: Использование инструментов с мышлением поддерживает только tool_choice: any (не specific, auto или другие значения).
Сохранение блоков мышления: При использовании инструментов вы должны передавать блоки thinking обратно в API для последнего сообщения ассистента. Включите полный неизмененный блок обратно в API для сохранения непрерывности рассуждений.

Пример: Передача блоков мышления с результатами инструментов

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

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-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)

Ответ API будет включать блоки thinking, text и 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-20250514",
    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 продолжит строить этот существующий ответ. Это требует сохранения блоков мышления при использовании инструментов по нескольким причинам:

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

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

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

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

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

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

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

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

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

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

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-20250514",
    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

В этом примере без чередующегося мышления:

Claude думает один раз в начале, чтобы понять задачу
Принимает все решения по использованию инструментов заранее
Когда результаты инструментов возвращаются, 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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    # Enable interleaved thinking with beta header
    extra_headers={
        "anthropic-beta": "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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "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}")

В этом примере с чередующимся мышлением:

Claude думает о задаче изначально
После получения результата калькулятора Claude может снова подумать о том, что означает этот результат
Затем Claude решает, как запросить базу данных на основе первого результата
После получения результата из базы данных Claude думает еще раз о обоих результатах перед формулированием окончательного ответа
Бюджет мышления распределяется между всеми блоками мышления в рамках хода

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

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

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

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

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

Шаблоны инвалидации кеша

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

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

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

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

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

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

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

Запрос 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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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, доказывая, что кеширование на основе сообщений инвалидируется при изменении параметров мышления.

Max tokens и размер контекстного окна с расширенным мышлением

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

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

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

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

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

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

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

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

контекстное окно =
  (текущие входные токены - предыдущие токены мышления) +
  (токены мышления + зашифрованные токены мышления + токены текстового вывода)

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

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

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

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

контекстное окно =
  (текущие входные токены + предыдущие токены мышления + токены использования инструментов) +
  (токены мышления + зашифрованные токены мышления + токены текстового вывода)

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

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

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

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

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

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

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

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

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

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

Редактирование мышления

Иногда внутренние рассуждения 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-3-7-sonnet-20250219",
    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")

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

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

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

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

Ценообразование

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

Модель	Базовые входные токены	Запись в кеш	Попадания в кеш	Выходные токены
Claude Opus 4	$15 / MTok	$18.75 / MTok	$1.50 / MTok	$75 / 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 сгенерировал внутренне
Выходные токены (видимые): Сокращенные токены мышления, которые вы видите в ответе
Без оплаты: Токены, используемые для генерации сводки

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

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

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

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

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

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

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

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

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

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

Попробуйте сборник примеров расширенного мышления

Изучите практические примеры мышления в нашем сборнике.

Советы по промптам для расширенного мышления

Изучите лучшие практики инженерии промптов для расширенного мышления.

Кэширование промптов Потоковая передача сообщений

On this page

Поддерживаемые модели
Как работает расширенное мышление
Как использовать расширенное мышление
Сокращенное мышление
Потоковое мышление
Расширенное мышление с использованием инструментов
Сохранение блоков мышления
Чередующееся мышление
Расширенное мышление с кешированием промптов
Понимание поведения кеширования блоков мышления
Max tokens и размер контекстного окна с расширенным мышлением
Контекстное окно с расширенным мышлением
Контекстное окно с расширенным мышлением и использованием инструментов
Управление токенами с расширенным мышлением
Шифрование мышления
Редактирование мышления
Различия в мышлении между версиями моделей
Ценообразование
Лучшие практики и соображения для расширенного мышления
Работа с бюджетами мышления
Соображения по производительности
Совместимость функций
Рекомендации по использованию
Следующие шаги

Первые шаги

Изучить возможности

Модели и цены

Узнать о Claude

Тестирование и оценка

Компоненты агента

Юридический центр

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

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

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

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

Сокращенное мышление

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

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

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

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

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

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

Max tokens и размер контекстного окна с расширенным мышлением

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

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

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

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

Редактирование мышления

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

Ценообразование

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

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

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

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

Рекомендации по использованию

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

Попробуйте сборник примеров расширенного мышления

Советы по промптам для расширенного мышления

Первые шаги

Изучить возможности

Модели и цены

Узнать о Claude

Тестирование и оценка

Компоненты агента

Юридический центр

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

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

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

​Сокращенное мышление

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

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

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

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

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

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

​Max tokens и размер контекстного окна с расширенным мышлением

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

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

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

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

​Редактирование мышления

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

​Ценообразование

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

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

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

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

​Рекомендации по использованию

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

Попробуйте сборник примеров расширенного мышления

Советы по промптам для расширенного мышления

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

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

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

Сокращенное мышление

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

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

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

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

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

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

Max tokens и размер контекстного окна с расширенным мышлением

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

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

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

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

Редактирование мышления

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

Ценообразование

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

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

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

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

Рекомендации по использованию

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