Prompt Cache 命中率从 30% 拉到 90%:cache_control 7 个反模式与修复

你给 Claude 请求加了 cache_control,但每次返回的 usage.cache_creation_input_tokens 都是 0,cache_read_input_tokens 也是 0。账单一分没省。这不是 bug —— 是你打 cache_control 的方式让 Anthropic 根本没机会建缓存。本文拆解 7 个最常见的反模式,每个都给出 ❌ 错误代码 和 ✅ 修复代码,以及一份从 usage 字段反推问题的诊断指南。

Anthropic Prompt Cache 简要回顾

先把规则讲清楚,后面所有反模式都建立在这几条规则上:

• 断点机制:在某个 content block 上打 cache_control: {type: "ephemeral"},Anthropic 会把这个 block 之前(包括它)的所有内容作为一个缓存前缀。
• 最大 4 个断点:一个请求最多打 4 个 cache_control。匹配时从前往后,选命中的最长前缀。
• 最低长度阈值:Sonnet / Opus 是 1024 tokens,Haiku 是 2048 tokens。短于阈值 = 不建缓存。
• TTL:默认 5m(5 分钟),也可以显式指定 1h(1 小时)。每次命中刷新 TTL 窗口。
• 计费:首次写入有约 25% surcharge,命中后 input 单价降到 10%。
• 命中条件:从请求开头开始,字节级完全一致(包括 tools 定义、system、messages 顺序)。任何位置的差异都会让该位置之后的缓存全部失效。

记住一句话:缓存匹配是前缀匹配,不是子串匹配。前缀里任何一个字节变了,缓存就断了。

用 usage 字段确认缓存有没有生效

// 一次健康的命中长这样
{
  "usage": {
    "input_tokens": 50,                      // 本次新增非缓存输入
    "cache_creation_input_tokens": 0,        // 没有新写入缓存
    "cache_read_input_tokens": 18742,        // 命中 18742 tokens
    "output_tokens": 350
  }
}

// 命中率 = 18742 / (50 + 0 + 18742) ≈ 99.7%

如果 cache_creation_input_tokens 一直是 0 且 cache_read_input_tokens 也是 0,意味着你的请求从未触发过缓存创建。下面 7 个反模式按这种症状从最常见到最隐蔽排序。

反模式 1:在动态内容上设置 cache_control

这是新手最常犯的错。你想缓存 system prompt + 用户输入,顺手把 cache_control 打在用户消息上。但用户消息每轮都不一样,缓存创建后立刻失效,下一轮从头再建,永远命中不了。

❌ 错误

const message = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "你是一个代码审查助手...(2K tokens 的 system prompt)",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: userQuery,                        // ← 每次都不一样
          cache_control: { type: "ephemeral" }    // ← 缓存这块没意义
        }
      ]
    }
  ]
});

// 结果:
// cache_creation_input_tokens: 2050  (每次都重建)
// cache_read_input_tokens: 0         (永远不命中)

✅ 修复

const message = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "你是一个代码审查助手...(2K tokens 的 system prompt)",
      cache_control: { type: "ephemeral" }       // ← 缓存稳定的 system
    }
  ],
  messages: [
    { role: "user", content: userQuery }         // ← 用户内容不打 cache_control
  ]
});

// 第一次:cache_creation_input_tokens: 2050
// 第二次起:cache_read_input_tokens: 2050,只为新增的 userQuery 付全价

原则:cache_control 只打在长期不变的内容末尾。变的部分往后放,不打断点。

反模式 2:断点放在变化最频繁的位置

稍微进阶的版本:你知道要缓存稳定内容,但你的"稳定 system prompt"末尾又拼了一个用户 ID 或会话时间戳。看起来人畜无害的一句"当前用户:user_42",每个用户都不同,意味着每个用户都建一份新缓存,跨用户完全无法复用。

❌ 错误

function buildSystemPrompt(userId, sessionTime) {
  return `你是 BUZZ 的助手,负责回答关于 API 的问题。
项目文档如下:
... (10K tokens 的项目文档) ...

当前用户:${userId}
会话开始时间:${sessionTime}`;
}

