Prompt Cache 怎么用？Claude / GPT 缓存机制与降本实战 | API Platform 文档

addtoken_geek

95人浏览 · 2026-07-13 21:02:52

addtoken_geek · 2026-07-13 21:02:52 发布

博客 / Prompt Cache 怎么用？Claude / GPT 缓存机制与降本实战

Claude 与 OpenAI Prompt Cache 缓存机制详解，含原理、代码示例、计费对比与降本实战测算，助你降低 LLM API 调用成本。

本文覆盖 Claude 和 OpenAI 两家的 Prompt Cache 机制，包含原理、代码、计费模型、降本测算和常见踩坑点。如果你正在做 Agent、RAG 或长上下文应用，建议先看第四节降本测算，确认缓存对你的收益。

Overview

# Prompt Cache 怎么用？Claude / GPT 缓存机制与降本实战

同样调用 Claude Sonnet 4 处理一个 50K token 的长上下文任务，有人每千次成本 $250，有人只要 $35。差距不在模型，在于有没有打开 Prompt Cache。

如果你在做长上下文应用、Agent 工作流、RAG 系统，或者大量重复调用同一个 system prompt，Prompt Cache 是目前 LLM API 里 ROI 最高的一项能力——但很多开发者要么没听说过，要么听说了却用错。这篇文章把 Claude 和 OpenAI 两家的缓存机制讲清楚：原理、参数、代码、降本测算、踩坑点，一次说透。

一、Prompt Cache 是什么：用空间换时间

Prompt Cache 的本质很朴素：LLM 推理时，对 prompt 的前缀部分做 KV Cache 持久化。下次请求如果前缀完全相同，就直接复用已算好的中间结果，跳过最贵的预填充（prefill）阶段。

这个机制不是 Anthropic 或 OpenAI 的发明，而是从 vLLM、SGLang 这类推理引擎里的 PagedAttention、RadixAttention 演化而来。区别在于：开源引擎的缓存是单机内存级的，请求结束就释放；而厂商 API 把它做成了跨请求、跨会话的持久化能力，按使用量计费。

为什么要做缓存？因为 prefill 阶段是 Transformer 推理里最贵的部分。一个 100K token 的 prompt，每生成一个输出 token 之前，都要先把这 100K token 全部过一遍 attention 计算。如果不缓存，你每发一次请求就重算一次；如果缓存了，第二次起这 100K token 的计算成本直接归零（只付一个读取费）。

所以 Prompt Cache 适用于一个明确场景：相同前缀、高频重复调用。 典型场景包括：

- 长 system prompt + 短用户输入：Agent 框架里固定的角色设定、工具描述、规则文档 - 多轮对话：每一轮的上下文都包含之前所有轮次，前缀天然重叠 - RAG 系统：检索回来的大段文档作为前缀，用户问题作为后缀 - 代码助手：项目代码库作为上下文，反复询问不同问题 - 批量处理同质任务：同一份 few-shot 示例 + 不同输入

如果你的应用是"一次性的、前缀都不一样"，Prompt Cache 帮不到你,但这种情况其实很少。

二、Claude 的 Prompt Caching：手动控制、定价激进

Anthropic 在 2024 年 8 月推出 Prompt Caching，目前已是正式能力（不再是 beta）。它的核心特点是手动控制、显式标记、定价激进。

2.1 工作原理：用 cache_control 标记缓存断点

Claude 的缓存不是自动的，你需要在请求里显式标记哪些内容块要被缓存。通过 cache_control 字段实现：

import anthropic

client = anthropic.Anthropic(
    api_key="your-api-key",
    base_url="https://api.addtoken.top/v1"  # 中转站示例
)

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "<长达 50000 token 的项目规范文档...>"
        },
        {
            "type": "text",
            "text": "<工具使用说明...>",
            "cache_control": {"type": "ephemeral"}  # 在这里标记缓存断点
        }
    ],
    messages=[
        {"role": "user", "content": "请帮我实现用户登录模块"}
    ]
)

cache_control 可以放在 system、messages、tools 任何一个内容块上。Claude 会把从请求开始到带有 cache_control 标记的内容块为止作为一个可缓存的前缀（cacheable prefix）。

关键限制：每个请求最多 4 个 cache breakpoint。 这意味着你不能把 prompt 切得太碎，要规划好哪些段落是稳定不变的。

