迁移指南

迁移到 Claude Opus 4.7

Claude Opus 4.7 是我们迄今为止最强大的通用可用模型。它具有高度自主性，在长期代理工作、知识工作、视觉任务和记忆任务方面表现出色。Claude Opus 4.7 在现有 Claude Opus 4.6 提示和评估中应该具有强大的开箱即用性能，价格相同为 $5 / $25 每 MTok，但在迁移时有一些值得了解的行为和 API 变化。它支持与 Claude Opus 4.6 相同的功能集，包括 100 万令牌上下文窗口（标准 API 定价，无长上下文溢价）、128k 最大输出令牌、自适应思考、提示缓存、批处理、Files API、PDF 支持、视觉以及完整的服务器端和客户端工具集（bash、代码执行、计算机使用、文本编辑器、网络搜索、网络获取、MCP 连接器、记忆）。

/claude-api migrate this project to claude-opus-4-7

更新您的模型名称

# Opus 迁移
model = "claude-opus-4-6"  # 之前
model = "claude-opus-4-7"  # 之后

破坏性变化

1. 扩展思考已移除： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 或更新的模型上不再受支持，并返回 400 错误。切换到 自适应思考（thinking: {type: "adaptive"}）并使用 工作量参数 来控制思考深度。自适应思考在 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=64000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       messages=[{"role": "user", "content": "..."}],
   )

   之后（Claude Opus 4.7）：

   client.messages.create(
       model="claude-opus-4-7",
       max_tokens=64000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # 或 "max"、"xhigh"、"medium"、"low"
       messages=[{"role": "user", "content": "..."}],
   )

   自适应思考可通过提示进行调整。有关在模型过度或不足思考时调整的指导，请参阅 校准工作量和思考深度。

2. 采样参数已移除： 在 Claude Opus 4.7 上将 temperature、top_p 或 top_k 设置为任何非默认值会返回 400 错误。最安全的迁移路径是从请求有效负载中完全省略这些参数。提示是在 Claude Opus 4.7 上指导模型行为的推荐方式。如果您使用 temperature = 0 来确保确定性，请注意它从未保证在先前的模型上输出相同。

3. 思考内容默认被省略： 思考块仍然出现在 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" 来恢复思考期间的可见进度。有关详细信息，请参阅 扩展思考。

4. 更新的令牌计数： Claude Opus 4.7 使用新的分词器，有助于其在广泛的任务中改进性能。与之前的模型相比，这个新的分词器在处理文本时可能使用大约 1 倍到 1.35 倍的令牌（最多约 35% 更多，因内容而异），/v1/messages/count_tokens 将为 Claude Opus 4.7 返回与 Claude Opus 4.6 不同的令牌数。Claude Opus 4.7 的令牌效率可能因工作负载形状而异。提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。请记住，这些控制可能会影响模型智能。我们建议更新您的 max_tokens 参数以提供额外的余量，包括压缩触发器。Claude Opus 4.7 在标准 API 定价下提供 100 万令牌上下文窗口，无长上下文溢价。

5. 预填充移除（从 Opus 4.6 继承）： 在 Claude Opus 4.7 上预填充助手消息会返回 400 错误。改用 结构化输出、系统提示指令或 output_config.format。

选择工作量级别

工作量参数 允许您调整 Claude 的智能与令牌支出，用更快的速度和更低的成本换取能力。对于编码和代理用例，从新的 xhigh 工作量级别开始，对于大多数智能敏感的用例，至少使用 high 工作量。尝试其他工作量级别以进一步调整令牌使用和智能：

• max： 最大工作量在某些用例中可以提供性能提升，但可能显示来自增加的令牌使用的收益递减。此设置有时也可能容易过度思考。我们建议为智能要求高的任务测试最大工作量。
• xhigh（新）： 超高工作量是大多数编码和代理用例的最佳设置。
• high： 此设置平衡令牌使用和智能。对于大多数智能敏感的用例，我们建议至少使用 high 工作量。
• medium： 适合需要减少令牌使用同时权衡智能的成本敏感用例。
• low： 保留用于短期、范围有限的任务和对智能不敏感的延迟敏感工作负载。

