Gemini CLI 模型路由机制详解：健康监控、降级策略链与本地 Gemma 路由器

Gemini CLI 内置的模型路由（Model routing）功能会在主模型失败时自动切换到备用模型，并在实验性模式下允许用本地运行的 Gemma 模型来承担路由决策，从而降低托管模型的使用成本。本文基于 docs/cli/model-routing.md 展开，结合 packages/core/src/availability、packages/core/src/routing、packages/core/src/fallback 等目录下的源码，讲清路由的完整工作机制：从模型健康状态机、策略链（policy chain）、用户交互意图，到 --model / GEMINI_MODEL / settings.json 的模型选择优先级，以及本地 Gemma 路由器的配置细节。

整体机制：ModelAvailabilityService 驱动的三个步骤

官方文档（docs/cli/model-routing.md）说明，模型路由由 ModelAvailabilityService 统一管理：它持续监控模型健康状态，并依据预定义的策略将请求路由到当前可用的模型。整个降级流程分三步：

1. 模型失败（Model failure）：当前选中的模型因配额（quota）或服务端错误（server errors）等原因失败时，CLI 启动降级流程。
2. 用户同意（User consent）：根据失败类型和模型策略，CLI 可能提示用户切换到备用模型——默认情况下总是会提示。但内部工具调用（如 prompt completion 和分类任务）使用 gemini-2.5-flash-lite 的静默降级链，会依次回退到 gemini-2.5-flash 和 gemini-2.5-pro，全程不提示、也不改变用户配置的模型。
3. 模型切换（Model switch）：用户批准、或策略允许静默降级时，CLI 会在当前轮次或整个会话剩余时间内改用可用的备用模型。

源码实现：模型健康状态机

ModelAvailabilityService 的实现位于 modelAvailabilityService.ts。它用一个 Map<ModelId, HealthState> 记录每个模型的健康状态，状态机有两类状态：

• terminal（终态不可用）：原因为 quota（配额）或 capacity（容量）。其中 capacity 类型的标记带 30 秒 TTL（ttlMs = 30000），到期后自动清除并恢复可用；quota 则长期生效，直到会话重置或标记健康。
• sticky_retry（粘性重试）：对应 retry_once_per_turn 原因。该状态带 consumed 标志，防止同一轮次内对同一模型无限重试（见 modelAvailabilityService.ts#L85-L106 中 markRetryOncePerTurn 的防死循环注释）；每轮结束时 resetTurn() 会把 consumed 复位，允许下一轮再试一次。

对外提供的方法包括：

• markTerminal(modelId, reason)：标记模型为终态不可用；
• markHealthy(modelId)：清除状态，恢复可用；
• snapshot(modelId)：返回 { available, reason } 快照，供路由查询；
• selectFirstAvailable(modelIds)：按给定顺序遍历模型列表，返回第一个可用模型及被跳过模型的列表与原因——这正是降级链选择备用模型的核心入口；
• reset()：清空全部健康状态。

策略链：policy catalog 如何定义"往哪里降、要不要提示"

文档提到的"根据失败类型和模型策略决定是否提示"，落地在 policyCatalog.ts 中。每个策略（ModelPolicy）描述：模型 ID、是否 isLastResort（链上唯一兜底）、maxAttempts、actions（每类失败应对取 prompt 还是 silent）、stateTransitions（失败后转入 terminal 还是 sticky_retry）。关键设计有：

• 默认动作是 prompt：DEFAULT_ACTIONS 对 terminal / transient / not_found / unknown 四类失败全部取 prompt，这与文档"默认总是提示你"一致；SILENT_ACTIONS 则全为 silent。
• 默认降级链：getModelPolicyChain 在非 preview 模式下返回 [DEFAULT_GEMINI_MODEL → DEFAULT_GEMINI_FLASH_MODEL]，后者标记 isLastResort: true 且 maxAttempts: 10；auto 模式下还会套用 AUTO_ROUTING_OVERRIDES（maxAttempts: 3、transient 失败静默处理并转入 sticky_retry），见 policyCatalog.ts#L60-L132。
• 静默工具链：FLASH_LITE_CHAIN 定义 flash-lite → flash → pro 三级全部 silent 的策略链，通过 getFlashLitePolicyChain() 暴露给内部工具调用（prompt completion、分类等），对应文档中"不提示、不改配置模型"的行为。
• 链校验：validateModelPolicyChain 强制要求链非空、且恰好存在一个 isLastResort 模型。

降级处理器：从失败到用户意图

当一次模型调用失败时，fallback/handler.ts 中的 handleFallback 负责编排整个流程：

1. classifyFailureKind(error) 对错误分类（quota、capacity 等，见 errorClassification.ts）；
2. resolvePolicyChain + buildFallbackPolicyContext 找到失败模型的策略及其后的候选模型；
3. 用 availability.selectFirstAvailable(...) 在候选中选第一个可用模型；若无候选但原活动模型仍可用，则直接静默回到活动模型重试；
4. 按所选策略的动作分支：action === 'silent' 时直接执行 retry_always 意图、不弹任何提示（这就是内部工具静默降级的实现路径）；否则调用 config.getFallbackModelHandler() 弹出交互，用户可给出 retry_always（永久切换，并轮换会话 ID 以避免后端出现有状态切换错误，见 handler.ts#L157-L196）、retry_once（仅本轮）、retry_with_credits、stop、retry_later、upgrade（打开升级页面）等意图。

