Skip to content

提示词缓存是怎么省钱的 ​

提示词缓存(Prompt Caching)会把一次请求中不变的前缀(系统提示、工具定义、长文档、对话历史)缓存起来;之后的请求如果以完全相同的前缀开头,这部分 token 就按远低于普通输入的单价计费,响应也更快。对 Claude Code、Codex 这类每次都带大量固定上下文的工具,缓存命中率直接决定了花费。

为什么需要缓存 ​

大模型 API 是无状态的:每次请求都要把完整的上下文重新发一遍。一个编程 Agent 的典型请求是这样的:

部分特点
系统提示几乎每次都一样
工具定义(读文件、执行命令、搜索……)几乎每次都一样
项目说明文件、已读入的代码一段时间内不变
历史对话只在末尾追加
本轮新问题每次不同,通常很短

前四部分占了绝大多数 token,并且在多轮对话里反复出现。缓存要解决的就是「同样的前缀反复按全价计费」的问题。

缓存是怎么匹配的 ​

无论 Anthropic 还是 OpenAI,缓存都是前缀匹配:从请求开头算起,逐 token 比对,只要中间有一个 token 不同,从这里往后的内容就都不能命中。

所以内容的顺序非常关键:

  1. 把不变的内容放在最前面:系统提示 → 工具定义 → 长文档。
  2. 会变的内容放在最后:本轮问题、时间戳、随机 ID。
  3. 不要在系统提示里放当前时间、请求 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 的大部分输入都是重复前缀,命中缓存后花费会明显下降。

相关阅读:为什么 Claude Code 一句话也要几千输入 token。

NiceAI · 稳定的 AI 大模型 API 中转站