我们预期工作量对此模型的重要性比任何先前的 Opus 都要大，并建议在升级时积极尝试它。

行为变化

Claude Opus 4.7 与 Claude Opus 4.6 有几个行为差异，这些不是 API 破坏性变化，但可能需要提示更新或支架移除。

1. 响应长度因用例而异： Claude Opus 4.7 根据其判断任务的复杂程度来校准响应长度，而不是默认为固定的冗长性。这通常意味着简单查询的答案更短，开放式分析的答案更长。如果您的产品依赖于特定的输出风格或冗长性，您可能需要调整您的提示。例如，要减少冗长性，您可能会添加："提供简洁、有针对性的响应。跳过非必要的上下文，并保持示例最少。" 如果您看到特定类型的冗长性示例（即过度解释），您可以在提示中添加额外的指令来防止它们。显示 Claude 如何以适当的简洁程度进行沟通的正面示例往往比负面示例或告诉模型不要做什么的指令更有效。

2. 更字面的指令遵循： Claude Opus 4.7 比 Claude Opus 4.6 更字面和明确地解释提示，特别是在较低的工作量级别。它不会默默地将指令从一个项目推广到另一个项目，也不会推断您没有提出的请求。这种字面性的优点是精确性和更少的混乱。它通常对具有精心调整的提示、结构化提取和您想要可预测行为的管道的 API 用例表现更好。对于迁移到 Claude Opus 4.7，提示和工具审查可能特别有帮助。

3. 更直接的语气： 与任何新模型一样，长篇写作的散文风格可能会改变。Claude Opus 4.7 更直接和有主见，验证转发短语和表情符号较少，而 Claude Opus 4.6 的风格更温暖。如果您的产品依赖于特定的声音，请根据新的基线重新评估风格提示。

4. 代理跟踪中的内置进度更新： Claude Opus 4.7 在长代理跟踪中为用户提供更定期、更高质量的更新。如果您添加了支架来强制临时状态消息（"每 3 个工具调用后，总结进度"），请尝试移除它。如果您发现 Claude Opus 4.7 的面向用户的更新的长度或内容对您的用例校准不当，请在提示中明确描述这些更新应该是什么样的，并提供示例。

5. 默认生成的子代理较少： Claude Opus 4.7 倾向于默认生成较少的子代理。但是，这种行为可以通过提示进行调整；给 Claude Opus 4.7 明确的指导，说明何时需要子代理。

6. 更严格的工作量校准： 与 Claude Opus 4.6 相比有意义的变化，Claude Opus 4.7 严格遵守 工作量级别，特别是在低端。在 low 和 medium 时，模型将其工作范围限制在所要求的范围内，而不是超越。这对延迟和成本很好，但在 low 工作量下运行中等复杂的任务时，存在一些思考不足的风险。如果您在复杂问题上观察到浅层推理，请将工作量提高到 high 或 xhigh，而不是围绕它进行提示。如果您需要为了延迟而保持 low 工作量，请添加有针对性的指导："此任务涉及多步推理。在响应之前仔细思考问题。" 请参阅 Claude Opus 4.7 的推荐工作量级别。

7. 默认工具调用较少： Claude Opus 4.7 倾向于比 Claude Opus 4.6 更少地使用工具，而更多地使用推理。这在大多数情况下会产生更好的结果。但是，增加工作量设置是增加工具使用级别的有用杠杆，特别是在知识工作中。high 或 xhigh 工作量设置在代理搜索和编码中显示显著更多的工具使用。对于您想要更多工具使用的场景，您也可以调整您的提示，明确指示模型何时以及如何正确使用其工具。

8. 实时网络安全防护： 在 Claude Opus 4.7 中新增，涉及禁止或高风险主题的请求可能导致拒绝。对于合法的安全工作，如渗透测试、漏洞研究或红队，请申请 网络验证计划 以请求降低对网络内容的限制。有关背景信息，请参阅 防护、警告和申诉。

