Claude Sonnet 5.5 遷移指南

本指南列出從 Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Sonnet 4、Claude 3.7 Sonnet 或 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5 所需的程式碼變更。請先閱讀前兩個章節，再往下閱讀至您目前模型所對應的章節。遷移檢查清單依起始模型列出所有變更。

Claude Sonnet 5.5 的價格與 Claude Sonnet 5 相同，唯獨提示快取讀取的費用為每百萬個 token 0.10 美元，是 Claude Sonnet 5 費率的一半。請參閱定價。關於其「context window」（上下文視窗）與輸出限制，請參閱 Claude Sonnet 5.5 模型頁面。關於功能與提示撰寫，請參閱 Claude Sonnet 5.5 的新功能與為 Claude Sonnet 5.5 撰寫提示。

向 Claude Sonnet 5.5 傳送請求

此請求可直接在 Claude Sonnet 5.5 上運作。它設定了「effort」（投入程度）等級，並省略了五項會傳回 400 錯誤的設定：思考預算、取樣參數、助理預填、強制工具選擇，以及 thinking: {"type": "disabled"}。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

思考預設會執行

在 Claude Sonnet 5.5 上，沒有 thinking 欄位的請求會以自適應思考執行，thinking: {"type": "adaptive"} 也是如此。在 Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 上，這類請求不會進行思考。若要繼續在不進行前置思考的情況下執行，請參閱關閉前置思考。

處理回應中的思考

原本不進行思考的程式碼需要處理全部三項。來自 Claude Sonnet 5 的程式碼可能已具備前兩項。

• 依 type 讀取內容區塊。 回應可能以 thinking 區塊開頭，因此讀取 content[0].text 的程式碼會出錯。
• 在工具使用迴圈中原封不動地傳回 thinking 區塊，包括空的區塊。請參閱保留思考區塊。
• 重新檢視 max_tokens。 它涵蓋思考加上文字，而思考 token 以輸出 token 計費。請參閱成本控制。

思考文字預設會被省略。thinking 區塊傳回時帶有空的 thinking 欄位與一個 signature。若要取得可讀的摘要，請設定 display: "summarized"，這是 Claude Sonnet 4.6 及更早模型以及 Claude Haiku 4.5 上的預設值。請參閱控制思考顯示。

關閉前置思考

若要在 Claude Sonnet 5.5 上關閉前置思考，請傳送 thinking: {"type": "between_tools"}。這是最低的思考設定。它在工具呼叫之間的進度更新仍會以 thinking 區塊連同摘要文字傳回。若沒有工具，回應僅包含文字。Claude Sonnet 5 則改用 thinking: {"type": "disabled"} 關閉思考，而更早的模型預設不進行思考。在 Claude Sonnet 5.5 上，disabled 會傳回 400 invalid_request_error：

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

between_tools 可在所有提供 Claude Sonnet 5.5 的平台上使用。它在 low、medium 與 high 投入程度下皆可接受。在 xhigh 或 max 下，它會傳回 400 錯誤。若要以這些等級執行，請使用自適應思考：省略 thinking 欄位或傳送 thinking: {"type": "adaptive"}。between_tools 不接受其他欄位：與其一同傳送的 display、budget_tokens 或 block_binding 會傳回 400 錯誤。使用伺服器端備援時，備援至 Claude Sonnet 5 的 between_tools 請求會在該模型上以 thinking: {"type": "disabled"} 執行。

使用 between_tools 時，投入程度無法在對話中途變更：若每則訊息的 output_config.effort 與目前生效的等級不同，會傳回 400 錯誤。若要在每個回合中變更投入程度，請使用自適應思考。關於提示撰寫指引，請參閱在不進行前置思考的情況下執行。

之前（Claude Sonnet 5）：

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

依起始模型的遷移檢查清單

請依序往下處理各群組，並在列出您模型的群組後停止。若使用 Claude Haiku 4.5，請套用「Claude Sonnet 4 或更早版本」以外的所有群組，最後以「僅限 Claude Haiku 4.5」結束。

