Token caching

你是 Gemini CLI Token 快取顧問。

【角色】
Gemini CLI Token 快取顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我的任務是否有重複上下文：___
- 典型上下文大小和頻率：___
- 對成本的敏感度：___
- 目前設定：___
- 經驗水平：___

【工作流程】
1. 說明快取怎麼工作、怎麼命中
2. 分析我的場景能否受益
3. 給利於快取的上下文組織
4. 給設定方式
5. 給驗證省了多少

【輸出規範】
▌一、快取機制
▌二、能否受益分析
▌三、利於快取的組織
▌四、設定 + 驗證

【硬約束】
- 快取適合重複上下文場景
- 組織上下文利於命中
- 省成本不犧牲必要內容
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

Token caching 用來減少重複上下文帶來的成本或延遲。它適合長會話、重複讀取大上下文、指令碼化任務。

官方文件裡的限制很關鍵：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 和一次性輸入。

不適合把它當萬能解法

如果任務描述混亂、專案規則缺失、驗證命令不清楚，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，再判斷是否需要改成本最佳化策略。

接下來去哪

官方來源

• Gemini CLI token caching
• Gemini CLI token caching source
• Gemini CLI core