外观
提示词缓存是怎么省钱的
提示词缓存(Prompt Caching)会把一次请求中不变的前缀(系统提示、工具定义、长文档、对话历史)缓存起来;之后的请求如果以完全相同的前缀开头,这部分 token 就按远低于普通输入的单价计费,响应也更快。对 Claude Code、Codex 这类每次都带大量固定上下文的工具,缓存命中率直接决定了花费。
为什么需要缓存
大模型 API 是无状态的:每次请求都要把完整的上下文重新发一遍。一个编程 Agent 的典型请求是这样的:
| 部分 | 特点 |
|---|---|
| 系统提示 | 几乎每次都一样 |
| 工具定义(读文件、执行命令、搜索……) | 几乎每次都一样 |
| 项目说明文件、已读入的代码 | 一段时间内不变 |
| 历史对话 | 只在末尾追加 |
| 本轮新问题 | 每次不同,通常很短 |
前四部分占了绝大多数 token,并且在多轮对话里反复出现。缓存要解决的就是「同样的前缀反复按全价计费」的问题。
缓存是怎么匹配的
无论 Anthropic 还是 OpenAI,缓存都是前缀匹配:从请求开头算起,逐 token 比对,只要中间有一个 token 不同,从这里往后的内容就都不能命中。
所以内容的顺序非常关键:
- 把不变的内容放在最前面:系统提示 → 工具定义 → 长文档。
- 会变的内容放在最后:本轮问题、时间戳、随机 ID。
- 不要在系统提示里放当前时间、请求 ID 这类每次都变的值,它会让后面的内容全部失效。
Anthropic:显式标记 cache_control
Anthropic 的 Messages API 需要在内容块上显式标记缓存断点:
json
{
"model": "<模型名>",
"max_tokens": 1024,
"system": [
{ "type": "text", "text": "你是一个代码助手……(很长的系统提示)",
"cache_control": { "type": "ephemeral" } }
],
"messages": [
{ "role": "user", "content": "这个函数为什么报错?" }
]
}要点(以 Anthropic 官方文档为准):
cache_control标在哪个块上,就把从开头到这个块为止的内容作为缓存前缀。- 首次请求是缓存写入,单价略高于普通输入;之后命中是缓存读取,单价只有普通输入的一小部分。
- 缓存有存活时间,默认较短(分钟级),每次命中会刷新;也有更长存活时间的选项,写入价格更高。
- 前缀太短不会被缓存,最小长度因模型而异。
- 响应的
usage中会分别返回cache_creation_input_tokens和cache_read_input_tokens,可以据此判断是否命中。
Claude Code 会自动为系统提示、工具定义和历史对话打缓存标记,用户不需要手动设置。
OpenAI:自动缓存
OpenAI 的缓存是自动的,不需要改请求:
- 达到一定长度(官方文档中为 1024 token 起)的提示会自动参与缓存。
- 同样是前缀匹配,命中部分按折扣后的输入价格计费。
- 响应的
usage.prompt_tokens_details.cached_tokens(Responses API 中为input_tokens_details.cached_tokens)表示命中的 token 数。 - 缓存在一段时间不用后会被清除。
通过中转使用时
NiceAI 兼容上述两种协议,cache_control 和 usage 字段的写法与官方一致。在 NiceAI 中:
- 实际扣费 = 按官方价格(区分普通输入、缓存写入、缓存读取、输出)计算的费用 × 分组倍率,见 分组与倍率说明。
- 每次请求的缓存 token 数可以在控制台的使用记录中查看。
- 不同分组的线路不同,缓存表现可能不同,以实际使用记录为准。
提高命中率的实践
| 做法 | 原因 |
|---|---|
| 固定系统提示,不放时间戳等变量 | 前缀一变,后面全部失效 |
| 工具列表顺序固定 | 工具定义也是前缀的一部分 |
| 长文档放在问题前面 | 问题每次不同,放后面不影响前缀 |
| 连续对话不要中途切换模型 | 缓存按模型区分 |
| 编程工具里少用「清空上下文后重新读取同样文件」 | 新会话需要重新写入缓存 |
观察 usage 中的缓存字段 | 用数据判断是否命中,而不是猜 |
小结
- 缓存按前缀匹配,顺序比内容更重要。
- Anthropic 需要
cache_control标记,OpenAI 自动缓存。 - 编程 Agent 的大部分输入都是重复前缀,命中缓存后花费会明显下降。