首页
/ Gemini CLI 本地模型路由实战:用本地 Gemma 模型驱动路由决策的完整配置与源码解析

Gemini CLI 本地模型路由实战:用本地 Gemma 模型驱动路由决策的完整配置与源码解析

2026-09-04 16:10:34作者：尤辰城Agatha
gemini-cli
An open-source AI agent that brings the power of Gemini directly into your terminal.
项目地址：https://gitcode.com/GitHub_Trending/gemi/gemini-cli

本篇技术指南基于 手动本地模型路由设置文档 展开,讲解如何在 Gemini CLI 中配置本地运行的 Gemma 模型(通过 LiteRT-LM 运行时以 HTTP 端点提供服务)来替代云端模型完成路由决策。读完本文,你将能够独立完成 Windows / Linux / macOS 三大平台的手动部署(下载运行时、拉取模型、启动服务、验证推理),正确编写 settings.json 中的 experimental.gemmaModelRouter 配置,并从源码层面理解路由策略链、Gemma 分类器的判定逻辑以及失败回退机制。

[!NOTE] 本地模型路由是一个实验性功能,仍在积极开发中。Gemini CLI 目前已提供全自动设置命令 gemini gemma setup(参见 gemini gemma 自动化设置指南),官方建议优先使用自动化方案,仅在自动化命令不可用(如严格的企业防火墙环境)时才按本文的手动步骤操作。

功能价值:为什么用本地模型做路由

Gemini CLI 内置模型路由机制:每次用户请求发出前,CLI 会先做一次"路由决策",判断该请求应该交给哪个 Gemini 模型处理。默认情况下,路由决策本身也要调用托管(云端)模型,这会产生额外的 API 开销。

本地模型路由的功能是:用一个运行在本机上的 Gemma 3 1B 模型来完成这个路由/分类决策,而不再把分类请求发送到托管模型。其价值在于:

  • 降低托管模型的使用成本:分类是高频操作,用本地推理替代云端调用可显著减少托管模型的 token 消耗;
  • 路由决策的延迟和质量相近:本地 Gemma 只承担"简单/复杂"二分类的轻量任务,决策延迟可接受,分类质量与云端分类器相当;
  • 自动回退保障:当本地服务不可用时,CLI 会静默回退到云端分类器,不报错、不中断会话。

按照 模型路由文档 中的模型选择优先级,本地 Gemma 路由器启用后,CLI 会使用本地 Gemma 模型(而非 Gemini 模型)来把请求路由到合适的模型。

手动设置总览

使用 Gemma 模型做路由决策有一个前提:你必须在机器上运行一个 Gemma 模型实现,该模型需要通过 HTTP 端点提供服务,并且以 Gemini API 的协议被访问(这正是 LiteRT-LM 运行时的作用——它把本地 Gemma 模型包装成 Gemini API 兼容的服务)。整体流程分为四步:

  1. 下载 LiteRT-LM 运行时二进制;
  2. 通过运行时下载 Gemma 模型(需同意 Gemma 使用条款);
  3. 启动 LiteRT-LM 运行时(本文以端口 9379 为例);
  4. 在 settings.json 中显式启用本地路由配置。

第 1 步:下载 LiteRT-LM 运行时

LiteRT-LM 运行时提供用于本地托管模型的预构建二进制。请下载与你系统对应的二进制(版本号 v0.9.0-alpha03,具体下载地址与文件清单见原始文档 docs/core/local-model-routing.md)。

Windows

  1. 下载 lit.windows_x86_64.exe 运行时二进制;
  2. Windows 上启用 GPU 需要 DirectXShaderCompiler:从 dxc 的最新 release 包中解压,从与你的架构匹配的 bin\ 目录中,把 dxil.dll 和 dxcompiler.dll 复制到 lit.windows_x86_64.exe 所在的目录;
  3. (可选)测试启动运行时:.\lit.windows_x86_64.exe serve --verbose

Linux

# 1. 下载 lit.linux_x86_64 后,确保二进制可执行:
chmod a+x lit.linux_x86_64

# 2. (可选)测试启动运行时:
./lit.linux_x86_64 serve --verbose

