遷移至 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. 更新您的模型名稱：

   # Before (Claude Sonnet 3.7)
   model="claude-3-7-sonnet-20250219"
   
   # After (Claude Sonnet 4.5)
   model="claude-sonnet-4-5-20250929"

2. 更新採樣參數

   這是從 Claude Sonnet 3.7 的重大變更。

   僅使用 temperature 或 top_p，不能同時使用：

   # Before (Claude Sonnet 3.7) - 這將在 Sonnet 4.5 中出錯
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # 無法同時使用
       ...
   )
   
   # After (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 命令的程式碼。

   # Before (Claude Sonnet 3.7)
   tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # After (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 測試版標頭：

   # Before (Claude Sonnet 3.7)
   client.messages.create(
       model="claude-3-7-sonnet-20250219",
       betas=["token-efficient-tools-2025-02-19"],  # 移除此項
       ...
   )
   
   # After (Claude Sonnet 4.5)
   client.messages.create(
       model="claude-sonnet-4-5-20250929",
       # 無令牌高效工具測試版標頭
       ...
   )

7. 移除擴展輸出測試版標頭

   擴展輸出的 output-128k-2025-02-19 測試版標頭 僅在 Claude Sonnet 3.7 中提供。

   從您的請求中移除此標頭：

   # Before (Claude Sonnet 3.7)
   client.messages.create(
       model="claude-3-7-sonnet-20250219",
       betas=["output-128k-2025-02-19"],  # 移除此項
       ...
   )
   
   # After (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. 更新您的模型名稱：

   # Before (Haiku 3.5)
   model="claude-3-5-haiku-20241022"
   
   # After (Haiku 4.5)
   model="claude-haiku-4-5-20251001"

2. 更新工具版本（如適用）

   這是從 Claude Haiku 3.5 的重大變更。

   Haiku 4.5 僅支援最新工具版本：

   # Before (Haiku 3.5)
   tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # After (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，不能同時使用：

   # Before (Haiku 3.5) - 這將在 Haiku 4.5 中出錯
   response = client.messages.create(
       model="claude-3-5-haiku-20241022",
       temperature=0.7,
       top_p=0.9,  # 無法同時使用
       ...
   )
   
   # After (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. 探索新功能

   詳見 Claude 4.5 的新功能 以了解上下文感知、增加的輸出容量（64K 令牌）、更高的智能和改進的速度。

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 並根據需要調整採樣參數：

# Before (Claude Sonnet 4)
model="claude-sonnet-4-20250514"

# After (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"

從 Claude Opus 4.1 → Sonnet 4.5 遷移

無重大變更。 所有 API 呼叫將無需修改即可工作。

只需更新您的模型 ID：

# Before (Claude Opus 4.1)
model="claude-opus-4-1-20250805"

# After (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"

Claude Sonnet 4.5 是我們最聰慧的模型，具有同類最佳的推理、編碼和長期運行代理功能。對於大多數使用情況，它相比 Opus 4.1 提供卓越的性能。

從 Claude Opus 4.1 → Opus 4.5 遷移

無重大變更。 所有 API 呼叫將無需修改即可工作。

只需更新您的模型 ID：

# Before (Claude Opus 4.1)
model="claude-opus-4-1-20250805"

# After (Claude Opus 4.5)
model="claude-opus-4-5-20251101"

Claude Opus 4.5 是我們最聰慧的模型，結合最大功能與實用性能。它在視覺、編碼和電腦使用方面具有階躍式改進，價格點比 Opus 4.1 更易於接受。適合複雜的專業任務和專業軟體工程。

在 Claude 4.5 模型之間遷移

無重大變更。 所有 API 呼叫將無需修改即可工作。

只需更新您的模型 ID。

需要幫助？

• 查看我們的 API 文件 以了解詳細規格
• 查看 模型功能 以進行性能比較
• 查看 API 發行說明 以了解 API 更新
• 如果在遷移期間遇到任何問題，請聯絡支援