Claude Effort 努力档位与思考指南

本文说明如何用 Anthropic 原生 Messages API 调用 Claude（经 API易网关转 AWS Bedrock），以及 output_config.effort（努力档位）和 thinking（自适应思考）的正确用法。基础的通道、计费与接入信息请先看 Claude API 基础说明。

适用模型：Claude Opus 4.8 / 4.7 / 4.6、Sonnet 4.6 等。本文以 Opus 4.8 为例。

在线测试工具

不想写代码？可以先用 API易在线推理测试工具体验：选择模型与 effort 档位、设置 Max Tokens、勾选「请求返回思考摘要」，即可直接对比不同档位的推理效果。

推理测试 · API易在线工具

网页端直接调用 Claude（也支持 GPT / Gemini）推理测试，无需写代码，填入 API易令牌即可使用。

API易在线推理测试工具：选择 claude-opus-4-8 模型与 effort 档位

请求的基本结构

Endpoint 与请求头

POST https://api.apiyi.com/v1/messages

Header	值	说明
`content-type`	`application/json`	固定
`anthropic-version`	`2023-06-01`	Anthropic 原生版本头，必填
`x-api-key`	`your-apiyi-key`	Anthropic 原生鉴权方式

经 API易转 Bedrock 时，客户端仍用 Anthropic 原生格式（x-api-key + /v1/messages），网关内部负责翻译成 Bedrock 的 bedrock-2023-05-31。你不需要写 anthropic_version: bedrock-2023-05-31。

最小请求体

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "你的问题" }
  ]
}

effort 努力档位

effort 控制 Claude 愿意花多少 token 来产出结果，在「彻底程度」和「速度/成本」之间权衡。它影响全部 token 消耗：正文、工具调用、以及扩展思考。

关键规则

effort 必须放在顶层独立的 output_config 对象里，不能放进 thinking 里 —— 放错会直接 ValidationException / 400。
无需 beta 头。effort 现已对所有支持的模型开放，不再需要 anthropic-beta: effort-2025-11-24。
默认值是 high；设成 "high" 与完全不传 effort 行为一致。

带 effort 的请求体

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "output_config": {
    "effort": "medium"
  },
  "messages": [
    { "role": "user", "content": "分析微服务与单体架构的取舍" }
  ]
}

档位一览

档位	说明	典型场景
`low`	最省。显著节省 token，能力略降。	简单任务、高并发、子 agent
`medium`	平衡。中等 token 节省。	多数 agentic 工作流的折中默认
`high`	默认值。高能力。	复杂推理、难编码、对质量敏感的任务
`xhigh`	长程扩展能力，介于 high 和 max 之间。	长时编码 / agentic 任务（超 30 分钟）
`max`	无约束的最强能力。	真正前沿的难题，最深推理

Opus 4.8 推荐：编码 / agentic 用 xhigh 起步，其它智力敏感任务用 high，只有在 eval 验证过质量不掉的前提下才下调到 medium / low。跑 xhigh / max 时把 max_tokens 设大（64k 起步），给模型留足思考 + 输出空间。

各模型支持的档位

不是所有模型都支持全部档位。xhigh 是 Opus 4.7 才新增的，max 不支持 Sonnet：

档位	Opus 4.6	Opus 4.7 / 4.8	Sonnet 4.6
`low` / `medium` / `high`	✅	✅	✅
`xhigh`	❌	✅	❌
`max`	✅	✅	❌

常见误用：claude-opus-4-6 配 effort: "xhigh"。4.6 没有 xhigh 档 —— 请改用 high / max，或把模型换成 claude-opus-4-8 再用 xhigh。

thinking 自适应思考

Opus 4.7 / 4.8 用自适应思考：由模型自己决定何时思考、思考多少，配合 effort 控制深度。

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive",
    "display": "summarized"
  },
  "output_config": {
    "effort": "xhigh"
  },
  "messages": [
    { "role": "user", "content": "一步步定位这个生产环境 Bug 的根因" }
  ]
}