值得注意的细节：只有用户选择 retry_always 或 retry_once 时，才会把失败模型标记为不可用（applyAvailabilityTransition）；若用户选择 stop 或 retry_later，健康状态保持不变，便于之后重试同一模型。

模型选择优先级

文档给出 CLI 实际使用模型的判定顺序为（高到低）：

1. --model 命令行参数：启动时指定则始终优先；
2. GEMINI_MODEL 环境变量；
3. settings.json 中的 model.name；
4. 本地 Gemma 模型路由器（实验性）：启用后由本地 Gemma 而非托管 Gemini 模型做出模型选择；
5. 默认模型 auto。

该优先级在源码中有直接对应：packages/cli/src/config/config.ts 中模型解析即 argv.model || process.env['GEMINI_MODEL'] || settings.model?.name，默认回落到 GEMINI_MODEL_ALIAS_AUTO（config.ts#L842-L844）。cli-reference.md 也确认 --model（别名 -m）默认值为 auto。

此外，ModelRouterService（modelRouterService.ts）在每个请求上下文上运行一条 CompositeStrategy 决策链，顺序为：FallbackStrategy（基于可用性状态机的降级路由）→ OverrideStrategy（运行时覆盖）→ ApprovalModeStrategy → GemmaClassifierStrategy（仅当 gemmaModelRouter.enabled 为 true 时插入） → 通用 ClassifierStrategy → NumericalClassifierStrategy → 兜底的 DefaultStrategy。每次路由决策都会通过 ModelRoutingEvent 上报遥测（含来源、延迟、推理原因、是否异常），路由抛异常时会兜底返回配置模型并以 router-exception 标记记录，见 modelRouterService.ts#L39-L67。

本地模型路由（实验性）：用 Gemma 做路由决策

文档说明，Gemini CLI 支持在本地运行一个 Gemma 模型来做路由决策，替代把路由决策发给托管模型，目标是降低托管模型成本，同时保持相近的决策延迟与质量。最简单的启用方式是自动化的 gemini gemma setup 命令（实现见 packages/cli/src/commands/gemma/setup.ts，负责按平台下载 LiteRT-LM 运行时二进制、校验 SHA256、下载模型并启动服务）；手动配置流程则见 docs/core/local-model-routing.md。

手动要点摘要：

• 下载对应平台的 LiteRT-LM 运行时（Windows lit.windows_x86_64.exe、Linux lit.linux_x86_64、macOS lit.macos_arm64）；
• 用 lit pull gemma3-1b-gpu-custom 下载模型（约 968.6 MB，需接受 Gemma 服务条款）；
• 以 lit serve --port=9379 启动服务（端口可自定），随后向 http://localhost:9379/v1beta/models/gemma3-1b-gpu-custom:generateContent 发送一条提示验证服务可用。

settings.json 配置与字段说明

要在 settings.json 中显式启用本地 Gemma 路由：

{
  "experimental": {
    "gemmaModelRouter": {
      "enabled": true,
      "classifier": {
        "host": "http://localhost:9379",
        "model": "gemma3-1b-gpu-custom"
      }
    }
  }
}

字段	类型	必填	说明
enabled	boolean	是	必须为 true 才启用该功能
classifier	object	是	本地模型端点配置，包含 host 与 model 标识
classifier.host	string	是	本地模型服务 URL，形如 http://localhost:<port>，需用 LiteRT-LM 启动时指定的端口
classifier.model	string	是	用于路由决策的模型名，必须为 "gemma3-1b-gpu-custom"

注意：配置变更后需要重启 CLI 才能生效（来自官方文档）。

从源码看（packages/core/src/config/config.ts），该配置的默认值为：enabled: false、autoStartServer: true（CLI 可自动拉起本地服务）、classifier.host 默认 http://localhost:9379、classifier.model 默认 gemma3-1b-gpu-custom，见 config.ts#L1360-L1368。ModelRouterService 正是通过 getGemmaModelRouterSettings()?.enabled 判断是否把 GemmaClassifierStrategy 插入决策链，因此"本地模型路由"生效的前提是 enabled: true 且本地服务可达；本地客户端实现位于 localLiteRtLmClient.ts。

行为验证与延伸阅读

• 单元/集成测试：modelAvailabilityService.test.ts、policyCatalog.test.ts、fallbackIntegration.test.ts（验证"失败 → 提示/静默 → 切换"的完整链路）、autoRoutingFallback.integration.test.ts、modelRouterService.test.ts；
• 自动设置命令的手动替代方案：docs/core/local-model-routing.md；Gemma 自动配置指南：docs/core/gemma-setup.md；
• 配置项总览中的 GEMINI_MODEL 说明见 docs/reference/configuration.md，--model 取值说明见 docs/cli/cli-reference.md。

适用前提小结：主模型自动降级默认开启且默认会提示切换；静默降级仅适用于内部工具调用与 auto 模式下的 transient 失败；本地 Gemma 路由仍标注为实验性功能（experimental），要求本地可运行 LiteRT-LM 服务并固定使用 gemma3-1b-gpu-custom 模型。