模型路由
Gemini CLI model routing 的用途：自動 fallback、提升穩定性、處理模型不可用或預覽模型變化。
模型路由解決的是“當前模型不合適或不可用時怎麼辦”。它讓 Gemini CLI 在不同模型之間做更穩定的選擇或回退。
Fallback 是可用性機制，不是質量保證。模型切換後仍要看 diff、測試和最終使用模型。
官方文件裡的關鍵點是：Gemini CLI 預設啟用模型路由，並由 ModelAvailabilityService 監控模型可用性。當主模型因為配額、服務端錯誤或模型不可用失敗時，CLI 會進入 fallback 流程。
工作機制
模型路由不是簡單地“隨機換模型”，而是按策略處理失敗：
- 當前模型請求失敗。
- Gemini CLI 根據模型策略判斷是否需要 fallback。
- 預設情況下，CLI 會提示使用者是否切換到 fallback model。
- 使用者同意後，fallback model 會用於當前 turn 或本 session 後續請求，具體取決於策略。
部分內部工具呼叫也可能使用靜默 fallback chain，例如 prompt completion 和 classification。這類 fallback 不會改變你顯式配置的主模型，所以排查時要區分“內部工具 fallback”和“當前對話主模型切換”。
適合場景
- preview 模型不穩定。
- 當前模型達到限制。
- 某些任務需要更強推理。
- 自動化任務需要減少中斷。
模型選擇優先順序
實際使用哪個模型，按這個順序決定：
- 啟動引數
--model。 - 環境變數
GEMINI_MODEL。 settings.json裡的model.name。- 實驗性的本地 Gemma model router。
- 預設模型
auto。
這意味著你排查“為什麼它沒用我想要的模型”時，先看啟動命令，再看環境變數，最後才看專案配置。
使用邊界
模型路由不是讓你忽略成本。團隊環境要明確預設模型、回退模型、預算和日誌。
不要把 fallback 當成質量保證。複雜程式碼改動仍然依賴清晰上下文、可執行驗證和人工 review。模型切換隻能提高可用性，不能替代工程驗收。
Auto routing 也不是黑盒魔法。官方 Gemini 3 文件把任務分成簡單和複雜兩類：簡單任務可能走 Flash，複雜任務在 Gemini 3 可用時優先 Pro，否則回落到 2.5 Pro。教程裡要把這個邏輯寫成“可能路由”，不要承諾某條 prompt 一定走某個模型。
| 現象 | 優先檢查 |
|---|---|
| 自動換到低成本模型 | 當前任務複雜度、Auto routing、配額 |
| 頻繁 fallback | 賬號限制、地區、服務狀態、模型預覽狀態 |
| Usage report 出現其他模型 | subagent、內部工具、fallback chain |
| 自動化結果不穩定 | 最終模型是否記錄、prompt 是否固定 |
| 手動指定無效 | 啟動引數、環境變數、settings 覆蓋順序 |
排查清單
- 用
gemini --version確認 CLI 版本。 - 檢查啟動命令裡是否傳了
--model。 - 檢查 shell 裡是否設定了
GEMINI_MODEL。 - 檢查
settings.json是否配置model.name。 - 如果 fallback 頻繁發生，優先確認配額、地區、賬號型別和當前模型狀態。
- 自動化場景要記錄最終使用模型，避免不同任務結果不可追溯。
如果你顯式傳了 --model，但看到實際輸出仍有其他模型，優先檢查 subagent 和內部工具，而不是馬上判斷配置失效。主會話模型、subagent 模型和內部 fallback 是三條不同線。
記錄模板
生產自動化裡建議把每次任務的模型資訊寫進日誌：
cli_version:
auth_type:
requested_model:
actual_models:
fallback_happened:
fallback_reason:
task_result:
verification:這個模板能幫助你區分質量問題和可用性問題。如果失敗發生在 fallback 之後，後續復現必須使用同樣的實際模型，而不是隻看啟動命令。
接下來去哪
本地模型路由
繼續看本地 Gemma / local routing 的適用邊界。
模型選擇
回看 /model、--model、alias 和 subagent 模型邊界。
Token caching
模型路由之外，還要看 token caching 和成本最佳化。