Gemini 緩存命中率低的 5 大原因：AI Studio 與 Vertex 緩存計費界定詳解

在 API易 的實際使用中，OpenAI 和 Claude 系列的緩存寫入與命中都很正常，命中率也很高。Gemini 文本模型卻不一樣：緩存命中率很低，甚至基本沒有。這是一個可以在賬單和用量明細裏復現的事實，也是不少開發者在對賬時最困惑的地方。

本文基於 Google 官方文檔（截至 2026 年 10 月 20 日），拆解 Gemini 緩存命中率低的 5 類原因，並講清 AI Studio（Gemini Developer API）與 Vertex AI 的緩存計費是怎麼界定的。

這不是一篇“甩鍋式”分析。Google 官方並沒有“使用中轉會降低 Gemini 緩存命中率”的規則，我們也無法在沒有上游請求記錄的情況下，斷言某個具體原因一定成立。本文的做法是：先講官方規則，再列出哪些條件會讓規則“失效”，最後給出一套你自己就能跑的排查與核賬方法。

核心價值：讀完本文，你將理解 Gemini 緩存何時命中、何時不命中，掌握“總輸入包含緩存部分”這一計費要點，並能用官方響應字段獨立覈對賬單。

Gemini 緩存命中率核心要點

先把結論擺在前面。理解 Gemini 緩存，需要先分清“隱式緩存”和“顯式緩存”兩種機制，兩者的觸發方式和計費方式完全不同。

官方文檔對 Developer API 的隱式緩存有一句關鍵表述：它不保證節省費用。顯式緩存雖然確定性更高，但需要額外的開發工作，包括創建緩存對象、管理有效期、在後續請求中引用該對象。

爲什麼 Gemini 的體驗和 OpenAI、Claude 不一樣

從使用者視角看，OpenAI 和 Claude 系列在 API易 上表現爲“發同樣的長前綴，就能穩定看到緩存寫入與命中”。Gemini 則要同時滿足幾個條件：模型支持隱式緩存、請求達到該模型的最低 token 門檻、可複用內容位於提示詞開頭、相似請求在較短時間內發出，而且在 Vertex 側還要落在同一個 Google Cloud 項目裏。

任何一個條件不滿足，請求都會按普通輸入價格計費，不會報錯，也不會有任何提示。這正是“命中率低”常常不被發現的原因：緩存沒命中是靜默發生的。

先界定一個概念：AI Studio 指什麼

本文把“AI Studio 渠道”理解爲 Gemini Developer API，也就是用 AI Studio 生成的 API Key 調用的那條路徑，與 Google Cloud 上的 Vertex AI 對比。兩者的緩存機制思路一致，但最低門檻數值、隔離範圍和存儲費規則存在差異，後文逐項展開。

Gemini 緩存命中率低的 5 類原因

下面的分析分兩層：前兩類是官方文檔明確的規則，後三類是“規則在中轉或工程實踐中被打破”的條件性解釋。我們無法僅憑“用了中轉”確定具體是哪一條，需要上游項目和請求記錄才能定位。

原因 1：請求沒有達到最低緩存 token 門檻

隱式緩存有最低 token 門檻，輸入太短的請求不會進入緩存。而且兩端的門檻並不完全一致。以下是當前文檔列出的部分模型數值：

這裏有兩個容易踩的坑。第一，新一代模型（如 Gemini 3.8 Flash）的門檻比 2.5 系列更高，用早期版本的 2,048 去估算會誤判。第二，同一個模型在 Vertex 上的門檻可能更高，一個 5,000 token 的請求在 Developer API 上夠格，在 Vertex 上就不夠。

日常對話類請求通常只有幾百到一兩千 token，天然低於門檻，這是 Gemini 在聊天場景下命中率很低的最直接原因之一。需要強調的是，達到門檻只是必要條件，不代表必然命中。

原因 2：可複用內容不在提示詞開頭

Google 對兩端給出的建議一致：把較長、重複使用的內容放在提示詞開頭，並在較短時間內發送具有相似前綴的請求。緩存依賴的是共同前綴，而不是“請求裏包含同一份文檔”。

換句話說，兩次請求都帶了同一份文檔，並不足以保證命中。還要看它在請求中的位置，以及它前面的內容是否穩定。下面這種寫法就很容易破壞前綴：

# 反例：變化內容放在最前面
[當前時間：2026-10-20 10:31:07]
[請求 ID：a8f3...]
{system 指令}
{長文檔}
{用戶問題}

