使用扩展思维构建

扩展思维为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..."
    }
  ]
}

有关扩展思维响应格式的更多信息，请参阅Messages API参考。

如何使用扩展思维

以下是在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-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对象，将type参数设置为enabled，并将budget_tokens设置为扩展思维的指定令牌预算。

budget_tokens参数确定Claude在其内部推理过程中允许使用的最大令牌数。在Claude 4模型中，此限制适用于完整的思维令牌，而不是摘要输出。更大的预算可以通过为复杂问题启用更彻底的分析来提高响应质量，尽管Claude可能不会使用分配的全部预算，特别是在超过32k的范围内。

budget_tokens必须设置为小于max_tokens的值。但是，当使用交错思维与工具时，您可以超过此限制，因为令牌限制变成您的整个上下文窗口（200k令牌）。

摘要思维

启用扩展思维后，Claude 4模型的Messages API返回Claude完整思维过程的摘要。摘要思维提供扩展思维的全部智能优势，同时防止滥用。

以下是摘要思维的一些重要考虑因素：

您需要为原始请求生成的完整思维令牌付费，而不是摘要令牌。
计费的输出令牌计数将不匹配您在响应中看到的令牌计数。
思维输出的前几行更加详细，提供详细的推理，这对提示工程目的特别有帮助。
随着Anthropic寻求改进扩展思维功能，摘要行为可能会发生变化。
摘要保留了Claude思维过程的关键思想，延迟最小，实现了可流式传输的用户体验，并便于从Claude 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-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: {"type": "auto"}（默认）或tool_choice: {"type": "none"}。使用tool_choice: {"type": "any"}或tool_choice: {"type": "tool", "name": "..."}将导致错误，因为这些选项强制工具使用，这与扩展思维不兼容。
保留思维块：在工具使用期间，您必须将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响应将包括思维、文本和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": "BDaL4VrbR2Oj0hO4XpJx T28J5TILnCrrUXoKiiNBZW9P+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。这对于维持模型的推理流程和对话完整性至关重要。

虽然您可以从先前的assistant角色轮次中省略thinking块，但我们建议始终将所有思维块传回API以进行任何多轮对话。API将：

自动过滤提供的思维块
使用保持模型推理所需的相关思维块
仅对显示给Claude的块的输入令牌计费

当Claude调用工具时，它正在暂停构建响应以等待外部信息。当工具结果返回时，Claude将继续构建现有响应。这需要在工具使用期间保留思维块，原因如下：

推理连续性：思维块捕获了Claude导致工具请求的逐步推理。当您发布工具结果时，包含原始思维确保Claude可以从中断的地方继续其推理。
上下文维护：虽然工具结果在API结构中显示为用户消息，但它们是连续推理流程的一部分。保留思维块在多个API调用中维护这种概念流程。有关上下文管理的更多信息，请参阅我们的上下文窗口指南。

重要：当提供thinking块时，连续thinking块的整个序列必须与模型在原始请求期间生成的输出匹配；您不能重新排列或修改这些块的序列。

交错思维

Claude 4模型中的扩展思维与工具使用支持交错思维，这使Claude能够在工具调用之间进行思考，并在接收工具结果后进行更复杂的推理。

通过交错思维，Claude可以：

在决定下一步做什么之前推理工具调用的结果
在中间推理步骤之间链接多个工具调用
基于中间结果做出更细致的决策

要启用交错思维，请在您的API请求中添加beta标头interleaved-thinking-2025-05-14。

以下是交错思维的一些重要考虑因素：

使用交错思维时，budget_tokens可以超过max_tokens参数，因为它代表一个助手轮次内所有思维块的总预算。
交错思维仅支持通过Messages API使用的工具。
交错思维仅支持Claude 4模型，使用beta标头interleaved-thinking-2025-05-14。
对Anthropic API的直接调用允许您在对任何模型的请求中传递interleaved-thinking-2025-05-14，没有效果。
在第三方平台上（例如，Amazon Bedrock和Vertex AI），如果您将interleaved-thinking-2025-05-14传递给除Claude 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-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.beta.messages.create(
    model="claude-sonnet-4-20250514",
    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-20250514",
    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-20250514",
    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}")

在这个使用交错思维的示例中：

