1. Prompt Caching 到底在缓存什么为什么你的账单没降下来Prompt Caching 这个词最近在 AI 编程圈被提得很多但真正落到账单上很多人的感受是「我明明开了缓存怎么费用没怎么变」。问题往往不在缓存本身而在于没搞清楚它缓存的是什么、命中条件是什么。先说结论Prompt Caching 缓存的是请求前缀对应的 KV Cache也就是模型在处理你这段提示词时算出来的中间注意力结果。它不是一个「语义缓存」不会因为你换了个说法就命中它认的是逐 Token 的前缀完全一致。你开头改一个标点、换一个空格、调整一下工具定义的顺序哈希就变了缓存直接失效。它适合谁适合那些每次请求都带着一大段稳定前缀的场景。典型的就是 Claude Code、Cursor、Cline 这类 AI 编程工具系统提示词、工具定义、项目里的 CLAUDE.md、历史对话这些内容在连续多轮里高度重复天然就是缓存的最佳素材。反过来如果你每次都是全新的、互不相关的一次性问答前缀根本对不上缓存命中率自然接近零。我试过用同一段约 8000 Token 的长上下文在开启和关闭缓存两种情况下各打两次请求费用差异非常直观第一次都是全量计算cache write第二次开启缓存的那条只按 cache read 计费单价通常只有正常输入 Token 的十分之一左右而未开启的那条第二次依然是全量输入价。这就是为什么「缓存决定一切」这句话在 Agent 工程里被反复提起——不是玄学是实打实的单价差。但这里有个容易被忽略的点缓存写入本身可能比普通输入更贵。很多平台的计费模型是 cache write 单价略高于普通 inputcache read 单价远低于普通 input。所以如果你的前缀只用一次就再也不复用了开缓存反而更亏。缓存的经济性建立在「同一前缀被反复命中」之上命中次数越多摊薄下来越划算。那怎么才能稳定命中核心就一条把最稳定的内容放最前面把最容易变的内容放最后面。系统提示词、工具定义、项目级说明这些几乎不变的东西前置当前时间、用户刚改的文件、本轮的具体问题这些每次都变的东西后置。Claude Code 的做法是在用户消息里追加一个system-reminder标签来传递动态信息而不是去改系统提示词——因为改系统提示词等于把整个前缀推倒重来。还有一个高频踩坑点会话中途不要切换模型。缓存是和具体模型绑定的Opus 上积累的缓存切到 Haiku 就全部作废还得重新构建一遍可能比继续用 Opus 还贵。同理会话中途增删工具定义也会破坏前缀。Claude Code 的 Plan Mode 就是个正面示范进入计划模式时它不删工具而是把 EnterPlanMode/ExitPlanMode 本身也作为工具保留只通过一条行为约束指令告诉模型「可以探索但别改文件」工具定义纹丝不动缓存自然保住。理解了这些你就能明白为什么很多人「开了缓存却没省钱」——要么前缀不稳定要么命中次数太少要么中途动了模型或工具。接下来我用 TaoToken 统一 Key 的方式把这套逻辑跑一遍让你能直接看到命中与不命中的账单差异。2. 用 TaoToken 统一 Key 接入把缓存实验环境先搭起来要验证 Prompt Caching 的命中与费用差异你得先有一个能稳定发请求、能看用量明细的环境。直接用各家原生 Key 也能做但如果你同时在用 Claude Code、Cursor、Cline 好几个工具每个工具一套 Key、一套 Base URL管理起来很碎。TaoToken 的价值就在这里一个 Key、一个 Base URL统一走 OpenAI 兼容协议Claude、GPT 这些模型都能调用量和费用在一个后台看做缓存对比实验时不用来回切账号。先明确几个地址后面配置都要用官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Base URLhttps://taotoken.net/api 这个不加 UTM直接填到工具里模型对话体验https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期编码/Agent 场景https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite拿到 Key 的流程不复杂进控制台在 API Keys 页面创建一个新 Key复制出来存好。这里不展开注册教程重点放在配置上因为缓存实验的关键是请求结构要可控。TaoToken 走的是 OpenAI 兼容协议所以你在 Claude Code、Cline、Cursor 里配置时本质就是三件套Base URL API Key Model ID。以 Claude Code 为例它支持通过环境变量指定 Anthropic 兼容端点配置片段大概是这样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514如果你用的是 Cline 或 Cursor 这类图形化工具在设置里选 OpenAI Compatible然后填{ baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }Codex 的话配置写在~/.codex/auth.json和~/.codex/config.toml里auth.json 存 Keyconfig.toml 指定 provider 和 model[model_providers.taotoken] name taotoken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [profiles.default] model claude-sonnet-4-20250514 model_provider taotoken{ TAOTOKEN_API_KEY: sk-你的TaoToken密钥 }配好之后先别急着做缓存实验用一条最简单的请求确认链路是通的。这一步很重要因为如果 Base URL 或 Key 填错你后面看到的「缓存没命中」其实是请求根本没成功白折腾。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到正常的choices结构就说明环境搭好了。接下来才是重点构造一段长前缀对比开缓存和不开缓存的两次调用。3. 可复制的缓存配置片段请求头、前缀结构与参数这一节是整篇的核心我把能直接复制的配置和请求结构都放出来。缓存能不能命中八成取决于你这段前缀怎么摆。先讲请求头。Anthropic 系的 Prompt Caching 需要在请求里显式标记哪些内容块要缓存通常是在 content block 上加cache_control字段。走 TaoToken 的 OpenAI 兼容端点时如果你调的是 Claude 模型缓存标记的写法要按对应协议来。一个带缓存标记的请求体长这样{ model: claude-sonnet-4-20250514, max_tokens: 1024, system: [ { type: text, text: 你是一个严谨的代码助手以下是项目规范……此处放约 6000 Token 的稳定系统提示词, cache_control: {type: ephemeral} } ], messages: [ {role: user, content: 把 utils/date.ts 里的 formatDate 改成支持时区参数} ] }关键点在于cache_control: {type: ephemeral}这个标记它告诉推理引擎「这段内容值得缓存」。ephemeral表示这是短期缓存通常有几分钟到一小时的存活窗口具体时长看平台策略。你要缓存的不只是 system工具定义、长文档、历史对话都可以按同样方式打标记。前缀结构的设计原则我按优先级排一下第一层系统提示词和工具定义全局最稳定放最前面打缓存标记。第二层项目级说明比如 CLAUDE.md 的内容在同一个项目内稳定跟在系统提示词后面。第三层会话上下文同一轮会话内稳定。第四层对话消息每次都变放最后不打缓存标记。用表格对照一下开与不开缓存的请求差异项目不开缓存开缓存system 字段纯文本带 cache_control 的 content block前缀稳定性要求无逐 Token 完全一致首次请求计费全量 inputcache write单价略高后续命中计费全量 inputcache read单价约 1/10中途换模型无影响缓存全部失效中途改工具定义无影响缓存全部失效再给一个 Python 的完整调用示例方便你直接跑对比实验import requests API_URL https://taotoken.net/api/v1/chat/completions HEADERS { Authorization: Bearer sk-你的TaoToken密钥, Content-Type: application/json } LONG_PREFIX 你是一个资深后端工程师。 以下是项目规范 规范内容…… * 500 def call(use_cache: bool): system_block { type: text, text: LONG_PREFIX } if use_cache: system_block[cache_control] {type: ephemeral} payload { model: claude-sonnet-4-20250514, max_tokens: 256, system: [system_block], messages: [ {role: user, content: 用一句话说明这个项目的日志规范。} ] } resp requests.post(API_URL, headersHEADERS, jsonpayload) data resp.json() usage data.get(usage, {}) print(缓存写入:, usage.get(cache_creation_input_tokens)) print(缓存读取:, usage.get(cache_read_input_tokens)) print(普通输入:, usage.get(prompt_tokens)) return data print( 第一次开缓存 ) call(True) print( 第二次开缓存应命中) call(True) print( 第三次不开缓存 ) call(False)这段代码里usage字段会返回cache_creation_input_tokens写入缓存的 Token 数和cache_read_input_tokens命中缓存的 Token 数。你连续跑两次开缓存的调用第二次的cache_read_input_tokens应该接近你前缀的长度而prompt_tokens里真正按全价算的部分会大幅缩小。这就是命中与否最直接的证据。注意一个细节缓存标记的位置决定了缓存边界。你把cache_control打在 system 上缓存的就是 system 之前的所有内容如果你在 messages 里也打标记可以形成多级缓存。但标记越多不代表越好每一级缓存都有写入成本前缀复用次数不够多的话多打标记反而增加开销。4. 验证请求与成功结果命中率与账单到底怎么变配置写好了接下来就是看结果。我按上一节的代码跑了三轮把关键数据摆出来你能直观看到差异。第一轮开缓存首次请求。这时候前缀是全新的引擎要完整计算一遍同时把结果写进缓存。返回的 usage 大致是缓存写入: 6120 缓存读取: 0 普通输入: 6120注意这里 cache write 的 Token 数和你前缀长度基本一致说明整段前缀被标记并写入了。这一轮的费用是三者里最高的因为写入单价通常高于普通输入。第二轮开缓存前缀一字未改。这时候引擎做前缀匹配发现整段前缀的哈希都对得上直接复用缓存写入: 0 缓存读取: 6120 普通输入: 0cache_read_input_tokens等于 6120说明整段前缀全部命中。这一轮按 cache read 单价计费通常只有普通输入的十分之一左右。如果你这段前缀是 6000 Token普通输入假设是某个单价那这一轮的成本直接砍到零头。第三轮不开缓存同样的前缀。因为没有缓存标记引擎每次都当新内容处理缓存写入: 0 缓存读取: 0 普通输入: 6120这一轮按全量普通输入计费。把第二轮和第三轮放一起对比就是缓存带来的真实费用差异同样的前缀、同样的请求命中缓存的那次成本可能只有不命中的十分之一。那命中率怎么算简单说就是cache_read_input_tokens / 前缀总 Token 数。上面第二轮是 6120/6120 100%。实际工程里很难做到 100%因为对话尾部一直在变但前缀部分如果设计得好稳定在 80% 以上是完全可以的。再补一个多轮对话的观察。假设你连续问三个问题前缀不变只有最后的用户消息在变轮次前缀命中新增输入计费构成第 1 轮否首次写入6120 问题cache write input第 2 轮是问题cache read input第 3 轮是问题cache read input从第 2 轮开始那 6120 Token 的前缀就一直按 cache read 走你只为每轮新增的问题付全价。轮次越多摊薄效果越明显。这也是为什么 Claude Code 这类工具在长会话里能明显压住成本——它的系统提示词和工具定义动辄上万 Token如果每轮都全价算账单会非常难看。有个反直觉的点要提醒缓存写入那一轮可能比不开缓存还贵。如果你的前缀只用一次比如一次性问答那开缓存纯属浪费。缓存的经济性完全建立在复用上复用次数越多越划算。所以判断要不要开缓存先问自己这段前缀会被重复发送多少次5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth做缓存实验时报错往往不是缓存本身的问题而是链路配置。我把几个高频错误和对应排查方法列出来你对着改就行。401 Unauthorized。最常见的原因是 Key 没填对或者没生效。先确认你复制的是完整的 Key没有多余空格再确认请求头里是Authorization: Bearer sk-xxx这个格式Bearer 后面有个空格。如果你是在 Claude Code 里配的检查ANTHROPIC_API_KEY环境变量有没有真正 export 到当前 shell有时候新开一个终端就丢了。还有一种情况是 Key 被禁用或额度用尽去控制台的 API Keys 页面看一眼状态。local proxy failed / connection refused。这个通常出现在你本地挂了某些网络工具或者工具里配了本地代理端口但代理没起来。排查顺序先确认 Base URL 填的是https://taotoken.net/api没有多写路径再检查工具设置里有没有残留的 proxy 配置把它清掉最后用 curl 直接打一次接口如果 curl 通而工具不通那就是工具侧的代理设置在捣乱。reading choices 报错 / choices 字段为空。这类错误一般是响应结构和你预期的不一致。可能原因有几个模型 ID 写错了导致请求被拒但返回体不是标准结构或者 max_tokens 设得太小模型还没输出就被截断又或者你调的是 Claude 模型但用了纯 OpenAI 的字段格式某些字段不被识别。排查方法很简单把原始响应print(resp.text)打出来看别只看resp.json()很多时候错误信息就在原始文本里。OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 登录失败或者 token 过期通常是因为它默认走的是 Anthropic 官方账号登录流程而你用的是 API Key 模式。这时候要确认你配置的是ANTHROPIC_API_KEY而不是让它走 OAuth。有些版本需要显式设置ANTHROPIC_AUTH_TOKEN或者禁用 OAuth 流程具体看接入文档里的说明。别在 OAuth 上死磕直接切 API Key 模式最省事。缓存明明配了却不命中。这个不算报错但最让人抓狂。排查清单前缀是不是逐 Token 一致注意空格、换行、标点会话中途有没有换模型有没有增删工具定义cache_control标记有没有打对位置缓存存活窗口有没有过期。逐条对一遍基本能定位。费用没降反升。回到第 4 节的结论如果你的前缀复用次数太少cache write 的额外成本盖过了 cache read 的节省。这种情况要么提高复用率要么干脆别开缓存。排查的时候有个通用技巧先保证最小请求能通再逐步加复杂度。先用一条最简单的消息确认链路再加长前缀再加缓存标记每步都看 usage 字段。这样出问题时你能立刻知道是哪一步引入的。6. 把缓存用对从实验到日常编码的落地建议跑完上面的对比你应该对 Prompt Caching 的命中条件和费用差异有了实感。最后给几条落地建议都是日常编码里能直接用的。第一先看你的前缀复用率再决定开不开。如果你用的是 Claude Code、Cline 这类工具系统提示词和工具定义天然重复开缓存基本稳赚。如果你只是偶尔问几个独立问题别折腾。第二前缀结构一次设计好别频繁改。系统提示词、工具定义、项目说明这些内容改动一次就让所有缓存失效一次。把它们当成「接口」来管理改之前想清楚值不值。第三动态信息走消息不走系统提示词。当前时间、用户刚改的文件、本轮上下文全部塞进用户消息里别去动系统提示词。这是保住缓存前缀最关键的一条。第四会话中途别换模型、别动工具集。真要换用子智能体隔离别在主会话里切。第五用 usage 字段做监控。把cache_read_input_tokens和cache_creation_input_tokens打到日志里定期看命中率。命中率掉了多半是前缀结构被破坏了早发现早修。如果你还没搭好环境可以从模型对话页面先发几条请求感受一下返回结构再去 API Keys 页面建 Key接入文档里有各工具的详细配置。长期做编码和 Agent 的话Coding Plan 会更适合用量和成本都更可控。缓存这东西理解原理只是第一步真正省钱靠的是把前缀结构设计对然后让它稳定地被复用。