我们用claude code 或OpenAI Codex ，或者cursor,trae等代码工具时，完全不用担心，工具中已经帮你做好了设置。但是若自己做agent工作流，需要自己手动添加 cache_control 标记，且非常推荐要添加。

2.2 计费模型：写入贵 25%，读取便宜 90%

Claude 的缓存定价是行业内最激进的，也是它最大的卖点：

price1
price1

关键判断：缓存写入比标准价贵 25%，但读取便宜 90%。所以只要同一份前缀被读取 ≥ 2 次，就已经回本。 读取次数越多，节省越多。一个被读取 10 次的前缀，整体输入成本能降到原来的 22% 左右。

2.3 最小缓存阈值：只有足够长的 Prompt 才能建立缓存

并不是任何长度的 Prompt 都可以启用 Prompt Cache。Anthropic 为不同模型设置了最小缓存长度（Minimum Cacheable Prompt Length），只有 cache_control 之前的内容达到对应阈值，系统才会建立缓存。

需要注意的是，该阈值因模型而异，并可能随着新模型发布而调整。例如，目前 Claude Sonnet 5 的最小缓存长度为 1024 Tokens，而 Claude Opus 4.5、Claude Haiku 4.5 等模型则要求 4096 Tokens

如果 cache_control 之前的内容未达到模型要求：

不会建立 Prompt Cache；不会收取缓存写入费用；请求仍会按普通输入 Token 正常计费； API 不会返回错误，而是静默跳过缓存。

因此，开发者可以通过响应中的 usage 字段（如 cache_creation_input_tokens 和 cache_read_input_tokens）确认缓存是否真正生效，而不要仅凭是否设置了 cache_control 来判断。

2.4 缓存生命周期（TTL）：默认 5 分钟，可扩展至 1 小时

这里有一个2026 年的关键变化，很多旧教程没跟上。

Prompt Cache 并不是永久保存。Anthropic 默认提供 5 分钟 TTL（Time To Live），即缓存会在最后一次命中后保留至少 5 分钟。每次成功命中缓存都会自动刷新 TTL，因此只要应用持续发送请求，缓存可以一直保持有效；只有当连续超过 5 分钟未使用时，缓存才会失效并需要重新建立。

也就是说你吃个饭的功夫，只要超过5分钟没有使用，缓存就会失效。再次创建缓存时，需要重新输入所有内容，费用暴涨。

如果你需要更长的缓存窗口（比如批量处理任务间隔超过 5 分钟），需要显式声明 1 小时 TTL：

Python

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

1 小时 TTL 的写入费稍贵（约 1.5× 标准价），但读取价不变。对于间隔较长的批量任务，这个依然划算。

从 Claude Code v2.1.108 开始，可以通过环境变量请求 1 小时 Prompt Cache：

Linux/macOS：

export ENABLE_PROMPT_CACHING_1H=1
claude

永久生效：

echo 'export ENABLE_PROMPT_CACHING_1H=1' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell：

env:ENABLE_PROMPT_CACHING_1H="1"
claude

或者永久生效：

setx ENABLE_PROMPT_CACHING_1H 1

2.5 响应里看缓存命中情况

调用完成后，response 的 usage 字段会返回三类 token 数： json

{
  "usage": {
    "input_tokens": 120,           // 未命中缓存、也未写入缓存的输入 token
    "cache_creation_input_tokens": 50000,  // 这次写入缓存的 token
    "cache_read_input_tokens": 0,   // 这次命中缓存的 token
    "output_tokens": 850
  }
}

第一次调用：cache_creation_input_tokens ≈ 50000，cache_read_input_tokens = 0。第二次调用相同前缀：cache_creation_input_tokens = 0，cache_read_input_tokens ≈ 50000。

监控这两个字段的比例，是评估你缓存策略是否合理的核心指标。

三、OpenAI 的 Prompt Caching：自动开启、前缀匹配

OpenAI 在 2024 年 10 月推出 Prompt Caching，策略与 Anthropic 完全相反——全自动、零配置、收益温和。

3.1 工作原理：自动 prefix 匹配，无需改代码

OpenAI 的缓存对开发者完全透明：

- 任何 ≥ 1024 token 的 prompt 自动进入缓存候选池 - 系统按 prompt 的前缀做哈希路由，把请求分发到同一台推理机 - 如果前缀已缓存，自动命中