const message = await anthropic.messages.create({
  model: "claude-opus-4-8",
  system: [
    {
      type: "text",
      text: buildSystemPrompt(userId, sessionTime),
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [...]
});

// 结果:每个 (userId, sessionTime) 组合都是一次新建
// cache_creation_input_tokens: 10050  (重建)
// cache_read_input_tokens: 0          (跨用户/跨会话不命中)

✅ 修复

// 把动态部分挪到 messages 里,system 保持纯静态
const STATIC_SYSTEM = `你是 BUZZ 的助手,负责回答关于 API 的问题。
项目文档如下:
... (10K tokens 的项目文档) ...`;

const message = await anthropic.messages.create({
  model: "claude-opus-4-8",
  system: [
    {
      type: "text",
      text: STATIC_SYSTEM,
      cache_control: { type: "ephemeral" }   // ← 跨所有用户共享
    }
  ],
  messages: [
    {
      role: "user",
      content: `[元数据] 用户:${userId} 时间:${sessionTime}\n\n${userQuery}`
    }
  ]
});

// 结果:第一个用户首次请求建立缓存,之后所有用户都命中
// cache_read_input_tokens: 10050

把动态片段(用户 ID、时间、随机种子、session token)从被缓存的前缀里挪出去,放到 messages 里或者放到 cache_control 之后。

反模式 3:4 个断点用错位置

Anthropic 给你 4 个 cache_control 断点。很多人不知道这点,只用 1 个;或者知道有 4 个但用错位置,比如把 4 个全打在前缀的末尾,等于只生效一个。

正确用法:让 4 个断点对应稳定性递减的 4 段内容。这样即使最末段在变,前面 3 段还能命中。

❌ 错误(4 个断点全堆在末尾)

// tools / system / docs / examples 都没打,只在 user 消息开头打了 4 次
{
  tools: [...],
  system: "...",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "项目文档...", cache_control: {type: "ephemeral"} },
        { type: "text", text: "few-shot 示例...", cache_control: {type: "ephemeral"} },
        { type: "text", text: "上下文...", cache_control: {type: "ephemeral"} },
        { type: "text", text: userQuery, cache_control: {type: "ephemeral"} }
      ]
    }
  ]
}

// 4 个断点全在最后一个用户消息里,而 userQuery 每次变
// 实际只命中第一个断点之前的内容(前 3 块只重复建)

✅ 修复(按稳定性递减分布)

{
  tools: [
    // ... 工具定义 ...
    // 最后一个 tool 上打第一个断点(tools 几乎不变)
    { name: "last_tool", ..., cache_control: { type: "ephemeral" } }
  ],
  system: [
    {
      type: "text",
      text: STATIC_SYSTEM_PROMPT,
      cache_control: { type: "ephemeral" }    // 第二个断点
    }
  ],
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: ragDocuments,                  // RAG 文档,每个 query 不同但
          cache_control: { type: "ephemeral" } // 同一 query 多轮交互可复用
        },                                     // 第三个断点
        {
          type: "text",
          text: fewShotExamples,
          cache_control: { type: "ephemeral" } // 第四个断点
        },
        { type: "text", text: userQuery }      // 不打断点
      ]
    }
  ]
}

// 即使 userQuery 变了,前 4 个断点的内容都能命中

排布原则:tools(几乎永不变) → system(稳定) → 文档/RAG(中期稳定) → few-shot(短期稳定) → user 消息(每次变),前 4 段每段末尾打一个断点。

反模式 4:时间戳 / UUID 进 prompt

这是最隐蔽的杀手。你以为 system prompt 是静态的,但里面藏着 new Date().toISOString() 或 uuid.v4()。每次请求生成的字符串都不一样,前缀就断了,缓存永远建不起来。

❌ 错误

function getSystemPrompt() {
  return `当前时间:${new Date().toISOString()}
你是一个助手...(后续 5K tokens)`;
}

await anthropic.messages.create({
  system: [
    { type: "text", text: getSystemPrompt(), cache_control: {type: "ephemeral"} }
  ],
  messages: [...]
});

// 每次请求 new Date() 都不同 → 缓存前缀永远不一致
// cache_creation_input_tokens: 5050 (每次重建)
// cache_read_input_tokens: 0

✅ 修复

// 把时间戳挪到 cache_control 之后,或者挪到 messages
const STATIC_SYSTEM = `你是一个助手...(5K tokens)`;

await anthropic.messages.create({
  system: [
    { type: "text", text: STATIC_SYSTEM, cache_control: {type: "ephemeral"} }
  ],
  messages: [
    {
      role: "user",
      content: `[当前时间:${new Date().toISOString()}]\n\n${userQuery}`
    }
  ]
});

// 缓存前缀稳定,跨所有请求命中

常见的"前缀污染源",自查列表:

• Date.now() / new Date().toISOString()
• uuid.v4() / crypto.randomUUID()
• Git commit SHA / build version
• 请求 ID / trace ID
• 用户 / 租户 ID(同一租户内可以保留,跨租户必须挪走)
• 动态拼接的目录路径(含临时目录名)

反模式 5:缓存命中阈值不够 1024 tokens

