Claude 扩展推理 Thinking
本文档详细说明通过 UniGateway 调用 Claude 模型扩展推理(Extended Thinking)能力的配置方法、跨代际适配规则、推理强度档位控制及思维链块结构。
章节导引
本篇为 Anthropic Messages API 参考的第 3 章节:
- Messages 概述与快速开始
- 请求参数与消息格式
- 扩展推理 Thinking(当前章节)
- 提示词缓存 Prompt Caching
- 工具调用与 Computer Use
- 响应、流式与错误处理
扩展推理架构概述
扩展推理(Extended Thinking)赋予 Claude 模型在给出最终回答前进行深入思考与自我验证的能力。思考过程以独立的思维链(Chain-of-Thought)内容块呈现,附带加密签名以确保内容完整性。
UniGateway 支持 Claude 全系列扩展推理协议,并负责在不同代际模型与多云平台(Direct API / Bedrock / Vertex AI)之间执行平滑的协议桥接。
各模型族默认思考行为
不同代际与档位的 Claude 模型在未显式传入 thinking 参数时的默认行为各不相同:
| 模型族 | 代表模型 ID | 默认状态 | 思考模式取值 | 说明 |
|---|---|---|---|---|
| Claude 4.5 系列 | claude-sonnet-4-5, claude-opus-4-5 | 默认关闭(off) | enabled + budget_tokens | 手动预算模式;开启时需显式指定 budget_tokens |
| Claude 4.6 系列 | claude-sonnet-4-6, claude-opus-4-6 | 默认关闭(off) | 推荐 adaptive;enabled 标记弃用 | 引入自适应思考与 4 档 effort 控制 |
| Claude 4.7 – 4.8 系列 | claude-opus-4-7, claude-opus-4-8 | 默认关闭(off) | adaptive 或 disabled | 官方完全移除 enabled 模式,全面转向 adaptive |
| Claude 5.0 – 5.1 系列 | claude-sonnet-5-0, claude-fable-5-1 | 5.0 默认 adaptive;Fable/Mythos 常开 | adaptive / disabled | 常开模型不支持 disabled;Mythos 预览版支持 enabled |
| Claude 5.5 及同档后续 | claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5 | Sonnet/Haiku 默认 adaptive;Opus 常开 | adaptive / disabled / between_tools | Opus 5.5 仅支持 adaptive;Sonnet 5.5 支持通过 between_tools 仅在工具之间思考 |
thinking.type 取值与处理规则
在请求体中传入 thinking 字段时,支持以下模式:
1. 自适应模式(type: "adaptive")
现代 Claude 模型的推荐模式。模型根据问题复杂度自主决定思考长度:
{
"model": "claude-sonnet-5-5",
"max_tokens": 8192,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [...]
}
- 向下代际适配转换:若客户端向旧版仅支持手动思考的 Claude 4.5 模型请求
adaptive,网关自动将请求转换为enabled并基于max_tokens动态推导安全的budget_tokens,并在响应头x-gateway-modified-thinking: adaptive_to_enabled中记录。
2. 手动预算模式(type: "enabled")
传统思考模式,需要提供 budget_tokens:
{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"thinking": {
"type": "enabled",
"budget_tokens": 2048
},
"messages": [...]
}
- 向上迁移转换:官方在 Claude 4.7 及以上模型中废弃并移除了
enabled模式。若客户端向 Claude 4.7+、5.x 或 5.5 模型发送带有enabled且未提供budget_tokens的请求,网关在出站时自动升级为adaptive,避免上游直接拦截。
3. 关闭思考(type: "disabled")
对于默认开启 Thinking 的模型(如 Claude Sonnet 5.0、Claude Sonnet 5.5、Claude Haiku 5.5),可通过显式传入 "type": "disabled" 关闭思考以降低延迟:
{
"model": "claude-haiku-5-5",
"max_tokens": 2048,
"thinking": {
"type": "disabled"
},
"messages": [...]
}
- 常开模型限制:对于常开推理模型(如 Claude Opus 5.5、Claude Fable 系列),官方不支持
disabled。若客户端尝试强行关闭,网关保持常开自适应模式以确保上游可用。
4. 工具间推理模式(type: "between_tools")
Claude Sonnet 5.5 特有模式。在多轮 Agent 循环中,关闭初始回答的前置长思考,仅在每次工具执行完毕后进行短暂的中间推理:
{
"model": "claude-sonnet-5-5",
"max_tokens": 8192,
"thinking": {
"type": "between_tools"
},
"tools": [...],
"messages": [...]
}
推理强度控制(output_config.effort)
配合 adaptive 思考模式,开发者可通过 output_config.effort 调节思考的深入程度:
| Effort 档位 | 语义说明 | 适用场景 |
|---|---|---|
low | 快速思考,轻度验证 | 简单查询、低复杂度任务、追求极低延迟的交互 |
medium | 平衡思考,标准验证 | 常规对话与代码生成(大部分模型的默认水平) |
high | 深入推导,多重分支分析 | 复杂逻辑推导、数学证明、架构设计 |
xhigh | 极高强度推理 | 前沿算法研究、复杂跨系统故障排查 |
max | 模型极限深度探索 | 极高难度学术分析与综合推演 |
关闭思考时的 Effort 约束
当通过 disabled 关闭思考或在 Sonnet 5.5 上使用 between_tools 时,若传入 output_config.effort,官方要求其取值不得超过 high(即不得传入 xhigh 或 max)。网关在检测到超限时会自动将其安全截断至 high,保障请求顺畅。
响应思考块结构与签名校验
当启用 Extended Thinking 时,模型响应的 content 数组将包含一个或多个 thinking 块:
{
"id": "msg_01...",
"type": "message",
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "首先分析用户关于 Raft 协议选主流程的问题...\n1. 节点状态有 Follower, Candidate, Leader...\n2. 心跳超时触发选举...",
"signature": "EqUBCAEqQzBBAiEAv..."
},
{
"type": "text",
"text": "Raft 选主机制的核心步骤如下:\n\n1. **心跳超时**:Follower 在随机超时时间内未收到 Leader 心跳,转换为 Candidate 并发起投票..."
}
],
"model": "claude-sonnet-5-5",
"stop_reason": "end_turn"
}
多轮对话回传规范
在随后的多轮对话中,客户端回传的 messages 历史中必须保留 thinking 块及其完整 signature。
- 网关与上游会严格校验思考块内容与其对应签名的哈希匹配性;
- 若敏感内容在底层被安全审查过滤,上游会返回
redacted_thinking块:{ "type": "redacted_thinking", "data": "eyJhbGciOi...", "signature": "EqUBCAEq..." } - 回传时必须原样带上该
redacted_thinking块,切勿手动丢弃或篡改; - 工具调用思考签名绑定:若思考块伴随
tool_use工具调用生成,后续多轮工具结果交互中,客户端不仅需回传工具返回结果,还需保留assistant历史中的thinking签名与关联关系;网关在跨协议桥接与跨云路由中全面维护签名一致性。
代码示例
Python SDK(开启自适应思考)
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get("UNIGATEWAY_API_KEY"),
base_url="https://api.unigateway.ai",
)
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[
{"role": "user", "content": "设计一个支持百亿级订单的分布式 ID 生成方案,对比各方案优劣。"}
],
)
for block in response.content:
if block.type == "thinking":
print("[Claude 思考过程]:\n", block.thinking)
elif block.type == "text":
print("\n[正式回复]:\n", block.text)
TypeScript SDK(开启自适应思考)
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.UNIGATEWAY_API_KEY,
baseURL: 'https://api.unigateway.ai',
});
const response = await client.messages.create({
model: 'claude-sonnet-5-5',
max_tokens: 4096,
thinking: { type: 'adaptive' },
output_config: { effort: 'high' },
messages: [
{ role: 'user', content: '设计一个支持百亿级订单的分布式 ID 生成方案,对比各方案优劣。' }
],
});
for (const block of response.content) {
if (block.type === 'thinking') {
console.log('[Claude 思考过程]:\n', block.thinking);
} else if (block.type === 'text') {
console.log('\n[正式回复]:\n', block.text);
}
}
下一步
- 掌握长上下文与大提示词的前缀缓存:提示词缓存 Prompt Caching
- 结合工具调用让 Claude 执行复杂操作:工具调用与 Computer Use
- 处理流式推送与状态码返回:响应、流式与错误处理