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

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

  1. 更新您的模型名称:

    • 从:claude-3-7-sonnet-20250219
    • 到:claude-sonnet-4-20250514claude-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 模型支持将工具使用与扩展思考交错,允许更自然的对话,其中工具使用和响应可以与常规消息混合。

交错思考处于测试阶段。要启用交错思考,请在您的 API 请求中添加 beta 标头 interleaved-thinking-2025-05-14

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

更新的文本编辑器工具

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

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

对于 Claude Sonnet 3.7,str_replace_editor 文本编辑器工具保持不变。

如果您正在从 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 更新。
  • 如果在迁移过程中遇到任何问题,请联系支持。