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 費率的一半。請參閱 Claude 定價。關於其上下文視窗與輸出限制，請參閱 Claude Sonnet 5.5 模型頁面。關於功能與提示撰寫，請參閱 Claude Sonnet 5.5 的新功能與為 Claude Sonnet 5.5 撰寫提示。

向 Claude Sonnet 5.5 傳送請求

此請求可直接在 Claude Sonnet 5.5 上運作。它設定了「effort level」（投入程度等級），而各 SDK 分頁會依區塊類型讀取回覆。它省略了五項會傳回 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 欄位的請求會以「adaptive 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 的平台上運作，無需 beta 標頭。它在 low、medium 與 high effort 下皆可接受。在 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 時，effort 無法在對話中途變更：與目前生效等級不同的逐訊息 output_config.effort 會傳回 400 錯誤。若要逐輪變更 effort，請使用自適應思考。關於提示撰寫指引，請參閱在不進行前置思考的情況下執行。

之前（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 effort 或以下發送最低的思考設定。
• 將強制工具使用替換為 auto 搭配 strict 工具，或在 Amazon Bedrock 上僅使用 auto。
• 保持對話為僅附加。
• 在 Claude API 和 Google Cloud 上，將電腦使用移至工具集，且不使用 fine-grained-tool-streaming-2025-05-14 beta 標頭。
• 將 advisor 工具與受支援的 advisor 搭配使用，並預期會收到加密的建議。
• 從 thinking 區塊讀取工具呼叫之間的文字。
• 處理拒絕，並設定備援。
• 重新執行您的 effort 掃描，並重新建立成本基準。

Claude Sonnet 4.6 或更早版本

• 預期未包含 thinking 欄位的請求會進行思考，並重新檢視 max_tokens。
• 以 effort 等級取代思考預算。
• 移除非預設的 temperature、top_p 和 top_k 值。
• 若您會顯示思考文字，請設定 display: "summarized"。
• 重新計算 token，並重新編列圖片 token 預算。

Claude Sonnet 4.5 或更早版本

• 取代助理「prefill」（預填）。
• 使用標準 JSON 剖析器剖析工具呼叫輸入。
• 在 Amazon Bedrock 上，將電腦使用從 computer_20250124 移至 computer_20251124。
• 明確設定 output_config.effort。
• 移除任何上下文視窗 beta 標頭。
• 移除 interleaved-thinking-2025-05-14，並以 eager_input_streaming 取代 fine-grained-tool-streaming-2025-05-14。
• 將 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 限制。在 Amazon Bedrock 上，Claude Sonnet 5.5 無法使用結構化輸出（包括嚴格工具使用）。在該平台上，請傳送不含 strict 的 auto，在提示中說明何時呼叫工具，並在您的程式碼中驗證工具輸入。

之前（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,
    # 嚴格工具使用：每次呼叫皆符合該工具的 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 與 Google Cloud 上也可讀取來自 Claude Haiku 5.5 的思考區塊。它無法讀取來自 Claude Opus 5、Claude Opus 5.5 或任何 Claude Fable 或 Claude Mythos 模型的區塊。API 會捨棄模型無法讀取的區塊。請求仍會傳回 200，且被捨棄的區塊不會計費。請參閱在對話中途切換模型。

每個 Claude Sonnet 5.5 思考區塊也會針對其之前的對話進行簽署。對於在 2026 年 8 月 31 日 00:00 UTC 當天或之後建立的帳戶，API 預設會在 Claude API、Amazon Bedrock 與 Google Cloud 上強制執行此規則。在這些帳戶上，於編輯較早歷史記錄後重播區塊的請求會傳回 400 錯誤。請保持對話為僅附加，並使用對話中途系統訊息變更指示或工具。Claude Sonnet 5.5 產生的思考區塊只能在產生它們的帳戶或與其連結的帳戶中使用。請參閱保留思考。

在 Claude API 和 Google Cloud 上，電腦使用需要工具集

