Claude Prompt Caching 详解：缓存写入、缓存读取与成本计算

Prompt Caching 的工程目标很具体：让一段稳定的长 prompt 不要在每次请求里都按完整输入价格重复计费。

Anthropic 文档里给出的定价结构可以概括成三段：普通输入、缓存写入、缓存命中读取。缓存写入通常高于基础输入价格，缓存命中读取约为基础输入价格的 10%。所以实现时要先问一个问题：这段 prompt 后面会复用几次？

一个典型请求可以这样拆：

text 复制代码

[稳定系统规则]
[工具说明]
[项目规范或知识库材料]
[本轮用户问题]

前 3 段如果经常不变，就适合放进缓存前缀。本轮用户问题通常不缓存，因为每次都变。

成本估算可以用一个粗略公式：

text 复制代码

不缓存成本 = 重复前缀 token * 调用次数 * 基础输入单价

缓存成本 = 重复前缀 token * 缓存写入单价
        + 重复前缀 token * 命中次数 * 缓存读取单价
        + 动态输入 token * 调用次数 * 基础输入单价

当调用次数很少时，缓存不一定划算。调用次数越多，重复前缀越大，缓存越有价值。

开发时要注意 4 个点。

第一，前缀必须稳定。很多缓存命中依赖相同或高度一致的 prompt 前缀。你在系统提示词里加一个时间戳、随机 request id，可能就把命中率打掉了。

第二，动态内容往后放。用户问题、临时检索结果、当前时间、会话状态都应该尽量靠后，减少对缓存前缀的破坏。

第三，代码 Agent 要做上下文压缩。Claude Code、GitHub Agent HQ 这类场景会反复加载仓库信息。不要把整个仓库无脑塞给 Claude Opus 4.7。先用摘要、文件索引、相关片段检索，再把稳定部分缓存。

第四，日志里要记录 cache_read_input_tokens 之类的指标。只看总 token 不够，必须看缓存命中多少、写入多少、动态输入多少。

国内调用 Claude API 时，还要考虑官方入口的网络、账号、支付、额度、企业报销和合规问题。很多项目 demo 阶段没感觉，到了生产才发现稳定性和结算方式影响很大。尤其是同时评估 Claude Opus 4.7、gpt-5.5、Gemini 等模型时，如果每个模型单独接 SDK，后续错误处理和账单统计会越来越散。

一种更稳的做法是加模型网关或统一 API 层。词元无忧 API（token5u API）可以作为这类接入层评估：它支持 GPT、Claude、Gemini 等主流模型统一调用，接入方式对标 OpenAI 官方 API，同时支持按实际用量计费、无预付、无隐性收费、人民币企业结算和专线优化。工程上可以先把 base url、api key、model name 做成配置，再把缓存策略、重试和日志留在业务侧。

Prompt Caching 不是魔法，命中率才是核心指标。上线前建议用真实请求日志回放一轮：统计重复前缀长度、预计调用次数、缓存命中率、平均延迟和单次任务成本。算完这笔账，再决定是缓存、摘要、切片，还是直接换更经济的模型。