缓存输入 token 很便宜:在 BroadNet Inference 上,DeepSeek V4.1 Flash 的缓存输入每百万 $0.0055,而新输入是 $0.175。缓存 token 详解介绍了价格以及如何读取 usage 字段。本文讲的是设计工作:如何安排提示词的布局,让缓存真正命中,以及如何证明它命中了。
为什么提示词的顺序决定缓存命中率?
各大服务商都按前缀缓存。OpenAI 的指南说,复用要求整个渲染后的前缀完全匹配。DeepSeek 的文档描述了同样的规则:请求只有在完全匹配一个已存储的前缀时才会命中,中途出现差异的则不会。Anthropic 按工具、系统、消息的顺序构建缓存。
在底层,服务器复用的是它为该前缀构建的 KV 缓存。所以缓存是从第一个 token 开始的一条直线。与上次调用不同的第一个字节,就是可复用部分的终点。在一个 50,000 token 的提示词开头放一行时间戳,就会让这 50,000 token 全部按全价计费。
正确的分层顺序是什么?
| 层 | 变化频率 | 示例 | 规则 |
|---|---|---|---|
| 1. 系统提示词 | 每次部署 | 角色、规则、输出格式 | 不放日期、ID、用户名 |
| 2. 工具定义 | 每次部署 | 函数 schema | 排序、确定性的 JSON |
| 3. 参考资料 | 每个会话或任务 | 代码仓库文件、合同、产品文档 | 固定顺序、稳定的标签 |
| 4. 对话历史 | 每一轮,只追加 | 之前的用户和助手轮次 | 绝不修改,只能添加 |
| 5. 新消息 | 每次调用 | 问题,以及必要时的当前时间 | 易变的数据放在这里 |
任何易变的内容都属于第 5 层:当前日期、用户的语言区域、请求 ID、每个问题都不同的检索片段。
哪些东西会在你不知不觉中破坏前缀?
- **字典顺序。**框架常常从字典或注册表构建
tools数组。如果插件的加载顺序不同,字节就会改变。 - JSON 格式。
json.dumps(x)和json.dumps(x, indent=2)是不同的前缀。键顺序不同的两个序列化器也是如此。 - **模板空白字符。**某条代码路径多出一个行尾空格,或者一条用
\r\n、另一条用\n。 - **动态工具列表。**移除用户不能用的工具会改变前缀。OpenAI 的指南建议保持定义稳定,并用
tool_choice或允许工具设置来限制使用。 - **原地总结历史。**把旧轮次改写成摘要,会让系统提示词之后的一切重置。尽量少做总结,要做就一次做一大段。
- **检索内容放在指令前面。**放在系统提示词和工具之间的 RAG 片段每次查询都不同,连工具层也会被破坏。
如何在代码中构建利于缓存的请求?
让每一层只由稳定的输入生成,并确定性地序列化:
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
SYSTEM = open("prompts/system.md").read() # versioned file, no templating
def stable_tools(registry: dict) -> list:
# Sort by name, sort keys inside each schema.
return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]
def docs_block(paths: list[str]) -> str:
parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
return "\n\n".join(parts)
def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
return (
[{"role": "system", "content": SYSTEM},
{"role": "user", "content": docs_block(doc_paths)}]
+ history # append-only
+ [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
)
resp = client.chat.completions.create(
model="broadnet/deepseek-v4.1-flash",
messages=build_messages(history, question, now_iso, files),
tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]
两个细节。当前时间放在最后一条消息里,而不是系统提示词里。历史按返回时的原样保存助手消息,这样下一次调用就会重新发送完全相同的字节。
如何证明前缀被缓存了?
在 CI 或 notebook 中运行一个两次调用的测试:
- 用你真实的系统提示词、工具和文档构建一个请求。
- 发送它,记下
usage.prompt_tokens。 - 只修改最后一条用户消息,再发送一次。
- 读取第二次调用的
usage.prompt_tokens_details.cached_tokens。它应该覆盖几乎全部共享前缀。 - 如果它是零或很小,就逐字节对比序列化后的请求体。第一个不同之处就是破坏缓存的元凶。
在大多数服务商上,缓存都是尽力而为的,DeepSeek 的文档也直接这么说,所以一次未命中并不能证明有 bug。持续未命中才能。在你的用量日志中跟踪每个请求缓存 token 与提示词 token 的比例,并用提示词缓存计算器看看更高的命中率能省多少。
对智能体和长上下文来说有什么不同?
智能体受益最大,因为它们每个任务都要把同一个大前缀重新发送几十次。有两个习惯很重要:
- **一个任务一个对话。**每个子步骤都开一个新对话,就等于把前缀扔掉了。
- **文件只读一次,放在靠前的位置。**如果智能体重新读取了某个文件,就把新副本追加到后面,而不是替换旧的,除非文件确实变了。
有了 100 万 token 上下文窗口,第 3 层可以容纳整个代码仓库。在按 token 计费的密钥上,只有被缓存时这才负担得起,这也是为什么提示词越长,分层顺序越重要。被缓存的前缀通常还能缩短首 token 时间;参见 TTFT 与吞吐量。
BroadNet Inference 适合什么场景
在 BroadNet Inference 上,模型报告缓存数据时,usage 块会给出 prompt_tokens_details.cached_tokens,DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 的缓存输入按价格页上列出的较低价格计费。BroadNet 的文档没有提供显式缓存断点或缓存键参数,所以上面的布局就是全部技巧。在不限量套餐上,缓存不影响账单,因为会话不计 token,但同样的结构仍然有助于降低延迟。