macOS

# 1. 下载 lit-macos-arm64 后,确保二进制可执行:
chmod a+x lit.macos_arm64

# 2. (可选)测试启动运行时:
./lit.macos_arm64 serve --verbose

注意:macOS 可能被配置为只允许运行"App Store 与已知开发者"的二进制。如果你在运行二进制时遇到错误提示,需要手动放行该应用:一种方式是通过 系统设置 -> 隐私与安全性,滚动到"安全性"区域,为 lit.macos_arm64 点击"仍要打开";另一种方式是在命令行执行 xattr -d com.apple.quarantine lit.macos_arm64 移除隔离属性。

第 2 步:下载 Gemma 模型

在使用 Gemma 之前,你需要先下载模型(并且同意 Gemma 使用条款与禁止使用政策)。这一步可以直接通过 LiteRT-LM 运行时完成,模型名称为 gemma3-1b-gpu-custom,下载量约 968.6 MB。

以下以 Linux 为例(Windows 使用 .\lit.windows_x86_64.exe,macOS 使用 ./lit.macos_arm64,命令形式相同):

$ ./lit.linux_x86_64 pull gemma3-1b-gpu-custom

[Legal] The model you are about to download is governed by
the Gemma Terms of Use and Prohibited Use Policy. Please review these terms and ensure you agree before continuing.

Do you accept these terms? (Y/N): Y

Terms accepted.
Downloading model 'gemma3-1b-gpu-custom' ...
Downloading... 968.6 MB
Download complete.

交互式提示会显示条款信息并要求你输入 Y 确认接受,之后才开始实际下载。

第 3 步:启动 LiteRT-LM 运行时

使用与你的系统对应的命令启动运行时,并配置你希望 Gemma 模型使用的端口。本文统一使用端口 9379,后续配置需与之保持一致:

# macOS 示例(Linux 换成 ./lit.linux_x86_64,Windows 换成 .\lit.windows_x86_64.exe)
./lit.macos_arm64 serve --port=9379 --verbose

(可选)第 4 步:验证模型服务

向本地端点发送一个快速 prompt,验证模型服务是否正常工作。这次请求会触发运行时加载模型并实际运行一次,服务输出中出现一个短笑话即表示成功。

Linux / macOS(curl)

$ curl "http://localhost:9379/v1beta/models/gemma3-1b-gpu-custom:generateContent" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"contents":[{"role":"user","parts":[{"text":"Tell me a joke."}]}]}'

Windows(PowerShell)

# 在 PowerShell 中发送请求
$uri = "http://localhost:9379/v1beta/models/gemma3-1b-gpu-custom:generateContent"
$body = @{contents = @( @{
  role = "user"
  parts = @( @{ text = "Tell me a joke." } )
})} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri $uri -Method Post -Body $body -ContentType "application/json"

注意请求路径的格式:/v1beta/models/<模型名>:generateContent —— 这正是 Gemini API 的 generateContent 协议,与下文源码中客户端所使用的 apiVersion: 'v1beta' 完全对应。

配置 settings.json

要在路由中使用本地 Gemma 模型,必须在 settings.json 中显式启用:

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

host 请使用你在启动 LiteRT-LM 运行时时所配置的端口。

注意:修改配置后必须重启 CLI,本地模型路由才会生效。

配置项 Schema 说明

文档给出的最小配置如下表:

字段 类型 必填 说明
enabled boolean 是 必须为 true 才能启用该功能。
classifier object 是 本地模型端点的配置,包含 host 与 model 两个指定项。
classifier.host string 是 本地模型服务的 URL,应为 http://localhost:<port>。
classifier.model string 是 用于决策的模型名,目前必须是 "gemma3-1b-gpu-custom"。

结合 settingsSchema.ts 中的实际 schema 定义,还可以补充以下文档未列出的细节与额外字段,使配置说明更完整:

字段 类型 默认值 说明
enabled boolean false 启用 Gemma 模型路由器;需要本地端点通过 LiteRT-LM shim 以 Gemini API 形式提供 Gemma 服务。
autoStartServer boolean false CLI 启动且 Gemma 路由器启用时,自动拉起 LiteRT-LM 服务器。
binaryPath string '' 自定义 LiteRT-LM 二进制路径;留空则使用默认位置 ~/.gemini/bin/litert/。
classifier.host string http://localhost:9379 分类器服务的 host。
classifier.model string gemma3-1b-gpu-custom 分类器使用的模型,目前仅在该模型上经过测试验证。

schema 中每个字段都标记了 requiresRestart: true,这从定义层面印证了文档中"修改配置后需重启"的要求。完整的 JSON Schema 也同步生成在 settings.schema.json 中,可供编辑器和校验工具使用。

源码级原理剖析:Gemma 路由器到底如何工作

光会配置还不够,理解底层调用链有助于排障和判断行为边界。以下分析基于当前仓库的实际实现。

1. 路由决策的策略链:Gemma 分类器只是链上的一环

路由决策统一由 ModelRouterService 负责。从源码结构看,它采用**责任链(组合策略)**模式,按固定顺序依次尝试各个 RoutingStrategy,第一个给出有效决策(非 null)的策略获胜:

FallbackStrategy → OverrideStrategy → ApprovalModeStrategy
→ GemmaClassifierStrategy(仅当 enabled 时注入)
→ ClassifierStrategy → NumericalClassifierStrategy → DefaultStrategy(终结策略)

关键逻辑在 initializeDefaultStrategy() 中:GemmaClassifierStrategy 只有在 config.getGemmaModelRouterSettings()?.enabled 为真时才会被加入策略链。也就是说,enabled: false 时本地路由器完全不参与决策,请求会落到后面的云端通用分类器等策略上。

此外,route() 方法在每次决策后都会记录一条 ModelRoutingEvent 遥测事件(包含所选模型、决策来源、延迟、推理说明等),失败时也会以 router-exception 来源记录——这意味着你可以通过遥测日志观察本地路由是否真的生效。

2. GemmaClassifierStrategy:本地分类的具体判定逻辑

GemmaClassifierStrategy 是本地路由的核心实现,几个值得注意的实现细节:

  • 模型白名单校验:策略在执行前会检查 classifier.model 是否等于 gemma3-1b-gpu-custom,否则直接抛出 Only gemma3-1b-gpu-custom has been tested 错误。这与文档中"model 必须是 gemma3-1b-gpu-custom"的硬性要求对应,是源码层面的强制约束。
  • 历史窗口与清洗:分类请求会携带最近 HISTORY_SEARCH_WINDOW = 20 轮历史,先过滤掉工具调用/工具响应(function call / function response)轮次,再取最后 HISTORY_TURNS_FOR_CONTEXT = 4 轮干净历史,拼上当前请求构成分类上下文。
  • 分类准则(Rubric):内置系统提示词把任务划分为 COMPLEX(选 pro)与 SIMPLE(选 flash)两类,判定依据包括:高操作复杂度(估计 4+ 步骤/工具调用)、战略规划与概念设计、高歧义或大范围调查、深度调试与根因分析;而高度具体、范围有限、只需 1–3 次工具调用的任务判为 SIMPLE。
  • 结构化输出:要求模型只输出 JSON {"reasoning": ..., "model_choice": "flash" | "pro"},并用 Zod schema(ClassifierResponseSchema)做严格解析。
  • 别名到真实模型的解析:拿到 flash/pro 结果后,通过 resolveClassifierModel 把别名映射为当前可用的具体 Gemini 模型(会综合 --model 指定、preview 访问权限、Gemini 3.x 发布状态等因素),而不是写死某个具体模型 ID。
  • 静默降级:如果分类器因任何原因失败(本地服务 API 错误、JSON 解析失败等),策略会记录警告并返回 null,让组合策略链继续走后面的云端分类器——这正是文档所述"本地服务宕机时 CLI 静默回退到云端分类器,不报错、不中断"的源码出处。

3. LocalLiteRtLmClient:以 Gemini API 客户端访问本地端点