你的 system prompt 写得很精炼,只有 800 tokens。打了 cache_control,但 usage 永远是 cache_creation_input_tokens: 0。

原因:Sonnet 和 Opus 的最低缓存阈值是 1024 tokens,Haiku 是 2048 tokens。低于阈值 Anthropic 直接不建缓存,cache_control 被忽略。

❌ 错误

const SHORT_SYSTEM = "你是一个 SQL 优化助手,擅长 PostgreSQL 索引设计。";
// 大约 30 tokens

await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    { type: "text", text: SHORT_SYSTEM, cache_control: {type: "ephemeral"} }
  ],
  messages: [...]
});

// 30 tokens < 1024,cache_control 被忽略
// cache_creation_input_tokens: 0
// cache_read_input_tokens: 0

✅ 修复(把可缓存内容堆到阈值以上)

// 把更多稳定内容(few-shot 例子、schema 定义、规则文档)塞到断点前
const RICH_SYSTEM = `你是一个 SQL 优化助手...

# 数据库 schema
${schemaDDL}                        // 8K tokens 的 DDL

# few-shot 示例
${optimizationExamples}             // 4K tokens 的优化案例

# 规则
${rulesDoc}                         // 3K tokens 的规则
`;
// 总计 ~15K tokens,远超阈值

await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    { type: "text", text: RICH_SYSTEM, cache_control: {type: "ephemeral"} }
  ],
  messages: [...]
});

// cache_creation_input_tokens: 15000 (首次)
// cache_read_input_tokens: 15000     (后续命中)

反过来说,如果你的整个 prompt 不到 1024 tokens,根本没必要打 cache_control,模型本身就快。

反模式 6:跨用户共享 system prompt 含 user-specific 内容

多租户场景下,你想把"通用平台 system prompt"做成一份在所有用户间共享。但你不小心在里面拼了用户级数据(用户偏好、历史记录),结果每个用户都建一份独立缓存,平台总缓存命中率被稀释到接近 0。

❌ 错误

function buildSystem(user) {
  return `你是 BUZZ 助手。

# 平台规则
${PLATFORM_RULES}              // 6K tokens 全局共享

# 用户偏好
语言:${user.language}          // ← 每个用户不同
时区:${user.timezone}
风格:${user.writingStyle}
最近 5 条历史:${user.recentHistory}   // ← 每用户每会话不同
`;
}

await anthropic.messages.create({
  system: [
    { type: "text", text: buildSystem(user), cache_control: {type: "ephemeral"} }
  ]
});

// 每个用户独立缓存
// 1000 个用户 = 1000 份独立 6K 缓存,首次都全价
// 整体命中率被稀释

✅ 修复(分层 cache_control)

// 把"全局共享"和"用户专属"切分开,分别打断点
await anthropic.messages.create({
  system: [
    {
      type: "text",
      text: PLATFORM_RULES,           // 6K tokens 平台共享
      cache_control: { type: "ephemeral" }    // 第一个断点,跨用户命中
    },
    {
      type: "text",
      text: buildUserContext(user),   // 1.5K tokens 用户专属
      cache_control: { type: "ephemeral" }    // 第二个断点,同用户多轮命中
    }
  ],
  messages: [...]
});

// 第一个断点:全平台所有用户共享缓存(高命中)
// 第二个断点:每个用户独立,但同一用户多轮会话都能命中

顺序很关键:共享内容必须在前,用户专属内容在后。前缀匹配是从头开始的,反过来排列会让共享部分也变成 user-specific。

反模式 7:走中转站 / 网关时 cache_control 字段被剥

这一条最让人崩溃 —— 你的代码完全正确,本地直连 Anthropic 命中率 95%,但接到某个中转站后命中率掉到 0,cache_creation_input_tokens 永远是 0。原因是中转站主动剥掉了 cache_control 字段。

为什么剥?三个动机:

• 架构限制:它们做了路由 / 缓存 / 改写,内部状态机无法稳定保持 cache_control 的字节顺序。
• 计费套利:按全价计费,但只为命中收 10% 折扣价,差价进自己口袋。剥掉 cache_control 让上游不命中,他们自己也不用对账。
• 压缩 prompt:中转站做了 system prompt 注入或裁剪,前缀已经变了,cache_control 字段索性一并删除避免暴露篡改。

❌ 错误(走某些中转站)