9. 高分辨率图像支持： Claude Opus 4.7 是第一个具有高分辨率图像支持的 Claude 模型，长边的最大图像分辨率为 2576 像素（从先前模型的 1568 像素提高）。这为视觉密集型工作负载解锁了收益，对于计算机使用、屏幕截图理解和文档分析特别有价值。高分辨率支持是自动的，不需要测试版标头或客户端选择加入。全分辨率图像可以使用比先前模型多约 3 倍的图像令牌（每个图像最多 4,784 令牌，相比之前的约 1,600 令牌上限），因此请为图像密集型工作负载重新预算 max_tokens 和成本预期，或在发送前进行下采样（如果您不需要额外的保真度）。模型返回的指向和边界框坐标在 Claude Opus 4.7 上与实际图像像素 1

   ，因此不需要缩放因子转换。有关详细信息，请参阅 Claude Opus 4.7 上的高分辨率图像支持。

推荐的变化

这些不是必需的，但会改进您的体验：

1. 重新评估 max_tokens： 因为相同的文本在 Claude Opus 4.7 上产生更高的令牌计数，我们建议更新您的 max_tokens 参数以提供额外的余量，包括压缩触发器。提示干预、task_budget 和 effort 可以帮助控制成本并确保适当的令牌使用。

2. 审计令牌计数预期： 任何估计客户端令牌或假设固定令牌与字符比率的代码路径都应针对 Claude Opus 4.7 重新测试。使用 令牌计数端点 来验证。

3. 采用 任务预算（测试版）： Claude Opus 4.7 引入了任务预算。这些预算让您告知 Claude 它有多少令牌用于完整的代理循环，包括思考、工具调用、工具结果和最终输出。模型看到运行倒计时并使用它来优先处理工作并在预算被消耗时优雅地完成任务。要使用，请设置测试版标头 task-budgets-2026-03-13 并将以下内容添加到您的输出配置：

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   您可能需要为您的用例尝试不同的任务预算。如果模型被给予对给定任务过于限制的任务预算，它可能不太彻底地完成任务，将其预算作为约束引用。对于质量比速度更重要的开放式代理任务，不要设置任务预算；为需要模型将其工作范围限制在令牌额度的工作负载保留任务预算。任务预算的最小值是 20k 令牌。

   这不是硬上限；这是模型意识到的建议。这与 max_tokens 不同，max_tokens 是每个请求生成令牌的硬上限（max_tokens 不传递给模型，模型不知道它），而 task_budget 是跨完整代理循环的建议上限。当您想要模型自我调节时使用 task_budget，并使用 max_tokens 作为硬的每个请求上限来限制使用。

4. 在 max 或 xhigh 工作量时设置大的 max_tokens： 如果您在 max 或 xhigh 工作量下运行 Claude Opus 4.7，请设置大的最大输出令牌预算，以便模型有空间在其子代理和工具调用中思考和行动。我们建议从 64k 令牌开始，然后从那里进行调整。

5. 如果高分辨率不必要，请下采样图像： 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"} 加上 工作量参数。
• 移除任何助手消息预填充。
• 如果您的 UI 显示思考内容，明确选择加入思考总结。
• 在更新的分词下重新基准端到端成本和延迟。
• 重新调整 max_tokens 以考虑更新的分词。
• 重新测试任何客户端令牌计数估计。
• 如果您的应用程序发送图像，请为 高分辨率图像支持 重新预算（每个全分辨率图像最多约 3 倍的图像令牌）。如果您不需要额外的保真度，请在发送前下采样。如果您从模型消费指向或边界框坐标，请移除任何缩放因子转换；坐标在 Claude Opus 4.7 上与实际图像像素 1
  。
• 审查上述行为变化的提示（响应长度、字面性、语气、进度更新、子代理、工作量校准、工具触发、网络防护、高分辨率图像处理）。
• 在移除现有长度控制提示后重新基准响应长度，然后明确调整。
• 如果使用 xhigh 或 max 工作量，将 max_tokens 提高到至少 64k 作为起点。
• 考虑为代理工作流采用任务预算（测试版）。
• 如果您的产品进行合法的安全工作，请申请 网络验证计划 以获得对网络内容的较低限制。

从 Opus 4.5 或更早版本迁移到 Claude Opus 4.7