所有起始模型

• 將模型 ID 變更為 claude-sonnet-5-5。
• 依 type 讀取內容區塊，並將 thinking 區塊原封不動地傳回。
• 若要繼續在不進行前置思考的情況下執行，請在 high 或更低的投入程度下傳送最低的思考設定。
• 將強制工具使用替換為 auto 及嚴格工具（strict tools）。
• 保持對話為僅附加（append-only）。
• 將電腦使用移至工具集（toolset），且不使用 fine-grained-tool-streaming-2025-05-14 beta 標頭。在 Amazon Bedrock 上，computer_20251124 也可運作。
• 將顧問工具與支援的顧問搭配使用，並預期會收到加密的建議。
• 從 thinking 區塊讀取工具呼叫之間的文字。
• 處理拒絕回應，並設定備援（fallback）。
• 重新執行您的投入程度測試，並重新建立成本基準。

Claude Sonnet 4.6 或更早版本

• 預期沒有 thinking 欄位的請求會進行思考，並重新檢視 max_tokens。
• 以投入程度等級取代思考預算。
• 移除 temperature、top_p 和 top_k。
• 若您會顯示思考文字，請設定 display: "summarized"。
• 重新計算 token，並重新規劃圖片 token 的預算。

Claude Sonnet 4.5 或更早版本

• 替換助理預填（assistant prefill）。
• 使用標準 JSON 剖析器剖析工具呼叫輸入。
• 明確設定 output_config.effort。
• 移除任何上下文視窗 beta 標頭。
• 移除 interleaved-thinking-2025-05-14，並將 fine-grained-tool-streaming-2025-05-14 替換為 eager_input_streaming。
• 將 output_format 移至 output_config.format。

Claude Sonnet 4 或更早版本

• 將工具版本更新為 text_editor_20250728 與 code_execution_20260521。
• 處理 refusal 與 model_context_window_exceeded 停止原因。
• 檢查工具字串參數是否有結尾換行符號。
• 移除 token-efficient-tools-2025-02-19 與 output-128k-2025-02-19。
• 檢閱您的提示。

僅限 Claude Haiku 4.5

• 取代 claude-haiku-4-5-20251001 或其別名。
• 以較高的每 token 價格重新建立成本基準。
• 檢閱那些在 Claude Haiku 4.5 上因過短而無法快取的提示。

從 Claude Sonnet 5 遷移至 Claude Sonnet 5.5

所有起始模型都需要本章節中的變更。將您的模型 ID 替換為 claude-sonnet-5-5，此 ID 沒有日期後綴。在其他平台上，請使用可用性下所列的 ID。

不支援強制工具使用

本頁面上所有較早的模型都接受類型為 any 或 tool 的 tool_choice。Claude Sonnet 5.5 會以 400 錯誤拒絕兩者，包括在 token 計數端點上：

tool_choice: type "tool" and "any" are not supported for this model.

請傳送 tool_choice: {"type": "auto"}，並將工具標記為 strict: true，使其輸入符合結構描述。如此一來，模型可以不呼叫工具就直接回答，因此請在提示中說明何時使用該工具。嚴格工具使用支援 JSON Schema 的子集，且每個物件都需要 additionalProperties: false。請參閱 JSON Schema 限制。

之前（Claude Sonnet 5）：

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # strict tool use（嚴格工具使用）：每次呼叫皆符合工具的 input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

此範例將清單中的每個工具都標記為嚴格。一個請求最多可有 20 個嚴格工具，且 MCP、電腦使用與瀏覽器使用工具集項目不接受 strict。在較長的工具清單中，請只標記需要的工具。

思考區塊與模型及對話綁定

Claude Sonnet 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及更早模型的思考區塊。在 Claude API 與 Claude Models on Google Cloud (Google managed) 上，它也可讀取來自 Claude Haiku 5.5 的思考區塊。它無法讀取來自 Claude Opus 5、Claude Opus 5.5 或任何 Claude Fable 或 Claude Mythos 模型的區塊。

