Claude Sonnet 5.5 開發指南:API 接入、遷移與調校
Building with Claude Sonnet 5.5
Anthropic 發佈 Claude Sonnet 5.5,較 Sonnet 5 快 30%,每 token 價格不變,多數工作成本最多可減 30%。指南詳述 API 用法、從 Sonnet 5 遷移時的行為變更及 effort 調校建議,並指出原生上下文窗口為 1M tokens。
指南整理 Sonnet 5.5 相對 Sonnet 5 的 API 變更與調校方法,涵蓋工具呼叫、thinking 區塊和 effort 設定,可作遷移核對參考。
Claude Sonnet 5.5 是 Claude 5.5 系列繼 Opus 5.5 之後推出的第二款模型。它明顯優於 Sonnet 5,智能程度更高、效率更好,速度快 30%。每個 token 的價格維持不變;由於 Sonnet 5.5 通常只需用少得多的 token 完成相同工作,大部分任務的成本最多可降低 30%。

感謝 @jkeatn 提供程式碼轉繪畫相關構思,以及 @IceSolst 提供參考圖片。
本指南介紹如何使用這個模型。要立即試用,請按原樣執行以下請求:
CODEPython
import anthropic 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"}, ) for block in response.content: if block.type == "text": print(block.text)
由於 Sonnet 5.5 預設會思考,迴圈會按類型讀取每個區塊,因此回應可能以 thinking 區塊開頭;讀取 content[0].text 的程式碼就會失效。
如何選擇 SONNET 5.5 或 OPUS 5.5
在 Claude 5.5 系列中,Opus 5.5 專為需要審慎判斷的複雜工作而設。Sonnet 5.5 則適合範圍明確的日常任務,例如修正錯誤和快速反覆改良功能。它也擅長製作精緻的文件、簡報和試算表,設計觸覺敏鋭。速度快亦令它非常適合快速反覆迭代。Claude Haiku 5.5 將於未來數週加入系列,支援大量、低延遲的工作流程。
| 你的工作負載 | 建議從以下模型開始 |
|---|---|
| 範圍明確的日常程式編寫:修正錯誤、快速反覆改良功能、按要求驗證 | Sonnet 5.5 |
| 大量日常開發工作 | Sonnet 5.5 |
| 製作精緻文件、簡報和試算表,例如單頁文件、圖表、摘要投影片、編輯文件和整理試算表;這些工作都受惠於良好的設計觸覺 | Sonnet 5.5 |
| 定義清晰、會重複執行的智能體任務:調查、審查、草擬 | Sonnet 5.5 |
| 需要審慎判斷的複雜工作,包括長期智能體程式編寫和知識工作 | Opus 5.5 |
| 最棘手的問題,需要最高智能水平 | Opus 5.5 |
「在 Epic 的早期測試中,Claude Sonnet 5.5 達到我們對更高階模型的品質要求,在系統設計審查和資料流程檢視中表現出色。新模型能處理數萬行程式碼,完成遊戲系統架構工作,同時維持快速回應、處理多小時任務,而且只需較少的指示。」(Daniel Vogel,Epic Games 營運總監)
Sonnet 5.5 最適合規格明確、而且有方法核驗結果的任務。正如提示指南所説:「面對最困難、需要長時間處理的工作,Opus 模型是更好的選擇。」
價格
| 每百萬 token | Sonnet 5.5 | Opus 5.5 |
|---|---|---|
| 輸入 | $2 | $4 |
| 輸出 | $10 | $20 |
| 快取寫入,5 分鐘 | $2.50 | $5 |
| 快取寫入,1 小時 | $4 | $8 |
| 快取讀取 | $0.20 | $0.20 |
Sonnet 5.5 的所有價格(包括批次處理和提示快取)均與 Sonnet 5 相同,因此只更換模型 ID 不會改變每個 token 的費用。僅限美國的推理(inference_geo: "us")收費為標準價格的 1.1 倍。
每個 token 的價格雖然不變,但整體帳單仍會不同,因為如前所述,Sonnet 5.5 每項任務通常使用比 Sonnet 5 少的 token。
請注意,不同平台可以為 Sonnet 預設不同的 effort 等級,例如 Claude Platform 預設為 high,而 Claude Code 預設為 medium。
Sonnet 5.5 使用高解像度影像級別,長邊最高可達 2576 像素;一張 2000×1500 影像所需 token 約為 Sonnet 4.6、Sonnet 4.5 或 Haiku 4.5 的 2.5 倍。如果不需要這些細節,請先縮小影像再傳送。
模型詳情
| 詳情 | Sonnet 5.5 |
|---|---|
| 模型 ID | Claude API、AWS 上的 Claude Platform、Google Cloud 和 Microsoft Foundry 使用 claude-sonnet-5-5;Amazon Bedrock 使用 anthropic.claude-sonnet-5-5 |
| 脈絡視窗 | 1M token,原生支援,無需 beta 標頭 |
| 輸出上限 | 128k token;使用 output-300k-2026-03-24 beta 標頭時,Message Batches API 最多可輸出 300k |
| 知識截止日期 | June 2026 |
| 思考模式 | 預設開啟(自適應思考);between_tools 可關閉預先思考 |
| Effort 等級 | low、medium、high、xhigh、max |
| 預設 effort | Claude API 預設為 high;Claude Code 預設為 medium |
| Tokenizer | 與 Sonnet 5 相同 |
| 可快取提示的最低長度 | 512 token(Sonnet 5 為 1,024) |
| 速率限制 | 與 Sonnet 5 分開設定,預設級別數值相同 |
| Priority Tier | Claude API 提供 |
| 資料保留 | 符合資格的客戶可使用零資料保留 |
Claude API 預設採用 high,讓你一開始便取得出色結果。先從這裏開始,評估後再按工作負載選擇所需的 effort 等級。如果你打算使用 xhigh 或 max effort,請留意 Sonnet 5.5 會思考更久,成本亦更高。部分任務可能因此失去 Sonnet 的優勢:品質、速度和成本之間的平衡。在這種情況下,可考慮使用 Opus 5.5。
從 SONNET 5 遷移
思考模式預設開啟。如果你在 Sonnet 5 關閉了思考模式,可以使用 between_tools 關閉預先思考。以下步驟 1 會示範做法。
把模型 ID 改為 claude-sonnet-5-5,然後處理五項破壞性變更及一項回應格式變更。Sonnet 5.5 遷移指南詳細説明每項變更。
Claude Code 亦可代你遷移。執行 /claude-api migrate this project to claude-sonnet-5-5,即可呼叫內置的 Claude API skill,在程式碼庫中更換模型 ID,並套用破壞性參數變更。
1. 使用 between_tools 關閉預先思考
Sonnet 5.5 的請求若沒有 thinking 欄位,便會使用自適應思考;若傳送 thinking: {"type": "disabled"},則會回傳 400 錯誤。請改為傳送新的 between_tools 設定。使用 between_tools 時,模型只會在工具呼叫之間思考,而且整體回應時間相同或更快。
CODEPython
# Before: Claude Sonnet 5 client.messages.create( model="claude-sonnet-5", max_tokens=16000, thinking={"type": "disabled"}, output_config={"effort": "xhigh"}, messages=[{"role": "user", "content": "..."}], ) # After: 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": "..."}], )
此示例亦把 effort 由 xhigh 降至 high,因為 between_tools 有以下限制:
between_tools可配合low、medium和higheffort 使用。使用xhigh或max時會回傳 400 錯誤;如要使用這些等級,請改用自適應思考。- 它不接受其他欄位。若一併傳送
display、budget_tokens或block_binding,便會回傳 400 錯誤。 - 使用
between_tools時,對話中途不能更改 effort。若要逐輪調整 effort,請使用自適應思考。 - 模型在工具呼叫之間撰寫的簡短進度更新,仍會以
thinking區塊及摘要文字傳回。請按類型讀取內容區塊,並把這些區塊與助理回合的其他內容一併原樣傳回。若沒有使用工具,回應就只會包含文字。 - 所有提供 Sonnet 5.5 的平台都支援這項功能,無需 beta 標頭。如果你的 SDK 版本未定義
between_tools,請更新 SDK。
如果你使用 between_tools 關閉預先思考,對於不使用工具但需要幾步推理的請求,請改用自適應思考。
2. 使用 auto 和 strict tools 取代強制 tool_choice
tool_choice 的 any 或 tool 類型會回傳 400 錯誤,連 token 計算端點也一樣。請傳送 auto,並將工具標記為 strict: true,確保輸入符合結構描述,同時在提示中説明何時應使用該工具:
CODEPython
weather_tool = { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"], "additionalProperties": False, }, "strict": True, } client.messages.create( model="claude-sonnet-5-5", max_tokens=1024, tools=[weather_tool], tool_choice={"type": "auto"}, # was {"type": "tool", "name": "get_weather"} messages=[ {"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."} ], )
嚴格工具使用要求每個物件都設定 additionalProperties: false。
3. 對話內容只可追加
Sonnet 5.5 的思考區塊與模型及對話綁定。Sonnet 5.5 能讀取 Sonnet 5 的思考區塊,因此由 Sonnet 5 切換至 Sonnet 5.5 時,對話會保留原有推理內容。其他模型都無法讀取 Sonnet 5.5 的思考區塊。
4. 把電腦操作功能改用 toolset
在 Claude API 和 Google Cloud 上,Sonnet 5.5 只透過 {"type": "computer_toolset_20260801"} 支援電腦操作;若請求宣告 computer_20251124,便會回傳 400 錯誤。請從請求移除 anthropic-beta: computer-use-2025-11-24 標頭;使用 SDK 時,亦要移除 betas 參數,改用標準用戶端呼叫 Messages API,而非 beta 命名空間。請替換 tools 項目,並更新智能體迴圈,以處理結果中的 tool_use 區塊成員、批次操作及 toolset_name。如果你有傳送 fine-grained-tool-streaming-2025-05-14 beta 標頭,也請一併移除,因為它與 toolset 項目同時使用會回傳 400 錯誤;需要這項功能的工具應各自設定 eager_input_streaming: true。Amazon Bedrock 仍接受 computer_20251124。
5. 檢查 advisor 配對是否相容
使用 advisor 工具時,以 Sonnet 5.5 執行的模型會拒絕 Opus 4.8、Opus 4.7 和 Sonnet 5 作為 advisor。可接受的 advisor 包括 Opus 5.5、Opus 5,以及 Sonnet 5.5 本身。所有可接受 advisor 提供的建議都會以加密形式,放在 advisor_redacted_result 區塊中傳回,因此你的程式碼無法讀取建議文字。
6. 從 thinking 區塊讀取工具呼叫之間的文字
這項變更不會造成錯誤,但使用者介面可能不再顯示模型在工具呼叫之間的備註。這些備註若長於一兩句,會以進度更新 thinking 區塊傳回;預設 display 設定會讓這些區塊保持空白。
使用自適應思考時,將 thinking.display 設為 "updates"(beta,需加上 thinking-display-updates-2026-08-18 標頭)或 "summarized",並顯示每個非空的 thinking 區塊,然後再顯示其後的 tool_use 區塊。使用 between_tools 時,文字傳回時不會帶有 display。
Sonnet 5.5 亦新增每則訊息的 effort(beta)、對話中途系統訊息,以及對話中途工具變更(beta)。如果你從 Sonnet 4.6 或更早版本,或 Haiku 4.5 遷移,遷移指南列有各起始模型的核對清單。
調校
重新執行 effort 測試
Effort 等級已重新校準,因此相同等級不再產生與 Sonnet 5 一樣多的思考,你以前的設定亦不會沿用。除非工作負載涉及智能體或對延遲敏感,否則請先使用 high。智能體程式編寫和多步驟工具使用方面,規格明確的任務可先用 medium,較困難或耗時較長的任務則改用 high。聊天及其他對延遲敏感的工作,可先用 medium 或 low。只有評估證明能提升品質時,才使用 xhigh 或 max。
思考過程會計入 max_tokens,因此要預留空間。智能體程式編寫可把 max_tokens 設為模型上限 128,000,並以串流方式接收回應。若想減少思考內容,請降低 effort 等級;在系統提示中要求模型少想一點,無法可靠地減少思考量。
移除 Sonnet 5 的權宜處理
現有 Sonnet 5 提示一般毋須修改便能良好運作。如果提示包含拒答引導、工具呼叫重試補丁或「不要偷懶」等權宜處理,請先移除並重新執行評估,再調校其他設定。
以 low effort 要求模型進行實際檢查
Sonnet 5.5 一般會在報告工作完成前檢查結果,但使用 low effort 時,有時會略過能驗證變更的檢查。如果模型報告已完成變更,卻沒有提供測試或建置輸出,提示指南建議在系統提示中加入以下段落:
CODEText
When you change code that can be run, built, or type-checked, run a real
check that exercises the change before reporting it done: the project's
tests, type-checker, or build, or the changed command itself. A syntax-only
check, or a check command that failed to start, does not count; if all
that is missing is the project's declared dependencies, install them with
its own package manager and lockfile (e.g. npm install, pip
install -r requirements.txt), never via sudo or the system package manager,
unless told not to. Only if no real check can run here, say which one you
did not run and why instead of reporting the change as done.使用 thinking.display 顯示進度
不要要求模型在回應中寫出推理過程,否則可能引發 reasoning_extraction 拒答。改為讀取摘要思考內容:
CODEPython
thinking={"type": "adaptive", "display": "summarized"}
若要單獨顯示面向使用者的進度備註,請使用 display: "updates"(beta)。如果你希望在可預測的時間點顯示進度,例如首次工具呼叫前一行,以及結尾的簡短回顧,請在系統提示中説明。
快取更多提示內容
可快取提示的最低長度降至 512 token,因此較短的系統提示和工具定義現在也符合資格。快取讀取費用是輸入價格的十分之一。在不同請求之間更改頂層 effort 會令快取失效;若只想讓某一輪使用不同等級,請使用每則訊息的 effort(beta),即可保留快取。
拒答及後備處理
在我們的自動化行為審查中,Sonnet 5.5 在大部分對齊和誠信指標上優於或媲美 Sonnet 5。它亦是首款配備與我們最強模型相若網絡安全防護的 Sonnet 模型。大部分日常軟件開發工作不受影響。
拒絕的請求會回傳 HTTP 200,並附有 stop_reason: "refusal";stop_details 會列出以下五種類別之一:cyber、bio、frontier_llm、reasoning_extraction 或 general_harms。伺服器端後備機制(fallbacks: "default",Claude API beta)會在 Sonnet 5 上重試 cyber 和 frontier_llm 類拒答,不會重試另外三種。你亦可使用 SDK 中介軟件或自行重試。
合法的網絡安全工作方面,Cyber Verification Program 即將擴展至支援 Sonnet 5.5。
供應情況
Claude Sonnet 5.5 今日已在以下平台推出。在開發者平台上,請使用以下模型 ID:
- Claude API 使用
claude-sonnet-5-5 - Amazon Bedrock 使用
anthropic.claude-sonnet-5-5 - AWS 上的 Claude Platform 使用
claude-sonnet-5-5 - Google Cloud 使用
claude-sonnet-5-5 - Microsoft Foundry 使用
claude-sonnet-5-5,僅限 Global Standard 部署
在 Claude Code 中
從 Claude Code v2.1.284(TypeScript Agent SDK v0.3.284 或更新版本)起,Claude API 上的 sonnet 別名會指向 Sonnet 5.5。它預設使用 medium effort,並原生支援 1M 脈絡視窗。在 Claude Code 中,你不能關閉 Sonnet 5.5 的思考模式;effort 會控制模型思考的程度。Sonnet 5.5 沒有快速模式。default 模型仍然是 Opus 5.5;範圍明確的任務可使用 /model sonnet 切換。
希望你喜歡試用 Sonnet 5.5,一如以往,歡迎分享意見。
來源:Anthropic:Claude.dev 開發者博客 · claude.dev