2026-08-27·SDK 与工具

Claude Prompt Caching 2026 实战——四档计费机制、cache_control 断点策略、5-min 与 1-hour TTL 取舍、与 Batch API 叠加、多模态缓存（图片 / PDF block）、五种最常见失效场景（未达门槛 / 断点改动 / TTL 过期 / 模型命名空间错位 / cache_control 错位）。

Claude Prompt Caching 全解：把 Claude API 成本砍到 1/10 的实战（2026）

Q: cache read 比 base input 便宜多少？

90% off——cache read 的 token 系数是 0.1 倍 base price。但 cache write 是额外收费——5min TTL 1.25x、1hour TTL 2x。所以「净省」取决于命中率：100% 命中的情况下，10 次请求总成本 = 1.25 + 9 × 0.1 = 2.15 倍单次 base 价，相比不用 cache 的 10 倍，节省 78%。

Q: 5-min 还是 1-hour TTL？默认哪个？

默认 5-min TTL（type: "ephemeral"）——绝大多数场景够用。1-hour 仅在长跑 batch / 高频 RAG / 多轮 agent loop 三种场景下胜出，因为它 cache write 系数翻倍（2x vs 1.25x）。经验法则：先试 5-min，命中率不到 70% 再换 1-hour。

Q: Prompt Caching 能和 extended thinking 共用吗？

能，但有 trade-off。thinking 块也会被 cache——如果你在 system 里用 extended thinking 触发（带 budget_tokens），thinking 内容会进 cache。但 budget_tokens 改了会让 cache block 失效（cache key 含 thinking 参数）。实战建议：thinking 参数保持稳定，或者 cache 不含 thinking 的部分。

Q: 怎么验证 cache 真的生效？

看响应里的 usage 三个字段：cache_creation_input_tokens（>0 = 刚写入）、cache_read_input_tokens（>0 = 命中）、input_tokens（剩余未缓存部分）。第一次调用：cache_creation=1024, cache_read=0, input=N。后续命中：cache_creation=0, cache_read=1024, input=N。调试关键：如果你看到 cache_creation 反复>0、cache_read 一直是 0——你的 cache 配置错了了。

Q: 图片 / PDF 这种非文本 block 也能 cache 吗？

能。cache_control 适用于所有 content block 类型（text / image / tool_use / tool_result）——单个 image block 上限 ~1568×1568 px 或 5MB base64。实战场景：多 PDF RAG（每个 PDF 转 image block 加 cache_control）、长截图分析、Vision+text 混合 prompt。回报：10 轮对话场景 input token 节省约 90%（每轮~6000 token → ~600 token）。

Q: cache_control 失效了怎么排查？

按顺序查这 5 个：(1) 断点位置：必须标在「想缓存的最末 block」，不是 user message 前；(2) 门槛：Sonnet 4.5+ 要 1024+ token 才生效；(3) TTL：5min 内必须有命中请求，否则 cache 被清；(4) 模型一致：每个 model 独立 namespace，不能跨模型共享；(5) 内容稳定性：断点之前任何 byte 变了，整个 cache block 失效。调试起点：先看 usage.cache_creation_input_tokens == 0（完全没写）还是 cache_read_input_tokens == 0（写了但没命中）——前者是配置错，后者是断点错位。

Claude API 的 Prompt Caching 是 2024-10 推出、2025-2026 全面成熟的一项关键特性——在长 system prompt + RAG 大上下文场景下，重复 prefix 的 cache 命中成本仅 0.1 倍 base price。本文基于 platform.claude.com/docs/en/build-with-claude/prompt-caching 与 claude-cookbooks 实战 notebooks，讲清楚：四档计费机制、cache_control 断点策略、5-min vs 1-hour TTL 取舍、与 Batch API 叠加的实战模式，以及 2026 年最常见的失效场景。

TL;DR

Prompt Caching 把重复 prefix 的成本砍到 0.1 倍 base price（cache read）；cache write 额外收 1.25x（5min TTL）或 2x（1hour TTL）

通过 cache_control: { type: "ephemeral" } 标记断点——断点之前的所有 token 会被缓存

最低门槛：Sonnet 4.5+ 是 1024 token；Opus 4.5+ 是 4096 token。达不到门槛的输入不缓存

TTL：5-min（默认，1.25x write）/ 1-hour（2x write）—— 选 1-hour 的 ROI 仅在 5+ 轮对话或批量调用

叠加：prompt caching + batch API = 双重折扣（~60% 总成本）；但 batch 不能 stream 且 24h 才回

四档计费：从 1.0x 到 0.1 倍

2025-11 规范把每次 Claude API 调用的 token 成本拆成四档——理解它们才能算清 ROI：

| 档位 | 系数 | 何时发生 | |---|---|---| | base input | 1.0x | 第一次写入 cache，或 cache miss | | cache write（5min TTL） | 1.25x | 写入 5-min 缓存的额外成本（首次写入） | | cache write（1hour TTL） | 2.0x | 写入 1-hour 缓存的额外成本 | | cache read | 0.1x | 命中缓存的前缀 token |

