AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

从 Fable 5.1 迁移到 Fable 5.2：改模型 ID、设 effort、调整 API 参数

チュートリアル

从 Fable 5.1 迁移到 Fable 5.2：改模型 ID、设 effort、调整 API 参数

把 Claude Code 与 API 从 Fable 5.1 迁到 Fable 5.2 的实操步骤：替换模型 ID（含 Amazon Bedrock 写法）、用 /model 与 /effort 控制会话与默认值、在 API 侧去掉 tool_choice 强制并省略采样参数、按 effort 调整 max_tokens，并说明两版在费用与耗时上的取舍。

Fable 5.2 发布后，从 Fable 5.1 迁过去并不需要重写整套调用逻辑，真正要动的只有三处：模型 ID、effort 档位、以及 API 请求里几个已经不再适用的参数。这篇教程把这三处拆成可以照着敲的步骤，并说明在 Claude Code 与直接调用 API 两种场景下，改动分别落在哪里、默认值有什么差别、哪些旧配置必须删掉。

适合读这篇的人：已经在用 Fable 5.1 跑 Claude Code 或自建 API 调用，想评估是否值得切换，或者已经决定切换但不确定要改哪些字段。文中涉及的单价、上下文与配额等易变信息，请以官网当前公布的信息为准。

准备工作

动手之前先确认几件事，否则改完参数也跑不起来。

  • 可用的模型访问权限。Fable 5.2 是当前的最新模型，Fable 5.1 仍处于可用状态（legacy），两者可以并存，因此迁移期间可以随时回退。
  • Claude Code 客户端。本文涉及的会话级切换行为依赖较新的版本：-p 中执行 /model 只影响当次会话、不写入默认值的行为需要 Claude Code v2.1.205 及以上；选择界面里按 s 只切换当前会话的行为需要 v2.1.257 及以上。版本号请以官网当前信息为准。
  • API 凭据与提供方。确认你的调用走的是 Claude API、Microsoft Foundry、Claude Platform on AWS、Claude Models on Google Cloud，还是 Amazon Bedrock——模型 ID 的写法在 Bedrock 上不同。
  • 一份可回退的旧配置。把当前使用的模型 ID、effort 档位、max_tokens 与采样参数记录下来，方便对比与回滚。
  • 一个用于验证的小任务。迁移后先用一个短任务跑通，确认请求不再返回 400，再放到正式流程里。

操作步骤

第一步：替换模型 ID

模型 ID 是最先要改的地方，而且写法随提供方而变。

提供方Fable 5.2 的模型 IDFable 5.1 的模型 ID
Claude API、Microsoft Foundry、Claude Platform on AWS、Claude Models on Google Cloudclaude-fable-5-2claude-fable-5-1
Amazon Bedrockanthropic.claude-fable-5-2anthropic.claude-fable-5-1

如果代码里把模型 ID 写成了常量或环境变量，改一处即可；如果散落在多个脚本里，建议先全局搜索 claude-fable-5-1 与 anthropic.claude-fable-5-1 两个字符串，逐个替换。

第二步：在 Claude Code 里切换模型

Claude Code 提供三种切换方式，区别在于改动是否会被保存为默认值。

方式生效范围
在 /model 的选择界面按 Enter切换并保存为后续新会话的默认模型
在 /model 的选择界面按 s仅当前会话
直接输入 /model <name>与按 Enter 相同，会保存为默认值
在 -p 执行过程中使用 /model仅该会话，不保存（Claude Code v2.1.205 及以上）
启动时加 claude --model <name> 或设置环境变量 ANTHROPIC_MODEL仅该次启动的会话
在设置文件的 model 项中固定新会话的默认值
环境变量 ANTHROPIC_DEFAULT_MODEL新会话的默认值

想把当前会话切到 Fable 5.2，同时把它设为以后的默认模型：

/model claude-fable-5-2

只想试一次、不动默认值，就在启动时指定：