只要開頭有一個字符不同，後面的長文檔就無法與上一次請求形成共同前綴。這一點是依據官方建議做出的推斷，但在工程上非常常見。

原因 3：中轉層改變了前綴（條件性）

如果中轉層在提示詞開頭插入變化的時間、標識、追蹤字段，或者對多輪上下文做了重排、壓縮、截斷，就會改變共同前綴，降低命中機會。這是一種條件性分析，不能直接認定某家服務存在這些行爲。

排查時要區分兩個層面：你發給中轉的請求前綴是否穩定，以及中轉發給 Google 的請求前綴是否穩定。前者你可以自己控制，後者需要看上游請求記錄。

原因 4：請求被分散到不同的 Vertex 項目（條件性）

Vertex 明確規定：緩存按 Google Cloud 項目隔離，不跨項目共享。如果同一個會話的多次請求被輪詢到不同的 Vertex 項目，那麼項目 A 建立的緩存，項目 B 無法使用。

這裏要謹慎：“換 Key”是否丟緩存，取決於是否同時換了項目。不能直接認定每次換 Key 都會丟緩存，需要進一步確認 Key 與項目的對應關係。

原因 5：只轉發了生成請求，沒有使用顯式緩存

如果調用鏈路只是轉發 generateContent 請求，沒有創建緩存對象，也沒有在後續請求裏引用它，那麼整條鏈路只依賴隱式緩存。隱式緩存沒有確定性保證，無法獲得顯式緩存那樣“創建一次，反覆引用”的穩定收益。

下表把這幾類中轉場景與官方規則對應起來：

🎯 技術建議：在排查 Gemini 緩存問題時，建議先通過 API易 apiyi.com 用同一份固定長前綴連續發起多次請求，再對比各次返回的緩存 token 字段。用受控的請求先排除前綴和門檻問題，再判斷是否與鏈路有關。

沒有上游項目和請求記錄，就無法僅憑“用了中轉”確定原因，也沒有官方依據認定 Vertex 的命中率必然高於 Developer API。

AI Studio 與 Vertex 緩存計費如何界定

很多人把“緩存命中”理解成免費或者整條請求統一打折，這是不對的。兩端的計費都要區分四類項目：普通輸入、緩存輸入、輸出，以及顯式緩存的存儲費。

兩端計費規則對照

Developer API 文檔把緩存 token 使用費、存儲時長、非緩存輸入和輸出都列爲計費因素。Vertex 則另外明確了兩點：創建緩存所用的輸入按標準輸入價格收費，隱式緩存沒有存儲費，顯式緩存有存儲費。具體單價請以兩端當前的官方定價頁爲準，不同模型和版本會變化。

輸入費用的計算公式

對於普通文本生成請求，可以按下面的結構理解輸入費用：

輸入費用 =
（總輸入 tokens − 緩存命中 tokens）× 普通輸入單價
＋ 緩存命中 tokens × 緩存輸入單價

輸出費用另算，顯式緩存還要另加存儲費。舉一個假設的例子：某次請求總輸入爲 10,000 tokens，其中緩存命中 8,000 tokens，那麼按普通價格計費的是 2,000 tokens，按緩存價格計費的是 8,000 tokens。

一個最容易算錯的點：總輸入已包含緩存部分

核賬時要看 Google 的原始響應，而不是隻看中轉後臺顯示的“緩存命中率”。在 generateContent 響應的 usageMetadata 中，有兩個關鍵字段：

因此，不能把 promptTokenCount 全部按普通價格算完，再額外加一筆緩存輸入費，那樣會重複計費。正確做法是先用總輸入減去緩存部分，得到按普通價格計費的部分。如果你使用的是新的 Interactions API，官方給出的緩存統計字段是 usage.total_cached_tokens。

兩件必須分開的事

還需要區分兩件事：Google 上游實際命中了多少緩存，以及中轉如何把這部分優惠計入你的賬單。前者可以用官方字段衡量，後者取決於中轉自身的計費規則，Google 官方文檔無法替其證明。所以對賬時，建議同時覈對上游返回的緩存字段和賬單明細的計費口徑。

💡 選擇建議：對賬時先看請求級別的緩存 token 字段，再看賬單彙總。如果需要在 OpenAI、Claude 和 Gemini 之間做同口徑對比，可以通過 API易 apiyi.com 用同一份提示詞分別調用，便於快速切換模型。

Gemini 與 Claude、OpenAI 的緩存計費差異

