Anthropic API/Claude 扩展推理 Thinking

配置 Claude 各代际模型的扩展推理能力、自适应模式、努力程度档位与签名保持。

Claude 扩展推理 Thinking

本文档详细说明通过 UniGateway 调用 Claude 模型扩展推理(Extended Thinking)能力的配置方法、跨代际适配规则、推理强度档位控制及思维链块结构。


章节导引

本篇为 Anthropic Messages API 参考的第 3 章节:

  1. Messages 概述与快速开始
  2. 请求参数与消息格式
  3. 扩展推理 Thinking(当前章节)
  4. 提示词缓存 Prompt Caching
  5. 工具调用与 Computer Use
  6. 响应、流式与错误处理

扩展推理架构概述

扩展推理(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-15.0 默认 adaptive;Fable/Mythos 常开adaptive / disabled常开模型不支持 disabled;Mythos 预览版支持 enabled
Claude 5.5 及同档后续claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5Sonnet/Haiku 默认 adaptive;Opus 常开adaptive / disabled / between_toolsOpus 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);
  }
}

下一步