Claude Opus 4.7 升級指南：轉模型前必查 7 個 workflow 風險

1. 第一個 breaking change：extended thinking 要改 adaptive thinking

唔好一開始就只改 prompt。先掃 API 設定。Anthropic 指，開發者可以透過 Claude API 使用 claude-opus-4-7；如果你嘅 app 係硬編 model ID，應該先放入小流量測試或 shadow eval。

更關鍵係 thinking 設定。Anthropic migration guide 明確寫到，Claude Opus 4.7 或之後唔再支援舊式 extended thinking 入面嘅 budget_tokens 設定，而且會回 400 error；遷移方向係改用 adaptive thinking。

實務上，先做三件事：

• 全文搜尋程式碼、SDK wrapper、prompt runner、內部平台設定入面嘅 budget_tokens。
• 移除舊式 extended thinking 設定，改用你所用 API 或 provider 支援嘅 adaptive thinking 設定。
• 唔好再將固定 thinking token budget 當成主要控制器；改用文件支援嘅 effort、task budget、prompt 約束同 eval 去校準任務深度。

Anthropic 嘅 prompting best practices 亦將 effort levels、task budgets、thinking configuration、sampling-parameter removal 同 tokenization，列為由 Opus 4.6 遷移到 Opus 4.7 時要留意嘅 API 變更。

2. Sampling 參數移除後，控制要搬返去 prompt 同 eval

如果舊 workflow 依賴 temperature、top_p 或 top_k 去控制創意度、穩定度、輸出差異，升級時就要重新設計。Anthropic prompting 文件將 sampling-parameter removal 列入 Opus 4.7 遷移注意事項；OpenRouter 嘅 Claude 4.7 migration guide 亦列出 sampling parameters removed、adaptive-only thinking 同 provider-specific effort 行為。

受影響嘅常見任務包括：

• 創意寫作、廣告文案：以前可能靠較高 sampling 產生更發散版本。
• 客服、合規、資料抽取：以前可能靠較低 sampling 追求穩定。
• 批次生成：以前可能用 sampling 參數控制多樣性。

升級後，比較穩陣嘅做法係將規則寫返入 prompt 同 eval：清楚定義語氣、格式、禁止事項同成功標準；用 few-shot 例子固定輸出風格；對抽取、分類、報告產生用結構化輸出要求；再將舊版 Claude 嘅 golden examples 變成 regression eval，逐題比較 Opus 4.7 嘅格式遵循、正確率、成本同延遲。

3. Tool use：將幾時查工具寫成明確 policy

如果舊 workflow 只係俾 Claude 一個寬鬆目標，等模型自己判斷幾時查工具，升級時最值得補強嘅就係 tool policy。Anthropic prompting best practices 指，Claude 最新模型受訓於精準跟指令，而且會受益於明確要求使用特定工具；同一份文件亦建議將 adaptive thinking 用於 multi-step tool use、complex coding tasks 同 long-horizon agent loops 等 agentic workload。

可以將以下規則直接寫入 system prompt 或工作流 policy：

• 涉及即時資訊、價格、政策、版本差異或外部文件時，必須先用指定查詢工具。
• 內部 knowledge base 冇答案時，必須講明無法確認，不可以估。
• 工具結果互相矛盾時，先列出衝突，再俾保守結論。
• 最終答案要分清楚邊啲資訊來自工具結果，邊啲係模型推論。

呢一步通常比單純換 model ID 更重要，因為 tool policy 會直接影響 agent 會唔會漏查資料、資料不足時會唔會亂估，以及工具結果衝突時會唔會過度自信。

4. 長任務 agent：成本要用 effort 同 task budget 去諗

Opus 4.7 其中一個遷移重點係長任務同 agentic workflow 嘅預算控制。Anthropic 文件指，Opus 4.7 introduces task budgets；官方文件亦講到，effort 參數可以喺能力、速度同 token spend 之間取捨，而 task budget 會俾 Claude 對整體任務可用 token 有概略估計。

如果你嘅 workflow 係 coding agent、research agent、browser agent、長時間資料處理或多工具 loop，建議將 budget 分成三層：

• 單次回覆 budget：最終輸出可以用幾多 token。
• 推理與工具 budget：多步驟任務入面，模型可以投入幾多 reasoning、tool calls 同 tool results。
• 任務級 budget：整段 agent loop 嘅成本同延遲上限。

唔好只用最終輸出上限去估整段 agent loop 成本。長任務成本可能來自多次工具查詢、工具結果回灌、圖片或 PDF 解析、重試同最終輸出；Opus 4.7 嘅 task budgets 同新 tokenizer，都令呢件事更需要重新 benchmark。

5. Token、RAG、cache 同 batch：全部要重跑 benchmark

呢個係最容易被低估嘅遷移位。Anthropic 文件指，Opus 4.7 新 tokenizer 處理文字時，可能會比前代模型使用約 1x 到 1.35x token；/v1/messages/count_tokens 對 Opus 4.7 回傳嘅 token count 亦會同 Opus 4.6 唔同，Anthropic 建議用呢個 endpoint 重新估算。

升級前應該重測：

• RAG chunk size 同 overlap。
• 長文件截斷門檻。
• conversation memory 長度。
• prompt caching 命中率同成本預估。
• batch job 成本上限。
• agent 每輪工具結果可以回灌幾大。
• 圖片同 PDF 預處理策略。

如果舊 workflow 已經貼近成本上限或 context limit，千祈唔好直接沿用舊版 token 估算。先用核心 prompt、長文件樣本同高流量任務跑 token benchmark，再決定要唔要調整 chunking、截斷或 cache key 設計。