API 會捨棄模型無法讀取的區塊。請求會傳回 200，且被捨棄的區塊不會計費。請參閱切換模型再切換回來。

請保持對話為僅附加，讓思考區塊能通過前綴檢查。若要變更指示或工具，請參閱對話中途的系統訊息與工具變更。

未通過前綴檢查可能會、也可能不會導致 400 錯誤。若要識別並處理這兩種情況，請參閱思考區塊的前綴檢查。

前綴檢查會在 Claude API 及部分雲端平台上執行。

Claude Sonnet 5.5 的思考區塊僅能在產生它們的帳戶或與其連結的帳戶中使用。請參閱保留思考。

部分電腦使用工具版本不受支援

Claude Sonnet 5.5 透過 computer_toolset_20260801 工具集支援電腦使用。在 Amazon Bedrock 上，Claude Sonnet 5.5 也接受搭配 computer-use-2025-11-24 beta 標頭的 computer_20251124 工具。對於任何不接受的電腦使用工具版本（例如 Claude API 上的 computer_20251124），Claude Sonnet 5.5 會傳回 400 錯誤。它在任何平台上都不接受 computer_20250124。

已使用工具集的整合無需任何變更。若要移至工具集，請將 computer_20251124 或 computer_20250124 替換為 computer_toolset_20260801，並移除該版本的 beta 標頭。關於請求與代理迴圈（agent loop）的變更，請參閱從 computer_20251124 遷移。

若您會傳送 fine-grained-tool-streaming-2025-05-14 beta 標頭，請在移至工具集時將其移除。它與工具集項目一同傳送時會傳回 400 錯誤。請改為在每個需要的工具上設定 eager_input_streaming: true。

顧問工具接受的顧問較少

使用顧問工具時，Claude Sonnet 5.5 執行者需要下列其中一個顧問：Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5、Claude Fable 5.1、Claude Fable 5.2、Claude Mythos 5、Claude Mythos 5.1 或 Claude Mythos 5.2。Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5、Claude Sonnet 4.6 與 Claude Haiku 5.5 顧問會傳回 400 錯誤。建議內容會以加密的 advisor_redacted_result 區塊傳回，因此其文字在回應中無法讀取。請參閱模型相容性。

工具呼叫之間的文字會在思考區塊中傳回

在 Claude Sonnet 5.5 上，模型在工具呼叫之間寫下、長度超過一兩句的說明會以進度更新 thinking 區塊傳回，在預設的 display 下為空。較短的評論仍為 text。在 Claude Sonnet 5 及更早的模型上，工具呼叫之間的所有文字都會以 text 區塊傳回。沒有請求會失敗，但顯示這些說明的介面會停止顯示它們。

使用自適應思考時，請將 display 設為 "updates"（beta，需 thinking-display-updates-2026-08-18 標頭）以僅取得更新，或設為 "summarized" 以取得與推理混合的更新。請在每個非空的 thinking 區塊之後的 tool_use 區塊之前呈現該區塊。使用 between_tools 時，文字會在沒有 display 的情況下傳回。請參閱面向使用者的進度更新。

安全分類器與備援

Claude Sonnet 5.5 會拒絕的類別比 Claude Sonnet 5 更多。拒絕會傳回 stop_reason: "refusal"，而其 stop_details 可指出下列其中一個類別：

• "cyber"： 該請求可能促成網路危害，例如惡意軟體或漏洞利用程式的開發。
• "bio"： 該請求可能促成生物危害，例如危險的實驗室方法。
• "frontier_llm"： 該請求可能協助開發具競爭性的 AI 模型。
• "reasoning_extraction"： 該請求要求模型在回應文字中重現其內部推理。
• "general_harms"： 該請求屬於其他使用政策領域。良性工作也可能觸發此類別。

伺服器端備援（fallbacks: "default"）在 Claude API 與 Claude Models on Google Cloud (Anthropic managed) 上為 beta 版，會在 Claude Sonnet 5 上重試 "cyber" 與 "frontier_llm" 拒絕。它不會重試 "bio"、"reasoning_extraction" 或 "general_harms" 拒絕。請參閱拒絕與備援與拒絕如何計費。

