Prompt 快取 — TokSpan 文件

運作方式

當您在多個 API 呼叫中傳送相同的 Prompt 前綴時，上游供應商會識別重複內容、跳過重新處理，並對已快取的部分以折扣費率計費。典型節省效果：

指標	無快取	快取命中時
首 Token 時間	基準	最快加速 80%
Prompt Token 成本	全額	便宜 50–90%

所有支援的模型預設已啟用快取——無需任何設定。供應商會自動管理快取生命週期（快取通常持續 5–30 分鐘，依供應商和負載而異）。

有利於快取的 Prompt 設計

快取比對的是前綴——即 messages 陣列開頭的 Token。請將 Prompt 設計為將所有靜態內容放在前面：

python
# ✅ GOOD: Static content first = high cache hit rate
messages = [
    {"role": "system", "content": "You are a legal assistant. Reference case law when answering..."},
    {"role": "user", "content": "What are the elements of negligence?"},
]

# ❌ BAD: Dynamic prefix kills cache
messages = [
    {"role": "user", "content": "What are the elements of negligence?"},  # Cache miss
    {"role": "system", "content": "You are a legal assistant..."},  # Too late
]

設計檢查清單

系統訊息放在最前面——一律將其作為 messages 中的第一個元素
靜態上下文放在動態查詢之前——Few-shot 範例、擷取的 RAG 上下文、工具定義應放在使用者當前問題之前
前綴中不要包含時間戳記／ID——不要在可快取內容之前添加每個請求唯一的資料
保持系統 Prompt 完全一致——整個前綴必須逐位元組匹配才能命中快取
前綴越長，節省越多——快取 10K Token 的系統 Prompt 遠比 200 Token 的節省更多

監控快取命中

回應中的 usage 物件可揭示您的 Prompt 是否命中快取：

Claude (Anthropic)：查看 cache_read_input_tokens 和 cache_creation_input_tokens
GPT-4o (OpenAI)：已快取的 Token 會反映在較低的 prompt_tokens 計費中
Gemini (Google)：上下文快取會顯示在使用量中繼資料中

import requests

response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-key"},
    json={"model": "claude-opus-4-8", "messages": [...]},
)

# Check for cache hits in the usage object
usage = response.json()["usage"]
if "cache_read_input_tokens" in usage:
    print(f"Cache hit! {usage['cache_read_input_tokens']} tokens served from cache")
    print(f"Cache creation: {usage.get('cache_creation_input_tokens', 0)} tokens written")
else:
    print("Cache miss — all prompt tokens billed at full price")

支援的模型

模型	供應商	最小可快取 Token 數	快取 TTL（典型值）
Claude Opus 4.8	Anthropic	1024	約 5 分鐘
Claude Sonnet 4.6	Anthropic	1024	約 5 分鐘
GPT-4o	OpenAI	1024	約 5–10 分鐘
Gemini 2.5 Pro	Google	32768	可設定（上下文快取 API）

最低 Token 門檻：每個供應商僅快取超過最低 Token 數的 Prompt（Claude 和 GPT-4o 通常為 1024 Token）。短 Prompt 無法受益。這使得快取對於具有大型系統 Prompt、RAG 管線或長歷史多輪對話的應用程式影響最為顯著。

Prompt Caching

運作方式

有利於快取的 Prompt 設計

設計檢查清單

監控快取命中

支援的模型