開發文件
提示詞快取
很長的系統提示詞、文件或多輪對話歷史，每次請求都原樣重發，其實大部分內容沒變。提示詞快取把這些重複的開頭部分快取起來，命中快取的部分按遠低於正常輸入的價格計費，回應也更快。
快取是怎麼命中的
快取按字首匹配：從請求開頭起，只要內容逐位元組相同，就能命中。中間任何一處改動，都會讓它之後的內容全部失效。所以要把不變的內容放前面（系統提示詞、工具定義、參考文件），會變的放後面（使用者的新問題、時間戳等）。
GPT 系列：自動快取
GPT 模型會自動快取較長的請求字首，不需要改程式碼。命中的 token 數在 usage.prompt_tokens_details.cached_tokens：
json
"usage": {
"prompt_tokens": 12400,
"completion_tokens": 310,
"prompt_tokens_details": { "cached_tokens": 11264 }
}Claude 系列：用 cache_control 標記
Claude 需要你在內容區塊上標記快取斷點 cache_control，斷點之前的全部內容（工具定義 → system → messages）會被快取：
cache_claude.py
from anthropic import Anthropic
client = Anthropic(api_key="sk-...", base_url="https://api.flyrouter.ai")
long_document = open("manual.md").read() # 很長、每次都相同的參考文件
msg = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=2048,
system=[
{"type": "text", "text": "你是產品客服，只根據下面的手冊回答問題。"},
{"type": "text", "text": long_document, "cache_control": {"type": "ephemeral"}},
],
messages=[{"role": "user", "content": "如何重設裝置？"}],
)
print(msg.usage)- 預設快取 5 分鐘，每次命中會重新計時。請求間隔較長時可用
{"type": "ephemeral", "ttl": "1h"}快取 1 小時。 - 一個請求最多 4 個快取斷點。
- 內容太短不會被快取（新款 Claude 約 512 token 起，舊款更高），也不會報錯。
用 usage 裡的兩個欄位確認效果：
| 欄位 | 意義 |
|---|---|
cache_creation_input_tokens | 本次寫入快取的 token 數 |
cache_read_input_tokens | 本次命中快取的 token 數 |
連續幾次請求後 cache_read_input_tokens 仍然是 0，通常是字首裡混進了每次都變的內容。
計費
- 快取命中：按快取讀取價計費，遠低於正常輸入價。
- 寫入快取（Claude）：首次寫入按快取寫入價計費，略高於正常輸入價；1 小時快取的寫入價更高。
- 各模型的快取讀取、寫入單價見 模型價格。
一段內容只要被重複使用兩次以上，開啟快取基本都更划算。
常見的快取失效原因
- 在系統提示詞裡放了目前時間、請求 ID 等每次都變的內容。
- 工具列表的順序或內容每次不同。
- 序列化 JSON 時鍵的順序不固定。
- 切換了模型：快取按模型隔離，換模型後需要重新寫入。
FlyRouter