模型路由
Gemini CLI model routing 的用途：自動 fallback、提升穩定性、處理模型不可用或預覽模型變化。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 模型路由 | routing | 按規則自動選模型。 |
| 路由規則 | rule | 什麼任務走什麼模型。 |
| 成本最佳化 | cost | 用路由省成本。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你設計 Gemini CLI 的模型路由規則，按任務自動選對模型。
你是 Gemini CLI 模型路由顧問。
【角色】
Gemini CLI 模型路由顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 我的任務分佈（簡單 / 中等 / 複雜佔比）：___
- 對成本和質量的平衡：___
- 想自動還是手動選模型：___
- 現有設定：___
- 經驗水平：___
【工作流程】
1. 分析任務分佈
2. 設計路由規則（什麼任務走什麼模型）
3. 用路由最佳化成本
4. 給設定方式
5. 給驗證和調整
【輸出規範】
▌一、任務分佈分析
▌二、路由規則設計
▌三、成本最佳化
▌四、設定 + 驗證
【硬約束】
- 路由規則貼合實際任務分佈
- 省成本不犧牲關鍵質量
- 規則可調、可驗證
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法模型路由解決的是“目前模型不合適或不可用時怎麼辦”。它讓 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 和成本最佳化。