迁移到 Claude 4

本页面提供从 Claude 3.7 模型迁移到 Claude 4 模型（Opus 4 和 Sonnet 4）的指导。

在大多数情况下，您可以通过最少的更改切换到 Claude 4 模型：

1. 更新您的模型名称：

   • 从：claude-3-7-sonnet-20250219
   • 到：claude-sonnet-4-20250514 或 claude-opus-4-20250514

2. 现有的 API 调用应该可以继续工作，无需修改，尽管 Claude 4 模型的 API 行为略有变化（详情请参阅 API 发布说明）。

​

Claude 4 的新特性

​

新的拒绝停止原因

由于 Claude 4 模型的智能水平提高，Claude 4 模型引入了一个新的 refusal（拒绝）停止原因，用于模型因安全原因拒绝生成的内容：

{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"I would be happy to assist you. You can "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}

在迁移到 Claude 4 时，您应该更新您的应用程序以处理 refusal 停止原因。

​

总结思考

启用扩展思考后，Claude 4 模型的 Messages API 会返回 Claude 完整思考过程的摘要。总结思考提供了扩展思考的全部智能优势，同时防止滥用。

虽然 API 在 Claude 3.7 和 4 模型之间保持一致，但扩展思考的流式响应可能会以”块状”传递模式返回，流式事件之间可能会有延迟。

有关更多信息，请参阅扩展思考文档。

​

交错思考

Claude 4 模型支持将工具使用与扩展思考交错，允许更自然的对话，其中工具使用和响应可以与常规消息混合。

有关更多信息，请参阅扩展思考文档。

​

更新的文本编辑器工具

Claude 4 模型的文本编辑器工具已更新，变更如下：

• 工具类型：text_editor_20250429
• 工具名称：str_replace_based_edit_tool
• Claude 4 模型不再支持 undo_edit 命令。

如果您正在从 Claude Sonnet 3.7 迁移并使用文本编辑器工具：

# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
    }
]

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

​

不再支持令牌高效工具使用

令牌高效工具使用仅在 Claude Sonnet 3.7 中可用。

如果您正在从 Claude Sonnet 3.7 迁移并使用令牌高效工具使用，我们建议从您的请求中移除 token-efficient-tools-2025-02-19 beta 标头。

token-efficient-tools-2025-02-19 beta 标头仍然可以包含在 Claude 4 请求中，但它不会产生任何效果。

​

不再支持扩展输出

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

如果您正在从 Claude Sonnet 3.7 迁移，我们建议从您的请求中移除 output-128k-2025-02-19。

output-128k-2025-02-19 beta 标头仍然可以包含在 Claude 4 请求中，但它不会产生任何效果。

​

性能考虑

​

Claude Sonnet 4

• 与 Claude Sonnet 3.7 相比，推理和智能能力得到改进
• 增强的工具使用准确性

​

Claude Opus 4

• 最强大的模型，具有卓越的推理和智能能力
• 比 Sonnet 模型慢
• 最适合需要深入分析的复杂任务

​

迁移检查清单

• 更新 API 调用中的模型 ID
• 测试现有请求（应该无需更改即可工作）
• 如果适用，移除 token-efficient-tools-2025-02-19 beta 标头
• 如果适用，移除 output-128k-2025-02-19 beta 标头
• 处理新的 refusal 停止原因
• 如果使用文本编辑器工具，更新工具类型和名称
• 移除使用 undo_edit 命令的任何代码
• 探索扩展思考的新工具交错功能
• 查看 Claude 4 提示工程最佳实践以获得最佳结果
• 在生产部署前在开发环境中测试

​

需要帮助？

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