thinking.type: "adaptive" —— 开启自适应思考（不传则不思考）。
thinking.display: "summarized" —— 让响应里返回思考摘要块；不需要展示可删掉。
effort 与思考的关系：high / xhigh / max 几乎总会深度思考；low / medium 在简单题上可能跳过思考。
display 默认值随模型不同：Opus 4.6 默认 summarized，Opus 4.7 / 4.8 默认 omitted（思考块仍在，但 thinking 文本为空，前端表现为「正文前一段停顿」）。想稳定拿到摘要就显式写 display: "summarized"。
没有 -thinking 后缀的原生模型。是否思考由 thinking 参数决定，不是靠模型名后缀；xxx-thinking 都是第三方别名，直接用基础模型 ID + thinking 参数即可。

Opus 4.7 / 4.8 不支持 thinking.type: "enabled" + budget_tokens（会 400）。请改用 adaptive + effort。

thinking 摘要的本质（重要）

摘要由 Anthropic 官方（模型/服务层）生成，不是网关或第三方模型二次加工；原始思维链（raw CoT）永不原文返回，你拿到的就是官方摘要。
不能用 system prompt 定制 thinking 摘要的语气/格式。system 影响的是模型「怎么思考」和「最终回答」的风格，摘要只是内部推理的可读呈现。语气、排版、风格等要求请放进对最终回答的约束，让它体现在 text 块里。
不要在 prompt 里要求模型把内部推理「原文」输出到回答中 —— 可能触发拒答（stop_reason: "refusal"，stop_details.category 可能为 reasoning_extraction）。需要看推理就读 display: "summarized" 的摘要。

多轮对话在同一模型上继续时，要把上一轮收到的 thinking 块原样回传（含签名、含空文本块）—— API 拒绝被修改过的 thinking 块。展示摘要没问题，但不要编辑后再回传。

解析响应

响应的 content 是一个块数组，按 type 区分：

for block in data["content"]:
    if block["type"] == "thinking":
        print("[思考摘要]", block["thinking"])
    elif block["type"] == "text":
        print("[回答]", block["text"])

token 用量在 usage 字段：

{
  "usage": {
    "input_tokens": 164,
    "output_tokens": 11056,
    "service_tier": "standard"
  }
}

若 stop_reason 为 max_tokens，说明输出被 max_tokens 截断（高 effort 下思考容易吃满），此时正文可能为空 —— 把 max_tokens 调大即可。

流式（stream）下的 thinking 字段

stream: true 时，思考内容不走 delta.text，而是专门的事件序列：

事件	字段	说明
`content_block_start`	`content_block.type = "thinking"`	思考块开始
`content_block_delta`	`delta.type = "thinking_delta"` → `delta.thinking`	思考摘要增量文本（不是 `delta.text`）
`content_block_delta`	`delta.type = "signature_delta"`	思考块签名，多轮回传时需原样保留
`content_block_stop`	—	思考块结束，之后才是正文 `text` 块

正文文本仍走 delta.type = "text_delta" → delta.text。若 display: "omitted"，思考块照常出现但 delta.thinking 为空字符串。

完整可运行示例

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("APIYI_API_KEY")
BASE_URL = "https://api.apiyi.com"

resp = requests.post(
    f"{BASE_URL}/v1/messages",
    headers={
        "content-type": "application/json",
        "anthropic-version": "2023-06-01",
        "x-api-key": API_KEY,
    },
    json={
        "model": "claude-opus-4-8",
        "max_tokens": 16000,
        "thinking": {"type": "adaptive", "display": "summarized"},
        "output_config": {"effort": "xhigh"},
        "messages": [
            {"role": "user", "content": "分析微服务与单体架构的取舍"}
        ],
    },
    timeout=300,
)

data = resp.json()
print("status:", resp.status_code, "| usage:", data.get("usage"))
for block in data.get("content", []):
    if block.get("type") == "thinking":
        print("\n[思考摘要]\n", block.get("thinking", ""))
    elif block.get("type") == "text":
        print("\n[回答]\n", block.get("text", ""))

curl https://api.apiyi.com/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: your-apiyi-key" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "thinking": { "type": "adaptive" },
    "output_config": { "effort": "xhigh" },
    "messages": [{ "role": "user", "content": "分析微服务与单体架构的取舍" }]
  }'

经 Bedrock 时的注意事项

