跳轉到主要內容
本頁面提供從 Claude 3.7 模型遷移到 Claude 4 模型（例如 Opus 4.1 和 Sonnet 4.5）的指導。 在大多數情況下，您可以透過最少的變更切換到 Claude 4 模型：
  1. 更新您的模型名稱：
    • 從：claude-3-7-sonnet-20250219
    • 到：claude-sonnet-4-5-20250929（或 claude-opus-4-1-20250805）
  2. 現有的 API 呼叫應該可以繼續運作而無需修改，儘管 API 行為略有變化（詳情請參閱 API 發布說明）。

​
Claude 4 的新功能

​
新的拒絕停止原因

Claude 4 模型引入了新的 refusal 停止原因，用於模型因安全原因拒絕生成的內容，這是由於 Claude 4 模型智能的提升： 
{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-5",
"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.x 時，您應該更新您的應用程式以處理 refusal 停止原因。

​
摘要思考

啟用延伸思考後，Claude 4 模型的 Messages API 會返回 Claude 完整思考過程的摘要。摘要思考提供延伸思考的完整智能優勢，同時防止濫用。 雖然 API 在 Claude 3.7 和 4 模型之間保持一致，但延伸思考的串流回應可能會以「分塊」的傳遞模式返回，串流事件之間可能會有延遲。
摘要是由與您在請求中指定的模型不同的模型處理的。思考模型看不到摘要輸出。
更多資訊請參閱延伸思考文件。

​
交錯思考

Claude 4 模型支援將工具使用與延伸思考交錯，允許更自然的對話，其中工具使用和回應可以與常規訊息混合。
交錯思考處於測試版。要啟用交錯思考，請在您的 API 請求中添加測試版標頭 interleaved-thinking-2025-05-14。
更多資訊請參閱延伸思考文件。

​
行為差異

Claude 4 模型，特別是 Sonnet 4.5，有顯著的行為變化，可能會影響您如何構建提示：

​
溝通風格變化

  • 更簡潔直接：Claude 4 模型溝通更有效率，解釋較不冗長
  • 更自然的語調：回應稍微更對話化，較不像機器
  • 專注效率：可能會跳過完成動作後的詳細摘要以保持工作流程動力（如果需要，您可以提示要求更多細節）

​
指令遵循

Claude 4 模型經過精確指令遵循的訓練，需要更明確的指導：
  • 明確說明動作：如果您希望 Claude 採取行動，請使用直接語言如「進行這些變更」或「實作此功能」，而不是「您能建議變更嗎」
  • 清楚說明期望的行為：Claude 會精確遵循指令，因此明確說明您想要的內容有助於獲得更好的結果
有關使用這些模型的全面指導，請參閱 Claude 4 提示工程最佳實務。

​
更新的文字編輯器工具

文字編輯器工具已針對 Claude 4 模型進行更新，變更如下：
  • 工具類型：text_editor_20250728
  • 工具名稱：str_replace_based_edit_tool
  • 不再支援 undo_edit 命令。
str_replace_editor 文字編輯器工具對於 Claude Sonnet 3.7 保持不變。
如果您正在從 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"
    }
]
更多資訊請參閱文字編輯器工具文件。

​
更新的程式碼執行工具

如果您正在使用程式碼執行工具，請確保您使用的是最新版本 code_execution_20250825，它添加了 Bash 命令和檔案操作功能。 舊版本 code_execution_20250522（僅 Python）仍然可用，但不建議用於新的實作。 遷移說明請參閱程式碼執行工具文件。

​
移除的功能

​
不再支援代幣高效工具使用

代幣高效工具使用僅在 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.5 用於：

  • 長時間運行的代理：最適合長期獨立工作的自主代理
  • 編碼任務：我們最強的編碼模型，具有進階規劃和安全工程能力
  • 大型上下文工作流程：透過記憶工具和上下文編輯功能增強上下文管理
  • 大多數使用案例：最新模型，具有最佳的能力和效能平衡

​
選擇 Claude Opus 4.1 用於：

  • 專業複雜任務：當您需要卓越的分析深度時
  • 速度不重要的任務：比 Sonnet 模型慢但更徹底

​
延伸思考建議

Claude 4 模型，特別是 Sonnet 4.5，在使用延伸思考進行編碼和複雜推理任務時顯示出顯著的效能改善。延伸思考預設為停用，但我們建議為要求高的工作啟用它。 啟用延伸思考：
  • API：在您的請求中包含 thinking 參數： 
    response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[...]
)
  • Claude Code：在您的設定中設定 MAX_THINKING_TOKENS 環境變數： 
    {
  "env": {
    "MAX_THINKING_TOKENS": "10000"
  }
}
重要：延伸思考會影響提示快取效率。當非工具結果內容被添加到對話中時，思考區塊會從快取中剝離，這可能會增加多輪對話的成本。我們建議在效能優勢超過快取權衡時啟用思考。

​
遷移檢查清單

  • 在您的 API 呼叫中更新模型 id
  • 測試現有請求（應該無需變更即可運作）
  • 查看 Claude 4 提示工程最佳實務以了解行為變化和提示最佳化
  • 更新提示以更明確地說明期望的動作（例如，「實作這個」vs「您能建議嗎」）
  • 調整對溝通風格的期望（更簡潔，如果需要詳細摘要可能需要提示）
  • 如適用，移除 token-efficient-tools-2025-02-19 測試版標頭
  • 如適用，移除 output-128k-2025-02-19 測試版標頭
  • 處理新的 refusal 停止原因
  • 如果使用文字編輯器工具，更新工具類型和名稱
  • 移除任何使用 undo_edit 命令的程式碼
  • 如果使用程式碼執行工具：如果仍在使用舊版本，升級到最新版本（code_execution_20250825）
  • 探索延伸思考的新工具交錯功能
  • 如果使用 Sonnet 4.5：查看 Sonnet 4.5 的新功能以了解其他功能
  • 如果使用 Sonnet 4.5：處理 model_context_window_exceeded 停止原因
  • 如果使用 Sonnet 4.5：考慮為長時間運行的代理啟用記憶工具（測試版）
  • 如果使用 Sonnet 4.5：考慮使用自動工具呼叫清除進行上下文編輯（測試版）
  • 對於代理工作流程：利用結構化狀態檔案的狀態追蹤功能（建議使用 JSON 處理結構化資料）
  • 在生產部署前在開發環境中測試

​
需要協助？

  • 查看我們的 API 文件以獲取詳細規格。
  • 查看模型功能以進行效能比較。
  • 查看 API 發布說明以了解 API 更新。
  • 如果在遷移過程中遇到任何問題，請聯繫支援。