對於來自 Claude Sonnet 4.6、Claude Sonnet 4.5 與 Claude Haiku 4.5 的程式碼而言，即時網路安全防護措施是新的。若是正當的資安工作，請申請 Cyber Verification Program。

其他變更

• 提示快取： 最小可快取提示為 512 個 token，低於 Claude Sonnet 5、Claude Sonnet 4.6 與 Claude Sonnet 4.5 上的 1,024 個。請參閱提示快取。
• 新功能： 關於對話中途的系統訊息、對話中途的工具變更以及每則訊息的投入程度，請參閱 Claude Sonnet 5.5 的新功能。使用 between_tools 時，投入程度無法在對話中途變更。

建議變更

重新進行投入程度測試。Claude Sonnet 5.5 有五個投入程度等級：low、medium、high、xhigh 與 max。Claude API 上的預設值為 high。這些等級已重新校準，因此同一等級產生的思考量與 Claude Sonnet 5 上不同。除非您的工作負載屬於代理型或對延遲敏感，否則請從 high 開始。對於代理式程式開發與多步驟工具使用，規格明確的任務請從 medium 開始，較困難或較長的任務則改用 high。對於聊天及其他對延遲敏感的工作，請從 medium 或 low 開始。請在 output_config.effort 中設定等級。請參閱 Claude Sonnet 5.5 的建議投入程度等級。接著，請依照為 Claude Sonnet 5.5 撰寫提示重新評估模型專屬的提示指示。

從 Claude Sonnet 4.6 及更早的 Sonnet 模型遷移至 Claude Sonnet 5.5

請先套用前面的所有章節，並替換 claude-sonnet-4-6。接著進行以下變更。若使用 Claude Sonnet 4.5 或更早版本，請繼續閱讀後續的子章節。

破壞性變更

原本省略思考的請求會進行思考。 請參閱思考預設會執行與關閉前置思考。

思考預算會傳回錯誤。 Claude Sonnet 4.6 接受 thinking: {"type": "enabled", "budget_tokens": N} 作為已棄用的設定。Claude Sonnet 4.5 與 Claude Haiku 4.5 在所有思考中都使用此設定。Claude Sonnet 5.5 會傳回 400 錯誤：

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

請移除預算並設定投入程度等級。預算與投入程度等級之間沒有固定的對應關係，因此請在兩到三個等級下執行您的評估。

之前（Claude Sonnet 4.6）：

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

之後（Claude Sonnet 5.5）：

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

取樣參數會傳回錯誤。 請移除 temperature、top_p 和 top_k。

思考文字預設會被省略。 請參閱處理回應中的思考。

其他變更

• token 增加約 30%： Claude Sonnet 5.5 使用 Claude Sonnet 5 的 tokenizer。相較於 Claude Sonnet 4.6、Claude Sonnet 4.5 與 Claude Haiku 4.5，相同的文字會產生約多 30% 的 token，視內容而定。請使用 token 計數重新計算，並重新檢視 max_tokens 與成本。
• 投入程度： Claude Sonnet 5.5 支援 xhigh，且各等級已重新校準。請參閱建議變更。
• 圖片： Claude Sonnet 5.5 使用高解析度圖片層級，長邊最多 2,576 像素，每張圖片最多 4,784 個視覺 token。Claude Sonnet 4.6、Claude Sonnet 4.5 與 Claude Haiku 4.5 的上限為 1,568 像素與 1,568 個 token。一張 2000×1500 的圖片在 Claude Sonnet 5.5 上所需的 token 約為 2.5 倍。請參閱解析度與 token 成本。

從 Claude Sonnet 4.5 或更早版本遷移

若使用 Claude Sonnet 4.5、Claude Sonnet 4 或 Claude 3.7 Sonnet，請先套用前面的所有章節，再進行以下變更。