三家的緩存思路不同，對賬口徑也不同。下表按“怎麼觸發、怎麼計費”對比，折扣比例和時長會隨模型版本調整，下表爲寫作時的大致口徑，具體數值請以各家官方定價頁爲準：

這張表裏有三處最容易混淆：

• 寫入費：Claude 寫緩存要多付錢，讀緩存才便宜，所以“寫得多、讀得少”會比不用緩存更貴；OpenAI 沒有寫入費，不命中也不會多花錢；Gemini 隱式緩存同樣沒有寫入費，只有顯式緩存會產生創建與存儲成本。
• 誰來決定緩存：Claude 由請求方明確標記斷點，所以命中表現最可預期；OpenAI 與 Gemini 隱式緩存都由平臺自動判斷，開發者只能靠穩定前綴提高概率。這也是用戶感覺 Claude、OpenAI “命中穩定”而 Gemini 不穩定的原因之一：Gemini 要同時受門檻、前綴、渠道隔離幾項影響。
• 總輸入口徑：Gemini 與 OpenAI 的總輸入已包含緩存部分，要先扣除再計價；Claude 的 input_tokens 不含緩存讀寫部分，三項要分別計價後相加。把一家的公式套到另一家，賬會算錯。通過 API易 apiyi.com 做跨模型對賬時，請先確認各家返回的字段口徑。

Gemini 緩存命中率快速上手：自己跑一次測試

理論說完，動手驗證最可靠。下面的思路是：構造一段超過最低門檻的固定長前綴，把變化的問題放在最後，連續請求幾次，觀察緩存 token 字段的變化。

極簡示例

以下代碼使用 OpenAI 兼容格式調用，並打印返回的用量信息。字段名以實際返回爲準，不同接入方式下緩存相關字段的命名可能不同：

import time
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 API易 統一接口
)

# 固定的長前綴：務必超過目標模型的最低緩存門檻
LONG_PREFIX = "這裏放一段穩定不變的長文檔或系統指令……" * 800

for i in range(3):
    resp = client.chat.completions.create(
        model="gemini-3.8-flash",
        messages=[
            {"role": "system", "content": LONG_PREFIX},
            {"role": "user", "content": f"請用一句話總結，第 {i} 次提問"},
        ],
    )
    print(i, resp.usage)
    time.sleep(2)

import time
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 使用 API易 統一接口
)

LONG_PREFIX = "這裏放一段穩定不變的長文檔或系統指令……" * 800


def extract_cached_tokens(usage) -> int:
    """嘗試從 usage 中讀取緩存 token 數，字段名以實際返回爲準"""
    details = getattr(usage, "prompt_tokens_details", None)
    if details is not None:
        cached = getattr(details, "cached_tokens", None)
        if cached is not None:
            return cached
    return 0


def estimate_input_cost(total_in: int, cached: int,
                        normal_price: float, cached_price: float) -> float:
    """
    按官方口徑估算輸入費用：
    總輸入已包含緩存部分，所以普通部分 = 總輸入 - 緩存部分
    單價請填入官方定價頁當前數值（每百萬 token）
    """
    normal_part = total_in - cached
    return (normal_part * normal_price + cached * cached_price) / 1_000_000


def run_test(model: str, rounds: int = 3):
    results = []
    for i in range(rounds):
        resp = client.chat.completions.create(
            model=model,
            messages=[
                {"role": "system", "content": LONG_PREFIX},
                {"role": "user", "content": f"請用一句話總結，第 {i} 次提問"},
            ],
        )
        usage = resp.usage
        cached = extract_cached_tokens(usage)
        results.append((i, usage.prompt_tokens, cached))
        print(f"第 {i} 次：總輸入={usage.prompt_tokens}，緩存命中={cached}")
        time.sleep(2)
    return results


if __name__ == "__main__":
    for m in ["gemini-3.8-flash"]:
        print("模型：", m)
        run_test(m)

🚀 快速開始：推薦使用 API易 apiyi.com 搭建這個對比測試。同一份腳本只需替換 model 參數，就能依次測 Gemini、OpenAI 和 Claude 系列，直觀看到不同模型的緩存表現差異。

測試時要控制的變量

跑測試時，建議逐條檢查下面這份清單，避免把“自己的問題”誤判成“鏈路的問題”：

如何解讀測試結果

如果前綴足夠長、結構穩定、間隔很短，但 Gemini 仍然幾乎沒有緩存命中，而同樣的提示詞在 OpenAI 或 Claude 上命中正常，就說明差異來自 Gemini 自身的緩存機制和上游鏈路條件，而不是你的提示詞寫法。這時可以考慮改用顯式緩存，把需要複用的長內容固定下來，主動創建緩存對象並在請求中引用。

