本地模型路由
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 和開發環境要單獨驗證。