LocalLiteRtLmClient 展示了"本地模型 + 托管 API 协议"这一组合的具体实现:

  • 它直接复用 @google/genai SDK 的 GoogleGenAI 客户端,通过 httpOptions.baseUrl 把请求指向你配置的 classifier.host(例如 http://localhost:9379);
  • 由于 SDK 强制要求 API key,本地端点使用占位值 'no-api-key-needed',实际不做鉴权;
  • apiVersion: 'v1beta' 与前面 curl 验证命令中的 /v1beta/models/... 路径一致;
  • 超时设为 10 秒:源码注释解释了原因——如果服务已启动但端口配错,会出现较长的 TCP 超时(这里压缩到 10s);服务未启动则是立即拒绝连接;模型未下载/不支持或服务端上下文超限则会立即返回错误。配置 host 端口错误时,你会在约 10 秒超时后看到分类失败并回退,这是排障时的一个重要线索。

分类请求的生成参数也很能说明设计取向:temperature: 0(决策要稳定可复现)、maxOutputTokens: 256(分类只需要很短的 JSON 输出)、responseMimeType: 'application/json',并且系统提示词之外还会附加一段 reminder(再次强调分类准则),以降低小模型在长上下文中"忘记输出格式"的概率。

4. 端到端数据流小结

综合上述源码,一次请求的本地路由流程可以归纳为:

  1. 请求进入 ModelRouterService.route(),组合策略链依次执行;
  2. 若 gemmaModelRouter.enabled 为 true,轮到 GemmaClassifierStrategy:取最近 4 轮干净历史 + 当前请求,经 LocalLiteRtLmClient.generateJson() 发送到 http://localhost:<port>/v1beta/models/gemma3-1b-gpu-custom:generateContent;
  3. 本地 Gemma 返回 {"reasoning", "model_choice"} JSON,Zod 解析通过后,resolveClassifierModel 把 flash/pro 解析为具体模型;
  4. 决策(含来源 GemmaClassifier、延迟、推理文本)写入遥测并返回给调用方;
  5. 任何一步失败 → 返回 null → 链上后续的云端分类器接管。

实用建议与常见问题

  • 优先使用自动设置:除非网络环境受限,请直接运行 gemini gemma setup,它会一键完成下载运行时、拉取模型、写入配置、启动服务器;配合 gemini gemma status / logs 与 /gemma 斜杠命令可以快速验证状态,详见 gemma-setup 文档。
  • 改完配置必须重启 CLI:gemmaModelRouter 下所有字段都标记 requiresRestart: true,热修改不生效。
  • 模型名不能换:源码对 classifier.model 有硬编码校验,填其他名称会直接抛错。
  • 验证服务最快的方式就是前文的 curl/PowerShell 请求;若返回短笑话,说明模型加载与推理链路正常。
  • 观察路由行为:开启遥测后可在事件流中查看每次路由决策的模型、来源与延迟;也可用调试日志查看 [Routing] Selected model: ... 输出。
  • 端口一致性:settings.json 中的 classifier.host 端口必须与 serve --port=... 一致,不一致时表现为约 10 秒超时后回退云端分类器。
  • 想停用:把 enabled 改为 false 即可;若使用了自动拉起的服务器,也可参考 gemma-setup 文档 中的 gemini gemma stop 停止 LiteRT 服务器。

参考路径

类别 路径
本文对应的原始文档 docs/core/local-model-routing.md
自动化设置指南 docs/core/gemma-setup.md
模型路由总览 docs/cli/model-routing.md
路由服务入口 packages/core/src/routing/modelRouterService.ts
Gemma 分类策略 packages/core/src/routing/strategies/gemmaClassifierStrategy.ts
本地 LiteRT-LM 客户端 packages/core/src/core/localLiteRtLmClient.ts
模型别名解析 packages/core/src/config/models.ts
设置项 schema 定义 packages/cli/src/config/settingsSchema.ts
生成的 JSON Schema schemas/settings.schema.json
策略链相关测试 packages/core/src/routing/modelRouterService.test.ts
gemini-cli
An open-source AI agent that brings the power of Gemini directly into your terminal.
项目地址：https://gitcode.com/GitHub_Trending/gemi/gemini-cli
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
527
590
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
904
1.82 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
889
5.78 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.52 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.33 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
981
502
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384