Token caching
Gemini CLI token caching 的作用：減少重複上下文成本、提升長任務效能，以及使用前需要理解的邊界。
Token caching 用來減少重複上下文帶來的成本或延遲。它適合長會話、重複讀取大上下文、指令碼化任務。
Token caching 受認證方式影響。API key 和 Vertex AI 場景可用；OAuth / Code Assist API 場景不要把 cached token 當成必然存在。
官方文件裡的限制很關鍵：token caching 只在 API key 認證或 Vertex AI 場景下可用。OAuth 使用者，包括 Google Personal / Enterprise 賬號走的 Code Assist API，目前不支援 cached content creation。
適合場景
- 多輪圍繞同一大專案。
- 反覆讀取同一批文件。
- CI/headless 中重複上下文。
- 長時間任務需要穩定效能。
它快取什麼
Token caching 的目標不是快取最終答案，而是複用前面已經處理過的系統指令和上下文。這樣後續請求不需要重複為同樣上下文付完整處理成本。
官方頁面沒有給出統一 TTL 或永久快取承諾，所以教程裡不要寫“快取會保留多久”。更穩的寫法是教讀者看 /stats，確認當前認證方式下是否真的出現 cached token。
適合快取的內容通常是：
- 穩定系統指令。
- 專案規則。
- 長期不變的上下文。
- 多輪任務反覆引用的檔案摘要。
不適合依賴 caching 的內容包括即時日誌、臨時錯誤輸出、頻繁變化的 diff 和一次性輸入。
| 內容 | 是否適合 caching | 原因 |
|---|---|---|
| 專案規則 / system instructions | 適合 | 穩定且重複出現 |
| 長文件和 schema | 適合 | 多輪任務會重複引用 |
| 當前 diff | 不適合 | 變化快，容易誤用舊上下文 |
| 測試失敗日誌 | 不適合 | 每次執行都可能不同 |
| 構建產物和依賴目錄 | 不適合 | 應先 ignore 或裁剪 |
不適合把它當萬能解法
如果任務描述混亂、專案規則缺失、驗證命令不清楚，token caching 也救不了。先把上下文結構和任務邊界做好。
也不要把 caching 理解成“所有 token 都免費”。它只是減少重複處理成本，不能替代上下文裁剪。
如何檢視效果
在 Gemini CLI 會話裡使用 /stats 檢視 token usage。當 cached token 可用時，stats 輸出裡會顯示相關節省情況。
如果 /stats 看不到 cached token，先確認當前認證方式是不是 Gemini API key 或 Vertex AI。如果你是 OAuth 登入，缺少 cached token 資訊是預期行為。
這也是為什麼團隊覆盤成本時要記錄認證方式。
如果團隊成員分別使用 OAuth、API key 和 Vertex AI，同一篇教程裡的 caching 截圖可能完全不同。商業教程建議把認證方式寫在截圖說明裡，否則讀者會以為自己配置錯了。
成本最佳化建議
- 用
.geminiignore排除構建產物、依賴目錄、日誌和大檔案。 - 自動化任務要記錄
/stats，否則很難判斷成本變化來自快取、模型切換還是上下文變化。 - 先減少無關上下文，再考慮 token caching。
- 團隊場景要統一認證方式，否則不同成員看到的 caching 行為可能不同。
驗證步驟
先準備一個穩定的大上下文任務，例如讀取同一組 docs 或 schema。第一輪執行後看 /stats，第二輪用同一認證方式、同一模型和同一上下文再執行一次，再比較 cached token 是否出現。中間不要改 GEMINI.md、settings、模型或輸入檔案，否則你無法判斷變化來自快取還是輸入漂移。
如果第二輪仍看不到 cached token，不要繼續改 prompt。先確認認證方式、官方支援範圍、模型是否支援 cached content creation，再判斷是否需要改成本最佳化策略。
接下來去哪
ACP mode
繼續看 IDE / 工具鏈透過協議控制 Gemini CLI 的執行方式。
.geminiignore
快取前先裁剪不該進入上下文的檔案。
Quota and pricing
成本最佳化要和 quota、模型選擇、認證方式一起看。