如果您从 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"  # 之前
model = "claude-opus-4-7"  # 之后

破坏性变化

1. 预填充移除 在上面的 Opus 4.7 破坏性变化 中涵盖。

2. 工具参数引用： Claude Opus 4.6 及更新的模型可能在工具调用参数中产生略微不同的 JSON 字符串转义（例如，不同的 Unicode 转义或正斜杠转义处理）。如果您将工具调用 input 解析为原始字符串而不是使用 JSON 解析器，请验证您的解析逻辑。标准 JSON 解析器（如 json.loads() 或 JSON.parse()）会自动处理这些差异。

推荐的变化

这些变化改进了您在 Opus 4.7 上的体验。标记为 (Opus 4.7 上必需) 的项目在 Opus 4.6 推出时是可选建议，但现在是强制性的；其余的仍然是推荐的。

1. 迁移到自适应思考（Opus 4.7 上必需）： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 上返回 400 错误。切换到 thinking: {type: "adaptive"} 并使用 工作量参数 来控制思考深度。请参阅 自适应思考。

   BeforeAfterCLITypeScriptC#GoJavaPHPRuby

   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=[...],
   )

   请注意，迁移也从 client.beta.messages.create 移动到 client.messages.create。自适应思考和工作量是 GA 功能，不需要测试版 SDK 命名空间或任何测试版标头。

2. 移除工作量测试版标头： 工作量参数现在是 GA。从您的请求中移除 betas=["effort-2025-11-24"]。

3. 移除细粒度工具流式传输测试版标头： 细粒度工具流式传输现在是 GA。从您的请求中移除 betas=["fine-grained-tool-streaming-2025-05-14"]。

4. 移除交错思考测试版标头： 自适应思考在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上自动启用交错思考。从您的请求中移除 betas=["interleaved-thinking-2025-05-14"]。标头在 Sonnet 4.6 上仍然对手动扩展思考有效，但手动模式已弃用。

5. 迁移到 output_config.format： 如果使用结构化输出，将 output_format={...} 更新为 output_config={"format": {...}}。旧参数仍然有效但已弃用，将在未来的模型版本中移除。

从 Claude 4.1 或更早版本迁移

如果您从 Opus 4.1、Sonnet 4（已弃用）或更早的模型直接迁移到 Claude Opus 4.7，请应用本指南顶部的 Claude Opus 4.7 变化、上面的累积变化以及本部分中的额外变化。

# 从 Opus 4.1
model = "claude-opus-4-1-20250805"  # 之前
model = "claude-opus-4-7"  # 之后

# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-opus-4-7"  # 之后

# 从 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-opus-4-7"  # 之后

额外的破坏性变化

1. 移除采样参数

   从 Claude 3.x 模型迁移时，这是一个破坏性变化。

   从 Claude Opus 4.7 开始，将 temperature、top_p 或 top_k 设置为任何非默认值将返回 400 错误。最安全的迁移路径是从请求中完全省略这些参数，并使用提示来指导模型的行为。如果您使用 temperature = 0 来确保确定性，请注意它从未保证相同的输出。

   Python

   # 之前 - 这将在 Claude 4+ 模型中出错
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # 非默认采样参数在 Opus 4.7 上返回 400
       # ...
   )
   
   # 之后
   response = client.messages.create(
       model="claude-opus-4-7",
       # ...
   )

2. 更新工具版本

   从 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"}]
   • 文本编辑器： 使用 text_editor_20250728 和 str_replace_based_edit_tool。有关详细信息，请参阅 文本编辑器工具文档。
   • 代码执行： 升级到 code_execution_20250825。有关迁移说明，请参阅 代码执行工具文档。

3. 处理 refusal 停止原因

   更新您的应用程序以 处理 refusal 停止原因：

   Python

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # 适当处理拒绝
       pass

4. 处理 model_context_window_exceeded 停止原因

   Claude 4.5+ 模型在由于达到上下文窗口限制而不是请求的 max_tokens 限制而停止生成时返回 model_context_window_exceeded 停止原因。更新您的应用程序以处理这个新的停止原因：

   Python

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # 适当处理上下文窗口限制
       pass