项	说明
`output_config`	必须放行。网关若有 `delete output_config` 覆盖规则，effort 会被静默吞掉（返回 200 但无效）。
`effort` 位置	顶层 `output_config` 内，不能放进 `thinking`。
beta 头	effort 不需要；adaptive thinking 也不需要。
`temperature` / `top_p`	Opus 4.7 / 4.8 配自适应思考时应使用默认采样；网关通常会为这两个模型剥离这两个参数，属正常，客户端不必设置。
非法 effort 值	Bedrock 对未知值宽容降级（返回 200），不报 400。所以不能用「invalid 是否报错」判断是否透传 —— 要看不同档位的 token 是否拉开差距。

常见报错排查

`"thinking.type.enabled" is not supported for this model`

经 AWS（Bedrock）通道调用 Opus 4.7 / 4.8 时，最常见的一个 400 报错：

status_code=400, InvokeModelWithResponseStream: ... Bedrock Runtime,
StatusCode: 400, ValidationException: "thinking.type.enabled" is not supported
for this model. Use "thinking.type.adaptive" and "output_config.effort" to
control thinking behavior.

原因：请求体里传了旧版的固定预算思考写法 thinking: { "type": "enabled", "budget_tokens": N }。Opus 4.7 / 4.8（以及更新的模型）已移除这种写法，只支持自适应思考；AWS 上游会直接返回 ValidationException 400。这与 thinking 自适应思考章节的提示一致。

报错里的 thinking.type.enabled 就是你请求体里的 thinking.type 字段值为 "enabled"。同理，budget_tokens 也已不被支持；temperature / top_p / top_k 在这些模型上一并被移除，传了也会 400。

解决：删掉 type: "enabled" 和 budget_tokens，改用 adaptive + output_config.effort 控制思考深度。

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "summarized" },
  "output_config": { "effort": "xhigh" },
  "messages": [
    { "role": "user", "content": "你的问题" }
  ]
}

旧写法（会 400）	新写法
`"thinking": { "type": "enabled", "budget_tokens": 8000 }`	`"thinking": { "type": "adaptive" }`
用 `budget_tokens` 控制思考量	用 `output_config.effort`（`low` ~ `max`）控制
`temperature` / `top_p` / `top_k`	删除即可，用 prompt 引导，无需采样参数

不想思考时：Opus 4.7 / 4.8 可传 thinking: { "type": "disabled" }，或干脆不传 thinking 字段（不传即不思考）。

参考

Anthropic — Effort 文档：platform.claude.com/docs/en/build-with-claude/effort
AWS Bedrock — Adaptive thinking：docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-adaptive-thinking.html
AWS Bedrock — Claude Opus 4.8：docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-8.html

产品基础

基础 API

图片 API（官转）

视频 API（官转）

多模态理解 API

文本 API

Claude Effort 努力档位与思考指南

在线测试工具

推理测试 · API易在线工具

请求的基本结构

Endpoint 与请求头

最小请求体

effort 努力档位

带 effort 的请求体

档位一览

各模型支持的档位

thinking 自适应思考

thinking 摘要的本质（重要）

解析响应

流式（stream）下的 thinking 字段

完整可运行示例

经 Bedrock 时的注意事项

常见报错排查

`"thinking.type.enabled" is not supported for this model`

参考

​在线测试工具

推理测试 · API易 在线工具

​请求的基本结构

​Endpoint 与请求头

​最小请求体

​effort 努力档位

​带 effort 的请求体

​档位一览

​各模型支持的档位

​thinking 自适应思考

​thinking 摘要的本质（重要）

​解析响应

​流式（stream）下的 thinking 字段

​完整可运行示例

​经 Bedrock 时的注意事项

​常见报错排查

​"thinking.type.enabled" is not supported for this model

​参考

在线测试工具

推理测试 · API易在线工具

请求的基本结构

Endpoint 与请求头

最小请求体

effort 努力档位

带 effort 的请求体

档位一览

各模型支持的档位

thinking 自适应思考

thinking 摘要的本质（重要）

解析响应

流式（stream）下的 thinking 字段

完整可运行示例

经 Bedrock 时的注意事项

常见报错排查

`"thinking.type.enabled" is not supported for this model`

参考