你不需要改任何代码。 调用方式、参数、消息结构都不变，账单自动按缓存价计算。

3.2 计费模型：写入不收费，读取打 5 折

OpenAI 的定价温和得多：

price3
price3

注意几个细节：

- GPT-5.6 之前的模型（GPT-4o、GPT-4 Turbo 等），写入不额外收费 - GPT-5.6 及之后的新模型，写入按 1.25× 计费（向 Anthropic 看齐） - 读取统一是 0.5×，没有 Anthropic 的 0.1× 那么激进

对比 Claude：OpenAI 命中时的单次成本是 Claude 的 5 倍（0.5× vs 0.1×），但写入时是免费的。 所以 OpenAI 的策略更适合"前缀不稳定、偶尔命中"的场景，Claude 更适合"前缀非常稳定、高频命中"的场景。

3.3 最小匹配：1024 token 连续前缀

OpenAI 的匹配规则比 Anthropic 严格：

- prompt 必须至少有 1024 token - 前 1024 token 必须完全连续一致才能命中 - 1024 token 之后的部分按更细粒度匹配

这意味着哪怕你的 system prompt 只差一个字符，也会从那一点开始完全 miss。所以用 OpenAI 缓存时，system prompt 的开头部分一定要稳定——不要在前面放时间戳、不要放随机 ID、不要放用户名。把这些动态内容放到 prompt 末尾。

3.4 TTL：约 5–10 分钟空闲即过期

OpenAI 没有公开承诺精确的 TTL，官方文档表述为"off-peak 期间缓存可能保留更久，繁忙期间可能更短"。实测下来大概是 5–10 分钟无访问就失效，繁忙时段可能更短。

OpenAI 不提供 1 小时 TTL 选项，这是它和 Claude 的一个关键差异。如果你的批量任务间隔较长，OpenAI 这边的命中率会明显下降。

3.5 响应里看命中

OpenAI 的 usage 字段：

json代码

{
  "usage": {
    "prompt_tokens": 51000,        // 总输入 token
    "prompt_tokens_details": {
      "cached_tokens": 50000       // 其中命中缓存的部分
    },
    "completion_tokens": 850
  }
}

cached_tokens / prompt_tokens 就是你的命中率。

四、降本实战：一个真实场景的测算

抽象讲完，看一个具体例子。假设你在做一个代码助手：

- 固定上下文：项目代码 + 规范文档 = 80K token - 用户问题：平均 500 token - 每天调用：10000 次 - 模型：Claude Sonnet 4（$3/MTok 输入）

不启用缓存：

- 每天输入成本 = 10000 × (80000 + 500) / 1e6 × $3 = $2415 - 月成本 ≈ $72,450

启用 Claude Prompt Cache（假设 95% 命中率）：

- 第一次写入：80K × 1.25 = 100K 等效 token - 后续 9999 次读取：80000 × 0.1 × 9999 = 7,999,200 等效 token - 用户问题部分：500 × 10000 = 5,000,000 token（不缓存） - 总等效输入 = 7,999,200 + 100,000 + 5,000,000 ≈ 13.1M token - 每天成本 = 13.1M / 1e6 × $3 = $39.3 - 月成本 ≈ $1179

降本比例：约 98.4%。

换成 OpenAI GPT-4o（$2.5/MTok 输入，缓存读取 0.5×）：

- 总等效输入 ≈ 80000 × 0.5 × 9999 + 500 × 10000 ≈ 45M token - 每天成本 = 45M / 1e6 × $2.5 = $112.5 - 月成本 ≈ $3375

对比结论：在高频长前缀场景下，Claude Prompt Cache 的成本优势是 OpenAI 的 3 倍以上。 但前提是你的前缀足够稳定、命中率足够高。如果命中率只有 50%，Claude 的写入溢价反而会让成本逼近甚至超过 OpenAI。

五、五个常见踩坑点

实际接入过程中，下面这些问题反复出现：

坑 1：动态内容放在前面，缓存永远不命中

错误写法（python）：

system = f"""
当前时间：{datetime.now()}
用户ID：{user_id}
项目规范：{project_spec}  # 这才是稳定的大段内容
"""

时间戳和用户 ID 让前缀每次都变，缓存永远 miss。正确做法：把稳定的大段内容放前面，动态信息放后面。

system = [
    {"type": "text", "text": project_spec, "cache_control": {"type": "ephemeral"}},
    {"type": "text", "text": f"当前时间：{datetime.now()}\n用户ID：{user_id}"}
]