直觉：cache write 一次贵 25%-100%，但 cache read 之后每条请求的前缀便宜 90%。只要命中次数足够多就赚。粗略 ROI 公式：

命中率 = cache_read / (cache_read + cache_write)
净节省 = (1.0x - 命中率 × 0.1x) - 命中率 × cache_write_系数 × 0.9

例子：1000 token system prompt + 100 token 真实问题，命中率 90%，5min TTL：

不缓存：1000 × 1.0 = 1000 tokens
缓存：   1000 × 1.25 = 1250 (首次) + 1000 × 0.1 = 100 (后续每次)
10 次：  1250 + 9 × 100 = 2150
vs 不缓存：10 × 1000 = 10000
节省：   78%

结论：长前缀 + 高频调用 = 必须开 cache；短前缀（< 1024 token）= 浪费钱。

cache_control 断点：模型在缓存什么

cache_control 是 messages 数组里每个 content block 上的可选字段（TypeScript SDK：{ type: "content", content: [...], cache_control: { type: "ephemeral" } }）。标记后，从 messages 开头到该断点（含）的所有 token 都会进入 cache。

断点的位置决定什么会被缓存。两种典型布局：

布局 1：单断点在 system 后——缓存整个 system prompt

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  system: [
    {
      type: "text",
      text: LONG_SYSTEM_PROMPT,  // 8000 token，包含 few-shot 示例、规则、文档
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [{ role: "user", content: userInput }]
});

布局 2：多断点分章节——按章节独立缓存（如长 system + 长文档库）

system: [
  { type: "text", text: ROLE_INSTRUCTIONS, cache_control: { type: "ephemeral" } },
  { type: "text", text: FEW_SHOT_EXAMPLES, cache_control: { type: "ephemeral" } },
  { type: "text", text: REFERENCE_DOCS }  // 不缓存——这段每轮不同
]

易错点：

cache_control 加在最后一个 system block 之后、第一个 user message 之前是常见反模式——应该把断点加在想缓存的最末尾 block 上
多个断点的开销是叠加的（每段独立写一次 cache）—— 用得太多反而贵
断点之前的内容必须是稳定的——一旦变了，整个 cache block 失效

5-min vs 1-hour TTL：怎么选

Anthropic 提供两个 TTL 选项：

type: "ephemeral"（默认，5-min 滚动）：每次 cache hit 把 TTL 续到当前时间 + 5min
type: "ephemeral-1h"（2025-Q3 新增，1-hour）：续到当前时间 + 1h

决策原则：

| 场景 | TTL | 原因 | |---|---|---| | 单轮交互（chat UI） | 5-min（ephemeral） | 用户不会回来，cache 在 5min 后空转 | | 多轮对话（同一 session） | 5-min | session 内续命；session 结束 cache 自然失效 | | 批量异步任务 | 5-min | batch 处理通常 < 24h，5min 窗口够 | | RAG + 高频检索 | 1-hour | 同一 query 模板反复用，cache 长期稳定 | | 长跑 agent loop | 1-hour | 同一 plan/execute 模板跨多轮 |

直觉：cache write 系数 (1.25x vs 2x) 不是关键，关键是命中率。1-hour TTL 只有在 cache 至少 5 次以上复用时才赢——少次复用连 5-min 都不该用。

与 Batch API 叠加：双重折扣

Prompt Caching 与 Batch API 可叠加——但场景不同：

Prompt Caching：实时 / 近流调用，节省重复前缀成本
Batch API：异步批处理（24h 内返回），所有 token 50% off

两者一起用：长 system prompt + 批量异步任务 = 双重折扣 ~60% 总成本。但有几个 trade-off：

Batch API 不支持 stream——必须等所有请求完成
Batch API 限流：100k 请求或 256MB 总输入 / 单批，24h 过期，29 天内可下载结果
Batch API 不支持 max_tokens: 0（cache pre-warming 用法）—— 必须等真实请求触发 cache

实战模式：先 dry-run 同步接口验证 params，再投 batch——batch 内部会用上你之前 warm 的 cache。

失效场景：什么时候 cache 不会命中

5 种最常见的 cache miss 原因：

未达最低门槛：Sonnet 4.5+ 需要 1024 token；Opus 4.5+ 需要 4096 token。短输入直接不缓存。
断点改了：每个请求都要重新算整个 cache block 的 hash。改一个字符就 invalidate。
TTL 过期：5min 内没有命中请求，cache 自动清。下次写入又要重新 cache write。
模型不同：Haiku 写的 cache，Sonnet 不能读——每个 model 独立 cache namespace。
cache_control 标记错位：把断点加在错的 block 上，或断点放错位置——导致想缓存的部分被遗漏。

调试方法：

