遷移到 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 更新
• 如果在遷移過程中遇到任何問題，請聯繫支持