5. 验证工具参数处理（尾部换行符）

   Claude 4.5+ 模型保留工具调用字符串参数中的尾部换行符，这些换行符在之前被剥离。如果您的工具依赖于与工具调用参数的精确字符串匹配，请验证您的逻辑正确处理尾部换行符。

6. 为行为变化更新您的提示

   Claude 4+ 模型具有更简洁、直接的沟通风格，需要明确的指导。查看 提示最佳实践 以获取优化指导。

额外的推荐变化

• 移除旧版测试版标头： 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4+ 模型都具有内置的令牌高效工具使用，这些标头没有效果。

迁移清单（从 Opus 4.5 或更早版本）

• 将模型 ID 更新为 claude-opus-4-7
• 应用所有 Opus 4.7 破坏性变化（扩展思考已移除、采样参数已移除、思考显示默认被省略、更新的分词）
• 破坏性： 移除助手消息预填充（返回 400 错误）；改用结构化输出或 output_config.format
• Opus 4.7 上破坏性： 将 thinking: {type: "enabled", budget_tokens: N} 替换为 thinking: {type: "adaptive"} 加上 工作量参数（在 Opus 4.7 上返回 400）
• 验证工具调用 JSON 解析使用标准 JSON 解析器
• 移除 effort-2025-11-24 测试版标头（工作量现在是 GA）
• 移除 fine-grained-tool-streaming-2025-05-14 测试版标头
• 移除 interleaved-thinking-2025-05-14 测试版标头（自适应思考在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上自动启用交错思考）
• 将 output_format 迁移到 output_config.format（如果适用）
• 如果从 Claude 4.1 或更早版本迁移：移除 temperature、top_p 和 top_k（非默认值在 Opus 4.7 上返回 400）
• 如果从 Claude 4.1 或更早版本迁移：更新工具版本（text_editor_20250728、code_execution_20250825）
• 如果从 Claude 4.1 或更早版本迁移：处理 refusal 停止原因
• 如果从 Claude 4.1 或更早版本迁移：处理 model_context_window_exceeded 停止原因
• 如果从 Claude 4.1 或更早版本迁移：验证工具字符串参数处理尾部换行符
• 如果从 Claude 4.1 或更早版本迁移：移除旧版测试版标头（token-efficient-tools-2025-02-19、output-128k-2025-02-19）
• 按照 提示最佳实践 审查和更新提示
• 在生产部署前在开发环境中测试

迁移到 Claude Sonnet 4.6

Claude Sonnet 4.6 结合了强大的智能与快速性能，具有改进的代理搜索功能和在与网络搜索或网络获取一起使用时的免费代码执行。它非常适合日常编码、分析和内容任务。

有关功能的完整概述，请参阅 模型概述。

更新您的模型名称：

# 从 Sonnet 4.5
model = "claude-sonnet-4-5"  # 之前
model = "claude-sonnet-4-6"  # 之后

# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-6"  # 之后

破坏性变更

从 Sonnet 4.5 迁移时

1. 不再支持预填充助手消息

   从 Sonnet 4.5 或更早版本迁移时，这是一项破坏性变更。

   在 Sonnet 4.6 上预填充助手消息会返回 400 错误。请改用结构化输出、系统提示指令或 output_config.format。

   常见的预填充用例和迁移方案：

   • 控制输出格式（强制 JSON/YAML 输出）：使用结构化输出或带有枚举字段的工具进行分类任务。

   • 消除前言（删除"Here is..."短语）：在系统提示中添加直接指令："直接回复，不要前言。不要以'Here is...'、'Based on...'等短语开头。"

   • 避免不当拒绝： Claude 现在在适当拒绝方面表现得更好。在用户消息中进行清晰的提示，无需预填充应该足够。

   • 继续（恢复中断的响应）：将继续移到用户消息中："您之前的响应被中断，以 [previous_response] 结尾。从中断的地方继续。"

   • 上下文补充/角色一致性（在长对话中刷新上下文）：将之前预填充的助手提醒注入到用户回合中。

