提示词缓存
很长的系统提示词、文档或多轮对话历史,每次请求都原样重发,其实大部分内容没变。提示词缓存把这些重复的开头部分缓存起来,命中缓存的部分按远低于正常输入的价格计费,响应也更快。
缓存是怎么命中的
缓存按前缀匹配:从请求开头起,只要内容逐字节相同,就能命中。中间任何一处改动,都会让它之后的内容全部失效。所以要把不变的内容放前面(系统提示词、工具定义、参考文档),会变的放后面(用户的新问题、时间戳等)。
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 时键的顺序不固定。
- 切换了模型:缓存按模型隔离,换模型后需要重新写入。