Google 於 November 2 宣布,gemini-2.5-pro 和 gemini-2.5-flash 已棄用,並將於 December 1, 2026 停用。重點不是日期,而是當天會發生什麼事:請求不會開始失敗,而是會改由另一個模型成功處理,並按該模型的費率計費。
這就是陷阱。服務突然報錯,很容易察覺。服務持續回傳答案,背後卻悄悄改用 gemini-3.8-flash 或 gemini-3.5-flash-lite,就不容易發現,尤其當你的日誌記錄的是你指定的模型,而不是實際作答的模型時。「沒有錯誤」不能證明一切都沒變。
因此,實際上必須在 December 1 之前完成:修改模型字串、調整參數,並針對重要的執行路徑進行迴歸測試。
淘汰公告實際上說了什麼
這兩個模型都已淘汰,無法再於 Google AI Studio 中選取。API 存取僅限過去曾實際使用過這些模型的既有使用者,因此不能直接用新的金鑰來使用它們進行比較測試。
淘汰公告頁面和版本說明都指出,自 December 1, 2026 起,所有使用舊名稱的 API 請求都會自動轉送至對應的替代模型,並依替代模型的費率計費。Google 建議在該日期之前更新模型字串。
這會帶來兩個結果。首先,舊名稱在期限過後仍可使用,也就少了一個通常會迫使使用者遷移的因素。其次,即使你沒有部署任何變更,成本和行為也都會改變。如果你的預算警示是以每次呼叫的固定成本為假設,警示就會失準。
這也會影響測試。由於已無法重新選取舊模型,新的金鑰或專案可能無法進行並排比較。如果你想建立前後比較的基準,就趁既有存取權限仍然有效時記錄下來,並儲存輸出結果,而不是憑記憶判斷舊模型的表現。
替代模型對應涉及等級變更
官方的對應關係很簡短:
gemini-2.5-pro會路由至gemini-3.8-flashgemini-2.5-flash會路由至gemini-3.5-flash-lite
仔細看這兩組對應。第一組從 Pro 等級模型轉向 Flash 等級模型。第二組從 Flash 模型轉向 Flash-Lite 模型。這些都不是同等替換,而且 3.8 系列的遷移指南記載了這次轉換伴隨的一系列 API 變更。
這對評估很重要。針對舊模型的指令遵循方式、拒絕行為或工具呼叫風格調整過的提示詞測試集,不見得能有效測試替代模型。請把這次替換視為需要建立新基準的模型變更,而不是單純的版本升級。
需要預先因應的重大變更
Gemini 3.8 遷移指南 列出了具體的 API 差異。其中有五項會影響實際整合。
思考設定改為列舉值。 thinking_budget 由字串列舉參數 thinking_level 取代。Gemini 3.8 Flash 不支援 minimal;有效選項為 low、medium(預設值)和 high。原本計算數值預算的程式碼,現在必須決定如何對應到這些選項,而這個決定是在品質與延遲之間取捨,不是單純換算。
取樣參數遭到移除。 API 不再接受 temperature、top_p 和 top_k。這項變更最可能在第一次請求時就直接觸發錯誤,而這些參數也最可能已經過數個月的調校。如果你的提示詞依賴低溫度來確保結果的確定性,現在這個控制手段已經消失,必須改靠嚴謹的提示詞與結構描述設計。
不支援 candidate_count。 這個參數在 Gemini 3 及後續版本都無法使用。原本會產生多個候選結果再挑選其一的工作流程,必須將這段選擇邏輯移到請求之外。
預填的模型回合遭到移除。 多輪對話應統一使用伺服器端的 previous_interaction_id。預填內容經常用來強制指定輸出格式;替代方式是結構描述或指令,而不是寫到一半的助理回合。
函式呼叫需要全面檢查。 指南特別指出幾項細節:將多模態素材放在回應酬載內、使用 \n\n 設定行內指令的格式、檢查與工具呼叫前文字相關的 Malformed_Function_Call 錯誤,以及在使用 generateContent API 時,確保每個 FunctionResponse 都包含 call_id 和 name。指南也提醒必須保留 thought_signature,而貿然升級 SDK 很容易破壞這一點。
簽章值得另外留意,因為它們失效時往往不會明顯報錯。模型就是靠簽章來驗證工具結果是否屬於自己發出的呼叫。如果 SDK 升級後漏掉簽章,或代理伺服器移除了不認得的欄位,請求仍可能成功,但工具呼叫迴圈卻出現異常行為。請把「我們升級了 SDK」視為一項變更,執行與更換模型同等程度的迴歸測試。
這些檢查很重要,因為失敗時很少會明確拋出例外。工具呼叫少了一個欄位,或簽章不再相符,仍然可能收到回應;只是回傳錯誤結果的頻率會比以前更高。
避免重工的五步驟順序
1. 找出所有模型字串。 搜尋設定檔、環境變數、SDK 用戶端的建立程式碼、作業定義、notebook,以及備援預設值。舊名稱通常不只出現在一個地方,而你漏掉的那個,往往就在每晚執行的作業裡。
2. 更改名稱,並在測試環境中執行。 盡可能不要在同一次部署中同時更改名稱與參數。你需要知道是哪項變更造成輸出差異。
3. 更改參數。 將 thinking_budget 換成 thinking_level,並審慎選擇 low、medium 或 high。移除 temperature、top_p、top_k 和 candidate_count。移除預先填入的模型回合,並將多輪對話狀態移至 previous_interaction_id。
4. 執行迴歸測試,而不是冒煙測試。 使用能代表實際流量的提示詞來比較輸出,特別留意函式呼叫與多輪對話流程。模型與提示詞變更的測試方法提供了正確的思路:固定評估輸入、記錄輸出,並檢視差異,而不是只用一個範例判定通過或失敗。
5. 上線後檢查計費與延遲。 新模型會依自己的費率計費,而思考等級的選擇會影響延遲。用量與成本追蹤指南涵蓋了監測機制的建置;這裡的重點是檢視新的基準,而不是假設舊的基準仍然適用。
無聲的失效模式:寫死的備援設定
這次遷移代價最高的情況,就是看起來已經完成。用戶端通常有備援邏輯:如果設定的模型無法使用,就改用寫死的預設模型。當舊名稱開始自動路由時,這套備援邏輯可能仍指向已退役的模型,但請求照樣成功。
結果就是,系統沒有回報任何錯誤,也正常處理流量,卻沒有執行你以為它正在執行的模型。如果日誌只記錄請求指定的模型,就看不出這個落差。
兩個習慣可以補上這個缺口。在每一層用 Grep 搜尋舊模型名稱,包括藏在用戶端包裝層裡的預設值。另外,遵循日誌記錄指南中的欄位記錄原則,記錄實際提供回應的模型,而不只是你請求指定的模型。同樣的記錄原則,也讓切換後的成本歸屬分析成為可能。
兩種停用方式,兩種失效模式
拿這個月稍早談過的 OpenAI 模型淘汰案例來比較,有助於理解差異。在那個案例中,對已退役模型發出的請求會失敗;錯誤會迫使使用者遷移,而且必須更改模型字串。替代模型對照表與確切的失敗行為,都整理在十月停用分析中。
Gemini 的做法正好相反:讓原本的名稱繼續可用,將請求導向接替模型,並按接替模型的費率計費。切換當下不會有任何功能故障。若有問題,也會出在行為與費用上,而且悄悄發生。
這兩種方式沒有哪一種天生比較好,但需要不同的監控方式。錯誤率儀表板能抓到第一種。只有模型身分記錄與輸出回歸測試能抓到第二種。
至於通用方法,包括如何盤點相依項目及分階段遷移,模型淘汰遷移指南涵蓋了不論供應商是誰都適用的部分。
檢查清單
- 搜尋整個程式碼庫與設定中的
gemini-2.5-pro和gemini-2.5-flash,包括備援預設值。 - 依工作負載決定替代模型:Pro 模型改用
gemini-3.8-flash,Flash 模型改用gemini-3.5-flash-lite。 - 將
thinking_budget替換為thinking_level,並選擇low、medium或high;Gemini 3.8 Flash 不可使用minimal。 - 從受影響的請求中移除
temperature、top_p、top_k和candidate_count。 - 移除預先填入的模型回合,並統一使用
previous_interaction_id管理多輪對話狀態。 - 稽核函式呼叫:回應酬載、
\n\n格式、Malformed_Function_Call,以及generateContent的每個FunctionResponse中的call_id與name。 - 在 December 1 前,使用實際提示詞執行回歸測試,並分別留意工具呼叫與多輪對話流程。
- 上線後,確認實際處理流量的模型,並重新建立成本與延遲的基準。
日期不是風險。真正的風險是,只因為沒有任何錯誤拋出,就以為遷移已經完成。
上述模型名稱與 API 行為依據 2026-11-03 查核的官方頁面;變更正式環境設定前,請先對照最新文件確認。