如果你的業務本來就是短對話，那麼與其追求命中率，不如接受 Gemini 在這類場景下緩存收益有限，把成本優化的重點放在模型選擇和輸出長度控制上。

常見問題

緩存命中率 Key Takeaways

• 現象是事實：OpenAI 與 Claude 系列緩存命中穩定，Gemini 命中率低甚至接近沒有，需要單獨分析。
• 官方不保證命中：Gemini 隱式緩存不保證節省費用，顯式緩存需要主動創建並引用緩存對象。
• 門檻因模型而異：新一代模型門檻更高，且 Vertex 與 Developer API 的數值可能不同。
• 前綴決定命中：長內容放開頭，開頭不要插入時間、ID 等變化內容，否則共同前綴被破壞。
• Vertex 按項目隔離：緩存不跨項目共享，請求分散到不同項目會丟失緩存。
• 總輸入含緩存：promptTokenCount 已包含緩存部分，核賬時要先扣除再分別計價。
• 用字段對賬：以官方響應的緩存字段爲準，並通過 API易 apiyi.com 做同提示詞的跨模型對比。

總結

Gemini 緩存命中率低，是由多個條件疊加造成的：隱式緩存不保證命中、最低 token 門檻隨模型升高、前綴必須穩定、Vertex 緩存按項目隔離，以及顯式緩存需要主動創建。其中後幾項在鏈路層面被改變時，命中率就會下降，但具體原因必須結合上游項目和請求記錄才能確定。

計費方面，記住三點：緩存命中不是免費；總輸入包含緩存部分，不能重複計費；顯式緩存另有存儲費，隱式緩存沒有。核賬以官方響應字段爲準，同時單獨覈對中轉的計費口徑。

下一步建議：用本文的測試腳本，在固定長前綴下對 Gemini 與 OpenAI、Claude 做一次對照測試，再決定是否引入顯式緩存。推薦通過 API易 apiyi.com 快速驗證效果，多個模型共用同一套接口，對比成本低。

參考資料

1. Gemini API 緩存文檔：隱式緩存與顯式緩存的官方說明
2. 鏈接： ai.google.dev/gemini-api/docs/caching

3. 說明： 包含最低 token 門檻與計費因素

4. Gemini API 定價頁：普通輸入、緩存輸入、輸出與存儲價格

5. 鏈接： ai.google.dev/gemini-api/docs/pricing

6. 說明： 覈對當前單價的依據

7. Vertex AI 上下文緩存概覽：緩存的項目隔離與計費規則

8. 鏈接： docs.cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview

9. 說明： 說明 Vertex 緩存不跨項目共享

10. Gemini API generateContent 參考：響應中的 usageMetadata 字段

11. 鏈接： ai.google.dev/api/generate-content
12. 說明： 核賬時使用的緩存 token 字段

作者：APIYI Team
技術交流：歡迎在評論區討論 Gemini 緩存的排查經驗，更多資料可訪問 API易 docs.apiyi.com 文檔中心

延伸閱讀

• Gemini 4 Argon 價格解讀：Vertex AI 已可拉取模型，5 種場景真實成本測算:Gemini 4 Argon 已在 Vertex AI 中可以拉取到模型。本文拆解 $2/$10 嚐鮮價與 $4/$20 正式價、95% 緩存摺扣、推理 token 計費與 1M 輸出上限帶來的隱性成本，對比 Gemini 3.8 Flash、GPT-6 Astra、Claude Opus 5.5，並給出 5 種場景成本測算與省錢接入代碼。
• claude-sonnet-5-5 對比 claude-opus-5-5:Opus 更快、Sonnet 只剩便宜？6 組數據講清企業長上下文 Agent 的最佳搭配:claude-opus-5-5 用起來比預期更快，claude-sonnet-5-5 是否只剩價格優勢？本文從速度、推理檔位、Token 效率、緩存計費、長上下文質量和 Agent 分工 6 個維度對比，給出企業長輸入長輸出場景的模型搭配方案。
• gemini-4-argon AI Studio 併發是多少？429 頻現的 5 類原因與 6 步解決方案:梳理 gemini-4-argon 在 Google AI Studio 的限流機制，講清 RPM、TPM 與併發的區別，並給出 6 步 429 解決方案和可直接運行的重試代碼。