在 Claude API 和 Google Cloud 上，Claude Sonnet 5.5 僅透過 computer_toolset_20260801 工具集支援電腦使用。在這些平台上，computer_20251124 會傳回 400 錯誤。Claude Sonnet 5.5 在任何平台上都不接受 computer_20250124。請找出您目前傳送的版本：

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

已傳送工具集的程式碼無需變更。從 computer_20251124 遷移列出了請求與代理迴圈的變更。其他平台請參閱相容性。

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

使用顧問工具時，Claude Sonnet 5.5 執行者需要下列其中一個顧問：Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5、Claude Fable 5.1、Claude Mythos 5 或 Claude Mythos 5.1。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 區塊之前呈現該 thinking 區塊。使用 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"，beta，僅限 Claude API）會在 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 個。請參閱提示快取。
• 新功能： 關於對話中途系統訊息、對話中途工具變更以及逐訊息 effort，請參閱 Claude Sonnet 5.5 的新功能。使用 between_tools 時，effort 無法在對話中途變更。

建議變更

重新執行您的 effort 掃描。Claude Sonnet 5.5 有五個 effort 等級：low、medium、high、xhigh 和 max。Claude API 上的預設值為 high。這些等級已重新校準，因此同一等級產生的思考量與 Claude Sonnet 5 上不同。除非您的工作負載屬於代理式或對延遲敏感，否則請從 high 開始。對於代理式程式設計和多步驟工具使用，定義明確的任務請從 medium 開始，較困難或較長的任務則改用 high。對於聊天和其他對延遲敏感的工作，請從 medium 或 low 開始。請在 output_config.effort 中設定等級。請參閱 Claude Sonnet 5.5 的建議 effort 等級。接著，請對照提示 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.

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

之前（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": "..."}],
)

取樣參數會傳回錯誤。 Claude Sonnet 4.6 及更早的模型以及 Claude Haiku 4.5 接受 temperature、top_p 和 top_k。在 Claude Sonnet 5.5 上，非預設值會傳回 400 錯誤。請將其移除。

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

其他變更

• token 約增加 30%： Claude Sonnet 5.5 使用 Claude Sonnet 5 的「tokenizer」（分詞器）。與 Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 相比，相同文字產生的 token 約多 30%，實際數量視內容而定。請使用 token 計數重新計算，並重新檢視 max_tokens 和成本。
• Effort： xhigh 為新增等級，且各等級已重新校準。請參閱建議變更。
• 圖片： Claude Sonnet 5.5 使用高解析度圖片層級，長邊最多 2576 像素，每張圖片最多 4,784 個視覺 token。Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 的上限為 1568 像素和 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.

請依每個預填的用途進行替換：

• 輸出格式： 使用結構化輸出，或在分類時使用帶有列舉欄位的工具。在 Amazon Bedrock 上，Claude Sonnet 5.5 無法使用結構化輸出。在該平台上，請在提示中描述格式或使用不含 strict 的工具，並在您的程式碼中驗證輸出。
• 開場白： 在系統提示中要求直接回答。
• 不必要的拒絕： 在使用者訊息中提供清楚的指示通常就已足夠。
• 接續： 將其移至使用者訊息，例如「Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.」
• 上下文提醒： 將其放在使用者回合中。

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

電腦使用。 Claude Sonnet 5.5 不接受 computer_20250124。請參閱電腦使用表格。

Effort。 Claude Sonnet 4.5 沒有 effort 參數。請依建議變更所述，明確設定 effort 等級。

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

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

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

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

Claude Sonnet 4 已在 Claude API 上停用，但仍可在 Amazon Bedrock 和 Google Cloud 上使用。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 並重新建立成本基準。請參閱 Claude 定價。
• 提示快取： 最小可快取提示從 4,096 個 token 降至 Claude Sonnet 5.5 的最小值。
• 交錯思考： 自適應思考會自動在工具呼叫之間執行，無需 beta 標頭。
• 路由： Claude Sonnet 5.5 可讀取 Claude Haiku 4.5 的思考區塊。向上移轉的對話會保留其推理。移回 Claude Haiku 4.5 的對話則會捨棄 Claude Sonnet 5.5 的區塊。