2. 工具参数 JSON 转义可能不同

   从 Sonnet 4.5 或更早版本迁移时，这是一项破坏性变更。

   工具参数中的 JSON 字符串转义可能与以前的模型不同。标准 JSON 解析器会自动处理这个问题，但自定义的基于字符串的解析可能需要更新。

从 Claude 3.x 迁移时

1. 更新采样参数

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   仅使用 temperature 或 top_p，不能同时使用两者。

2. 更新工具版本

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   更新到最新的工具版本（text_editor_20250728、code_execution_20250825）。删除任何使用 undo_edit 命令的代码。

3. 处理 refusal 停止原因

   更新您的应用程序以处理 refusal 停止原因。

4. 为行为变化更新您的提示

   Claude 4 模型具有更简洁、直接的通信风格。查看提示工程最佳实践以获取优化指导。

推荐的变更

1. 删除 fine-grained-tool-streaming-2025-05-14 beta 标头： 细粒度工具流现在在 Sonnet 4.6 上是 GA，不再需要 beta 标头。
2. 将 output_format 迁移到 output_config.format： output_format 参数已弃用。请改用 output_config.format。

从 Sonnet 4.5 迁移

考虑从 Sonnet 4.5 迁移到 Sonnet 4.6，它以相同的价格点提供更高的智能。

如果您不使用扩展思考

如果您在 Sonnet 4.5 上不使用扩展思考，您可以在 Sonnet 4.6 上继续不使用它。您应该明确设置努力级别以适合您的用例。在禁用思考的 low 努力下，您可以期望相对于没有扩展思考的 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 上仍然可用，但已弃用。迁移到自适应思考与努力参数。

迁移到自适应思考

自适应思考是 Sonnet 4.6 上 budget_tokens 的推荐替代品。它特别适合以下工作负载模式：

• 自主多步代理： 将需求转化为工作软件的编码代理、数据分析管道和错误查找，其中模型在许多步骤中独立运行。自适应思考让模型为每个步骤校准其推理，在更长的轨迹上保持在路径上。对于这些工作负载，从 high 努力开始。如果延迟或令牌使用是一个问题，缩减到 medium。
• 计算机使用代理： Sonnet 4.6 在使用自适应模式的计算机使用评估中实现了同类最佳的准确性。
• 双模态工作负载： 简单和困难任务的混合，其中自适应在简单查询上跳过思考，在复杂查询上进行深度推理。

使用自适应思考时，在您的任务上评估 medium 和 high 努力。正确的级别取决于您的工作负载在质量、延迟和令牌使用之间的权衡。

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"}],
)

在迁移期间保留 budget_tokens

如果您需要在迁移期间临时保留 budget_tokens，大约 16k 令牌的预算为更困难的问题提供了余地，而不会有失控令牌使用的风险。此配置已弃用，将在未来的模型版本中删除。

编码和代理用例

对于代理编码、前端设计、工具繁重的工作流和复杂的企业工作流，从 medium 努力开始。如果您发现延迟太高，请考虑将努力降低到 low。如果您需要更高的智能，请考虑将努力增加到 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 努力开始。如果您需要更多深度，将努力增加到 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"}],
)

Sonnet 4.6 迁移检查清单

• 将模型 ID 更新为 claude-sonnet-4-6
• 破坏性： 删除助手消息预填充；改用结构化输出或 output_config.format
• 破坏性： 验证工具参数 JSON 解析处理转义差异
• 破坏性： 将工具版本更新到最新（text_editor_20250728、code_execution_20250825）；不支持旧版本（如果从 3.x 迁移）
• 破坏性： 删除任何使用 undo_edit 命令的代码（如果适用）
• 破坏性： 更新采样参数以仅使用 temperature 或 top_p，不能同时使用两者（如果从 3.x 迁移）
• 在您的应用程序中处理新的 refusal 停止原因
• 删除 fine-grained-tool-streaming-2025-05-14 beta 标头（现在是 GA）
• 将 output_format 迁移到 output_config.format
• 按照提示工程最佳实践审查和更新提示
• 推荐： 从 thinking: {type: "enabled", budget_tokens: N} 迁移到 thinking: {type: "adaptive"} 与努力参数（budget_tokens 已弃用，将在未来版本中删除）
• 在生产部署前在开发环境中测试

