Claude Opus 4.7 迁移指南：升级前要排查的 7 个工作流风险

升级 Claude Opus 4.7，最怕的不是旧 prompt 一夜之间全部失效，而是旧系统把关键控制藏在过时参数、旧 token 估算或不够明确的工具策略里。Anthropic 的迁移文档显示，Opus 4.7 延续了 Opus 4.6 的主要平台能力，但迁移时仍要处理 thinking configuration、sampling-parameter removal、task budgets 与 tokenization 等变化。

本文以 Anthropic 明确描述的 Opus 4.6 → Opus 4.7 迁移为基准。如果你是从更早的 Claude 模型升级，可以把这份清单当作回归测试起点，但仍应另外比对原模型版本的差异。

先判断：你用 Claude 的方式是哪一种？

升级工作量取决于使用方式。手动聊天、文档草稿一类场景，重点通常是常用 prompt 和输出风格的回归测试；API、RAG、Agent、coding 或 vision 工作流，则要更仔细地检查参数、工具策略、token 成本和延迟。

使用方式	升级前最该检查
手动聊天、文档草稿、知识工作	常用 prompt、语气、输出格式、引用规则、工具使用规则
Messages API / SDK	model ID、thinking 设置、sampling 参数、token counting、错误处理
Tool use / RAG / web search	何时必须查工具、何时不得猜测、工具失败时如何 fallback
长任务 Agent / coding Agent	effort、task budget、token budget、延迟和回归评测
图片、截图、PDF、computer-use 工作流	图像分辨率、downsample 策略、token 成本、视觉识别质量

1. 先修 breaking change：extended thinking 改为 adaptive thinking

第一步不是重写 prompt，而是扫 API 设置。Anthropic 表示，开发者可以通过 Claude API 使用 claude-opus-4-7；如果你的应用直接指定 model ID，建议先把它纳入小流量测试或 shadow eval，而不是一键全量切换。

更关键的是 thinking 设置。Anthropic migration guide 明确写到，Claude Opus 4.7 或之后不再支持旧式 extended thinking 的 budget_tokens 设置，并会返回 400 error；迁移方向是改用 adaptive thinking。

实操上，先做三件事：

• 搜索代码、SDK wrapper、prompt runner 和内部平台配置里的 budget_tokens。
• 移除旧式 extended thinking 设置，改用你所使用 API 或 provider 支持的 adaptive thinking 配置。
• 不要再把固定 thinking token budget 当成主要控制器；改用文档支持的 effort、task budget、prompt 约束和 eval 来校准任务深度。

Anthropic 的 prompting best practices 也把 effort levels、task budgets、thinking configuration、sampling-parameter removal 和 tokenization 列为从 Opus 4.6 迁移到 Opus 4.7 时需要关注的 API 变化。

2. 把 sampling 参数的控制迁回 prompt 和 eval

如果旧工作流依赖 temperature、top_p 或 top_k 来控制创意度、稳定性或输出差异，升级时要重新设计控制方式。Anthropic 的 prompting 文档把 sampling-parameter removal 列入 Opus 4.7 迁移注意事项；OpenRouter 的 Claude 4.7 migration guide 也列出 sampling parameters removed、adaptive-only thinking 与 provider-specific effort 行为。

这会影响三类常见任务：

• 创意写作、广告文案：过去可能靠更高 sampling 获得更发散的版本。
• 客服、合规、资料抽取：过去可能靠更低 sampling 追求稳定输出。
• 批量生成：过去可能用 sampling 参数控制多样性。

升级后，更稳的做法是把规则写进 prompt 和 eval：明确语气、格式、禁止事项与成功标准；用 few-shot 示例固定输出风格；对抽取、分类、报告生成使用结构化输出要求；把旧版 Claude 的 golden examples 做成回归评测，逐题比较 Opus 4.7 的格式遵循、正确率、成本和延迟。

3. Tool use：把“什么时候查工具”写成明确 policy

