迁移到 Claude 4.5

本指南涵盖了迁移到 Claude 4.5 模型的两个关键迁移路径：

• Claude Sonnet 3.7 → Claude Sonnet 4.5：我们最智能的模型，具有同类最佳的推理、编码和长期运行代理功能
• Claude Haiku 3.5 → Claude Haiku 4.5：我们最快且最智能的 Haiku 模型，为实时应用和大容量智能处理提供接近前沿的性能

两种迁移都涉及需要更新实现的重大变化。本指南将通过分步说明和清晰标记的重大变化来指导您完成每个迁移路径。

在开始迁移之前，我们建议查看Claude 4.5 中的新增功能，以了解这些模型中提供的新功能和能力，包括扩展思考、上下文感知和行为改进。

从 Claude Sonnet 3.7 迁移到 Claude Sonnet 4.5

Claude Sonnet 4.5 是我们最智能的模型，为推理、编码和长期运行的自主代理提供同类最佳的性能。此迁移包括几个需要更新实现的重大变化。

迁移步骤

1. 更新您的模型名称：

   # 之前 (Claude Sonnet 3.7)
   model="claude-3-7-sonnet-20250219"
   
   # 之后 (Claude Sonnet 4.5)
   model="claude-sonnet-4-5-20250929"

2. 更新采样参数

   这是从 Claude Sonnet 3.7 的重大变化。

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

   # 之前 (Claude Sonnet 3.7) - 这将在 Sonnet 4.5 中出错
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # 不能同时使用
       ...
   )
   
   # 之后 (Claude Sonnet 4.5)
   response = client.messages.create(
       model="claude-sonnet-4-5-20250929",
       temperature=0.7,  # 使用 temperature 或 top_p，不能同时使用
       ...
   )

3. 处理新的 refusal 停止原因

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

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

4. 更新文本编辑器工具（如适用）

   这是从 Claude Sonnet 3.7 的重大变化。

   更新到 text_editor_20250728（类型）和 str_replace_based_edit_tool（名称）。删除任何使用 undo_edit 命令的代码。

   # 之前 (Claude Sonnet 3.7)
   tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # 之后 (Claude Sonnet 4.5)
   tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   有关详细信息，请参阅文本编辑器工具文档。

5. 更新代码执行工具（如适用）

   升级到 code_execution_20250825。旧版本 code_execution_20250522 仍然有效，但不推荐使用。有关迁移说明，请参阅代码执行工具文档。

6. 删除令牌高效工具使用测试版标头

   令牌高效工具使用是仅适用于 Claude 3.7 Sonnet 的测试版功能。所有 Claude 4 模型都内置了令牌高效工具使用，因此您不应再包含测试版标头。

   从您的请求中删除 token-efficient-tools-2025-02-19 测试版标头：

   # 之前 (Claude Sonnet 3.7)
   client.messages.create(
       model="claude-3-7-sonnet-20250219",
       betas=["token-efficient-tools-2025-02-19"],  # 删除此项
       ...
   )
   
   # 之后 (Claude Sonnet 4.5)
   client.messages.create(
       model="claude-sonnet-4-5-20250929",
       # 无令牌高效工具测试版标头
       ...
   )

7. 删除扩展输出测试版标头

   扩展输出的 output-128k-2025-02-19 测试版标头仅在 Claude Sonnet 3.7 中可用。

   从您的请求中删除此标头：

   # 之前 (Claude Sonnet 3.7)
   client.messages.create(
       model="claude-3-7-sonnet-20250219",
       betas=["output-128k-2025-02-19"],  # 删除此项
       ...
   )
   
   # 之后 (Claude Sonnet 4.5)
   client.messages.create(
       model="claude-sonnet-4-5-20250929",
       # 无输出 128k 测试版标头
       ...
   )

8. 更新您的提示以适应行为变化

   Claude Sonnet 4.5 具有更简洁、直接的通信风格，需要明确的指导。查看Claude 4 提示工程最佳实践以获取优化指导。