迁移到 Claude Sonnet 4.5

Claude Sonnet 4.5 结合了强大的智能和快速的性能，使其成为日常编码、分析和内容任务的理想选择。

有关功能的完整概述，请参阅模型概述。

更新您的模型名称：

# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之后

# 从 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之后

破坏性变更

这些破坏性变更适用于从 Claude 3.x Sonnet 模型迁移时。

1. 更新采样参数

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   仅使用 temperature 或 top_p，不能同时使用两者。

2. 更新工具版本

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   更新到最新的工具版本（text_editor_20250728、code_execution_20250825）。删除任何使用 undo_edit 命令的代码。

3. 处理 refusal 停止原因

   更新您的应用程序以处理 refusal 停止原因。

4. 为行为变化更新您的提示

   Claude 4 模型具有更简洁、直接的通信风格。查看提示工程最佳实践以获取优化指导。

Sonnet 4.5 迁移检查清单

• 将模型 ID 更新为 claude-sonnet-4-5-20250929
• 破坏性： 将工具版本更新到最新（text_editor_20250728、code_execution_20250825）；不支持旧版本（如果从 3.x 迁移）
• 破坏性： 删除任何使用 undo_edit 命令的代码（如果适用）
• 破坏性： 更新采样参数以仅使用 temperature 或 top_p，不能同时使用两者（如果从 3.x 迁移）
• 在您的应用程序中处理新的 refusal 停止原因
• 按照提示工程最佳实践审查和更新提示
• 考虑为复杂推理任务启用扩展思考
• 在生产部署前在开发环境中测试

迁移到 Claude Haiku 4.5

Claude Haiku 4.5 是最快、最聪明的 Haiku 模型，具有接近前沿的性能，为交互式应用程序和大容量处理提供高级模型质量。

有关功能的完整概述，请参阅模型概述。

更新您的模型名称：

# 从 Haiku 3.5
model = "claude-3-5-haiku-20241022"  # 之前
model = "claude-haiku-4-5-20251001"  # 之后

# 从 Haiku 3
model = "claude-3-haiku-20240307"  # 之前
model = "claude-haiku-4-5-20251001"  # 之后

审查新的速率限制： Haiku 4.5 与 Haiku 3.5 和 Haiku 3 有不同的速率限制。有关详细信息，请参阅速率限制文档。

探索新功能： 有关上下文感知、增加的输出容量（64k 令牌）、更高的智能和改进的速度的详细信息，请参阅模型概述。

破坏性变更

这些破坏性变更适用于从 Claude 3.x Haiku 模型迁移时。

1. 更新采样参数

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   仅使用 temperature 或 top_p，不能同时使用两者。

2. 更新工具版本

   从 Claude 3.x 模型迁移时，这是一项破坏性变更。

   更新到最新的工具版本（text_editor_20250728、code_execution_20250825）。删除任何使用 undo_edit 命令的代码。

3. 处理 refusal 停止原因

   更新您的应用程序以处理 refusal 停止原因。

4. 为行为变化更新您的提示

   Claude 4 模型具有更简洁、直接的通信风格。查看提示工程最佳实践以获取优化指导。

Haiku 4.5 迁移检查清单

• 将模型 ID 更新为 claude-haiku-4-5-20251001
• 破坏性： 将工具版本更新到最新（text_editor_20250728、code_execution_20250825）；不支持旧版本
• 破坏性： 删除任何使用 undo_edit 命令的代码（如果适用）
• 破坏性： 更新采样参数以仅使用 temperature 或 top_p，不能同时使用两者
• 在您的应用程序中处理新的 refusal 停止原因
• 审查并调整新的速率限制（与 Haiku 3.5 分开）
• 按照提示工程最佳实践审查和更新提示
• 考虑为复杂推理任务启用扩展思考
• 在生产部署前在开发环境中测试

获取帮助

• 查看 API 文档以获取详细规范
• 查看模型功能以获取性能比较
• 查看 API 发行说明以获取 API 更新
• 如果在迁移期间遇到任何问题，请联系支持