如果旧工作流只是给 Claude 一个宽泛目标，让模型自行判断何时查工具，升级时最值得补强的是 tool policy。Anthropic 的 prompting best practices 指出，Claude 最新模型受训于精确遵循指令，并且会受益于明确要求使用特定工具；同一份文件也建议将 adaptive thinking 用于 multi-step tool use、complex coding tasks 和 long-horizon agent loops 等 Agentic workload。

可以把这类规则直接写进 system prompt 或工作流 policy：

• 涉及实时信息、价格、政策、版本差异或外部文档时，必须先使用指定查询工具。
• 内部知识库没有答案时，必须说明无法确认，不得猜测。
• 工具结果彼此矛盾时，先列出冲突，再给出保守结论。
• 最终答案要区分哪些信息来自工具结果，哪些是模型推理。

这通常比单纯替换 model ID 更重要。tool policy 会直接影响 Agent 是否漏查资料、是否在证据不足时编造答案，以及在工具结果冲突时是否过度自信。

4. 长任务 Agent：用 effort 和 task budget 管成本

Opus 4.7 的一个迁移重点，是长任务与 Agentic 工作流的预算控制。Anthropic 的 What’s new 文件指出，Opus 4.7 introduces task budgets；官方文档也说明，effort 参数可在能力、速度和 token spend 之间取舍，task budget 则让 Claude 对整个任务可用 token 有一个大致估计。

如果你的工作流是 coding Agent、research Agent、browser Agent、长时间数据处理或多工具 loop，建议把预算拆成三层：

• 单次回复预算：最终输出最多可以用多少 token。
• 推理与工具预算：多步骤任务中，模型可以投入多少 reasoning、tool calls 和 tool results。
• 任务级预算：整段 Agent loop 的成本与延迟上限。

不要只用最终输出上限来估算整段 Agent loop 的成本。长任务的开销可能来自多次工具查询、工具结果回灌、图片或 PDF 解析、重试与最终输出；Opus 4.7 的 task budgets 和新 tokenizer 都意味着这部分需要重新 benchmark。

5. Token、RAG、缓存和 batch：全部重跑 benchmark

这是最容易被低估的迁移项。Anthropic 文档指出，Opus 4.7 的新 tokenizer 在处理文本时，可能会比前代模型使用约 1x 到 1.35x 的 token；/v1/messages/count_tokens 对 Opus 4.7 返回的 token count 也会不同于 Opus 4.6，Anthropic 建议用该 endpoint 重新估算。

升级前建议重测：

• RAG chunk size 和 overlap。
• 长文档截断阈值。
• conversation memory 长度。
• prompt caching 命中率与成本预估。
• batch job 的成本上限。
• Agent 每轮工具结果可回灌的大小。
• 图片与 PDF 的预处理策略。

如果旧工作流已经接近成本上限或 context limit，不要直接沿用旧版 token 估算。先用核心 prompt、长文档样本和高流量任务跑 token benchmark，再决定是否调整 chunking、截断规则或 cache key 设计。

6. 图片、截图和 PDF：重新设定预处理规则

Opus 4.7 文档提到 high-resolution image support；官方文档也提醒，如果不需要额外图像保真度，应在送入 Claude 前先 downsample，以避免 token 使用增加。

这会影响三类工作流：

• 截图理解：例如 UI QA、表格截图、dashboard 分析。
• 文档图像处理：例如扫描 PDF、合同截图、演示文稿页面。
• computer-use / browser automation：例如模型需要理解画面位置、按钮、表单和错误信息。

从 Opus 4.6 升级时，PDF 和 vision 能力本身仍属于 Anthropic 列出的同一组主要平台能力；真正要重测的是送多大的图片、是否需要高分辨率，以及 downsample 后关键文字和 UI 元件是否仍能识别。

7. Provider 或内部 gateway：不要假设参数映射完全一致

如果你不是直接调用 Anthropic API，而是通过 OpenRouter、云平台或内部 gateway 调用 Claude，不能假设字段名、忽略规则和 effort 行为完全相同。OpenRouter 的 Claude 4.7 migration guide 就单独列出 sampling parameters removed、adaptive-only thinking 与 provider-specific effort 行为。

