提示快取

Prompt Caching 允許快取重複使用的 prompt 前綴，減少 token 消耗和回應延遲。

運作原理

當你的請求中包含較長的、重複使用的 system prompt 或上下文資訊時：

首次請求 — 完整處理所有 token，並快取 prompt 前綴
後續請求 — 命中快取時，快取部分的 token 不再重複計費
快取過期 — 快取有一定的 TTL（通常 5-10 分鐘），過期後需重新快取

快取支援

OfoxAI 的模型資源分別由 AWS Bedrock、Azure OpenAI、Google Cloud、阿里云、火山云 等模型官方云廠商提供。云廠商支援 Prompt Caching 的模型，OfoxAI 同樣支援。

云廠商	代表模型	快取機制
AWS Bedrock	Claude 系列	原生 Prompt Caching
多家雲端廠商	GPT 系列	自動快取
Google Cloud	Gemini 系列	Context Caching
阿里云	Qwen 系列	平台側快取
火山云	Doubao 系列	平台側快取

具體模型的快取支援情況以各云廠商官方文件為準。OfoxAI 會透傳快取相關參數，無需額外設定。

本文講的是自動 / 隱式快取（模型自動複用重複前綴，盡力而為）。若你需要主動建立快取、確定性命中大段反覆複用的上下文，Gemini 還支援顯式快取 —— 見 Gemini 顯式快取（cachedContents）。

使用方式

OpenAI 協議

OpenAI 模型的 Prompt Caching 是自動的 — 當偵測到重複的 prompt 前綴時自動啟用：

caching_openai.py


# 長 system prompt 會被自動快取
SYSTEM_PROMPT = """你是 OfoxAI 的技術支援助手。
 
以下是你需要了解的產品資訊：
- OfoxAI 是一個 LLM Gateway，支援 100+ 大模型
- 支援 OpenAI / Anthropic / Gemini 三大協議
- ...
（省略更多產品知識）
"""
 
# 第一次請求：快取 system prompt
response1 = client.chat.completions.create(
    model="openai/gpt-6.1-sol",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": "OfoxAI 支援哪些模型？"}
    ]
)
 
# 第二次請求：命中快取，更快更便宜
response2 = client.chat.completions.create(
    model="openai/gpt-6.1-sol",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},  # 快取命中
        {"role": "user", "content": "如何設定 Claude Code？"}
    ]
)

Anthropic 協議

Anthropic 模型支援顯式的 cache control：

caching_anthropic.py


import anthropic
 
client = anthropic.Anthropic(
    base_url="https://api.ofox.io/anthropic",
    api_key="<你的 OFOXAI_API_KEY>"
)
 
response = client.messages.create(
    model="anthropic/claude-sonnet-5.5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "你是一個專業助手。以下是產品文件...",
        "cache_control": {"type": "ephemeral"}  # 顯式啟用快取
    }],
    messages=[{"role": "user", "content": "總結產品特點"}]
)
 
# 查看快取命中情況
print(f"快取寫入 token: {response.usage.cache_creation_input_tokens}")
print(f"快取命中 token: {response.usage.cache_read_input_tokens}")

成本節省

快取命中後，快取部分的 token 按較低的快取讀取價格計費，節省比例因模型而異。部分模型寫入快取時另按快取寫入價格計費，該價格可能高於一般輸入價格。

各模型的快取讀取與快取寫入價格以模型列表中對應模型頁面的標示為準。

實際節省比例取決於快取命中率和各云廠商的計費策略，請參考 OfoxAI 控制台的用量統計查看詳情。

最佳實踐

將長文本放在前面 — system prompt、知識庫內容等不變的部分放在 messages 開頭
保持前綴一致 — 只有完全相同的前綴才能命中快取
合理設計 prompt 結構 — 將固定部分和變化部分分離


# ✅ 好的設計：固定內容在前，變化內容在後
messages = [
    {"role": "system", "content": LONG_STATIC_PROMPT},   # 可快取
    {"role": "user", "content": dynamic_question}          # 變化部分
]
 
# ❌ 不好的設計：變化內容穿插在固定內容中
messages = [
    {"role": "system", "content": f"Today is {date}. {LONG_PROMPT}"}  # 每天不同，無法快取
]

快取命中可以在 API 回應的 usage 欄位中查看，也可以在 OfoxAI 控制台的用量統計中查看快取命中率。