9. 考虑为复杂任务启用扩展思考

   为编码和推理任务启用扩展思考以获得显著的性能改进（默认禁用）：

   response = client.messages.create(
       model="claude-sonnet-4-5-20250929",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[...]
   )
   扩展思考会影响提示缓存效率。

10. 测试您的实现

在部署到生产环境之前在开发环境中进行测试，以确保所有重大变化都得到正确处理。

Sonnet 3.7 → 4.5 迁移检查清单

• 将模型 ID 更新为 claude-sonnet-4-5-20250929
• 重大变化：更新采样参数以仅使用 temperature 或 top_p，不能同时使用
• 在您的应用程序中处理新的 refusal 停止原因
• 重大变化：将文本编辑器工具更新为 text_editor_20250728 和 str_replace_based_edit_tool（如适用）
• 重大变化：删除任何使用 undo_edit 命令的代码（如适用）
• 将代码执行工具更新为 code_execution_20250825（如适用）
• 删除 token-efficient-tools-2025-02-19 测试版标头（如适用）
• 删除 output-128k-2025-02-19 测试版标头（如适用）
• 按照Claude 4 最佳实践审查和更新提示
• 考虑为复杂推理任务启用扩展思考
• 处理 model_context_window_exceeded 停止原因（Sonnet 4.5 特定）
• 考虑为长期运行的代理启用内存工具（测试版）
• 考虑使用自动工具调用清除进行上下文编辑（测试版）
• 在生产部署前在开发环境中进行测试

从 Claude Sonnet 3.7 中删除的功能

• 令牌高效工具使用：token-efficient-tools-2025-02-19 测试版标头仅适用于 Claude 3.7 Sonnet，在 Claude 4 模型中不受支持（参见步骤 6）
• 扩展输出：output-128k-2025-02-19 测试版标头不受支持（参见步骤 7）

两个标头都可以包含在 Claude 4 请求中，但不会产生任何效果。

从 Claude Haiku 3.5 迁移到 Claude Haiku 4.5

Claude Haiku 4.5 是我们最快且最智能的 Haiku 模型，具有接近前沿的性能，为交互式应用和大容量智能处理提供高级模型质量和实时性能。此迁移包括几个需要更新实现的重大变化。

有关新功能的完整概述，请参阅Claude 4.5 中的新增功能。

迁移步骤

1. 更新您的模型名称：

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

2. 更新工具版本（如适用）

   这是从 Claude Haiku 3.5 的重大变化。

   Haiku 4.5 仅支持最新的工具版本：

   # 之前 (Haiku 3.5)
   tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # 之后 (Haiku 4.5)
   tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
   • 文本编辑器：使用 text_editor_20250728 和 str_replace_based_edit_tool
   • 代码执行：使用 code_execution_20250825
   • 删除任何使用 undo_edit 命令的代码

3. 更新采样参数

   这是从 Claude Haiku 3.5 的重大变化。

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

   # 之前 (Haiku 3.5) - 这将在 Haiku 4.5 中出错
   response = client.messages.create(
       model="claude-3-5-haiku-20241022",
       temperature=0.7,
       top_p=0.9,  # 不能同时使用
       ...
   )
   
   # 之后 (Haiku 4.5)
   response = client.messages.create(
       model="claude-haiku-4-5-20251001",
       temperature=0.7,  # 使用 temperature 或 top_p，不能同时使用
       ...
   )

4. 审查新的速率限制

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

5. 处理新的 refusal 停止原因

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

6. 考虑为复杂任务启用扩展思考

   为编码和推理任务启用扩展思考以获得显著的性能改进（默认禁用）：

   response = client.messages.create(
       model="claude-haiku-4-5-20251001",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 5000},
       messages=[...]
   )
   扩展思考会影响提示缓存效率。

7. 探索新功能

   有关上下文感知、增加的输出容量（64K 令牌）、更高的智能和改进的速度的详细信息，请参阅Claude 4.5 中的新增功能。

