---
title: "模型路由"
description: "Gemini CLI model routing 的用途：自動 fallback、提升穩定性、處理模型不可用或預覽模型變化。"
verifiedAt: "2026-05-09"
---

模型路由解決的是“當前模型不合適或不可用時怎麼辦”。它讓 Gemini CLI 在不同模型之間做更穩定的選擇或回退。

> [!IMPORTANT]
> Fallback 是可用性機制，不是質量保證。模型切換後仍要看 diff、測試和最終使用模型。

官方文件裡的關鍵點是：Gemini CLI 預設啟用模型路由，並由 `ModelAvailabilityService` 監控模型可用性。當主模型因為配額、服務端錯誤或模型不可用失敗時，CLI 會進入 fallback 流程。

## 工作機制

模型路由不是簡單地“隨機換模型”，而是按策略處理失敗：

1. 當前模型請求失敗。
2. Gemini CLI 根據模型策略判斷是否需要 fallback。
3. 預設情況下，CLI 會提示使用者是否切換到 fallback model。
4. 使用者同意後，fallback model 會用於當前 turn 或本 session 後續請求，具體取決於策略。

部分內部工具呼叫也可能使用靜默 fallback chain，例如 prompt completion 和 classification。這類 fallback 不會改變你顯式配置的主模型，所以排查時要區分“內部工具 fallback”和“當前對話主模型切換”。

## 適合場景

- preview 模型不穩定。
- 當前模型達到限制。
- 某些任務需要更強推理。
- 自動化任務需要減少中斷。

## 模型選擇優先順序

實際使用哪個模型，按這個順序決定：

1. 啟動引數 `--model`。
2. 環境變數 `GEMINI_MODEL`。
3. `settings.json` 裡的 `model.name`。
4. 實驗性的本地 Gemma model router。
5. 預設模型 `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 是三條不同線。

## 記錄模板

生產自動化裡建議把每次任務的模型資訊寫進日誌：

```text
cli_version:
auth_type:
requested_model:
actual_models:
fallback_happened:
fallback_reason:
task_result:
verification:
```

這個模板能幫助你區分質量問題和可用性問題。如果失敗發生在 fallback 之後，後續復現必須使用同樣的實際模型，而不是隻看啟動命令。

## 接下來去哪

<Cards>
  <Card title="本地模型路由" description="繼續看本地 Gemma / local routing 的適用邊界。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/53-local-model-routing" />
  <Card title="模型選擇" description="回看 /model、--model、alias 和 subagent 模型邊界。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/51-model-selection" />
  <Card title="Token caching" description="模型路由之外，還要看 token caching 和成本最佳化。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/54-token-caching" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