Claude最初思考任务
在接收到计算器结果后，Claude可以再次思考该结果的含义
然后Claude根据第一个结果决定如何查询数据库
在接收到数据库结果后，Claude在制定最终响应之前再次思考两个结果
思维预算分布在轮次内的所有思维块中

这种模式允许更复杂的推理链，其中每个工具的输出都会影响下一个决策。

扩展思维与提示缓存

提示缓存与思维有几个重要考虑因素：

扩展思维任务通常需要超过5分钟才能完成。考虑使用1小时缓存持续时间来维持跨越更长思维会话和多步骤工作流程的缓存命中。

思维块上下文移除

来自先前轮次的思维块从上下文中移除，这可能影响缓存断点
当继续使用工具使用的对话时，思维块被缓存并在从缓存读取时计为输入令牌
这创建了一个权衡：虽然思维块在视觉上不消耗上下文窗口空间，但当缓存时它们仍然计入您的输入令牌使用量
如果思维被禁用，如果您在当前工具使用轮次中传递思维内容，请求将失败。在其他上下文中，传递给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，证明当思维参数更改时基于消息的缓存失效。

扩展思维的最大令牌和上下文窗口大小

在较旧的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)

下图说明了扩展思维与工具使用的令牌管理：

使用扩展思维管理令牌

鉴于扩展思维Claude 3.7和4模型的上下文窗口和max_tokens行为，您可能需要：

更积极地监控和管理您的令牌使用
随着提示长度的变化调整max_tokens值
可能更频繁地使用令牌计数端点
注意先前的思维块不会在您的上下文窗口中累积

进行此更改是为了提供更可预测和透明的行为，特别是随着最大令牌限制显著增加。

思维加密

完整的思维内容被加密并在signature字段中返回。此字段用于验证思维块是由Claude生成的，当传回API时。

只有在使用扩展思维工具时才严格需要发送回思维块。否则，您可以从先前的轮次中省略思维块，或者如果您传回它们，让API为您剥离它们。

如果发送回思维块，我们建议按照您收到的方式传回所有内容，以保持一致性并避免潜在问题。

以下是思维加密的一些重要考虑因素：

当流式响应时，签名通过content_block_delta事件内的signature_delta在content_block_stop事件之前添加。
signature值在Claude 4中比在先前模型中显著更长。
signature字段是一个不透明字段，不应被解释或解析 - 它仅用于验证目的。
signature值在平台间兼容（Anthropic API、Amazon Bedrock和Vertex AI）。在一个平台上生成的值将与另一个平台兼容。

思维编辑

偶尔Claude的内部推理会被我们的安全系统标记。当这种情况发生时，我们加密thinking块的部分或全部内容，并将其作为redacted_thinking块返回给您。redacted_thinking块在传回API时被解密，允许Claude继续其响应而不丢失上下文。

当构建使用扩展思维的面向客户的应用程序时：

注意编辑的思维块包含不可人类阅读的加密内容
考虑提供简单的解释，如：“Claude的一些内部推理已出于安全原因自动加密。这不会影响响应的质量。”
如果向用户显示思维块，您可以过滤掉编辑的块，同时保留正常的思维块
透明地说明使用扩展思维功能可能偶尔导致一些推理被加密
实施适当的错误处理，以优雅地管理编辑的思维而不破坏您的UI

以下是显示正常和编辑思维块的示例：

