BUZZ AI Gateway
文档 · 核心概念 · Prompt Caching

Prompt Caching

Anthropic Prompt Cache 把重复长上下文的输入价格降到 1/10。机制本身从外面看简单到极致:给一个 content block 标 cache_control,后续请求里这部分 token 计为 cache_read_input_tokens 而不是 input_tokens。但 "什么时候缓存、缓存多长、放在哪",决定了它是一项小优化还是一根成本主杠杆。

是什么

Claude 请求在模型层就是一串扁平 token 流。Prompt Cache 让 Anthropic 对这串 token 的前缀做记忆化。第一次发送被标记的前缀,模型完整处理一遍,Anthropic 把对应的注意力状态写入 ephemeral cache。后续命中同一前缀的请求直接跳过算力,只付一笔很小的读费用。

定价模型很清晰:

token 类别相对成本
标准输入1.0×
缓存写入(5 分钟)1.25×(一次性)
缓存写入(1 小时)2.0×(一次性)
缓存读取0.1×
输出5.0×(随模型不同)

第一次稍贵一点,然后永远九折(直到 TTL 过期为止)。只要被缓存的前缀在 TTL 内被复用至少两次,数学就是赚的。

以上倍率为 Anthropic 官方计价,在上游层面生效。BUZZ 字节级透传 cache_control,以上游返回的 cache 命中/写入 token 数为准计费,不在此基础上额外加价。

cache_control 工作原理

你给一个或多个 content block 加 cache_control 注解。这个标记的语义是:从请求开头到这个块为止的全部内容,都是一段候选缓存前缀。Anthropic 对这段前缀做哈希,然后查表。

{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "<30 KB 稳定的 instruction 与上下文>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "针对上面上下文的提问"}
  ]
}

两条重要规则:

  1. 缓存断点是位置敏感的。缓存覆盖区间是 [0 字节, 标记块] 闭区间。如果你修改了前面任何内容,缓存就失效。稳定的、不变的内容必须放最前面。
  2. 最多 4 个断点。它们形成分层缓存,最长前缀匹配优先。利用这一点可以把 system prompt、稳定中段、按会话刷新的段分别缓存。

命中信息出现在响应的 usage 里:

"usage": {
  "input_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 30000,
  "output_tokens": 240
}

cache_read_input_tokens: 30000 就是收益。这 30000 token 只花了正常输入价格的 1/10。

5 分钟 vs 1 小时 TTL

Anthropic 提供两种缓存时长。决策几乎只看一个指标:请求间隔。

TTL写入溢价选择场景
5 分钟(默认)1.25×交互式会话,几分钟内同一上下文被多次命中(对话、agent 工具循环、IDE 助手)
1 小时2.0×定时批处理、日常报表生成、跨数分钟到一小时的请求复用同一上下文

用更长 TTL 的写法:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

简单决策法:复用间隔短于 5 分钟,选默认即可;复用间隔在 5 分钟到 1 小时之间,1 小时 TTL 比反复重建 5 分钟缓存便宜;超过 1 小时,你每次都在创建新缓存,要重新评估缓存是否还有意义。

BUZZ 怎么转发 cache_control

BUZZ 不解析 cache_control,字节级透传给上游通道。Cache 本身存活在 Anthropic 基础设施里,不在 BUZZ。三个值得理解的延伸结论:

实战模式

长稳定 system prompt。20K token 的 instruction 加示例块?标 cache_control。会话从第二轮起,输入这一头几乎免费。

RAG 配稳定检索集。会话内反复检索同一批文档?把这些文档放进 system prompt 并缓存。用户消息变,缓存前缀不变。

Tool 定义复用。长 tools[] 数组可以缓存。把缓存断点放在最后一个工具定义之后,整个工具目录就是一段缓存前缀。

多步 agent 循环。每一次 tool round-trip 都是一次新请求。开了缓存后,对话历史(往往是 prompt 中最长的部分)只付一次写入费,后续每轮迭代都是读。会话越长,收益越复利。

相关链接