企业官网建设流程全解析

Gemini CLI 中使用 Gemini 3 Pro 与 Gemini 3 Flash：模型选择、路由与配额回退实战指南

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

本篇基于 gemini-cli 官方文档 Gemini 3 Pro and Gemini 3 Flash on Gemini CLI 展开，系统讲解如何在 Gemini CLI 中升级启用 Gemini 3 系列模型、通过/model命令与-m标志完成选择、理解 Auto/Pro 路由类型的工作原理，以及触达配额上限和容量错误时的回退与重试机制。读完本文，你将能够独立完成 Gemini 3 的启用配置，并结合仓库源码理解其底层的模型解析、可用性判定与退避重试实现。

快速上手：升级并切换到 Gemini 3

要开始使用 Gemini 3（Pro 与 Flash），首先将 Gemini CLI 升级到最新版本：

npm install -g @google/gemini-cli@latest

如果你的版本在 0.21.1 及以上，只需两步即可启用：

1. 在 Gemini CLI 中运行/model。
2. 选择Auto (Gemini 3)。

此外，官方文档特别提示：Gemini 3.1 Pro Preview 正在灰度发布。你可以通过/model命令选择Manual来判断自己是否已有访问权限——如果能在下拉列表中看到gemini-3.1-pro-preview，说明你的账号已开通。若有访问权限，选择Auto (Gemini 3)时，3.1 模型也会被纳入模型路由；你也可以直接用-m标志启动该模型：

gemini -m gemini-3.1-pro-preview

从源码看，模型标识的定义集中在 packages/core/src/config/models.ts 中。例如PREVIEW_GEMINI_MODEL = 'gemini-3-pro-preview'、PREVIEW_GEMINI_3_1_MODEL = 'gemini-3.1-pro-preview'以及 Flash 系列的PREVIEW_GEMINI_FLASH_MODEL = 'gemini-3-flash-preview'（该常量在 3.5 Flash 灰度实验期间是模块级变量，可通过setFlashModels()动态调整）。这也印证了文档中“版本能力取决于后端与账号权限”的说法：模型可用集合由常量表VALID_GEMINI_MODELS统一约束。

/model命令的选项与生效方式

/model命令会打开一个选择对话框，当前仓库文档 Gemini CLI model selection 给出的完整选项表如下：

官方建议大多数用户选择Auto系列选项；只有在需要固定某个具体模型时才使用Manual。

两点实现细节值得注意：

• 变更作用范围：/model的修改会作用于当前及后续所有交互。此外，/model命令（以及--model标志）不会覆盖子代理（sub-agent）所使用的模型，因此即使指定了/model，模型用量报告中仍可能出现其他模型。
• 别名解析：在 resolveModel() 中，auto、pro、flash、flash-lite等别名会被解析为具体模型。例如pro在无预览权限时降级为gemini-2.5-pro；flash在 3.5 Flash 实验开启时解析为gemini-3-flash（对应SECONDARY_GEMINI_3_5_FLASH_MODEL），否则解析为gemini-3-flash-preview。此外，代码中定义了DEFAULT_THINKING_MODE = 8192的上限，注释说明其目的是“防止思考（thinking）失控循环”，从源码结构看，这是 Gemini 3 思考型模型在 CLI 侧的一个重要安全约束。

用量限额与自动回退

Gemini CLI 会在你触达 Gemini 3 Pro 的每日用量上限时明确告知。此时系统会提供三类选项：

• 切换到Gemini 2.5 Pro；
• 升级以获得更高限额（可参考订阅计划（Plans）页面对比档位）；
• 停止当前操作。

同时，系统还会告诉你用量限额的重置时间，即 Gemini 3 Pro 何时可以再次使用。类似地，当 Gemini 2.5 Pro 触达每日上限时，你会看到提示，引导回退到Gemini 2.5 Flash。

在源码层面，这类配额对话框由 ProQuotaDialog 组件实现，可以确认文档描述的选项与代码一致：

• 配额终止错误（isTerminalQuotaError）或模型不存在时，选项为“切换到回退模型 / 升级获得更高限额 / Stop”；其中Upgrade for higher limits仅当认证方式为 Google 登录（AuthType.LOGIN_WITH_GOOGLE）且非 Ultra 档位时才会出现（见组件第 82-90 行的条件判断）；
• 当失败模型与回退模型相同时，只保留Keep trying与Stop两个选项。

容量错误：过载、退避重试与人工决策

Gemini 3 Pro 在高峰期可能出现过载（overloaded）。此时 Gemini CLI 会询问你是继续尝试 Gemini 3 Pro 还是回退到 Gemini 2.5 Pro。

Keep trying（继续尝试）选项采用指数退避（exponential backoff）：系统繁忙时，CLI 会拉大每次重试之间的等待间隔。如果请求没有立即发生，请等待几分钟让请求处理完成。

仓库源码印证了这一机制：packages/core/src/utils/retry.ts 中的retryWithBackoff()函数默认初始延迟initialDelayMs: 5000（5 秒），并在重试过程中动态调整currentDelay。

