本指南涵盖 Messages API 代码的迁移。如果您使用 Claude Managed Agents,则除了更新模型名称外无需进行任何更改。
使用 Claude API 技能自动完成迁移。 在 Claude Code 中,运行 /claude-api migrate 以调用内置的 Claude API 技能。它适用于本页面上的任何目标模型:
/claude-api migrate this project to claude-opus-4-8该技能会应用模型 ID 替换,并根据需要在您的代码库中针对目标模型应用破坏性参数更改、预填充替换和 effort 校准,然后生成一份需要手动验证的项目清单。在编辑任何文件之前,它会要求您确认迁移范围(整个工作目录、子目录或特定文件列表)。该技能还会检测 Amazon Bedrock、Vertex AI、Claude Platform on AWS 和 Microsoft Foundry 客户端,并针对每个平台调整模型 ID 格式和功能更改。
Claude Mythos 5 是 Claude Mythos Preview(仅限邀请的研究预览版)的访问受限后继版本。如需具有相同功能的正式发布模型,请参阅 Claude Fable 5。
迁移基本上是即插即用的。Claude Mythos 5 使用与 Claude Mythos Preview 相同的 Messages API 和相同的工具使用模式,并且由于两个模型使用相同的分词器,令牌数量大致保持不变。需要检查的关键更改是不再可用的功能(在下一节中列出)和思考输出。
有关 Claude Mythos Preview 的停用时间表,请参阅模型弃用。
model = "claude-mythos-preview" # Before
model = "claude-mythos-5" # After扩展思考和思考令牌预算: claude-mythos-5 不支持手动扩展思考(thinking: {type: "enabled", budget_tokens: N}),会返回 400 错误。自适应思考始终开启:模型会在每个请求中自行决定何时思考以及思考多少,无需任何 thinking 配置。thinking: {type: "disabled"} 会返回错误。budget_tokens 没有直接替代项:思考是自适应的,而 effort 参数是一个独立的输出级别控制,而非思考预算。
之前(Claude Mythos Preview):
client.messages.create(
model="claude-mythos-preview",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)之后(Claude Mythos 5):
client.messages.create(
model="claude-mythos-5",
max_tokens=16000,
messages=[{"role": "user", "content": "..."}],
)助手预填充: claude-mythos-5 不支持预填充助手消息,会返回 400 错误,与 Claude Mythos Preview 相同。请改用系统提示指令。
思考输出: 在 claude-mythos-5 上,原始思维链永远不会返回,但当 thinking.display 设置为 summarized 时,思考块仍会携带可读的摘要文本。在同一模型上继续对话时,请原样传回思考块。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。
claude-mythos-5 使用与 claude-mythos-preview 相同的分词器(随 Claude Opus 4.7 引入的分词器)。从 claude-mythos-preview 迁移时,令牌数量大致保持不变。与 Claude Opus 4.7 之前的模型相比,相同的内容可能会分词为大约多 30% 的令牌,具体因内容和工作负载形态而异。
与 claude-mythos-preview 相比,/v1/messages/count_tokens 为 claude-mythos-5 返回的值大致保持不变。请在您自己的工作负载上重新建立成本和延迟基准。
claude-mythos-preview 更新为 claude-mythos-5。thinking: {type: "enabled", budget_tokens: N})。自适应思考始终开启,无需 thinking 字段。thinking: {type: "disabled"} 配置。在 claude-mythos-5 上禁用思考会返回错误。budget_tokens。它没有直接替代项:思考是自适应的,而 effort 参数是一个独立的输出级别控制,而非思考预算。thinking 字段的代码仅将其视为显示文本,并在同一模型上继续对话时原样传回思考块。thinking.display 在 claude-mythos-5 上默认为 "omitted",与 Claude Mythos Preview 相同;设置 display: "summarized" 以接收可读摘要。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。thinking 和 redacted_thinking 块。来自 claude-mythos-5 的思考块与生成它们的模型绑定,Claude Fable 5 和 Claude Mythos 5 以外的模型会静默忽略它们。剥离可使跨模型请求保持最小化和统一。claude-mythos-preview 迁移时,令牌数量大致保持不变。Claude Fable 5 是 Anthropic 能力最强的广泛发布模型,在 Claude API、Claude Platform on AWS、Amazon Bedrock、Vertex AI 和 Microsoft Foundry 上正式发布。
迁移基本上是即插即用的。Claude Fable 5 使用与 Claude Opus 4.8 相同的 Messages API 和相同的工具使用模式。它默认支持相同的 100 万令牌上下文窗口和相同的 128k 最大输出令牌。由于两个模型使用相同的分词器,令牌数量大致保持不变。
需要检查的关键更改是始终开启的自适应思考、思考输出、安全分类器拒绝和定价。迁移前涵盖定价和数据保留;变更内容涵盖其余部分。
Claude Fable 5 的定价为每百万输入令牌 10 美元、每百万输出令牌 50 美元,而 Claude Opus 4.8 分别为 5 美元和 25 美元。详情请参阅 Claude 定价。
Claude Fable 5 需要 30 天数据保留,在零数据保留(ZDR)安排下不可用;它被指定为受管控模型(Covered Model)。来自数据保留配置不满足此要求的组织的请求会返回 400 invalid_request_error。具有 ZDR 安排的组织应联系其 Anthropic 客户团队讨论数据保留配置;Claude Opus 4.8 在 ZDR 下仍然可用。或者,您可以按工作区配置数据保留;请参阅特定模型的数据保留要求。在 Amazon Bedrock、Vertex AI 和 Microsoft Foundry 上,数据保留由各平台管理。
如果您的代码基于 Claude Opus 4.7 或更早版本,请先应用从 Claude Opus 4.7 迁移到 Claude Opus 4.8,对于早于 Claude Opus 4.7 的模型,还需应用 Claude Opus 4.7 迁移步骤。这些章节涵盖了本节不再重复的破坏性更改(采样参数被拒绝、手动扩展思考被拒绝、预填充被移除、新分词器)。
model = "claude-opus-4-8" # Before
model = "claude-fable-5" # After本节中的项目描述了在您替换模型 ID 后值得检查的 API 和行为差异。
自适应思考始终开启: 自适应思考是 claude-fable-5 上唯一的思考模式。模型会在每个请求中自行决定何时思考以及思考多少,无需任何 thinking 配置。thinking: {type: "disabled"} 会返回错误。使用 effort 参数来控制思考深度。
需要检查的行为变化:在 Claude Opus 4.8 上,没有 thinking 字段的请求在不思考的情况下运行;在 claude-fable-5 上,相同的请求会以自适应思考方式运行。max_tokens 仍然是总输出(思考加响应文本)的硬性限制,因此对于在 Claude Opus 4.8 上不带思考运行的工作负载,请重新审视该参数。请参阅成本控制。
之前(Claude Opus 4.8):
client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)之后(Claude Fable 5):
client.messages.create(
model="claude-fable-5",
max_tokens=16000,
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)扩展思考和思考预算(未变更): claude-fable-5 不支持手动扩展思考(thinking: {type: "enabled", budget_tokens: N}),会返回 400 错误,与 Claude Opus 4.8 相同。budget_tokens 没有直接替代项:思考是自适应的,而 effort 参数是一个独立的输出级别控制,而非思考预算。
助手预填充(未变更): claude-fable-5 不支持预填充助手消息,会返回 400 错误,与 Claude Opus 4.8 相同。请改用系统提示指令。
思考输出: 在 claude-fable-5 上,原始思维链永远不会返回,但当 thinking.display 设置为 summarized 时,思考块仍会携带可读的摘要文本。在同一模型上继续对话时,请原样传回思考块。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。
安全分类器和 refusal 停止原因: claude-fable-5 在请求和响应生成期间运行安全分类器。当分类器拒绝请求时,Messages API 会以成功的 HTTP 200 响应返回 stop_reason: "refusal",而非错误。stop_details.category 字段报告触发的分类器,类别包括 "cyber"、"bio" 和 "reasoning_extraction" 等,当拒绝未映射到任何命名类别时则为 null。完整集合请参阅拒绝类别表。
对于在生成任何输出之前被拒绝的请求,您不会被收取输入令牌费用。当分类器在流式传输中途触发时,输入和已流式传输的输出会被计费;请丢弃部分输出。
要在另一个模型上自动重新运行被拒绝的请求,请传递可选的 fallbacks 参数,该参数在 Claude API 和 Claude Platform on AWS 上处于测试阶段。该参数在 Message Batches API 或 Amazon Bedrock、Vertex AI 和 Microsoft Foundry 上不可用;在这三个平台上,请在客户端运行重试或使用 SDK 拒绝回退中间件。请参阅处理停止原因。
从 high effort 开始: effort 参数的默认值仍为 high。在 Claude Opus 4.8 上,针对编码和高自主性工作的建议是显式设置 xhigh。在 claude-fable-5 上,对大多数任务使用 high 作为默认值,并将 xhigh 保留给对能力最敏感的工作负载。claude-fable-5 上较低的 effort 设置仍然表现良好,通常超过先前模型上的 xhigh 性能。如果任务完成但耗时超过必要时间,请降低 effort。请参阅为 Claude Fable 5 编写提示。
更低的提示缓存最小值: claude-fable-5 上的最小可缓存提示长度为 512 个令牌,低于 Claude Opus 4.8 上的 1,024 个令牌。在 Claude Opus 4.8 上因太短而无法缓存的提示现在可以创建缓存条目,无需更改代码。在 Amazon Bedrock 上,claude-fable-5 的最小值为 1,024 个令牌。各模型的最小值请参阅提示缓存。
claude-fable-5 需要 30 天数据保留,否则会返回 400 invalid_request_error。请参阅特定模型的数据保留要求。claude-opus-4-8 更新为 claude-fable-5。thinking: {type: "disabled"} 配置。在 claude-fable-5 上禁用思考会返回错误,没有 thinking 字段的请求会以自适应思考方式运行。claude-fable-5 上仍不受支持。thinking 字段的代码仅将其视为显示文本,并在同一模型上继续对话时原样传回思考块。thinking.display 在 claude-fable-5 上默认为 "omitted",与 Claude Opus 4.8 相同;设置 display: "summarized" 以接收可读摘要。请参阅 Claude Fable 5 和 Claude Mythos 5 上的思考输出。thinking 和 redacted_thinking 块。来自 claude-fable-5 的思考块与生成它们的模型绑定,Claude Fable 5 和 Claude Mythos 5 以外的模型会静默忽略它们。剥离可使跨模型请求保持最小化和统一。例外情况是兑换回退额度,这需要按照该功能的确切规则回显请求正文。stop_reason: "refusal" 并读取 stop_details.category 字段。要在另一个模型上自动重新运行被拒绝的请求,请考虑使用可选的 fallbacks 参数(测试版)。请参阅处理停止原因。effort 设置。对大多数任务从 high 开始,包括在 Claude Opus 4.8 上以 xhigh 运行的工作负载。claude-opus-4-8 迁移时,令牌数量大致保持不变;每令牌定价不同。Claude Opus 4.8 是 Anthropic 能力最强的 Opus 级模型。它基于 Claude Opus 4.7 构建。
Claude Opus 4.8 在现有的 Claude Opus 4.7 提示和评估上应具有强大的开箱即用性能。对于已在 Claude Opus 4.7 上运行的代码,没有破坏性的 API 更改。它支持与 Claude Opus 4.7 相同的功能集,包括 100 万令牌上下文窗口、128k 最大输出令牌、自适应思考、提示缓存、批处理、Files API、PDF 支持、视觉以及完整的服务器端和客户端工具集。它还新增了对话中系统消息,并公开记录了拒绝停止详情。
如果您的代码基于 Claude Opus 4.6 或更早版本,在升级到 Claude Opus 4.8 之前,还需应用下面的 Claude Opus 4.7 迁移步骤。这些步骤包含破坏性更改(采样参数被拒绝、手动扩展思考被拒绝、新分词器),仅靠 4.8 升级无法涵盖这些更改。
在 Microsoft Foundry 上,Claude Opus 4.8 在发布时具有 20 万令牌的上下文窗口。100 万上下文窗口适用于 Claude API、Amazon Bedrock 和 Vertex AI。请参阅 Microsoft Foundry 中的 Claude。
# Opus 迁移
model = "claude-opus-4-7" # Before
model = "claude-opus-4-8" # After这些不是破坏性更改。在 Claude Opus 4.7 上运行的代码在 Claude Opus 4.8 上无需更改即可继续工作。以下项目描述了在您替换模型 ID 后值得检查的行为差异。
采样参数(未变更): 在 Claude Opus 4.8 上将 temperature、top_p 或 top_k 设置为非默认值会返回 400 错误,与 Claude Opus 4.7 相同。SDK 请求类型仍然定义这些字段以与早期模型兼容,因此设置它们的代码可以通过类型检查,但 API 会在服务器端拒绝该请求。如果您在迁移到 Opus 4.7 时移除了这些参数,则无需进一步更改。
Effort 默认值为 high: Claude Opus 4.8 上的 effort 参数默认值在所有界面(包括 Claude Code 和 Messages API)上均为 high。如果您已显式设置 effort,您的设置保持不变。对于编码和高自主性工作,请显式设置 xhigh。请根据您的延迟和成本预算重新评估您的 effort 设置。
100 万上下文窗口为默认值: Claude Opus 4.8 默认提供完整的 100 万令牌上下文窗口,无需测试版标头,也没有长上下文溢价。如果您的客户端为了与旧模型兼容而传递上下文窗口测试版标头,您可以在 Claude Opus 4.8 上将其移除。
对话中系统消息: Claude Opus 4.8 接受在 messages 数组中紧跟用户轮次之后的 role: "system" 消息(需遵守放置规则)。对于从一开始就适用的指令,请使用顶层 system 字段。早期模型(包括 Claude Opus 4.7)会拒绝 messages 中的 role: "system" 并返回 400 错误。如果您维护了重建完整消息历史以更新指令的代码路径,您可以简化它们并保留早期轮次的提示缓存命中。
拒绝停止详情: 拒绝响应上的 stop_details 对象(自 Claude Opus 4.7 起可用)现已公开记录。当模型拒绝请求时,除了现有的 refusal 停止原因外,它还会标识拒绝的类别。无需测试版标头,也没有退出选项。请参阅处理停止原因。
更低的提示缓存最小值: Claude Opus 4.8 上的最小可缓存提示长度为 1,024 个令牌,低于 Claude Opus 4.7。在 Claude Opus 4.7 上因太短而无法缓存的提示现在可以创建缓存条目,无需更改代码。各模型的最小值请参阅提示缓存。
Effort 级别重新校准: 与 Claude Opus 4.7 相比,Claude Opus 4.8 上每个 effort 级别背后的令牌分配有所变化:medium 允许稍多的思考,high 稍少,而 xhigh 则大幅增加。如果您针对 Claude Opus 4.7 的成本或延迟调整了某个 effort 级别,请在调整之前先在相同级别上重新建立基准。请参阅 Effort。
claude-opus-4-7 更新为 claude-opus-4-8(或更新别名)。effort 设置。所有界面上的默认值均为 high;对于编码和高自主性工作,请显式设置 xhigh。stop_details(自 Claude Opus 4.7 起可用;现已公开记录)。Claude Opus 4.7 具有高度自主性,在长周期智能体工作、知识工作、视觉任务和记忆任务方面表现出色。
Claude Opus 4.7 在现有的 Claude Opus 4.6 提示和评估上应具有强大的开箱即用性能,定价保持相同的每百万令牌 $5 / $25,但在迁移时有一些行为和 API 更改值得了解。它支持与 Claude Opus 4.6 相同的功能集,包括:
# Opus 迁移
model = "claude-opus-4-6" # Before
model = "claude-opus-4-7" # After扩展思考已移除: Claude Opus 4.7 或更高版本的模型不再支持 thinking: {type: "enabled", budget_tokens: N},会返回 400 错误。请切换到自适应思考(thinking: {type: "adaptive"}),并使用 effort 参数来控制思考深度。自适应思考在 Claude Opus 4.7 上默认关闭:没有 thinking 字段的请求在不思考的情况下运行,与 Opus 4.6 的行为一致。显式设置 thinking: {type: "adaptive"} 以启用它。
之前(Claude Opus 4.6):
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)之后(Claude Opus 4.7):
client.messages.create(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)自适应思考可通过提示进行引导。有关在模型过度思考或思考不足时进行调整的指导,请参阅校准 effort 和思考深度。
采样参数已移除: 在 Claude Opus 4.7 上将 temperature、top_p 或 top_k 设置为任何非默认值会返回 400 错误。最安全的迁移路径是从请求负载中完全省略这些参数。在 Claude Opus 4.7 上,提示是引导模型行为的推荐方式。如果您之前使用 temperature = 0 来获得确定性,请注意它在先前的模型上也从未保证过完全相同的输出。
思考内容默认省略: 思考块仍会出现在 Claude Opus 4.7 的响应流中,但除非您显式选择加入,否则其 thinking 字段为空。这是相对于 Claude Opus 4.6 的静默更改,后者的默认行为是返回摘要思考文本。要在 Claude Opus 4.7 上恢复摘要思考内容,请将 thinking.display 设置为 "summarized":
thinking = {
"type": "adaptive",
"display": "summarized",
}Claude Opus 4.7 上的默认值为 "omitted"。如果您的产品向用户流式传输推理过程,新的默认值会表现为输出开始前的长时间停顿;设置 display: "summarized" 以在思考期间恢复可见的进度。详情请参阅扩展思考。
更新的令牌计数: Claude Opus 4.7 使用新的分词器,这有助于其在广泛任务上的性能提升。新分词器在处理文本时可能使用大约 1 倍到 1.35 倍的令牌数量(最多约多 35%,因内容而异)。
/v1/messages/count_tokens 为 Claude Opus 4.7 返回的令牌数量将与 Claude Opus 4.6 不同。令牌效率可能因工作负载形态而异。
提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。这些控制可能会牺牲模型智能。更新您的 max_tokens 参数以提供额外的余量,包括压缩触发器。Claude Opus 4.7 以标准 API 定价提供 100 万上下文窗口,无长上下文溢价。
预填充移除(从 Opus 4.6 延续): 在 Claude Opus 4.7 上预填充助手消息会返回 400 错误。请改用结构化输出、系统提示指令或 output_config.format。
effort 参数允许您调整 Claude 的智能与令牌消耗之间的平衡,以能力换取更快的速度和更低的成本。对于编码和智能体用例,从新的 xhigh effort 级别开始,对于大多数智能敏感的用例,至少使用 high effort。尝试其他 effort 级别以进一步调整令牌使用和智能:
max: 最大 effort 在某些用例中可以带来性能提升,但可能会因令牌使用增加而出现收益递减。此设置有时也可能容易过度思考。针对智能要求高的任务测试最大 effort。xhigh(新增): 超高 effort 是大多数编码和智能体用例的最佳设置。high: 此设置平衡令牌使用和智能。对于大多数智能敏感的用例,至少使用 high effort。medium: 适用于需要减少令牌使用同时牺牲部分智能的成本敏感用例。low: 保留用于短小、范围明确的任务以及对智能不敏感的延迟敏感工作负载。对于此模型,effort 比任何先前的 Opus 都更重要。升级时请积极尝试不同的设置。
Claude Opus 4.7 与 Claude Opus 4.6 相比有若干行为差异,这些差异不属于 API 破坏性变更,但可能需要更新提示或移除脚手架代码。
响应长度因用例而异: Claude Opus 4.7 会根据其对任务复杂度的判断来校准响应长度,而不是默认使用固定的详细程度。这通常意味着简单查询会得到更简短的回答,而开放式分析则会得到更长的回答。
如果您的产品依赖于特定的输出风格或详细程度,您可能需要调整提示。例如,要降低详细程度,可添加:"提供简洁、聚焦的响应。跳过非必要的上下文,并尽量减少示例。"如果您发现特定类型的过度解释,请在提示中添加针对性的指令来防止这种情况。
展示 Claude 如何以适当简洁程度进行沟通的正面示例,往往比告诉模型不要做什么的负面示例或指令更有效。
更字面化的指令遵循: Claude Opus 4.7 比 Claude Opus 4.6 更字面、更明确地解读提示,尤其是在较低的 effort 级别下。它不会默默地将针对某一项的指令泛化到另一项,也不会推断您未提出的请求。这种字面化的好处是精确性更高、反复修改更少。对于具有精心调优提示、结构化提取以及需要可预测行为的流水线等 API 用例,它通常表现更好。在迁移到 Claude Opus 4.7 时,对提示和调用框架进行审查可能特别有帮助。
更直接的语气: 与任何新模型一样,长篇写作的文风可能会有所变化。Claude Opus 4.7 更加直接和有主见,相比 Claude Opus 4.6 更温暖的风格,它较少使用肯定式的开场措辞和表情符号。如果您的产品依赖于特定的语气风格,请根据新的基准重新评估风格提示。
智能体轨迹中内置的进度更新: Claude Opus 4.7 在长时间的智能体轨迹中会向用户提供更规律、更高质量的更新。如果您添加了脚手架来强制生成中间状态消息(例如"每 3 次工具调用后,总结一下进度"),请尝试移除它。如果您发现 Claude Opus 4.7 面向用户的更新在长度或内容上与您的用例不够匹配,请在提示中明确描述这些更新应该是什么样的,并提供示例。
默认生成更少的子智能体: Claude Opus 4.7 默认倾向于生成更少的子智能体。不过,这一行为可以通过提示来引导;请向 Claude Opus 4.7 明确说明何时需要使用子智能体。
更严格的 effort 校准: 与 Claude Opus 4.6 相比有显著变化,Claude Opus 4.7 严格遵守 effort 级别,尤其是在较低级别。在 low 和 medium 级别下,模型会将其工作范围限定在所要求的内容内,而不会超额完成。
这有利于降低延迟和成本,但对于在 low effort 下运行的中等复杂度任务,存在一定的思考不足风险。如果您在复杂问题上观察到推理过浅,请将 effort 提升至 high 或 xhigh,而不是通过提示来绕过这个问题。
如果出于延迟考虑需要将 effort 保持在 low,请添加针对性的指导:"此任务涉及多步推理。在响应之前请仔细思考问题。"请参阅 Claude Opus 4.7 的推荐 effort 级别。
默认更少的工具调用: Claude Opus 4.7 倾向于比 Claude Opus 4.6 更少地使用工具,而更多地使用推理。在大多数情况下,这会产生更好的结果。
要增加工具使用,请提高 effort 设置。high 或 xhigh effort 设置在智能体搜索和编码中会显示出明显更多的工具使用。您也可以调整提示,明确指示模型何时以及如何正确使用其工具。
实时网络安全防护: Claude Opus 4.7 新增了此功能,涉及禁止或高风险主题的请求可能会被拒绝。对于渗透测试、漏洞研究或红队演练等合法的安全工作,请申请加入网络安全验证计划以请求降低限制。背景信息请参阅防护措施、警告和申诉。
高分辨率图像支持: Claude Opus 4.7 是首个支持高分辨率图像的 Claude 模型。最大图像分辨率在长边上为 2576 像素,高于之前模型的 1568 像素。这为视觉密集型工作负载带来了提升,对于计算机使用、屏幕截图理解和文档分析尤其有价值。
高分辨率支持是自动启用的,无需 beta 标头或客户端选择加入。需要规划以下两点:
max_tokens 和成本预期,或者如果不需要额外的保真度,请在发送前进行降采样。详情请参阅 Claude Opus 4.7 上的高分辨率图像支持。
以下变更不是必需的,但会改善您的使用体验:
重新评估 max_tokens: 由于相同的文本在 Claude Opus 4.7 上会产生更高的令牌计数,请更新您的 max_tokens 参数以提供额外的余量,包括压缩触发器。提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。
审核令牌计数预期: 任何在客户端估算令牌或假设固定令牌与字符比率的代码路径都应针对 Claude Opus 4.7 重新测试。使用令牌计数端点进行验证。
采用任务预算(beta): Claude Opus 4.7 引入了任务预算。这些预算让您可以告知 Claude 在完整的智能体循环(包括思考、工具调用、工具结果和最终输出)中可用的令牌数量。模型会看到一个实时倒计时,并利用它来确定工作优先级,在预算消耗时优雅地完成任务。要使用此功能,请设置 beta 标头 task-budgets-2026-03-13,并将以下内容添加到您的输出配置中:
output_config = {
"effort": "high",
"task_budget": {"type": "tokens", "total": 128000},
}您可能需要针对您的用例尝试不同的任务预算。如果给模型的任务预算过于严格,它可能会以预算作为约束条件,不够彻底地完成任务。
对于质量比速度更重要的开放式智能体任务,请不要设置任务预算。任务预算应保留用于需要模型将其工作限定在令牌配额内的工作负载。任务预算的最小值为 20k 令牌。
任务预算不是硬性上限;它是模型知晓的一个建议值。它与 max_tokens 不同:
task_budget: 跨整个智能体循环的建议性上限。模型可以看到它并用它来调整自己的节奏。max_tokens: 每个请求生成令牌的硬性上限。它不会传递给模型,因此模型不知道它的存在。当您希望模型自我调节时使用 task_budget,当您需要硬性上限来限制使用量时使用 max_tokens。
在 max 或 xhigh effort 下设置较大的 max_tokens: 如果您在 max 或 xhigh effort 下运行 Claude Opus 4.7,请设置较大的最大输出令牌预算,以便模型有足够的空间在其子智能体和工具调用中进行思考和行动。从 64k 令牌开始,然后进行调优。
如果不需要高分辨率,请对图像进行降采样: Claude Opus 4.7 支持最大 2576px / 3.75MP 的图像。高分辨率图像会使用更多令牌。如果不需要额外的图像保真度,请在发送给 Claude 之前对图像进行降采样,以避免令牌使用量增加。请参阅图像和视觉。
claude-opus-4-6 更新为 claude-opus-4-7(或更新别名)。temperature、top_p 和 top_k。thinking: {type: "enabled", budget_tokens: N} 替换为 thinking: {type: "adaptive"} 加上 effort 参数。max_tokens 以适应更新后的分词方式。xhigh 或 max effort,请将 max_tokens 提高到至少 64k 作为起点。如果您从 Claude Opus 4.5、Opus 4.1(已弃用)或更早的模型直接迁移到 Claude Opus 4.7,请应用上述所有 Opus 4.7 变更,以及本节中在 Opus 4.5 和 Opus 4.7 之间生效的累积变更。如果您从 Opus 4.6 迁移,则只需参考上面的 Opus 4.7 部分。
# Opus 迁移
model = "claude-opus-4-5" # Before
model = "claude-opus-4-7" # After移除预填充已在上面的 Opus 4.7 破坏性变更中介绍。
工具参数引号处理: Claude Opus 4.6 及更高版本的模型在工具调用参数中可能产生略有不同的 JSON 字符串转义(例如,对 Unicode 转义或正斜杠转义的不同处理)。如果您将工具调用的 input 作为原始字符串解析而不是使用 JSON 解析器,请验证您的解析逻辑。标准 JSON 解析器(如 json.loads() 或 JSON.parse())会自动处理这些差异。
这些变更可改善您在 Opus 4.7 上的体验。标记为**(Opus 4.7 上必需)**的项目在 Opus 4.6 发布时是可选建议,但现在是强制性的;其余项目仍为推荐。
迁移到自适应思考(Opus 4.7 上必需): thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 上会返回 400 错误。请切换到 thinking: {type: "adaptive"} 并使用 effort 参数来控制思考深度。请参阅自适应思考。
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 32000},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)请注意,此迁移还将从 client.beta.messages.create 迁移到 client.messages.create。自适应思考和 effort 是正式发布(GA)功能,不需要 beta SDK 命名空间或任何 beta 标头。
移除 effort beta 标头: effort 参数现已正式发布。请从您的请求中移除 betas=["effort-2025-11-24"]。
移除细粒度工具流式传输 beta 标头: 细粒度工具流式传输现已正式发布。请从您的请求中移除 betas=["fine-grained-tool-streaming-2025-05-14"]。
移除交错思考 beta 标头: 自适应思考在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上会自动启用交错思考。请从您的请求中移除 betas=["interleaved-thinking-2025-05-14"]。该标头在 Sonnet 4.6 上配合手动扩展思考时仍然有效,但手动模式已弃用。
迁移到 output_config.format: 如果使用结构化输出,请将 output_format={...} 更新为 output_config={"format": {...}}。旧参数仍然有效,但已弃用,将在未来的模型版本中移除。
如果您从 Opus 4.1(已弃用)或更早的模型直接迁移到 Claude Opus 4.7,请应用本指南顶部的 Claude Opus 4.7 变更和上述累积变更,以及本节中的附加变更。
# 来自 Opus 4.1
model = "claude-opus-4-1-20250805" # Before
model = "claude-opus-4-7" # After
# 来自 Sonnet 3.7
model = "claude-3-7-sonnet-20250219" # Before
model = "claude-opus-4-7" # After移除采样参数
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
从 Claude Opus 4.7 开始,将 temperature、top_p 或 top_k 设置为任何非默认值都会返回 400 错误。最安全的迁移路径是从请求中完全省略这些参数,并使用提示来引导模型的行为。如果您之前使用 temperature = 0 来获得确定性,请注意它从未保证过完全相同的输出。
# 之前 - 这在 Claude 4+ 模型中会报错
response = client.messages.create(
model="claude-3-7-sonnet-20250219",
temperature=0.7,
top_p=0.9, # Non-default sampling params return 400 on Opus 4.7
# ...
)
# 之后
response = client.messages.create(
model="claude-opus-4-7",
# ...
)更新工具版本
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
更新到最新的工具版本。移除所有使用 undo_edit 命令的代码。
# 之前
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# 之后
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因:
response = client.messages.create(...)
if response.stop_reason == "refusal":
# 适当处理拒绝情况
pass处理 model_context_window_exceeded 停止原因
Claude 4.5+ 模型在生成因达到上下文窗口限制(而非请求的 max_tokens 限制)而停止时,会返回 model_context_window_exceeded 停止原因。请更新您的应用程序以处理这个新的停止原因:
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# 适当处理上下文窗口限制
pass验证工具参数处理(尾随换行符)
Claude 4.5+ 模型会保留工具调用字符串参数中之前被去除的尾随换行符。如果您的工具依赖于对工具调用参数的精确字符串匹配,请验证您的逻辑能够正确处理尾随换行符。
针对行为变化更新您的提示
Claude 4+ 模型具有更简洁、直接的沟通风格,需要明确的指示。请查阅提示最佳实践以获取优化指导。
token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4+ 模型都内置了令牌高效的工具使用,这些标头不起作用。claude-opus-4-7output_config.formatthinking: {type: "enabled", budget_tokens: N} 替换为 thinking: {type: "adaptive"} 加上 effort 参数(在 Opus 4.7 上返回 400)effort-2025-11-24 beta 标头(effort 现已正式发布)fine-grained-tool-streaming-2025-05-14 beta 标头interleaved-thinking-2025-05-14 beta 标头(自适应思考会自动启用交错思考)output_format 迁移到 output_config.format(如适用)temperature、top_p 和 top_k(非默认值在 Opus 4.7 上返回 400)text_editor_20250728、code_execution_20250825)refusal 停止原因model_context_window_exceeded 停止原因token-efficient-tools-2025-02-19、output-128k-2025-02-19)Claude Sonnet 4.6 将强大的智能与快速的性能相结合,具有改进的智能体搜索能力,并且在与网络搜索或网络抓取一起使用时提供免费的代码执行。它非常适合日常编码、分析和内容任务。
有关功能的完整概述,请参阅模型概述。
Sonnet 4.6 的定价为每百万输入令牌 3 美元,每百万输出令牌 15 美元。详情请参阅 Claude 定价。
更新您的模型名称:
# 从 Sonnet 4.5 开始
model = "claude-sonnet-4-5" # Before
model = "claude-sonnet-4-6" # After不再支持预填充助手消息
从 Sonnet 4.5 或更早版本迁移时,这是一个破坏性变更。
在 Sonnet 4.6 上预填充助手消息会返回 400 错误。请改用结构化输出、系统提示指令或 output_config.format。
常见的预填充用例及迁移方法:
控制输出格式(强制 JSON/YAML 输出):使用结构化输出或带有枚举字段的工具来处理分类任务。
消除开场白(移除"以下是..."之类的短语):在系统提示中添加直接指令:"直接响应,不要开场白。不要以'以下是...'、'基于...'等短语开头。"
避免不当拒绝: Claude 现在在适当拒绝方面表现得更好。在用户消息中使用清晰的提示而不使用预填充应该就足够了。
续写(恢复被中断的响应):将续写内容移至用户消息:"您之前的响应被中断,结尾是 [previous_response]。请从中断处继续。"
上下文注入 / 角色一致性(在长对话中刷新上下文):将之前作为预填充助手提醒的内容改为注入到用户回合中。
工具参数 JSON 转义可能不同
从 Sonnet 4.5 或更早版本迁移时,这是一个破坏性变更。
工具参数中的 JSON 字符串转义可能与之前的模型不同。标准 JSON 解析器会自动处理这一点,但基于字符串的自定义解析可能需要更新。
更新采样参数
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
仅使用 temperature 或 top_p 其中之一,不要同时使用两者。
更新工具版本
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
更新到最新的工具版本(text_editor_20250728、code_execution_20250825)。移除所有使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、直接的沟通风格。请查阅提示最佳实践以获取优化指导。
fine-grained-tool-streaming-2025-05-14 beta 标头: 细粒度工具流式传输在 Sonnet 4.6 上现已正式发布,不再需要 beta 标头。output_format 迁移到 output_config.format: output_format 参数已弃用。请改用 output_config.format。建议从 Sonnet 4.5 迁移到 Sonnet 4.6,后者以相同的价格提供更高的智能。
Sonnet 4.6 的默认 effort 级别为 high,而 Sonnet 4.5 没有 effort 参数。在从 Sonnet 4.5 迁移到 Sonnet 4.6 时,请考虑调整 effort 参数。如果未明确设置,使用默认 effort 级别可能会导致更高的延迟。
如果您在 Sonnet 4.5 上未使用扩展思考,可以在 Sonnet 4.6 上继续不使用它。您应该明确将 effort 设置为适合您用例的级别。在禁用思考的 low effort 下,您可以期待与未使用扩展思考的 Sonnet 4.5 相似或更好的性能。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
output_config={"effort": "low"},
messages=[{"role": "user", "content": "Your prompt here"}],
)如果您在 Sonnet 4.5 上使用带有 budget_tokens 的扩展思考,它在 Sonnet 4.6 上仍然有效,但已弃用。请迁移到带有 effort 参数的自适应思考。
自适应思考是 Sonnet 4.6 上 budget_tokens 的推荐替代方案。它特别适合以下工作负载模式:
high effort 开始。如果延迟或令牌使用是一个问题,请降低到 medium。使用自适应思考时,请在您的任务上评估 medium 和 high effort。合适的级别取决于您的工作负载在质量、延迟和令牌使用之间的权衡。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=64000,
thinking={"type": "adaptive"},
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "Your prompt here"}],
)如果您在使用自适应思考时发现行为不一致或质量下降,请先尝试降低 effort 设置或使用 max_tokens 作为硬性限制。带有 budget_tokens 的扩展思考在 Sonnet 4.6 上仍然有效,但已弃用且不再推荐。
如果您在迁移期间需要暂时保留 budget_tokens,约 16k 令牌的预算可以为较难的问题提供余量,同时避免令牌使用失控的风险。此配置已弃用,将在未来的模型版本中移除。
对于智能体编码、前端设计、工具密集型工作流和复杂的企业工作流,从 medium effort 开始。如果您发现延迟过高,请考虑将 effort 降低到 low。如果您需要更高的智能,请考虑将 effort 提高到 high 或迁移到 Opus 4.7。
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=16384,
thinking={"type": "enabled", "budget_tokens": 16384},
output_config={"effort": "medium"},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)对于聊天、内容生成、搜索、分类和其他非编码任务,从带有扩展思考的 low effort 开始。如果您需要更深入的处理,请将 effort 提高到 medium。
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
thinking={"type": "enabled", "budget_tokens": 16384},
output_config={"effort": "low"},
betas=["interleaved-thinking-2025-05-14"],
messages=[{"role": "user", "content": "Your prompt here"}],
)claude-sonnet-4-6output_config.formattext_editor_20250728、code_execution_20250825);不支持旧版本(如果从 3.x 迁移)undo_edit 命令的代码(如适用)temperature 或 top_p 其中之一,不要同时使用两者(如果从 3.x 迁移)refusal 停止原因fine-grained-tool-streaming-2025-05-14 beta 标头(现已正式发布)output_format 迁移到 output_config.formatthinking: {type: "enabled", budget_tokens: N} 迁移到带有 effort 参数的 thinking: {type: "adaptive"}(budget_tokens 已弃用,将在未来版本中移除)Claude Sonnet 4.5 将强大的智能与快速的性能相结合,非常适合日常编码、分析和内容任务。
有关功能的完整概述,请参阅模型概述。
Sonnet 4.5 的定价为每百万输入令牌 3 美元,每百万输出令牌 15 美元。详情请参阅 Claude 定价。
更新您的模型名称:
# 从 Sonnet 3.7 开始
model = "claude-3-7-sonnet-20250219" # Before
model = "claude-sonnet-4-5-20250929" # After这些破坏性变更适用于从 Claude 3.x Sonnet 模型迁移的情况。
更新采样参数
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
仅使用 temperature 或 top_p 其中之一,不要同时使用两者。
更新工具版本
从 Claude 3.x 模型迁移时,这是一个破坏性变更。
更新到最新的工具版本(text_editor_20250728、code_execution_20250825)。移除所有使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、直接的沟通风格。请查阅提示最佳实践以获取优化指导。
claude-sonnet-4-5-20250929text_editor_20250728、code_execution_20250825);不支持旧版本(如果从 3.x 迁移)undo_edit 命令的代码(如适用)temperature 或 top_p 其中之一,不可同时使用(如果从 3.x 迁移)refusal 停止原因Claude Haiku 4.5 是速度最快、最智能的 Haiku 模型,具有接近前沿的性能,可为交互式应用程序和大批量处理提供优质的模型质量。
有关功能的完整概述,请参阅模型概述。
Haiku 4.5 的定价为每百万输入令牌 1 美元,每百万输出令牌 5 美元。详情请参阅 Claude 定价。
更新您的模型名称:
# 来自 Haiku 3.5
model = "claude-3-5-haiku-20241022" # Before
model = "claude-haiku-4-5-20251001" # After查看新的速率限制: Haiku 4.5 的速率限制与 Haiku 3.5 是分开的。详情请参阅速率限制文档。
如需在编码和推理任务上获得显著的性能提升,请考虑使用 thinking: {type: "enabled", budget_tokens: N} 启用扩展思考。
探索新功能: 有关上下文感知、更大的输出容量(64k 令牌)、更高的智能水平和更快的速度等详细信息,请参阅模型概述。
以下重大变更适用于从 Claude 3.x Haiku 模型迁移的情况。
更新采样参数
从 Claude 3.x 模型迁移时,这是一项重大变更。
仅使用 temperature 或 top_p 其中之一,不可同时使用。
更新工具版本
从 Claude 3.x 模型迁移时,这是一项重大变更。
更新至最新的工具版本(text_editor_20250728、code_execution_20250825)。删除所有使用 undo_edit 命令的代码。
处理 refusal 停止原因
更新您的应用程序以处理 refusal 停止原因。
针对行为变化更新您的提示
Claude 4 模型具有更简洁、更直接的沟通风格。请查看提示最佳实践以获取优化指导。
claude-haiku-4-5-20251001text_editor_20250728、code_execution_20250825);不支持旧版本undo_edit 命令的代码(如适用)temperature 或 top_p 其中之一,不可同时使用refusal 停止原因Was this page helpful?