Prompt Caching 实战：缓存命中省 90%，AI 编程成本直降

如果你在使用 Claude Code、Cursor 或其他 AI 编程工具，你可能已经注意到 API 账单上的一行数字：cache_read_input_tokens。这个看似不起眼的字段，可能为你节省高达 90% 的输入 token 费用。

Prompt Caching（提示缓存）是近年来 AI API 领域最重要的成本优化技术之一。本文将深入解析其工作原理、三大供应商的实现差异，以及如何在实际项目中最大化利用缓存来降低成本。

---

什么是 Prompt Caching

Prompt Caching 的核心思想非常直观：如果两次 API 调用的前缀内容相同，第二次调用就不需要重新处理这些重复内容。

在没有缓存的情况下，每次 API 调用都需要处理完整的输入——包括 system prompt、工具定义、历史对话等。这些内容在连续的多轮对话中往往大量重复。Prompt Caching 机制允许 API 服务端将这些重复的前缀内容缓存起来，后续调用直接复用，仅对新增部分进行完整处理。

举个具体例子：

1. 第一次调用：发送 system prompt（8K tokens）+ 用户消息（200 tokens）= 处理 8,200 tokens，全部按标准价格计费
2. 第二次调用：发送同样的 system prompt（8K tokens）+ 新的用户消息（300 tokens）= 8K tokens 命中缓存（按缓存价格计费），仅 300 tokens 按标准价格计费

缓存命中的 tokens 价格远低于标准价格——以 Anthropic 为例，缓存命中的输入 tokens 仅需标准价格的 10%。这意味着你的 8K system prompt 在第二次调用时，只花原来 1/10 的价格。

关键概念：Prompt Caching 是服务端行为，缓存发生在 API 供应商的基础设施中。开发者不需要自己管理缓存存储，只需要遵循正确的请求构造方式。

---

三大供应商 Prompt Caching 对比

目前三大主流 AI API 供应商都支持 Prompt Caching，但实现方式和定价策略各有不同。

Anthropic：显式缓存，折扣最大

Anthropic 的 Prompt Caching 采用显式标记方式，需要在请求中通过 cache_control 字段指定哪些内容需要缓存。优点是开发者对缓存行为有完全掌控，缺点是需要修改请求格式。

缓存命中时折扣高达 90%，是三家中最大的。但首次缓存写入会多收 25% 的费用。对于反复使用相同前缀的场景（如 AI 编程工具），综合下来依然非常划算。

OpenAI：全自动缓存，无感体验

OpenAI 的 Prompt Caching 完全自动化，开发者无需做任何修改。API 服务端会自动检测请求前缀是否匹配已缓存的内容。缓存命中折扣为 50%，虽然不如 Anthropic 激进，但胜在零成本接入。

Google：显式缓存，自定义 TTL

Google 的方案折中了 Anthropic 和 OpenAI 的优点。需要显式标记，但支持自定义缓存过期时间（TTL），适合对缓存生命周期有特殊需求的场景。缓存命中折扣为 75%。

---

为什么 AI 编程工具最受益

在所有 Prompt Caching 的使用场景中，AI 编程工具（如 Claude Code、Cursor、Windsurf、Cline）是受益最大的类型。原因有以下几点：

1. System Prompt 体量巨大

AI 编程工具的 system prompt 通常包含大量内容：

• 工具定义：文件读写、终端执行、搜索等工具的 JSON Schema 定义，通常 3,000-5,000 tokens
• 行为规则：代码风格、安全规则、输出格式等约束，通常 2,000-4,000 tokens
• 项目上下文：CLAUDE.md 或类似的项目说明文件，通常 1,000-3,000 tokens
• 会话状态：已读取的文件内容、执行的命令记录等

以 Claude Code 为例，其完整 system prompt 可达 10,000-15,000 tokens。在一个典型的编程会话中，你可能进行 50-100 轮对话。如果没有缓存，这 15K tokens 的 system prompt 会被反复处理 100 次，总共消耗 150 万输入 tokens。有了缓存，第 2 次到第 100 次的 system prompt 部分都以 10% 的价格计费。

2. 对话上下文高度重叠

编程对话的特点是渐进式积累：每一轮对话都包含之前所有轮次的历史。这意味着第 N 轮对话的输入中，前 N-1 轮的内容都是重复的。缓存可以完美覆盖这种渐进式增长模式。

3. 使用频率高

开发者使用 AI 编程工具的频率远高于普通聊天应用。一天下来，一个活跃的 Claude Code 用户可能产生数百次 API 调用。高频使用确保缓存一直处于活跃状态，命中率极高。

---

OpenStarry 如何完整透传 Prompt Caching

作为 AI API 聚合网关，OpenStarry 对 Prompt Caching 提供完整透传支持。这意味着：

• 请求透传：你在请求中设置的 cache_control 等缓存控制字段会原样传递给上游供应商
• 响应透传：上游返回的 cache_creation_input_tokens 和 cache_read_input_tokens 等字段会完整返回给你
• 计费精确：OpenStarry 按照上游实际返回的 token 分类进行计费——缓存命中的 tokens 按缓存价格计费，不会按标准价格多收
• 多供应商一致：无论你调用的是 Claude、GPT 还是 Gemini，缓存行为和计费逻辑都保持一致

from openai import OpenAI

client = OpenAI(
    base_url="https://www.openstarry.com",
    api_key="sk-your-key-here"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的 Python 开发助手。"
                       "请遵循 PEP 8 规范，优先使用类型注解..."
                       # 这里是你的完整 system prompt
        },
        {"role": "user", "content": "帮我写一个异步 HTTP 客户端"}
    ]
)

# 查看缓存命中情况
usage = response.usage
print(f"标准输入 tokens: {usage.prompt_tokens}")
print(f"缓存命中 tokens: {getattr(usage, 'cache_read_input_tokens', 0)}")
print(f"缓存写入 tokens: {getattr(usage, 'cache_creation_input_tokens', 0)}")

提示：通过 OpenStarry 调用 Claude API 时，Prompt Caching 的行为与直接调用 Anthropic 官方 API 完全一致。你无需做任何额外适配。

---

最佳实践：最大化缓存命中率

要充分利用 Prompt Caching，关键在于合理组织请求内容的顺序。核心原则是：静态内容放前面，动态内容放后面。

原则一：将不变内容放在消息序列最前面

推荐的内容排列顺序：

1. System Prompt（几乎不变）— 放最前面
2. 工具定义（会话内不变）— 紧跟其后
3. 项目文档/规则（长期不变）— 第三层
4. 历史对话记录（只追加不修改）— 中间层
5. 当前用户消息（每次都新的）— 放最后

这种排列确保了内容变化总是从尾部发生，前面的静态前缀能被完整缓存命中。

原则二：避免在前缀中插入动态内容

一个常见错误是在 system prompt 中嵌入动态信息（比如当前时间戳）。这会导致每次请求的前缀都不同，彻底破坏缓存。

# 错误做法：在 system prompt 中嵌入时间戳
system_msg = f"当前时间：{datetime.now()}。你是一个代码助手..."

# 正确做法：将动态信息放到用户消息中
system_msg = "你是一个代码助手..."
user_msg = f"（当前时间：{datetime.now()}）请帮我检查这段代码"

原则三：保持请求频率

缓存有存活时间限制（通常 5 分钟）。如果两次请求间隔超过这个时间，缓存会过期。对于交互式编程工具来说，这通常不是问题；但对于定时批处理任务，需要注意控制请求间隔。

---

目标缓存命中率

不同类型的应用，合理的缓存命中率目标也不同：

监控建议：在你的应用中添加缓存命中率的监控指标。如果实际命中率远低于目标值，说明请求构造方式有优化空间。检查是否存在动态前缀、请求间隔过长等问题。

---

真实成本节省计算

让我们通过一个具体的例子来计算 Prompt Caching 的实际成本节省。

场景：使用 Claude Sonnet 4.6 的 AI 编程工具

假设条件：

• System prompt + 工具定义：12,000 tokens（固定不变）
• 每天 80 轮对话，平均每轮新增 500 tokens 用户输入
• 平均对话上下文积累：6,000 tokens 历史消息
• Claude Sonnet 4.6 输入价格：$3/M tokens
• 缓存命中价格：$0.3/M tokens（90% off）
• 缓存写入价格：$3.75/M tokens（125%）

无缓存的情况

每轮对话平均输入 tokens：12,000 + 6,000 + 500 = 18,500 tokens

每天总输入：18,500 x 80 = 1,480,000 tokens

每天输入费用：1.48M x $3 = $4.44

每月输入费用：$4.44 x 30 = $133.20

有缓存的情况（90% 命中率）

每轮对话：

• 缓存命中部分：约 16,650 tokens（90%）x $0.3/M = $0.005
• 标准计费部分：约 1,850 tokens（10%）x $3/M = $0.006
• 单轮合计：$0.011

每天：$0.011 x 80 = $0.88

每月：$0.88 x 30 = $26.40

节省幅度

每月节省：$133.20 - $26.40 = $106.80，节省比例 80.2%

注意：以上仅计算了输入 token 的节省。输出 token 不受缓存影响。对于输入远大于输出的 AI 编程场景，Prompt Caching 的节省效果尤为显著。而且随着缓存命中率的提升，节省比例会进一步增大。

不同模型的节省对比

从上表可以看出，Anthropic 的 Claude 模型在缓存场景下的成本优势最为明显。对于使用 Claude Opus 这样的高端模型，Prompt Caching 每月可以节省超过 $500，这对于个人开发者和小团队来说是非常可观的数字。

---

实战技巧总结

1. 始终把 system prompt 放在消息列表最前面，这是最基本也是最重要的优化
2. 避免在 system prompt 中嵌入任何动态内容，将时间戳、用户 ID 等放到用户消息中
3. 监控 cache_read_input_tokens 指标，这是衡量优化效果的核心数据
4. 对于批量任务，保持请求间隔在 5 分钟以内，防止缓存过期
5. 使用 OpenStarry 的用量统计面板查看每日缓存命中率和成本节省明细
6. 对于 Anthropic API，合理使用 cache_control 标记，选择正确的断点位置
7. AI 编程工具用户：保持长会话而非频繁开启新会话，有利于上下文累积和缓存复用