响应里看 usage.cache_creation_input_tokens 与 usage.cache_read_input_tokens 字段——前者>0 表示写入，后者>0 表示命中
cache_read_input_tokens == 0 + 高频调用 = cache 配置错了
监控 cache_creation_input_tokens 与 cache_read_input_tokens 的比例：理想是 1:N（一次写入 N 次读取）

预防：CI 里加一个cache 命中率指标——每次调用后断言 cache_read_input_tokens / total_input_tokens > 0.5（连续 5 次平均），不达标就 fail。

多模态缓存：图片 / 文档 block 也能 cache

cache_control 同样适用于非文本 block——这是 2025-Q3 后才完全稳定的能力：

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "你是文档分析助手。回答用户关于附件的问题。",
      cache_control: { type: "ephemeral" }
    },
    // 图片 block 也参与缓存
    {
      type: "image",
      source: {
        type: "base64",
        media_type: "image/png",
        data: BASE64_PNG_OF_LONG_PDF_PAGE  // 大图（如 PDF 转 PNG 后 2MB+）
      },
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [{ role: "user", content: "图里第 3 页第 5 段的数字是多少？" }]
});

实战场景：

多 PDF RAG：每个 PDF 转成 image block（最高 1568×1568 px 限制），加 cache_control。多 PDF 多轮问答场景，反复问同一组 PDF 时命中率高
长截图分析：产品 bug 截图（多张）、UI 评审文档，重复截图的多轮对话 cache 命中
Vision + text 混合：图片作为系统背景（"看这张参考图"），多轮对话复用

注意事项：

单个 image block 上限 1568×1568 px 或 ~5MB base64——超出会被 reject
图片 hash 算法与文本不同，但 cache 行为一致：5-min TTL / cache_creation / cache_read 都独立计费
cache_creation 系数 1.25x 同样适用 image block（写入贵 25%）

回报：RAG 场景里若每个 PDF 转 PNG 都 ~1MB base64，不开 cache 每轮 ~6000 token；开 cache 后每轮 ~600 token（cache_read 0.1x），10 轮对话省 90% input 成本。

常见问题

cache read 比 base input 便宜多少？

90% off——cache read 的 token 系数是 0.1 倍 base price。但 cache write 是额外收费——5min TTL 1.25x、1hour TTL 2x。所以"净省"取决于命中率：100% 命中的情况下，10 次请求总成本 = 1.25 + 9 × 0.1 = 2.15 倍单次 base 价，相比不用 cache 的 10 倍，节省 78%。

5-min 还是 1-hour TTL？默认哪个？

默认 5-min TTL（type: "ephemeral"）——绝大多数场景够用。1-hour 仅在长跑 batch / 高频 RAG / 多轮 agent loop 三种场景下胜出，因为它 cache write 系数翻倍（2x vs 1.25x）。经验法则：先试 5-min，命中率不到 70% 再换 1-hour。

Prompt Caching 能和 extended thinking 共用吗？

能，但有 trade-off。thinking 块也会被 cache——如果你在 system 里用 extended thinking 触发（带 budget_tokens），thinking 内容会进 cache。但 budget_tokens 改了会让 cache block 失效（cache key 含 thinking 参数）。实战建议：thinking 参数保持稳定，或者 cache 不含 thinking 的部分。

怎么验证 cache 真的生效？

看响应里的 usage 三个字段：

cache_creation_input_tokens（>0 = 刚写入）
cache_read_input_tokens（>0 = 命中）
input_tokens（剩余未缓存部分）

第一次调用：cache_creation=1024, cache_read=0, input=N。后续命中：cache_creation=0, cache_read=1024, input=N。 调试关键：如果你看到 cache_creation 反复>0、cache_read 一直是 0——你的 cache 配置有问题。

图片 / PDF 这种非文本 block 也能 cache 吗？

能。cache_control 适用于所有 content block 类型（text / image / tool_use / tool_result）——单个 image block 上限 ~1568×1568 px 或 5MB base64。实战场景：多 PDF RAG（每个 PDF 转 image block 加 cache_control）、长截图分析、Vision+text 混合 prompt。回报：10 轮对话场景 input token 节省约 90%（每轮~6000 token → ~600 token）。

cache_control 失效了怎么排查？

按顺序查这 5 个：(1) 断点位置：必须标在「想缓存的最末 block」，不是 user message 前；(2) 门槛：Sonnet 4.5+ 要 1024+ token 才生效；(3) TTL：5min 内必须有命中请求，否则 cache 被清；(4) 模型一致：每个 model 独立 namespace，不能跨模型共享；(5) 内容稳定性：断点之前任何 byte 变了，整个 cache block 失效。调试起点：先看 usage.cache_creation_input_tokens == 0（完全没写）还是 cache_read_input_tokens == 0（写了但没命中）——前者是配置错，后者是断点错位。

官方参考资料

本文基于截至 2026 年 8 月的 Anthropic API 价格与缓存机制；价格调整以官方 Pricing 页为准。建议每季度 review 一次 cache 命中率指标。