Claude Fable 5 升级 5.1：API迁移与兼容检查

1. 迁移前先建立 Fable 5 基线

保存一组能够代表生产流量的请求：普通对话、长上下文、结构化输出、并行工具、失败重试和多轮 thinking。记录模型 ID、HTTP 状态、request ID、输入/输出/缓存 Token、总耗时和业务验收结果。没有旧版本基线，就无法判断 5.1 是改进还是行为漂移。

2. 先在测试环境切换模型 ID

MODEL_ID=claude-fable-5-1
FALLBACK_MODEL=claude-fable-5

先请求模型列表确认渠道存在，再发最小文本请求。401 表示密钥或权限问题，404/模型不存在通常表示渠道尚未开放，429 需要区分额度和限流；这些状态码应由代码处理，不要交给模型猜测。

3. 回归所有 tool use 分支

重点测试强制工具选择、连续工具调用、工具参数校验、工具报错回传和结束条件。对每个工具保留 JSON Schema 测试样本，确保缺失字段、额外字段和错误类型都能被确定性代码拒绝。兼容渠道还要检查 Anthropic tool block 是否被转换成 OpenAI 风格调用，以及转换后是否丢失调用 ID。

4. 检查 thinking block 的保存与回放

如果应用会把上一轮响应完整写回下一轮，请确认 thinking block 的顺序、签名和关联关系符合当前 API 要求。不要自行拼接、删改或伪造推理块。只需要最终答案的业务，可只保存必要的可见消息与结构化状态，减少兼容风险和上下文膨胀。

5.1 的 effort 应作为显式配置，而不是从用户文本里猜。规划、执行和复核可以采用不同档位，但必须设置上限，防止简单任务长期运行。

5. 重新计算缓存与长上下文成本

将稳定的系统提示、工具定义和固定资料放入可缓存区域，把用户问题和实时数据留在动态区。分别观察 cache creation、cache read、普通输入和输出用量。缓存命中率低时，继续堆叠大上下文不会自动省钱。

6. 灰度上线与回退

先放 1% 非关键流量，验证状态码和账单字段。
扩大到 5%—10%，比较业务成功率和单位任务成本。
工具调用或结构化输出失败时回退 Fable 5/Opus 5，但限制重试次数。
只有在连续观察窗口稳定后，才调整默认模型。

不要在一次请求中隐式切换多个模型，否则日志无法解释。模型资料见 Claude Fable 5.1 API；选型差异见 Fable 5.1 vs Opus 5。

7. 三个会直接阻断迁移的变化

变化	旧代码风险	迁移办法
强制 tool choice	`any` 或指定 `tool` 会返回 HTTP 400	改用 `auto`，在提示中明确要求调用，并使用 strict tools 或 JSON 输出约束
thinking 向后兼容	Fable 5 无法读取 Fable 5.1 产生的 thinking blocks	回退旧模型时仅传递可见消息和应用状态，不回放新模型 thinking
历史消息被编辑	改写更早轮次会让已保存 thinking blocks 失效	保持历史不可变；需要修正时新增一轮消息

这些变化必须进入自动化回归测试。只验证普通文本请求会漏掉最容易在生产中出错的分支。

8. 强制工具调用的前后差异

迁移前：可能在 5.1 返回 400

{
  "model": "claude-fable-5-1",
  "tool_choice": {"type": "tool", "name": "lookup_order"},
  "tools": [{"name": "lookup_order", "input_schema": {"type": "object"}}]
}

迁移后：auto + 明确指令 + 严格 schema

{
  "model": "claude-fable-5-1",
  "tool_choice": {"type": "auto"},
  "tools": [{
    "name": "lookup_order",
    "description": "查询订单；回答订单状态前必须调用",
    "strict": true,
    "input_schema": {
      "type": "object",
      "properties": {"order_id": {"type": "string"}},
      "required": ["order_id"],
      "additionalProperties": false
    }
  }]
}

应用代码仍要校验参数、订单权限和返回结果。模型选择工具不等于模型获得执行权限。

9. Thinking block 兼容矩阵

产生 thinking 的模型	下一轮模型	处理建议
Fable 5	Fable 5.1	新模型可读取旧模型块，但仍需保留原始顺序
Fable 5.1	Fable 5	不要回传 5.1 thinking；改传可见答案与结构化状态
Fable 5.1	Fable 5.1，历史未改	保持原始消息和 block，不自行拼接
Fable 5.1	Fable 5.1，早期消息被编辑	thinking 失效；从最后一个可信状态重新开始

Fable 5.1 使用 adaptive thinking，不能像部分旧模型那样直接关闭。控制成本时应调整 effort，而不是伪造或删除 thinking block。

10. Effort 校准不要一次拍板

从 high 开始建立基线，再分别测试 medium、xhigh 或 max。低 effort 可能减少工具调用和解释，高 effort 可能增加计划、搜索和验证步骤；因此必须同时记录成功率和 Token，不能把“输出更长”当作“质量更好”。

medium：格式转换、明确的小修复和低风险批处理。
high：默认迁移起点，适合大多数复杂生产任务。
xhigh：多轮搜索、编码 Agent 和需要反复工具调用的任务。
max：仅留给错误代价极高且高 effort 已失败的少数问题。

11. 灰度、监控和回滚模板

MODEL_PRIMARY=claude-fable-5-1
MODEL_FALLBACK=claude-opus-5
ROLLOUT_PERCENT=5
MAX_MODEL_ATTEMPTS=2
LOG_FIELDS=model,request_id,status,usage,tool_calls,latency,fallback_reason

回退不应偷偷发生。每次回退都记录原因，并避免把 5.1 thinking block 交给不能读取它的旧模型。发布顺序建议为：影子流量 → 1% 非关键请求 → 5% → 20% → 50% → 100%；每一阶段都设置最低成功率、最高单位任务成本和最长延迟阈值。

发布失败条件

出现未处理的 400 tool choice 错误。
结构化输出或工具参数通过率低于旧版本基线。
单位成功任务成本超过预算阈值。
回退后对话状态丢失或重复执行有副作用的工具。

官方来源：Anthropic Fable 5.1 migration guide、Fable 5.1 overview、Effort documentation，核对日期 2026-09-19。实际渠道字段与权限以接口响应为准。