6. 圖片、截圖同 PDF：前處理規則要重新定

Opus 4.7 文件提到 high-resolution image support；官方文件亦提醒，如果唔需要額外影像保真度，應該喺送入 Claude 之前先 downsample，以避免 token 使用增加。

呢點會影響三類 workflow：

• 截圖理解：例如 UI QA、表格截圖、dashboard 分析。
• 文件影像處理：例如掃描 PDF、合約截圖、簡報頁面。
• computer-use / browser automation：例如模型要理解畫面位置、按鈕、表單同錯誤訊息。

由 Opus 4.6 升上去時，PDF 同 vision 能力本身仍然係 Anthropic 列出嘅同一組主要平台能力；真正要重測嘅係送幾大張圖、係咪需要高解析度，以及 downsample 之後關鍵文字同 UI 元件仲認唔認到。

7. Provider 或內部 gateway：唔好假設參數映射一樣

如果你唔係直接打 Anthropic API，而係經 OpenRouter、雲端平台或內部 gateway 叫 Claude，就唔可以假設欄位名稱、忽略規則同 effort 行為完全相同。OpenRouter 嘅 Claude 4.7 migration guide 就單獨列出 sampling parameters removed、adaptive-only thinking 同 provider-specific effort 行為。

所以，除咗睇 Anthropic 文件，亦要睇你實際 provider 嘅 migration note。特別係多模型 router、fallback gateway、內部 prompt 平台，經常會將上游 API 參數包成自己嘅欄位；升級時要確認邊啲欄位仍然有效、邊啲會被忽略、邊啲會直接導致錯誤。

邊啲通常唔使大改？

如果你係由 Opus 4.6 升到 Opus 4.7，平台能力唔係成套翻新。Anthropic migration guide 表示，Opus 4.7 支援同 Opus 4.6 相同嘅主要功能集合，包括 1M token context window、128k max output tokens、adaptive thinking、prompt caching、batch processing、Files API、PDF support、vision，以及完整 server-side / client-side tools。

換句話講，第一優先通常唔係重寫以下基建：

• Files API 同文件上傳流程。
• PDF / vision 能力是否存在。
• prompt caching 或 batch processing 是否可用。
• 工具呼叫能力本身。
• 長 context 能力本身。

真正要重校嘅係你點控制呢啲能力：幾時用工具、花幾多 token、用幾高 effort、圖片送幾大，以及失敗時點 fallback。

實際遷移 checklist

可以將呢份清單交俾工程、AI platform owner 或負責 Claude workflow 嘅團隊，用嚟快速搵高風險位。

API 同參數

• 將模型名稱切換到 claude-opus-4-7，並先做小流量或 shadow eval；Anthropic 指開發者可透過 Claude API 使用呢個 model ID。
• 搜尋 thinking、budget_tokens 同舊式 extended thinking wrapper，改成 adaptive thinking；Opus 4.7 或之後唔支援舊設定，會回 400。
• 搜尋 temperature、top_p、top_k 等 sampling 控制，改用 prompt、few-shot、schema 同 eval 管理穩定性。
• 如果經 OpenRouter 或其他代理層使用 Claude，另查該 provider 嘅 Claude 4.7 migration guide 同參數映射。

Prompt 同 tool use

• 將幾時必須用工具寫入 system prompt；Anthropic 文件指最新 Claude 模型受益於明確 tool-use 指示。
• 寫清楚幾時唔可以估答案，以及資料不足時要點答。
• 寫清楚工具結果衝突、工具失敗、外部資料不足時嘅 fallback 行為。
• 對資料抽取、分類、報告產生等 workflow 加結構化輸出格式。

Agent 同 coding workflow

• 對 coding agent、research agent、browser agent 重新校準 effort 同任務預算；Anthropic 文件將 adaptive thinking 同 multi-step tool use、complex coding tasks、long-horizon agent loops 連埋一齊討論。
• 評估係咪使用 task budgets；Opus 4.7 文件列出 task budgets，亦提醒 token counting 會同前代唔同。
• 唔好只用最終輸出上限估整段 agent loop 成本；工具呼叫、工具結果、重試同最終輸出都要入成本模型。
• 用舊版 Claude 成功案例建立 regression eval，比較 Opus 4.7 嘅成功率、格式遵循、延遲同成本。

Token、文件同影像

• 用 /v1/messages/count_tokens 重新估算核心 prompt、RAG chunks、長文件同批次任務成本。
• 重測 chunk size、截斷門檻、conversation memory 同 prompt caching 策略。
• 對圖片、截圖同 PDF 頁面建立 downsample policy；唔需要高保真時先降低解析度，以控制 token 使用。

建議升級順序

最穩陣嘅做法唔係一次過全面替換，而係分四步：

1. 靜態掃描：搵出 model ID、thinking、sampling、token counting、image preprocessing 同 provider-specific 參數。
2. 小流量 eval：用現有 golden set 比較舊版 Claude 同 Opus 4.7 嘅輸出質素、格式遵循、tool use、成本同延遲。
3. 重寫高風險 prompt：優先處理 tool use、RAG、coding agent、資料抽取同合規任務。
4. 逐步放量：監控 token 使用、工具呼叫次數、錯誤率、延遲同人工回報。

一句講晒：由舊版 Claude 搬到 Opus 4.7，核心唔係將 prompt 全部推倒重寫，而係將舊 workflow 入面隱藏嘅控制邏輯顯性化。thinking 改 adaptive，sampling 改由 prompt 同 eval 控制，長任務改用 budget 思維，圖片同 token 成本重新 benchmark；咁樣升級風險最低，亦最容易保留舊 workflow 嘅可控性。