实战 Claude 的 effort 参数：让智能体“按需用力“省 token（含 Opus 4.8 更新）

TL;DR

effort 参数最早随 Claude Opus 4.5（2025 年 11 月）引入，用来控制模型"思考多努力"；在 2026 年 5 月 28 日发布的 Claude Opus 4.8 中，它进一步成熟------effort 控制被带到了 claude.ai 界面，模型也更擅长在长程任务里自我纠错。本文给应用开发者一套可直接套用的思路：用低 effort 跑批量、简单、对延迟敏感的任务，用高 effort 跑复杂推理与长程智能体任务，并通过实测对比成本与质量来挑档位。下面给出可运行的 Python 代码与一套压测脚本骨架。

为什么 effort 值得你关心

对智能体类应用，真正吃成本的往往是模型"想得太多"------在不需要深思的子任务上也输出长篇推理。effort 参数的意义就是把"用多少力"变成一个你能显式控制的旋钮：简单任务调低，省 token、降延迟；难任务调高，换质量。

官方数据给了很实在的参照：在 Opus 4.5 上，medium effort 能在追平此前最强模型表现的同时少用约 76% 的 token。Opus 4.8 延续了这套机制，并在 agentic coding、computer-use（浏览器智能体）等基准上进一步提升------这些能力在高 effort 下最能发挥，但并非每个调用都需要。

注意：参数的确切字段名与取值范围请以你所用 SDK 版本的官方文档为准，下面代码以通用调用形态示意，落地时按文档校正字段名。

实战一：按任务类型分配 effort

核心思路是写一个路由函数，根据任务复杂度选择档位。

python 复制代码

import anthropic

client = anthropic.Anthropic()  # 读取环境变量 ANTHROPIC_API_KEY
MODEL = "claude-opus-4-8"  # effort 起于 4.5，本文用当前最新的 Opus 4.8

def classify_effort(task: str) -> str:
    """极简启发式：实际可换成一个轻量分类模型或规则集。"""
    cheap_signals = ["格式化", "抽取字段", "翻译一句", "分类", "yes/no"]
    if any(s in task for s in cheap_signals) or len(task) < 80:
        return "low"
    if any(s in task for s in ["重构", "调试", "多步", "规划", "证明"]):
        return "high"
    return "medium"

def run(task: str, effort: str | None = None) -> str:
    effort = effort or classify_effort(task)
    resp = client.messages.create(
        model=MODEL,
        max_tokens=2048,
        # 若 SDK 暴露的是 thinking/effort 配置，请按文档替换下面这行
        extra_body={"effort": effort},
        messages=[{"role": "user", "content": task}],
    )
    return resp.content[0].text

print(run("把这段地址抽取成 JSON：北京市海淀区中关村大街1号"))  # → low
print(run("帮我重构这个有竞态条件的多线程下载器并解释每步"))      # → high

实战二：用一次压测挑出"够用就好"的档位

不要凭感觉选 effort。对你自己的真实任务集跑一轮对比，看质量是否真的随 effort 提升、提升是否值回 token。

python 复制代码

import time, json

def benchmark(tasks: list[str], efforts=("low", "medium", "high")):
    rows = []
    for t in tasks:
        for e in efforts:
            t0 = time.time()
            out = run(t, effort=e)
            rows.append({
                "task": t[:40],
                "effort": e,
                "latency_s": round(time.time() - t0, 2),
                "out_chars": len(out),
            })
    print(json.dumps(rows, ensure_ascii=False, indent=2))
    return rows

# 评分可接入你已有的自动判分（如单测通过率、字段抽取准确率）
benchmark(["把这句翻译成英文：今天发布了新模型",
           "为给定函数写出能覆盖边界条件的单元测试"])

判定规则很简单：如果某任务在 low 和 high 下的下游指标几乎一致，就固定用 low；只有当高档位带来可量化的质量提升时，才为它多付 token。

实战三：在智能体循环里动态升档

长程智能体里更聪明的做法，是默认低档跑，只有在遇到失败或不确定时才临时升档重试。

python 复制代码

def agent_step(task: str, max_retries: int = 1) -> str:
    out = run(task, effort="low")
    attempt = 0
    while needs_more_thinking(out) and attempt < max_retries:
        out = run(task, effort="high")   # 升档重试
        attempt += 1
    return out

def needs_more_thinking(out: str) -> bool:
    # 替换成你的真实校验：JSON 是否合法、测试是否通过、是否含"我不确定"
    return "我不确定" in out or len(out) < 5

这套"先省后补"的策略，能在绝大多数简单步骤上吃到低成本，只在真正困难的步骤上花算力，往往是性价比最高的组合。

落地清单

先把任务分成廉价/普通/困难三类并默认走低档；再用真实任务集压测，只为带来可量化质量提升的步骤升档；最后在智能体循环里加"失败再升档重试"。务必以官方文档核对 effort 字段名与取值，再上生产。

参考资料

Anthropic, Introducing Claude Opus 4.8: https://www.anthropic.com/news/claude-opus-4-8
Anthropic, Effort (Claude API Docs): https://platform.claude.com/docs/en/build-with-claude/effort