claude --model claude-fable-5-2

如果需要在多个终端里同时跑不同模型，不要用 /model 来回切，而是每个终端启动时各自带上 --model，这样互不干扰。

第三步：确定 effort 的起点

effort 决定模型在思考上投入多少。迁移时最容易踩的坑，是把 Fable 5.1 上用的档位原样搬过来——官方建议在迁移时按自己的评测重新定档，而不是沿用旧值。

推荐的起点是 high：能力提升的大部分在 high 上就能拿到，再往上收益不稳定、因任务而异。只有在最困难的长时间编码或 agent 任务上，并且自己的评测确实测到了提升，才考虑 xhigh；反过来，如果评测证明质量能保住，可以降到 medium 或 low。max 留给测量模型上限、或者不在意时间和 token 消耗的少数任务。

注意默认值在两个入口上并不一致：

入口不指定 effort 时的默认档位
Claude Codemedium（与 Opus 5.5、Sonnet 5.5、Haiku 5.5 相同）
APIhigh（Fable 5.1 也是 high）

也就是说，在 Claude Code 里什么都不写，会从 medium 起步；而在 API 里省略 effort，会从 high 起步。如果你的评测是在 high 上做的，Claude Code 侧就要显式指定，否则实际跑的不是你测过的配置。

第四步：在 Claude Code 里指定 effort

把当前会话设为 high 并保存为默认值：

/effort high

只想让当前会话生效，就在选择界面按 s（Claude Code v2.1.257 及以上）。/effort 的生效范围如下：

用法生效范围
在选择界面按 Enter，或直接输入档位名保存为默认值，后续会话继续生效
在选择界面按 s仅当前会话（v2.1.257 及以上）
在 -p 执行过程中使用 /effort仅该会话，不保存
/effort auto清除当前模型已保存的档位

也可以在启动时把模型和 effort 一起传进去，--effort 只对当次会话生效：

claude --model claude-fable-5-2 --effort high

需要写进设置文件时，在项目级、本地级、管理员级设置，或通过 --settings 传入的设置顶层写 effortLevel。注意这个键对所有模型生效：

{
  "model": "claude-fable-5-2",
  "effortLevel": "high"
}

不想改文件、只想临时试一下，可以在启动时用 --settings 直接传 JSON：

claude --model claude-fable-5-2 --settings '{"effortLevel":"high"}'

如果不同模型需要不同档位，用 modelSettings 按模型分别设置。effortLevel 可接受的值为 low、medium、high、xhigh，它同时充当未在 modelSettings 中单独指定档位的模型的默认值。max 不能写进这两个键中的任何一个。此外也可以用环境变量 CLAUDE_CODE_EFFORT_LEVEL 来设定。

第五步：调整 API 请求参数

API 侧除了换模型 ID，还要按 Fable 5.2 的约束清理请求体。逐项对照下表：

项目Fable 5.2 下的处理方式
思考（thinking）始终开启，无法关闭；深度通过 effort 调节
tool_choice用类型 any 或 tool 强制使用工具会返回 400 错误，必须去掉强制
temperature、top_p、top_k省略不传
effort省略时为 high；迁移时按自己的评测重新定档
max_tokenshigh 及以上要取较大值

其中 max_tokens 这一条尤其容易被忽略：它是思考内容与回复正文合计的输出上限，而 Fable 5.2 在 high 及以上档位会消耗明显更多的思考 token，沿用旧值很容易被截断。具体该设多大，取决于任务长度，建议先用一个代表性任务观察实际输出量再定。

把上面几条落到代码里，请求体大致是这样：

{
  "model": "claude-fable-5-2",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "..." }
  ]
}

对比迁移前的写法，需要删掉的是 temperature、top_p、top_k 三个字段，以及 tool_choice 中形如 {"type": "any"} 或 {"type": "tool", "name": "..."} 的强制写法。如果业务逻辑依赖“必须调用某个工具”，改成在提示词里明确要求，或由应用层校验返回结果，而不是靠 tool_choice 强制。