另外，从 ModelAvailabilityService 的结构可以看出，CLI 会对每个模型维护健康状态（terminal或sticky_retry），失败原因分为quota（配额）与capacity（容量）两类。值得关注的实现细节是：capacity 类的 terminal 状态带有 30 秒 TTL（getHealth()中ttlMs = 30000），过期后自动清除——这意味着模型容量错误被视为短期状态，CLI 会在短暂标记后重新尝试该模型，与文档中“Keep trying 会持续重试”的行为相呼应。

模型选择与路由类型（Auto 与 Pro）

在使用 Gemini CLI 时，你可能希望控制请求如何在各模型之间路由。默认情况下，Gemini CLI 使用Auto路由。当你使用 Gemini 3 Pro 时，可以用 Auto 路由或 Pro 路由来管理用量限额：

• Auto 路由：先判断 prompt 属于复杂操作还是简单操作。简单 prompt 自动使用Gemini 2.5 Flash；复杂 prompt 若已启用 Gemini 3 Pro 则使用Gemini 3 Pro，否则使用Gemini 2.5 Pro。
• Pro 路由：如果希望任务一定由最强模型处理，通过/model选择Pro。Gemini CLI 会优先使用当前可用的最强模型，包括已启用的 Gemini 3 Pro。

关于模型失败后的整体路由（fallback）行为，仓库文档 Model routing 给出了更完整的说明，值得结合阅读：

1. 模型失败：当前选定的模型因配额或服务端错误失败时，CLI 启动回退流程；
2. 用户同意：根据失败类型与模型策略，CLI 可能提示你切换到回退模型（默认总是提示）。部分内部工具调用（如 prompt 补全、分类）使用gemini-2.5-flash-lite的静默回退链，会依次尝试gemini-2.5-flash与gemini-2.5-pro，不提示也不改变已配置模型；
3. 模型切换：经批准（或策略允许静默回退）后，CLI 会在当前轮次或整个会话内使用可用的回退模型。

从源码结构看，具体的路由策略由 packages/core/src/routing/strategies/ 目录下的一组策略实现：classifierStrategy（基于分类器判断复杂度，对应 Auto 路由的“简单/复杂”判定）、overrideStrategy、fallbackStrategy、approvalModeStrategy等，由modelRouterService.ts组合调度。文档中“Auto 路由先判断 prompt 复杂度”的描述，可以推断正是由分类器策略完成的。

在 Gemini Code Assist 中启用 Gemini 3

如果你使用的是Gemini Code Assist Standard 或 Enterprise，在 Gemini CLI 上启用 Gemini 3 Pro 需要配置发布渠道（release channels），分为两步：管理员启用 + 用户启用。

管理员操作

拥有Google Cloud Settings Admin权限的管理员需要：

• 打开 Gemini CLI for Code Assist 所使用的 Google Cloud 项目；
• 进入Admin for Gemini>Settings；
• 在Release channels for Gemini Code Assist in local IDEs中选择Preview；
• 点击Save changes。

用户操作

管理员启用Preview后等待 2～3 分钟，然后：

• 打开 Gemini CLI；
• 使用/settings命令；
• 将Preview Features设置为true。

重启 Gemini CLI 后，你就应该可以访问 Gemini 3 了。

模型选择的优先级顺序

当多个来源都指定了模型时，实际使用哪一个由 Model routing 文档 定义的优先级顺序决定：

1. --model命令行标志：启动时通过--model（或其短形式-m）指定的模型始终优先生效；
2. GEMINI_MODEL环境变量：未使用--model时，使用环境变量指定的模型；
3. settings.json中的model.name：以上都未设置时，使用配置文件中的model.name属性；
4. 本地模型路由（实验性）：若settings.json中启用了 Gemma 本地模型路由，CLI 会使用本地 Gemma 模型来做出路由决策，而非托管模型。该特性可通过自动化的gemini gemma setup命令配置，有助于降低托管模型调用成本；
5. 默认模型：以上均未设置时使用默认模型，默认为auto。

这也解释了文档开头的示例gemini -m gemini-3.1-pro-preview为何能直接启动 3.1 模型：命令行标志优先级最高，会覆盖其余所有配置来源。

小结与延伸阅读

• 启用 Gemini 3 的核心路径：升级到最新版 →/model→ 选择Auto (Gemini 3)；需要精确控制时用-m指定具体模型（如gemini-3.1-pro-preview）。
• 触达每日限额时按提示切换 2.5 系列或升级；容量错误时Keep trying走指数退避重试，也可以主动回退到 2.5 Pro。
• Code Assist 用户需管理员切换 Preview 发布渠道 + 用户侧将Preview Features置为true。
• 遇到问题时，建议在项目仓库的 issue 区先检索是否已有同类问题，没有匹配项时再新建 issue，或在讨论区（discussions）留言反馈。

可进一步深入阅读的相关文档与源码：

• Gemini CLI model selection（/model 命令）
• Model routing（回退路由与优先级）
• 模型常量与解析逻辑
• 配额/容量对话框实现
• 模型可用性服务
• 重试与指数退避工具

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli