迁移到 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 模型引入了一个新的 refusal 停止原因，用于模型因安全原因拒绝生成的内容，这是由于 Claude 4 模型智能的提升：

{"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_20250728
• 工具名称：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_20250728",
        "name": "str_replace_based_edit_tool"
    }
]

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

​

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

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

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

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

​

不再支持扩展输出

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

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

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

​

性能考虑

​

Claude Sonnet 4

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

​

Claude Opus 4

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

​

迁移检查清单

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

​

需要帮助？

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