---
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="/zh-Hant/docs/gemini-cli/official/05-models-runtime/54-token-caching" />
  <Card title="模型路由" description="回看預設 routing、fallback 和最終模型排查。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/52-model-routing" />
  <Card title="Local development" description="本地 runtime 和開發環境要單獨驗證。" href="/zh-Hant/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)
