Claude API 提示缓存(Prompt Caching)实战:把长上下文成本打下来
摘要
当你的 Claude API 请求里塞进了一份长文档、一大段系统提示或几十个 few-shot 示例,每次调用都在为同样的内容重复付费。提示缓存(prompt caching)就是为解决这个痛点而生:把固定不变的前缀缓存起来,命中后这部分输入的费用大幅下降。本文用实战视角讲清 Claude API 提示缓存的原理、代码写法、命中条件与省钱效果,并说明如何通过 jiekou.vip 在国内稳定使用这一能力。
一、为什么长上下文这么贵
Claude API 按输入和输出 token 计费。长上下文场景(客服知识库问答、代码库分析、合同审阅)的特点是:每次请求都带着同一大坨固定内容,只有末尾的用户问题在变。假设系统提示 + 文档共 5 万 token,用户每次只问几十字,那 99% 的输入费用都花在了重复的前缀上。这正是提示缓存能大幅优化的地方。
二、提示缓存的原理
提示缓存的思路很朴素:把请求里”固定不变的前缀”标记为可缓存。第一次调用时,Anthropic 接口会把这段前缀写入缓存(这次会有一点写入开销);之后一段时间内的请求,只要前缀完全一致,就直接命中缓存,这部分输入按远低于原价的费率计费。
关键点在于”前缀”和”完全一致”:缓存是从头开始按块匹配的,所以你要把不变的内容(system 提示、文档、示例)放在前面,把每次都变的用户输入放在最后。任何靠前位置的改动都会让后面的缓存失效。
三、代码实战:Python 写法
用官方 anthropic SDK,在需要缓存的内容块上加 cache_control 标记即可。以缓存一份长文档为例:
from anthropic import Anthropicclient = Anthropic( api_key="你的_jiekou_KEY", base_url="https://api.highwayapi.ai/anthropic",)long_document = "……这里是一份很长的产品手册全文……"resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, system=[ {"type": "text", "text": "你是产品支持助手,只依据文档回答。"}, { "type": "text", "text": long_document, "cache_control": {"type": "ephemeral"}, }, ], messages=[{"role": "user", "content": "退货政策是几天?"}],)print(resp.usage) # 关注 cache 相关字段
这里把长文档放进 system 数组并打上 cache_control。第一次请求写入缓存,之后针对同一文档的不同提问都能命中,输入成本骤降。返回的 usage 里会有缓存创建与缓存读取的 token 数,用来验证是否真的命中。
四、命中缓存的三个前提
想让缓存真正生效,注意三点:
- 前缀必须完全一致。 哪怕改一个空格、换一个日期,靠前的缓存块就会失效。把动态内容(如当前时间、用户名)放到缓存块之后。
- 要达到最小可缓存长度。 太短的内容不会被缓存,长文档、大段系统提示才划算。
- 缓存有存活时间。 默认缓存是短时的(ephemeral),一段时间不用会过期。高频访问的场景收益最大,低频访问可能频繁触发重新写入。
五、什么场景收益最大
提示缓存最适合”同一份长前缀被反复调用”的场景:
- 客服 / 文档问答:同一份知识库被成千上万次提问命中;
- 代码库分析:把关键源码作为固定上下文,反复对它提问;
- 批量处理:用同一套长指令 + few-shot 示例处理大批数据;
- 多轮长对话:把靠前的固定历史缓存起来。
这些场景里,缓存往往能把输入成本削掉一大半,比单纯换更便宜的模型还立竿见影。反过来,如果你每次请求内容都完全不同,缓存就派不上用场。
六、结合模型分级,把成本压到极致
提示缓存不是孤立的招数,配合模型分级效果更好。把固定长文档缓存起来后,简单提问交给 claude-haiku-4-5,复杂分析用 claude-sonnet-4-6,只有疑难任务才动用 claude-opus-4-8。缓存削减重复输入的费用,分级路由控制单价,两者叠加,Claude API 的整体成本能被压到相当低的水平。
在国内使用这套能力,网络稳定是前提。通过 jiekou.vip 接入,base_url 换成 https://api.highwayapi.ai/anthropic 即可,免翻墙、按量计费,提示缓存等原生能力都能正常使用。若遇到 404,先检查 URL 尾部是否多写或少写了 /v1;base_url 域名是 api.highwayapi.ai,不是 jiekou.vip。
小结
提示缓存是把 Claude API 长上下文成本打下来的关键武器:把固定前缀标记为可缓存,命中后输入费用大幅下降。用好它的诀窍是”固定内容靠前、动态内容靠后、前缀完全一致”。再叠加模型分级,成本还能进一步压缩。通过 jiekou.vip 在国内稳定接入这套能力,你就能既省钱又省心地跑好长上下文应用。