因此，除了 Anthropic 文档，也要查你实际 provider 的 migration note。尤其是多模型 router、fallback gateway、内部 prompt 平台，常会把上游 API 参数封装成自己的字段；升级时应确认哪些字段仍有效、哪些会被忽略、哪些会直接报错。

哪些地方通常不用大改？

如果你是从 Opus 4.6 升到 Opus 4.7，平台能力并不是全部推倒重来。Anthropic migration guide 表示，Opus 4.7 支持与 Opus 4.6 相同的主要功能集合，包括 1M token context window、128k max output tokens、adaptive thinking、prompt caching、batch processing、Files API、PDF support、vision，以及完整的 server-side / client-side tools。

也就是说，第一优先级通常不是重写这些基础设施：

• Files API 与文件上传流程。
• PDF / vision 能力是否存在。
• prompt caching 或 batch processing 是否可用。
• 工具调用能力本身。
• 长 context 能力本身。

真正要重新校准的是你如何控制这些能力：何时用工具、花多少 token、用多高 effort、图片送多大，以及失败时如何 fallback。

实际迁移 checklist

可以把下面这份清单交给工程团队、AI platform owner 或负责 Claude 工作流的同事，用来快速找出高风险点。

API 与参数

• 将模型名称切换到 claude-opus-4-7，并先做小流量或 shadow eval；Anthropic 表示开发者可通过 Claude API 使用这个 model ID。
• 搜索 thinking、budget_tokens 和旧式 extended thinking wrapper，改成 adaptive thinking；Opus 4.7 或之后不支持旧式设置，会返回 400。
• 搜索 temperature、top_p、top_k 等 sampling 控制，改用 prompt、few-shot、schema 和 eval 管理稳定性。
• 如果通过 OpenRouter 或其他代理层使用 Claude，另查该 provider 的 Claude 4.7 migration guide 与参数映射。

Prompt 与 tool use

• 把何时必须用工具写进 system prompt；Anthropic 文档指出，最新 Claude 模型受益于明确的 tool-use 指示。
• 把何时不能猜答案、资料不足时如何回答写清楚。
• 把工具结果冲突、工具失败、外部资料不足时的 fallback 行为写清楚。
• 对资料抽取、分类、报告生成等工作流加入结构化输出格式。

Agent 与 coding 工作流

• 对 coding Agent、research Agent、browser Agent 重新校准 effort 与任务预算；Anthropic 文档将 adaptive thinking 与 multi-step tool use、complex coding tasks、long-horizon agent loops 放在一起讨论。
• 评估是否使用 task budgets；Opus 4.7 文档列出 task budgets，并提醒 token counting 与前代不同。
• 不要只用最终输出上限估算整段 Agent loop 成本；把工具调用、工具结果、重试和最终输出都纳入成本模型。
• 用旧版 Claude 的成功案例建立 regression eval，比较 Opus 4.7 的成功率、格式遵循、延迟和成本。

Token、文档与图像

• 用 /v1/messages/count_tokens 重新估算核心 prompt、RAG chunks、长文档与批量任务成本。
• 重测 chunk size、截断阈值、conversation memory 和 prompt caching 策略。
• 对图片、截图和 PDF 页面建立 downsample policy；不需要高保真时先降低分辨率，以控制 token 使用。

建议升级顺序

更稳的升级方式不是一次性全面替换，而是分四步推进：

1. 静态扫描：找出 model ID、thinking、sampling、token counting、image preprocessing 和 provider-specific 参数。
2. 小流量 eval：用既有 golden set 比较旧版 Claude 与 Opus 4.7 的输出质量、格式遵循、tool use、成本和延迟。
3. 重写高风险 prompt：优先处理 tool use、RAG、coding Agent、资料抽取和合规任务。
4. 逐步放量：监控 token 使用、工具调用次数、错误率、延迟和人工反馈。

一句话总结：从旧版 Claude 迁移到 Opus 4.7，核心不是把 prompt 全部重写，而是把旧工作流里隐含的控制逻辑显性化。thinking 改 adaptive，sampling 改 prompt/eval，长任务改预算驱动，图片与 token 成本重新 benchmark；这样升级风险最低，也最能保留旧工作流的可控性。