---
title: "本地模型路由"
description: "Gemini CLI local model routing 的使用场景：本地模型、隐私、离线/半离线环境、性能和能力边界。"
verifiedAt: "2026-05-09"
---

本地模型路由是实验能力。它让 Gemini CLI 用本机运行的 Gemma 模型做 routing decision，而不是把这类决策交给 hosted model。它不是默认上手路径，更像成本、治理或实验场景里的高级配置。

> [!WARNING]
> 本地路由不等于完全本地运行 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。

## 验收方式

不要只看配置文件是否写好了。真正的验收顺序是：

1. 本地 runtime 能启动。
2. 本地模型 endpoint 能响应一个简单请求。
3. `settings.json` 指向正确 host 和 model。
4. Gemini CLI 重启后没有配置错误。
5. 路由行为符合预期，并且日志能解释最终选择。

## 边界

- 本地模型质量可能不如云端强模型。
- 工具调用和上下文能力要单独验证。
- 配置复杂度更高。
- 本地服务不可用时，模型选择问题会更难排查。
- 生产团队不要把实验功能作为唯一策略，除非已经能监控 routing 质量、失败率、本地服务稳定性和版本漂移。

上线前还要写清“关闭实验”的路径。读者应该知道删掉 `experimental.gemmaModelRouter` 或设为 disabled 后，CLI 会回到默认模型路由，而不是继续依赖本地服务。

## 和本地模型的区别

本页讲的是本地 router，不是把 Gemini CLI 全部换成本地 LLM。router 只参与“选哪个模型/路线”的判断，后续主对话仍可能调用云端 Gemini 模型，Web、MCP、Shell、文件工具也仍然按各自权限工作。

所以隐私表达要准确：本地 routing 可以减少部分 hosted routing 决策，但不能承诺“完全离线”“所有代码不出本机”。如果教程面向企业用户，这句话必须写清楚。

本地服务还会带来运维问题：端口占用、模型文件下载、GPU/CPU 差异、runtime 版本变化都会影响体验。普通课程默认不应要求读者先维护这些环境。

## 接下来去哪

<Cards>
  <Card title="Token caching" description="继续看认证方式、缓存节省和 /stats 验证。" href="/docs/gemini-cli/official/05-models-runtime/54-token-caching" />
  <Card title="模型路由" description="回看默认 routing、fallback 和最终模型排查。" href="/docs/gemini-cli/official/05-models-runtime/52-model-routing" />
  <Card title="Local development" description="本地 runtime 和开发环境要单独验证。" href="/docs/gemini-cli/official/07-integrations-automation/76-local-development" />
</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)
