---
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="/docs/gemini-cli/official/05-models-runtime/53-local-model-routing" />
  <Card title="模型选择" description="回看 /model、--model、alias 和 subagent 模型边界。" href="/docs/gemini-cli/official/05-models-runtime/51-model-selection" />
  <Card title="Token caching" description="模型路由之外，还要看 token caching 和成本优化。" href="/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)
