核验清单

  • ✓检查自己调用API时，system prompt里不变的角色设定、固定长文档背景是不是放在了整个prompt最前面，用户当次输入是不是放在最后面
  • ✓查看账单明细或控制台是否有区分缓存命中/未命中token用量的字段，确认自己有没有在实际消耗这部分折扣
  • ✓核对自己调用的具体模型、接口协议（OpenAI兼容/原生SDK等）对应哪个字段名——不同协议下命中token的字段名不同，认错字段等于白核对
  • ✓如果厂商提供显式缓存（需要主动声明的缓存模式），确认自己是不是真的按文档要求加了对应参数，而不是想当然以为"没配置也能命中"
  • ✓不要凭这篇文章或任何第三方文章里的具体折扣比例、有效期数字去做成本预算，下单前务必打开对应厂商官方计费文档核对当天的真实数字

1. 现象：同样的system prompt，为什么有的调用便宜、有的调用贵

很多接入DeepSeek、通义千问API做应用的开发者会发现一件事：账单里同样字数的一次调用，有时候花的钱明显比预期少。原因往往不是模型突然降价，而是这次请求命中了"上下文缓存"——如果本次请求的开头一段内容跟之前某次调用完全一致，重复的那部分不用重新计算，按更低的价格计费；如果这次请求的内容跟之前调用没有重复，或者重复的部分没有被系统识别出来，那就只能按标准价格全额计费。很多开发者一开始并不知道这套机制的存在，也就没有针对性地设计自己的prompt结构，实际上是在白白错过一笔本可以省下来的费用。

2. 机制原理：检测前缀重复，命中部分按更低价格计费

上下文缓存的核心逻辑是：每次请求进来，系统会检测这次请求的内容前缀是否与之前某次调用留存下来的缓存内容重复。如果重复，重复的这部分token不需要重新走一遍完整的推理计算，可以直接从缓存里取用，因此计费时会按一个更低的单价结算，这部分单价通常明显低于标准输入token单价；没有命中缓存、或者本身就是全新内容的部分，仍然按标准价格计费。这套机制通常是自动生效的，不需要额外开关；但也有厂商提供"主动声明缓存"的模式，需要开发者在请求里显式加上特定参数，换取更确定的命中率。具体是自动命中还是需要主动声明、命中的判定条件是什么、缓存能保留多久，各家实现细节并不一样，必须以调用的那个具体厂商、具体模型的官方API文档为准。

3. prompt结构设计：固定部分放最前面，可变部分放最后面

这套缓存机制之所以能生效，前提是"前缀"要能完全匹配——大多数实现方式是从prompt的最开头开始逐段比对，只要中间某个位置开始出现差异，后面的内容即便碰巧重复也可能无法计入这次的连续前缀匹配。这就决定了一个很直接的工程建议：把每次调用都不变的内容——比如system角色设定、长文档背景、few-shot示例——放在整个prompt的最前面，保证这部分内容在不同调用之间逐字节完全一致；把每次调用都会变化的内容——比如用户当次输入的问题、当前时间戳、随机生成的会话ID——放在prompt的最后面。如果把这两类内容的顺序颠倒，或者中间插入了任何哪怕一个字符的可变内容，前面本该重复的那部分很可能就无法被识别为同一个前缀，命中率会明显下降，即便账面上看整段prompt的重复字数完全一样。

4. 去哪核对账单里缓存命中和未命中的token量

不同厂商、不同接口协议下，返回结果里标注缓存命中量的字段名并不统一，不能凭记忆套用同一个字段名去解析所有调用。实际操作上，应该先查阅自己调用的那个具体接口（比如OpenAI兼容协议、厂商自己的原生SDK协议）对应的官方文档，确认响应体里到底叫什么字段名、这个字段算不算在总输入token量里、是单独报告还是包含在内。除了单次调用返回的字段，多数平台的控制台/账单详情页也会提供按"缓存命中"分类的用量统计入口，方便按天或按月核对整体的命中比例，而不用自己一条条把日志里的字段加总。建议在正式大规模调用前，先用少量真实请求实测一遍，确认自己真的看懂了返回结果里哪部分是缓存命中、哪部分是未命中，再据此推算整体成本，而不是假设文档描述的理想命中率就是自己业务场景下的真实命中率。

5. 如实说明：具体命中规则、折扣比例、缓存有效期以官方文档为准

需要特别提醒的是，这篇文章只讲清楚"存在这套机制、原理是什么、该怎么设计prompt、去哪核对账单"这几件事本身不会变的道理，但具体的命中判定条件（比如最小可缓存的token长度、前缀匹配的颗粒度）、缓存命中之后打几折、缓存内容能保留多长时间、是否需要额外声明参数——这些数字在不同厂商之间差异很大，同一家厂商也可能随时间调整定价和规则。不同厂商对"隐式自动缓存"和"显式主动声明缓存"的实现方式也不完全相同，有的可能是两种模式并存、优惠幅度不同，也有的只提供其中一种。这篇文章不会写出具体的折扣比例或有效期数字，因为这类会过期的具体数字一旦写死在文章里，很容易在厂商调整定价后变成误导读者的过期信息；正确做法永远是打开自己实际调用的那家厂商当天的官方计费文档，核对当下真实生效的规则。

6. 小结：结构决定命中率，具体折扣看官方文档

上下文缓存本质上是"重复内容不用重复付费"的一套计费优化机制，是否真能帮你省钱，很大程度上取决于你的prompt结构设计是否符合"固定部分在前、可变部分在后"这个原则，而不是取决于你有没有主动做什么复杂配置。把这个结构原则落地、定期去账单和控制台核对实际命中比例，是眼下能确定拿到手的收益；至于具体能省多少钱、命中规则细到什么程度，这些会随时间变化的数字，永远以调用的那个具体厂商官方文档当天写的为准。