8. 测试您的实现

   在部署到生产环境之前在开发环境中进行测试，以确保所有重大变化都得到正确处理。

Haiku 3.5 → 4.5 迁移检查清单

• 将模型 ID 更新为 claude-haiku-4-5-20251001
• 重大变化：将工具版本更新为最新版本（例如 text_editor_20250728、code_execution_20250825）- 不支持旧版本
• 重大变化：删除任何使用 undo_edit 命令的代码（如适用）
• 重大变化：更新采样参数以仅使用 temperature 或 top_p，不能同时使用
• 审查并调整新的速率限制（与 Haiku 3.5 分开）
• 在您的应用程序中处理新的 refusal 停止原因
• 考虑为复杂推理任务启用扩展思考（新功能）
• 利用上下文感知在长期会话中更好地管理令牌
• 为更大的响应做准备（最大输出从 8K 增加到 64K 令牌）
• 按照Claude 4 最佳实践审查和更新提示
• 在生产部署前在开发环境中进行测试

在 Sonnet 4.5 和 Haiku 4.5 之间选择

Claude Sonnet 4.5 和 Claude Haiku 4.5 都是具有不同优势的强大 Claude 4 模型：

为以下情况选择 Claude Sonnet 4.5（最智能）：

• 复杂推理和分析：用于复杂任务的同类最佳智能
• 长期运行的自主代理：用于独立工作长期的代理的卓越性能
• 高级编码任务：我们最强大的编码模型，具有高级规划和安全工程
• 大型上下文工作流：增强的上下文管理，具有内存工具和上下文编辑功能
• 需要最大能力的任务：当智能和准确性是首要优先事项时

为以下情况选择 Claude Haiku 4.5（最快且最智能的 Haiku）：

• 实时应用：为具有接近前沿性能的交互式用户体验提供快速响应时间
• 大容量智能处理：以改进的速度大规模提供具有成本效益的智能
• 成本敏感的部署：以较低价格点提供接近前沿的性能
• 子代理架构：用于多代理系统的快速、智能代理
• 大规模计算机使用：具有成本效益的自主桌面和浏览器自动化
• 需要速度的任务：当低延迟至关重要，同时保持接近前沿的智能时

扩展思考建议

Claude 4 模型，特别是 Sonnet 和 Haiku 4.5，在使用扩展思考进行编码和复杂推理任务时显示出显著的性能改进。扩展思考默认禁用，但我们建议为要求苛刻的工作启用它。

重要：扩展思考会影响提示缓存效率。当非工具结果内容被添加到对话时，思考块会从缓存中删除，这可能会增加多轮对话中的成本。我们建议在性能优势超过缓存权衡时启用思考。

其他迁移场景

上面涵盖的主要迁移路径（Sonnet 3.7 → 4.5 和 Haiku 3.5 → 4.5）代表最常见的升级。但是，您可能正在从其他 Claude 模型迁移到 Claude 4.5。本部分涵盖这些场景。

从 Claude Sonnet 4 → Sonnet 4.5 迁移

重大变化：不能在同一请求中同时指定 temperature 和 top_p。

所有其他 API 调用将无需修改即可工作。更新您的模型 ID 并根据需要调整采样参数：

# 之前 (Claude Sonnet 4)
model="claude-sonnet-4-20250514"

# 之后 (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"

从 Claude Opus 4.1 → Sonnet 4.5 迁移

无重大变化。 所有 API 调用将无需修改即可工作。

只需更新您的模型 ID：

# 之前 (Claude Opus 4.1)
model="claude-opus-4-1-20250805"

# 之后 (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"

Claude Sonnet 4.5 是我们最智能的模型，具有同类最佳的推理、编码和长期运行代理功能。对于大多数用例，它相比 Opus 4.1 提供卓越的性能。

需要帮助？

• 查看我们的API 文档以获取详细规范
• 查看模型功能以进行性能比较
• 查看API 发布说明以了解 API 更新
• 如果在迁移过程中遇到任何问题，请联系支持