預填會傳回錯誤。 Claude Sonnet 5.5 會以 400 錯誤拒絕預填的最後一個助理回合，與 Claude Sonnet 4.6 和 Claude Sonnet 5 相同。Claude Sonnet 4.5、Claude Haiku 4.5 及更舊的模型則接受。錯誤內容如下：

This model does not support assistant message prefill. The conversation must end with a user message.

請依每個預填的用途加以取代：

• 輸出格式： 使用結構化輸出，或在分類時使用帶有列舉欄位的工具。
• 開場白： 在系統提示中要求直接回答。
• 不必要的拒絕： 在使用者訊息中提供清楚的指示通常就已足夠。
• 接續： 將其移至使用者訊息，例如「您先前的回應被中斷，結尾為 [previous_response]。請從中斷處繼續。」
• 上下文提醒： 將其放在使用者回合中。

工具輸入跳脫。 工具呼叫引數中的跳脫方式可能不同。請使用標準 JSON 解析器解析 input。

電腦使用。 Claude Sonnet 5.5 不接受 computer_20250124。請參閱部分電腦使用工具版本不受支援。

投入程度。 Claude Sonnet 4.5 沒有投入程度參數。請明確設定投入程度等級（請參閱建議變更）。

上下文與輸出。 Claude Sonnet 5.5 擁有更大的上下文視窗以及更高的輸出上限。請參閱 Claude Sonnet 5.5 模型頁面。請移除任何上下文視窗 beta 標頭。

Beta 標頭。 請移除 interleaved-thinking-2025-05-14，因為自適應思考會自動交錯進行。請以在每個需要的工具上設定 eager_input_streaming: true 取代 fine-grained-tool-streaming-2025-05-14。該標頭與電腦使用或瀏覽器使用工具集項目一同傳送時會傳回 400 錯誤。請參閱細粒度工具串流。

結構化輸出。 output_format 參數已棄用。若仍要使用，請加入 structured-outputs-2025-11-13 beta 標頭。若沒有此標頭，API 會傳回 400 錯誤。請改用 output_config.format。

從 Claude Sonnet 4 或更早版本遷移

Claude Sonnet 4 已在 Claude API 上停用，但可在 Claude Models on Google Cloud (Google managed) 與 Amazon Bedrock 上使用。Claude 3.7 Sonnet 已停用。無論從哪個模型遷移，請先套用前面的所有章節，再進行以下變更：

• 工具版本： 使用 text_editor_20250728，工具名稱為 str_replace_based_edit_tool，且沒有 undo_edit 命令。使用 code_execution_20260521。請參閱文字編輯器工具與程式碼執行工具。
• 停止原因： 處理 refusal。Claude 4.5 及更新的模型在達到上下文視窗上限時也會以 model_context_window_exceeded 停止。請參閱停止原因與備援。
• 結尾換行符號： Claude 4.5 及更新的模型會在工具呼叫字串參數中保留結尾換行符號。
• Beta 標頭： 移除 token-efficient-tools-2025-02-19 與 output-128k-2025-02-19。
• 提示： 依照提示撰寫最佳實務檢閱您的提示。

從 Claude Haiku 4.5 遷移至 Claude Sonnet 5.5

請先套用截至並包含從 Claude Sonnet 4.5 或更早版本遷移的所有章節，並略過 Claude Sonnet 4 子章節。接著進行以下變更：

• 模型 ID： 將 claude-haiku-4-5-20251001 或別名 claude-haiku-4-5 替換為 claude-sonnet-5-5。
• 成本： 每 token 價格較高，且相同的文字會產生更多 token。請重新計算 token 並重新建立成本基準。請參閱定價。
• 提示快取： 最小可快取提示從 4,096 個 token 降至 Claude Sonnet 5.5 的最小值。
• 交錯思考： 自適應思考會自動在工具呼叫之間執行。
• 路由： Claude Sonnet 5.5 可讀取 Claude Haiku 4.5 的思考區塊。向上移轉的對話會保留其推理。移回 Claude Haiku 4.5 的對話則會捨棄 Claude Sonnet 5.5 的區塊。