一个完整示例

下面把整条链路串起来：从命令行启动一个使用 Fable 5.2、effort 为 high 的 Claude Code 会话，再用 API 发一次等价请求。

场景一：Claude Code 交互式会话。先启动并指定模型与 effort，两者都只对本次会话生效，不影响默认配置：

claude --model claude-fable-5-2 --effort high

进入会话后确认当前配置，如果发现 effort 不是 high，用 /effort high 补上。若希望这套配置成为以后所有新会话的默认值，改用 /model claude-fable-5-2 与 /effort high，两者都会写入用户设置。

场景二：非交互式批量执行。在脚本里跑一次性任务时，用 -p 模式，并在启动参数里固定模型与 effort：

claude -p "整理这个目录下的变更说明" --model claude-fable-5-2 --effort high

这种写法不会改动默认模型，适合在 CI 或多终端并行时使用。

场景三：直接调用 API。把模型 ID 换成 claude-fable-5-2（Amazon Bedrock 上为 anthropic.claude-fable-5-2），去掉采样参数与工具强制，并把 max_tokens 放大：

{
  "model": "claude-fable-5-2",
  "max_tokens": 16000,
  "messages": [
    { "role": "user", "content": "把这段日志按错误类型归类" }
  ]
}

如果请求返回 400，优先检查两处：tool_choice 是否还残留 any 或 tool 的强制写法，以及是否还在传 temperature、top_p、top_k。

场景四：用设置文件统一管理。团队里多人共用一套配置时，把模型与 effort 写进设置文件，避免每个人各自记参数：

{
  "model": "claude-fable-5-2",
  "effortLevel": "high"
}

需要按模型区分档位时，改用 modelSettings 单独指定，effortLevel 则作为其余模型的兜底值。

注意事项

两个入口的默认 effort 不同。Claude Code 不指定时是 medium，API 不指定时是 high。如果你的评测是在 high 上做的，Claude Code 侧必须显式指定，否则实际运行配置与评测配置不一致。

不要直接沿用 Fable 5.1 的档位。迁移时应按自己的评测重新定档，从 high 起步，再根据结果上下调整。

max 不能写进设置文件。effortLevel 与 modelSettings 都只接受 low、medium、high、xhigh。

思考无法关闭。Fable 5.2 的思考始终开启，只能通过 effort 调节深度。这意味着输出 token 中会包含思考部分，计费与截断判断都要把这块算进去。

工具强制会直接报错。tool_choice 使用 any 或 tool 会返回 400，不是降级处理，而是请求失败。迁移前务必检查所有构造请求体的位置。

权限收紧的环境下，被拒绝的命令可能变多。在只自动放行部分操作、其余一律拒绝的配置下（例如 --permission-mode dontAsk），Fable 5.2 触发的拒绝次数可能高于 Fable 5.1，被拒绝的命令不会执行，任务仍会继续推进。如果生产环境对允许的操作范围限制得很窄，迁移后应额外统计被拒绝的命令数量，评估对结果的影响。

费用与耗时的取舍要按用途判断。在小型任务上的对比结果显示，两版成功率相同，Fable 5.2 的费用更低、耗时更长。因此：需要反复自动执行、费用会累积的批处理场景，Fable 5.2 更合适；需要人坐在屏幕前等结果的交互场景，Fable 5.1 的响应更快。这类结论来自小规模任务，困难任务、长时间 agent 作业、大型代码库以及 high 以外的档位都未经验证，不要直接外推到所有场景。

单价与配额以官网为准。Fable 5.2 的各项单价低于 Fable 5.1，Batch API 下输入与输出均有折扣，但具体数字、可用区域与速率限制会随时间调整，做预算前请查阅官网当前信息。

Fable 5.1 仍可使用。它处于 legacy 状态，迁移期间可以保留旧配置作为回退路径，不必一次性全量切换。

戻る