本地模型路由
Gemini CLI local model routing 的使用场景：本地模型、隐私、离线/半离线环境、性能和能力边界。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| 本地模型 | local model | 在本地跑的模型。 |
| 路由 | routing | 本地和云端模型的分配。 |
| 隐私 | privacy | 本地模型的数据不出本机。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你规划 Gemini CLI 的本地模型路由（隐私、成本、能力权衡）。
你是 Gemini CLI 本地模型路由顾问。
【角色】
Gemini CLI 本地模型路由顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 为什么想用本地模型（隐私 / 成本 / 离线）：___
- 本地的算力情况：___
- 哪些任务想走本地：___
- 对质量的底线：___
- 经验水平：___
【工作流程】
1. 判断本地模型是否适合我的场景
2. 设计本地 vs 云端的路由
3. 说明隐私和能力权衡
4. 给配置方式
5. 给验证
【输出规范】
▌一、本地是否适合
▌二、本地 / 云端路由
▌三、隐私与能力权衡
▌四、配置 + 验证
【硬约束】
- 本地模型能力有限，按任务取舍
- 隐私敏感任务优先本地
- 不夸大本地模型能力
- 不要替我臆测情况或编造不存在的能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法本地模型路由是实验能力。它让 Gemini CLI 用本机运行的 Gemma 模型做 routing decision，而不是把这类决策交给 hosted model。它不是默认上手路径，更像成本、治理或实验场景里的高级配置。
本地路由不等于完全本地运行 Gemini CLI。它主要影响 routing decision，工具调用、主模型请求和外部服务边界仍要单独确认。
Firecrawl 搜到的 GitHub issue 和 discussion 也说明，通用本地模型 / OpenAI-compatible provider 支持仍不是普通官方主路径。教程不能把社区提案写成正式能力；本页只讨论官方文档里的 Gemma router 实验边界。
官方现在更推荐使用自动化的 gemini gemma setup。手动配置仍然存在，但主要适合需要理解底层运行方式，或自动 setup 无法满足环境要求的用户。
适合场景
- 想减少 hosted model routing 成本。
- 希望 routing decision 尽量在本机完成。
- 需要测试本地 Gemma router 的质量和延迟。
- 企业环境想把模型路由链路纳入本地监控。
不适合场景
- 第一次安装 Gemini CLI。
- 只想快速体验对话和工具调用。
- 不想维护本地 runtime。
- 没有明确的成本、隐私或路由控制诉求。
| 目标 | 本地路由是否合适 | 说明 |
|---|---|---|
| 快速上手 | 不合适 | 增加 runtime 维护成本 |
| 降低 routing 成本 | 可能合适 | 仍要衡量本地延迟 |
| 完全离线 coding agent | 不足够 | 主模型和工具链仍可能联网 |
| 企业可观测 | 可能合适 | 需要记录 routing 质量和失败率 |
| 普通教程默认配置 | 不合适 | 读者环境差异太大 |
配置思路
本地 router 的前提是：本机有一个通过 HTTP endpoint 暴露的 Gemma 模型服务。官方手动文档以 LiteRT-LM runtime 为例：下载 runtime，接受 Gemma 模型条款，启动本地服务，然后在 settings.json 里启用 experimental.gemmaModelRouter。
最小配置包含三个信息：
enabled: true：显式启用。classifier.host：本地服务地址，例如http://localhost:9379。classifier.model：本地服务实际暴露的模型名，例如gemma3-1b-gpu-custom。
配置改完后需要重启 Gemini CLI。
验收方式
不要只看配置文件是否写好了。真正的验收顺序是：
- 本地 runtime 能启动。
- 本地模型 endpoint 能响应一个简单请求。
settings.json指向正确 host 和 model。- Gemini CLI 重启后没有配置错误。
- 路由行为符合预期，并且日志能解释最终选择。
边界
- 本地模型质量可能不如云端强模型。
- 工具调用和上下文能力要单独验证。
- 配置复杂度更高。
- 本地服务不可用时，模型选择问题会更难排查。
- 生产团队不要把实验功能作为唯一策略，除非已经能监控 routing 质量、失败率、本地服务稳定性和版本漂移。
上线前还要写清“关闭实验”的路径。读者应该知道删掉 experimental.gemmaModelRouter 或设为 disabled 后，CLI 会回到默认模型路由，而不是继续依赖本地服务。
和本地模型的区别
本页讲的是本地 router，不是把 Gemini CLI 全部换成本地 LLM。router 只参与“选哪个模型/路线”的判断，后续主对话仍可能调用云端 Gemini 模型，Web、MCP、Shell、文件工具也仍然按各自权限工作。
所以隐私表达要准确：本地 routing 可以减少部分 hosted routing 决策，但不能承诺“完全离线”“所有代码不出本机”。如果教程面向企业用户，这句话必须写清楚。
本地服务还会带来运维问题：端口占用、模型文件下载、GPU/CPU 差异、runtime 版本变化都会影响体验。普通课程默认不应要求读者先维护这些环境。
接下来去哪
Token caching
继续看认证方式、缓存节省和 /stats 验证。
模型路由
回看默认 routing、fallback 和最终模型排查。
Local development
本地 runtime 和开发环境要单独验证。