坑 2：缓存断点放错位置

cache_control 标记的是"缓存到这里为止"，不是"从这里开始"。如果你把断点放在 system prompt 的中间，那只有前半部分会被缓存，后半部分每次都要重算。

经验法则：断点放在内容块的最末尾，让缓存覆盖最大范围。

坑 3：忽视 5 分钟 TTL，批量任务莫名其妙变贵

2026 年 3 月 Anthropic 默认 TTL 降到 5 分钟后，很多批量任务的成本突然翻倍。原因是任务间隔超过 5 分钟，缓存已失效，每次都重新写入。

应对： 评估任务间隔，超过 5 分钟的批量任务显式声明 ttl: "1h"。

坑 4：用 OpenAI 时把 system 拆成多个 message

OpenAI 的缓存按 token 流的连续前缀匹配。如果你把 system 拆成多条 message：

messages = [
    {"role": "system", "content": "规则A"},
    {"role": "system", "content": "规则B"},
    {"role": "system", "content": "规则C"},
    {"role": "user", "content": "..."}
]

虽然功能等价，但 OpenAI 内部会把它们拼成一条 token 流，前缀匹配仍然有效。但如果你在不同请求里用了不同的拼接顺序，命中率会大幅下降。保持 system 的结构稳定。

坑 5：只看 input_tokens，不看 cache_creation 和 cache_read

很多开发者接入缓存后只盯着总 input_tokens 数量，没发现缓存其实根本没命中。正确的监控指标是：

- cache_read_input_tokens / (cache_read_input_tokens + cache_creation_input_tokens + input_tokens) = 命中率 - 命中率 90% 时，说明缓存策略健康

六、选型建议：Claude 还是 OpenAI？

基于上面的分析，给一个直接的选型建议：

选 Claude Prompt Cache 的场景：

- 长上下文（>20K token）+ 高频重复调用（>10 次/小时） - Agent 框架，固定 system prompt + 工具定义 - 代码助手、文档问答、企业知识库 - 需要精确控制缓存边界

选 OpenAI Prompt Cache 的场景：

- 前缀不太稳定，命中率预期 30%–60% - 不想改代码，希望透明降本 - 任务间隔超过 5 分钟但又不到 1 小时 - 多模型混用，希望统一调用方式

两个都用：

- 复杂业务里，固定上下文部分走 Claude 缓存（吃 0.1× 读取价） - 短上下文动态部分走 GPT-4o（吃自动缓存的便利性） - 通过 API 中转层（如 addtoken.top 这类 OpenAI 兼容接口）统一调度，按场景路由

七、几个高频问题

Q1：第三方 API 中转会破坏缓存吗？

不一定。取决于中转层是否做了请求哈希路由。一个合格的 OpenAI 兼容中转层应该保留原始请求结构透传给上游，这样前缀匹配仍然有效。但如果中转层在请求里插入了广告、水印、用户标识等动态内容，缓存会被破坏。选择中转服务时要确认这一点。

本文示例使用 Token补给站（https://addtoken.top）进行测试。平台提供 OpenAI 与 Anthropic 兼容 API，保持与官方协议一致，支持透传 Prompt Caching 等相关字段，方便开发者在不修改业务代码的情况下接入和验证缓存能力。实际缓存是否命中仍以 Anthropic 官方缓存策略和请求内容为准。

Q2：缓存会泄漏其他用户的内容吗？

不会。Anthropic 和 OpenAI 都明确说明缓存是按账号/组织隔离的。你的缓存只有你自己的后续请求能命中。

Q3：缓存命中会降低输出质量吗？

不会。缓存的是 prefill 阶段的 KV 中间结果，对模型本身是等价的。命中和不命中，模型看到的输入完全一样，输出概率分布也完全一样。

Q4：为什么我的 `cache_creation_input_tokens` 比预期多很多？

最常见原因是同一个请求里有多个 cache breakpoint，且每个断点都触发了写入。检查你的 cache_control 数量，4 个断点意味着最多 4 次写入。

Q5：Claude Code 自动用 Prompt Cache 吗？

是的。Claude Code 在内部已经接入了 Prompt Caching，CLAUDE.md 文件、项目上下文、对话历史都会自动缓存。这也是为什么 Claude Code 在长会话场景下相对其他工具成本更低的原因之一。