// 你发送的请求(完全正确)
{
  "system": [
    {
      "type": "text",
      "text": "...(15K tokens)...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  ...
}

// 中转站转发给 Anthropic 时变成
{
  "system": [
    {
      "type": "text",
      "text": "...(15K tokens)..."
      // cache_control 字段被剥了 ❌
    }
  ],
  ...
}

// 你看到的 usage:
// input_tokens: 15050
// cache_creation_input_tokens: 0
// cache_read_input_tokens: 0
// 每次都全价

✅ 修复(走透明转发的网关)

# 用 BUZZ 这种字节级透传的网关
export ANTHROPIC_BASE_URL=https://buzzai.cc
export ANTHROPIC_AUTH_TOKEN=<你的 BUZZ key>

# 代码完全不用改
claude   # 或者 SDK 调用

// 走 BUZZ 后,cache_control 原样转发到 Anthropic
// 你看到的 usage 和直连 Anthropic 完全一致
{
  "input_tokens": 50,
  "cache_creation_input_tokens": 15000,    // 首次
  "cache_read_input_tokens": 0,
  "output_tokens": 200
}

// 第二次同样请求:
{
  "input_tokens": 50,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 15000,        // ← 命中
  "output_tokens": 200
}

判断网关有没有剥 cache_control 的方法很简单:

1. 同一个请求,本地直连 Anthropic 跑一次,记下 cache_creation_input_tokens。
2. 等 5 分钟内再发同样请求,看 cache_read_input_tokens 是否非 0。
3. 切换到目标网关,重复以上两步。
4. 如果网关下 cache_creation_input_tokens 显著小于直连,或 cache_read 一直为 0,基本可以确定它在剥字段。

BUZZ 的设计原则就是字节级透传:你发出去什么字节,Anthropic 收到什么字节;Anthropic 返回什么字节,你拿到什么字节。cache_control、tools 定义、JSON schema、Streaming 事件全部不动。

诊断工具:从 usage 字段读懂 cache 行为

遇到"打了 cache_control 但不省钱"时,别盲改代码,先把 usage 字段抄出来对照下表:

一段诊断代码,直接拷贝用

function diagnoseCache(usage) {
  const total = usage.input_tokens
              + (usage.cache_creation_input_tokens || 0)
              + (usage.cache_read_input_tokens || 0);

  const hitRate = (usage.cache_read_input_tokens || 0) / total;

  console.log(`
[Cache 诊断]
  本次新增输入:        ${usage.input_tokens}
  本次写入缓存:        ${usage.cache_creation_input_tokens || 0}
  本次命中缓存:        ${usage.cache_read_input_tokens || 0}
  本次输出:           ${usage.output_tokens}
  命中率:             ${(hitRate * 100).toFixed(1)}%
  状态:               ${
    hitRate > 0.8  ? '健康' :
    hitRate > 0.3  ? '可优化' :
    usage.cache_creation_input_tokens > 0 ? '前缀在变,反模式 2/4/6' :
    total < 1024   ? '不到 1024 阈值,反模式 5' :
    '前缀有问题或 cache_control 被剥,反模式 1/4/7'
  }
  `);
}

// 用法
const message = await client.messages.create({...});
diagnoseCache(message.usage);

实测:从 30% 到 92% 命中率

下面是一个典型的 RAG 应用,从有问题的初版迭代到最终稳态的过程。场景:用户问关于一份 50 页 PDF 文档的问题,每次会话平均 5-10 轮。

v6 到稳态的关键是:

• 4 个 cache_control 按稳定性递减分布
• 所有 user-specific 数据放进 messages,不进入缓存前缀
• 使用透明转发的网关,确保 cache_control 不被剥
• 5 分钟内连续多轮交互,5m TTL 持续刷新

从 v1 到 v6,单轮成本下降到原来的 14%,响应延迟也从平均 4.2s 降到 1.8s(命中部分跳过了 prefill)。

BUZZ 在这个链条里做了什么

说回反模式 7。BUZZ 作为 Anthropic API 网关,在 Prompt Cache 链条里只做一件事:什么都不做。

• cache_control 字段字节级透传,顺序、字段名、值都不动
• tools 数组顺序不重排
• system 内容不注入、不裁剪
• Streaming 事件按到达顺序逐个转发
• 响应里的 usage 字段完整透传,你看到的 cache_creation_input_tokens 和 cache_read_input_tokens 就是 Anthropic 返回的

这意味着你之前在直连 Anthropic 时调好的 cache_control 策略,接到 BUZZ 后行为完全一致。Claude Code 用 BUZZ 长会话能稳定 90%+ 命中率,就是因为 Claude Code 的 prompt 结构和 BUZZ 的透传策略天然匹配。

# 切到 BUZZ 不需要改代码
export ANTHROPIC_BASE_URL=https://buzzai.cc
export ANTHROPIC_AUTH_TOKEN=<你的 BUZZ key>

# Claude Code / Anthropic SDK / 自研 client 全都即开即用
claude

FAQ