提示缓存省钱指南:把输入费砍到 1/10
多轮对话与 Agent 场景里,每一轮都要把整段 system、工具定义和历史重新发一遍——这部分才是账单大头。 提示缓存让上游把这段「前缀」存起来,下次读缓存只按 0.1× 计费。 写法对了,输入费能砍到原来的 1/10;写法错了,每轮都在花 1.25× 的写价重建缓存。这一页讲清楚怎么写对。
先看懂账单:输入 token 分三种价
| 类型 | 含义 | 计费(相对输入刊例) |
|---|---|---|
| 未缓存(新增) | 本轮新增、上游没见过的部分 | 1× |
| 读缓存 | 命中的前缀,上游直接复用 | 0.1× |
| 写缓存 | 本轮新建缓存的部分(只在断点处发生) | 1.25×(1 小时档 2×) |
读占比 = 读缓存 ÷ 总输入,就是你真省下来的比例。命中的条件只有四个:前缀一字不差、断点处以前写过、前缀够长、还在寿命内(5 分钟滑动,或 1 小时档)。 十二条守则都是围绕这四个条件来的。
十二条客户端守则
以 Claude 为主,括号里标 GPT / 其他型号的差异。前三条解决 80% 的「明明用了缓存却不省钱」。
- 01前缀顺序固定tools → system → messages。工具定义排序固定,会话中不增删(GPT 同样把 tools 算进前缀)。
- 02断点打三处tools 末项、system 末块、最后一条消息(tool_result 也算)各打一个 cache_control。缓存只在断点处写入,上游从每个断点向前找以前写过的条目;想让别的线程读到 system / tools,就必须在 tools 末项和 system 末块各打一个。单线程最省事的写法是请求顶层加 "cache_control":{"type":"ephemeral"}(自动缓存,断点随对话前移)。官方上限最多 4 个断点。原生 /v1/messages 三处都能打;OpenAI 格式调 Claude 时网关透传 system / 消息块上的断点(见下文),tools 末项断点仍需原生。
- 03动态内容放最后时间、请求 id、用户名、随机语一律不进 system / 首条消息——前缀差一个字符就整段重写。
- 04前缀够长Fable 5.1 / Fable 5 / Opus 5 / Opus 5.5 ≥ 512 token,Opus 4.8 / Sonnet 5 ≥ 1,024,Opus 4.7 ≥ 2,048,Haiku 4.5 ≥ 4,096 才会建缓存;GPT ≥ 1,024,按 128 递增计命中。差一点就够的 system 宁可补长到门槛。
- 05同一会话不换参数不换模型、不改 thinking / effort / speed、不改 tool_choice、不忽然加图或 web_search——这些都会让前缀失效。
- 06线性追加每轮只在末尾追加,不重排、不截头。上下文压缩时保留头部(system + 早期消息)不动,只压中段。
- 07先单发再并发新会话第一条单独发,等它返回(≥ 3 秒)再扇出子任务;热会话并发没事。冷启动同时发 N 条 = N 次写费。
- 08给会话一个稳定 id(Claude Code 格式)metadata.user_id = user_<sha256>_account_<uuid>_session_<uuid>:account 段每客户 / 每项目固定,session 段随会话变。网关据此把整个会话钉在同一条渠道 1 小时(主备切换不换线、首字节后不跨渠道重试),备胎是冷的,换一次渠道 = 整段重写。同线程命中本身不依赖它;共享账号池线路「同 account 跨线程共享」我们实测忽有忽无,不作承诺,跨线程看第 11 条。GPT /v1/responses 用 prompt_cache_key(+ user)。
- 09拒答轮不落缓存stop_reason=refusal 的那一轮会照收写费但不会被缓存;把它删掉或改写后重发,别带着继续追加。
- 10闲置策略缓存寿命 5 分钟滑动,从请求开始计时(生成耗时算在内)。兑现 1h 的线路,人在环场景打 ttl:"1h"(写价 2×);不兑现的线路,闲置预计 < 50 分钟可用保活(见下),更长就接受重建。
- 11号池线路跨线程共享靠 sentinel共享账号池线路(Max 满血版)按「system + tools + 首条消息首块」的指纹把请求分到某个账号,换线程 = 换账号 = 前缀重写。要让多个线程 / 子代理共享前缀,把首条 user 消息的首个文本块写成常量(如 "Session start. Follow the system conventions."),真问题放第二块——实测两个新线程都整段读到(15,117 / 9,592)。工作区级线路(稳定标准版)天然共享,不需要。
- 12看 usage 自证每次响应都带缓存三分账(下表)。写占比 > 30% 就是在反复重建——回头对照第 1、3、6 条。
照着抄:Claude 原生格式
官方 Anthropic SDK,base_url 指向网关(不带 /v1),密钥就是你现有的 sk- 密钥。三处断点 + Claude Code 格式的 metadata.user_id(钉渠道)+ 首条消息的 sentinel 首块(号池线路跨线程用),第二轮起读缓存 ≈ 整段前缀:
# pip install anthropic
import hashlib, uuid
from anthropic import Anthropic
client = Anthropic(api_key="sk-aiapiway-****", base_url="https://gw.aiapiway.com")
# 会话身份(Claude Code 格式):account 段每客户 / 每项目固定并持久化,session 段每个会话新建。
# 网关据此把整个会话钉在同一条渠道 1 小时(主备切换不换线);同线程命中不依赖它。
ACCOUNT = "8d3c2f1e-0000-4000-8000-000000000000" # 固定 uuid,存配置里复用
SESSION = str(uuid.uuid4())
USER_ID = f"user_{hashlib.sha256(ACCOUNT.encode()).hexdigest()}_account_{ACCOUNT}_session_{SESSION}"
# 号池类线路(Max 满血版)要让多个线程 / 子代理共享同一段前缀:首条 user 消息的**首个文本块**用常量(sentinel),
# 真问题放第二块。工作区级线路(稳定标准版)天然共享,这一块可有可无。
SENTINEL = {"type": "text", "text": "Session start. Follow the system conventions."}
TOOLS = [ # 顺序固定、会话中不增删;末项打断点 ①
{"name": "read_file", "description": "读取文件",
"input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}},
{"name": "run_shell", "description": "执行命令",
"input_schema": {"type": "object", "properties": {"cmd": {"type": "string"}}, "required": ["cmd"]},
"cache_control": {"type": "ephemeral"}},
]
SYSTEM = [ # 长而稳定的系统提示,末块打断点 ②;时间 / 用户名 / 请求 id 等动态内容不要放这里
{"type": "text", "text": "你是资深工程助手……(整段前缀 ≥ 512 token 才会建缓存)",
"cache_control": {"type": "ephemeral"}},
]
history = []
def ask(question: str) -> str:
blocks = [{"type": "text", "text": question}]
if not history:
blocks = [SENTINEL, *blocks] # 只有会话第一条带 sentinel;之后每轮线性追加
history.append({"role": "user", "content": blocks})
# 最后一条消息打断点 ③:只在发送时给最后一块加,历史里不留,断点随对话前移
last = history[-1]
body = [*history[:-1], {**last, "content": [*last["content"][:-1],
{**last["content"][-1], "cache_control": {"type": "ephemeral"}}]}]
resp = client.messages.create(
model="claude-opus-5", max_tokens=1024,
tools=TOOLS, system=SYSTEM, messages=body,
metadata={"user_id": USER_ID},
)
history.append({"role": "assistant", "content": resp.content})
u = resp.usage # 自证:第二轮起 读 ≈ 整段前缀,写 ≈ 只有上一轮新增
print(f"读 {u.cache_read_input_tokens} / 写 {u.cache_creation_input_tokens} / 未缓存 {u.input_tokens}")
return "".join(b.text for b in resp.content if b.type == "text")
ask("先看一下 src/ 目录结构")
ask("把 README 里的安装步骤改成 pnpm")
只有一个线程、不想管断点?请求顶层加 "cache_control":{"type":"ephemeral"} 即可(SDK 里用 extra_body 传),网关原样透传,上游自动把断点放在最后一个可缓存块。
用 OpenAI 格式调 Claude?照样打断点
用 OpenAI SDK / /v1/chat/completions 调 Claude 时,网关会把请求转成 Claude 格式,并从 2026-09-24 起透传 content[].cache_control(system 块与 user / assistant 文本块;最多 4 个,多了保留最后 4 个)。 推荐写法:system 末块 + 最后一条消息各打一个断点——第二轮起读缓存 ≈ 整段前缀(我们在 Max 满血版实测 96%+)。 单线程也可以只在请求顶层写 "cache_control":{"type":"ephemeral"}(OpenAI SDK 用 extra_body 传;2026-09-28 起网关同样透传,上游自动缓存,占 4 个断点之一,实测第二轮读 ≈ 整段前缀)。 OpenAI 的 tools[] 没有 cache_control 字段, 要在 tools 末项打断点、或看原生三分账字段,再迁到 /v1/messages(密钥、地址不变):
# pip install openai
from openai import OpenAI
client = OpenAI(api_key="sk-aiapiway-****", base_url="https://gw.aiapiway.com/v1")
# system / user 用数组块,末块打断点;最多 4 个 cache_control(官方上限,多了网关保留最后 4 个)。
# OpenAI tools[] 没有 cache_control 字段——要在 tools 末项打断点请用原生 /v1/messages。
SYSTEM = [
{"type": "text", "text": "你是资深工程助手……(整段前缀 ≥ 512 token 才会建缓存)",
"cache_control": {"type": "ephemeral"}},
]
history = []
def ask(question: str) -> str:
history.append({"role": "user", "content": [
{"type": "text", "text": question, "cache_control": {"type": "ephemeral"}},
]})
# 历史消息里的 cache_control 可留可不留;上游按断点写前缀,末条断点随对话前移即可
r = client.chat.completions.create(
model="claude-opus-5",
messages=[{"role": "system", "content": SYSTEM}, *history],
)
answer = r.choices[0].message.content or ""
history.append({"role": "assistant", "content": answer})
cached = (r.usage.prompt_tokens_details.cached_tokens
if r.usage and r.usage.prompt_tokens_details else 0)
print(f"prompt={r.usage.prompt_tokens} cached={cached}") # 第二轮起 cached ≈ 整段前缀
return answer
ask("先看一下 src/ 目录结构")
ask("把 README 里的安装步骤改成 pnpm")
自证字段仍是 usage.prompt_tokens_details.cached_tokens(OpenAI 语义里 prompt_tokens = 总输入,含读 / 写)。
闲置保活的算术(只在人会回来时用)
缓存寿命 5 分钟、从请求开始计时。人在环的场景(看完回复想 8 分钟再问)回来第一条就会整段重写。 原样重发上一条请求并把 max_tokens 设为 1,只读不写:50K 前缀一次保活 ≈ 读价 0.1×, 重建一次 ≈ 写价 1.25×,约等于 12 次保活。所以闲置预计 < 50 分钟划算,更长就停掉,回来时接受重建一次。 兑现 1 小时档的线路直接打 ttl:"1h" 更省心(写价 2×,一次顶 8 次 5 分钟重建)。这是客户端策略,网关不代发。
# 闲置保活(只对不兑现 1h 的线路、且人会回来的场景):原样重发上一条请求,max_tokens=1 → 只读不写
import threading, time
last_request = {} # 每次真实请求后存下 kwargs(model / tools / system / messages / metadata)
last_started_at = 0.0 # 上一请求「开始」的时间:缓存寿命从请求开始算,不是从返回算
def keep_alive():
while True:
time.sleep(30)
if not last_request:
continue
if time.time() - last_started_at >= 4 * 60: # 距上一请求开始 ≥ 4 分钟就补一发
client.messages.create(**{**last_request, "max_tokens": 1})
globals()["last_started_at"] = time.time()
threading.Thread(target=keep_alive, daemon=True).start()
# 算术:50K 前缀一次保活 ≈ 读价 0.1×;一次重建 ≈ 写价 1.25×,约等于 12 次保活。
# 闲置预计 < 50 分钟划算;更长就停掉保活,回来时接受重建一次。
怎么自证:各型号族看哪个字段
左右滑动查看更多
| 型号族 | 读缓存 | 写缓存 | 备注 |
|---|---|---|---|
| Claude(原生 /v1/messages) | usage.cache_read_input_tokens | usage.cache_creation_input_tokens | usage.input_tokens 是未缓存部分,三者相加才是总输入 |
| Claude(OpenAI 格式) | usage.prompt_tokens_details.cached_tokens | —(已并入 prompt_tokens) | prompt_tokens = 总输入(含读 / 写) |
| GPT(Responses / Chat) | prompt_tokens_details.cached_tokens | —(自动缓存无写费) | ≥ 1,024 自动命中,128 递增 |
| DeepSeek | prompt_cache_hit_tokens | — | 64 token 块自动缓存 |
| Gemini | cachedContentTokenCount | —(显式缓存另有存储费) | 2.5+ 隐式缓存自动生效 |
经验值:同一线程连续追加,第二轮起读占比应 ≥ 90%;写占比长期 > 30% 说明前缀在变或线程在换,回头对照第 1、3、6、11 条。
两类 Claude 线路的差别
- 同一工作区内跨线程共享前缀:开新会话、起子代理,只要 tools+system 一样就直接读到(探针 98%)。
- 兑现 1 小时档:人在环场景打
ttl:"1h",写价 2×。 - OpenAI 格式调这条线也可打断点(system 末块 + 末条消息);上游另有自动缓存(同线程实测 97%、不收写费)作兜底。
- 同线程连续追加命中率与官方一致(我们实测 94.1%,第 2 请求起 98.1%;探针 96%),且不依赖 metadata.user_id。
- 跨线程默认不共享(按指纹分账号);要共享用第 11 条 sentinel。同 account 段 user_id 的共享我们实测忽有忽无,不作承诺。
- 1 小时档目前不兑现(按 5 分钟处理、按 5 分钟计价),闲置用保活算术。
- OpenAI 格式调这条线同样支持打断点(网关透传;探针 96%+);不打断点则无自动缓存兜底。
我们承诺什么、不承诺什么
- 承诺计费:读缓存按 0.1×、写缓存按 1.25×(1 小时档 2×)计,与官方一致;上游回传的缓存三分账原样出现在你的响应 usage 与账单里,不做改写。
- 承诺可见:每把密钥的读 / 写 / 未缓存占比与两个诊断码(NOBP=没打断点、REBUILD=每轮重建)我们后台按令牌可查,发邮件到
[email protected]即可索取,也会主动提醒写占比异常的客户。 - 承诺网关行为:原生
/v1/messages请求体只转发不改写(不注入、不删 cache_control、不重排); OpenAI 格式调 Claude 时透传content[].cache_control(system / 消息文本块,最多 4 个;不注入、不发明断点)与请求顶层的cache_control(自动缓存,占 4 个断点之一);同一 user_id 的会话钉在同一条渠道 1 小时,首字节后不跨渠道重试。 tools 末项断点仍需原生格式(OpenAItools[]无此字段)。 - 不承诺具体命中率:命中率取决于你的请求怎么写。按本页守则写,单线程连续追加的目标区间是 ≥ 90%(实测 94.1%);多线程 / 子代理在工作区级线路天然共享, 在号池线路用 sentinel 后按同线程算;闲置超过寿命回来的第一条一定重建,这是官方机制,不是故障。