{
  "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。有关更多详细信息，请参阅上面的保留思维块部分。

示例：处理编辑的思维块

此示例演示了如何处理当Claude的内部推理包含被安全系统标记的内容时可能出现在响应中的redacted_thinking块：

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")

不同模型版本中思维的差异

Messages API在Claude Sonnet 3.7和Claude 4模型之间处理思维的方式不同，主要在编辑和摘要行为方面。

请参阅下表进行简要比较：

功能	Claude Sonnet 3.7	Claude 4模型
思维输出	返回完整思维输出	返回摘要思维
交错思维	不支持	支持`interleaved-thinking-2025-05-14` beta标头

定价

扩展思维使用标准令牌定价方案：

模型	基础输入令牌	缓存写入	缓存命中	输出令牌
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个令牌。我们建议从最小值开始，逐步增加思维预算以找到您用例的最佳范围。更高的令牌计数能够实现更全面的推理，但根据任务的不同，收益递减。增加预算可以以增加延迟为代价提高响应质量。对于关键任务，测试不同设置以找到最佳平衡。请注意，思维预算是目标而不是严格限制——实际令牌使用可能根据任务而变化。
起始点： 对于复杂任务，从较大的思维预算（16k+令牌）开始，并根据您的需要进行调整。
大预算： 对于超过32k的思维预算，我们建议使用批处理以避免网络问题。推动模型思考超过32k令牌的请求会导致长时间运行的请求，可能遇到系统超时和开放连接限制。
令牌使用跟踪： 监控思维令牌使用以优化成本和性能。

性能考虑

响应时间： 由于推理过程所需的额外处理，准备好可能更长的响应时间。考虑生成思维块可能增加总体响应时间。
流式要求： 当max_tokens大于21,333时需要流式传输。流式传输时，准备好处理到达的思维和文本内容块。

功能兼容性

思维与temperature或top_k修改以及强制工具使用不兼容。
当启用思维时，您可以将top_p设置为1到0.95之间的值。
启用思维时无法预填充响应。
思维预算的更改会使包含消息的缓存提示前缀失效。但是，当思维参数更改时，缓存的系统提示和工具定义将继续工作。

使用指南

任务选择： 对特别复杂的任务使用扩展思维，这些任务受益于逐步推理，如数学、编码和分析。
上下文处理： 您不需要自己删除先前的思维块。Anthropic API自动忽略先前轮次的思维块，在计算上下文使用时不包括它们。
提示工程： 如果您想最大化Claude的思维能力，请查看我们的扩展思维提示技巧。

下一步

尝试扩展思维食谱

在我们的食谱中探索思维的实际示例。

扩展思维提示技巧

学习扩展思维的提示工程最佳实践。

提示缓存流式消息

On this page

支持的模型
扩展思维的工作原理
如何使用扩展思维
摘要思维
流式思维
扩展思维与工具使用
保留思维块
交错思维
扩展思维与提示缓存
理解思维块缓存行为
扩展思维的最大令牌和上下文窗口大小
扩展思维的上下文窗口
扩展思维与工具使用的上下文窗口
使用扩展思维管理令牌
思维加密
思维编辑
不同模型版本中思维的差异
定价
扩展思维的最佳实践和考虑因素
使用思维预算
性能考虑
功能兼容性
使用指南
下一步

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

使用扩展思维构建

支持的模型

扩展思维的工作原理

如何使用扩展思维

摘要思维

流式思维

扩展思维与工具使用

保留思维块

交错思维

扩展思维与提示缓存

理解思维块缓存行为

扩展思维的最大令牌和上下文窗口大小

扩展思维的上下文窗口

扩展思维与工具使用的上下文窗口

使用扩展思维管理令牌

思维加密

思维编辑

不同模型版本中思维的差异

定价

扩展思维的最佳实践和考虑因素

使用思维预算

性能考虑

功能兼容性

使用指南

下一步

尝试扩展思维食谱

扩展思维提示技巧

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

​支持的模型

​扩展思维的工作原理

​如何使用扩展思维

​摘要思维

​流式思维

​扩展思维与工具使用

​保留思维块

​交错思维

​扩展思维与提示缓存

​理解思维块缓存行为

​扩展思维的最大令牌和上下文窗口大小

​扩展思维的上下文窗口

​扩展思维与工具使用的上下文窗口

​使用扩展思维管理令牌

​思维加密

​思维编辑

​不同模型版本中思维的差异

​定价

​扩展思维的最佳实践和考虑因素

​使用思维预算

​性能考虑

​功能兼容性

​使用指南

​下一步

尝试扩展思维食谱

扩展思维提示技巧

支持的模型

扩展思维的工作原理

如何使用扩展思维

摘要思维

流式思维

扩展思维与工具使用

保留思维块

交错思维

扩展思维与提示缓存

理解思维块缓存行为

扩展思维的最大令牌和上下文窗口大小

扩展思维的上下文窗口

扩展思维与工具使用的上下文窗口

使用扩展思维管理令牌

思维加密

思维编辑

不同模型版本中思维的差异

定价

扩展思维的最佳实践和考虑因素

使用思维预算

性能考虑

功能兼容性

使用指南

下一步