使用扩展思考构建

扩展思考为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": "让我逐步分析一下...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "基于我的分析..."
    }
  ]
}

有关扩展思考响应格式的更多信息，请参阅消息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可能不会使用分配的整个预算，特别是在超过32k的范围内。

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

摘要思考

启用扩展思考后，Claude 4模型的消息API会返回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"}}

// 额外的思考增量...

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

// 额外的文本增量...

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响应将包含思考、文本和工具使用块：

{
    "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。这对于维护模型的推理流程和对话完整性至关重要。

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

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

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

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

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

交错思考

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

通过交错思考，Claude可以：

在决定下一步操作之前，对工具调用的结果进行推理
在多个工具调用之间链接思考步骤
基于中间结果做出更细微的决策

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

交错思考仅支持通过消息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，证明基于消息的缓存在思考参数更改时会失效。

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

在较旧的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字段中返回。该字段用于在传回API时验证思考块是由Claude生成的。当流式传输响应时，签名通过content_block_stop事件之前的content_block_delta事件中的signature_delta添加。

请注意，签名字段将比以前的模型明显更长。这是一个不透明的字段，不应该被解释或解析 - 它仅用于验证目的。

只有在使用带有扩展思考的工具时，才有必要发送回思考块。否则，您可以省略先前回合的思考块，或者如果您将它们传回，让API为您剥离它们。

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

思考编辑

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

不同模型版本间的思考差异

消息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)

用例

提示工程

测试与评估

加强保护措施

法务中心

​支持的模型

​扩展思考的工作原理

​如何使用扩展思考

​摘要思考

​流式传输思考

​扩展思考与工具使用

​保留思考块

​交错思考

​扩展思考与提示缓存

​理解思考块缓存行为

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

​扩展思考的上下文窗口

​扩展思考和工具使用的上下文窗口

​管理扩展思考的令牌

​思考加密

​思考编辑

​不同模型版本间的思考差异

​定价

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

​使用思考预算

​性能考虑

​功能兼容性

​使用指南

​下一步

尝试扩展思考食谱

扩展思考提示技巧

支持的模型

扩展思考的工作原理

如何使用扩展思考

摘要思考

流式传输思考

扩展思考与工具使用

保留思考块

交错思考

扩展思考与提示缓存

理解思考块缓存行为

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

扩展思考的上下文窗口

扩展思考和工具使用的上下文窗口

管理扩展思考的令牌

思考加密

思考编辑

不同模型版本间的思考差异

定价

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

使用思考预算

性能考虑

功能兼容性

使用指南

下一步