BroadRouter

如何组织提示词,让前缀被缓存

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 · 更新于

每个请求都按从最稳定到最不稳定的顺序排列:系统提示词、工具定义、参考文档、对话历史,最后是新消息。让每一层在每次调用之间逐字节一致:开头不放时间戳或 ID,工具排好序,JSON 确定性序列化,历史只追加。然后测量 cached_tokens,确认前缀确实被复用。

缓存输入 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、每个问题都不同的检索片段。

哪些东西会在你不知不觉中破坏前缀?

  1. **字典顺序。**框架常常从字典或注册表构建 tools 数组。如果插件的加载顺序不同,字节就会改变。
  2. JSON 格式。json.dumps(x) 和 json.dumps(x, indent=2) 是不同的前缀。键顺序不同的两个序列化器也是如此。
  3. **模板空白字符。**某条代码路径多出一个行尾空格,或者一条用 \r\n、另一条用 \n。
  4. **动态工具列表。**移除用户不能用的工具会改变前缀。OpenAI 的指南建议保持定义稳定,并用 tool_choice 或允许工具设置来限制使用。
  5. **原地总结历史。**把旧轮次改写成摘要,会让系统提示词之后的一切重置。尽量少做总结,要做就一次做一大段。
  6. **检索内容放在指令前面。**放在系统提示词和工具之间的 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 中运行一个两次调用的测试:

  1. 用你真实的系统提示词、工具和文档构建一个请求。
  2. 发送它,记下 usage.prompt_tokens。
  3. 只修改最后一条用户消息,再发送一次。
  4. 读取第二次调用的 usage.prompt_tokens_details.cached_tokens。它应该覆盖几乎全部共享前缀。
  5. 如果它是零或很小,就逐字节对比序列化后的请求体。第一个不同之处就是破坏缓存的元凶。

在大多数服务商上,缓存都是尽力而为的,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,但同样的结构仍然有助于降低延迟。

常见问题

为什么我的提示词缓存命中率很低?

提示词开头附近有东西在每次调用时都会变。常见原因有:系统提示词里有时间戳或请求 ID,工具的序列化顺序不同,检索到的文档放在了指令前面,或者历史被总结和改写了。

用户问题应该放在长文档前面还是后面?

后面。文档放前面,问题放最后。这样文档就构成了可复用的前缀,而且许多模型在问题紧跟材料时回答得也更好。

工具定义会破坏提示词缓存吗?

只有在它们发生变化时才会。工具是前缀的一部分,所以要保持同样的工具集合、同样的顺序和同样的 JSON。要在某次调用中限制工具,用 tool_choice,而不是修改列表。

few-shot 示例的顺序会影响缓存吗?

会。打乱顺序的示例每次都会产生不同的前缀。把顺序固定下来,或者把每个请求都不同的示例放在稳定部分之后。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity