如何通过 Prompt 缓存优化长上下文对话的 Token 消耗？

把 50KB 的 API 文档或整个项目的 README 每次都传给 Claude，不仅响应慢得像蜗牛，Token 账单还涨得飞快。最近在用 Claude 3.5 Sonnet 处理一个超长代码库时，通过开启 Prompt Caching 把首字延迟（TTFT）降低了 80% 以上，成本直接砍掉了一大截。

核心逻辑很简单：把那些「不经常变动但必须得有」的上下文（比如框架文档、代码规范、项目全局定义）标记为缓存点。

在 Claude API 中，你不能简单地把一段话扔进去就指望它缓存，必须在 contents 数组中显式地给特定的文本块打上 cache_control 标签。

实战配置步骤：

如果你在用 Python 调用，结构应该是这样的：

response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=1024,
    system=[
        {
            "type": "text", 
            "text": "这里放入你那 2 万字的 API 文档或项目上下文...", 
            "cache_control": {"type": "ephemeral"} # 关键点：标记为临时缓存
        }
    ],
    messages=[{"role": "user", "content": "帮我分析这个函数怎么改"}]
)

几个避坑的实战技巧：

1. 缓存点的位置必须在末尾
缓存是线性扫描的。如果你在一段长文本中间打了个缓存标签，那么这个标签之后的所有内容都无法被之前的缓存覆盖。建议把最稳定的系统提示词和文档放在最前面，然后在这个大块的末尾打标签。

2. 意识到 5 分钟的生存期
Claude 的缓存是临时性的（Ephemeral），默认 5 分钟没被调用就失效了。如果你是写个脚本跑一次，没必要开；但如果你在开发一个需要频繁对话的 AI 编程助手，这个配置就是救命稻草。

3. 监控缓存命中率
别盲目猜测是否生效，看 API 返回的 usage 字段。命中缓存时，你会看到 cache_read_tokens 有数值，而 cache_creation_tokens 只在第一次写入时出现。

效率提升对比：

未开启缓存： 每次对话 → 传输 30k tokens → 等待 3-5 秒 → 支付全额费用。
开启缓存后： 首次对话 → 写入缓存 → 之后每次对话 → 读取缓存 → 等待 0.5 秒 → 支付极低读取费。

对于我们这种经常要把整个 src 目录喂给 AI 的开发者来说，这比优化 Prompt 词句带来的体感提升要明显得多。