---
title: "提示词缓存的结构设计：稳定前缀写法 | BroadRouter"
description: "如何安排大模型提示词的布局，让被缓存的前缀保持一致：系统提示词、工具 schema、文档、只追加的历史，外加一个能证明缓存生效的测试。"
url: https://broadrouter.com/zh/blog/prompt-structure-for-caching/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/blog/prompt-structure-for-caching/)（2026-11-16 更新）。

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

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 2026-11-14 · 更新于 2026-11-16

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

## 要点

-   缓存匹配的是精确前缀。改动一个字节，后面的一切都会失效，所以各层的顺序比它们的大小更重要。
-   四层内容，最稳定的放前面：系统提示词、工具、文档、历史。新的用户消息放在最后。
-   工具和 JSON 文档要按排好序的键和固定的分隔符序列化；字典顺序是悄无声息的缓存杀手。
-   每次调用要限制可用工具时，用 tool\_choice，而不是删除工具定义。
-   测试一下：把同一个前缀发送两次，检查第二次调用的 prompt\_tokens\_details.cached\_tokens 是否上升。

**本页内容**

1.  为什么提示词的顺序决定缓存命中率？
2.  正确的分层顺序是什么？
3.  哪些东西会在你不知不觉中破坏前缀？
4.  如何在代码中构建利于缓存的请求？
5.  如何证明前缀被缓存了？
6.  对智能体和长上下文来说有什么不同？
7.  BroadNet Inference 适合什么场景

[缓存输入 token](https://broadrouter.com/zh/glossary/cached-input-tokens/) 很便宜：在 BroadNet Inference 上，DeepSeek V4.1 Flash 的缓存输入每百万 $0.0055，而新输入是 $0.175。[缓存 token 详解](https://broadrouter.com/zh/blog/cached-input-tokens-explained/)介绍了价格以及如何读取 usage 字段。本文讲的是设计工作：如何安排提示词的布局，让缓存真正命中，以及如何证明它命中了。

## 为什么提示词的顺序决定缓存命中率？

各大服务商都按**前缀**缓存。OpenAI 的指南说，复用要求整个渲染后的前缀完全匹配。DeepSeek 的文档描述了同样的规则：请求只有在完全匹配一个已存储的前缀时才会命中，中途出现差异的则不会。Anthropic 按工具、系统、消息的顺序构建缓存。

在底层，服务器复用的是它为该前缀构建的 [KV 缓存](https://broadrouter.com/zh/glossary/kv-cache/)。所以缓存是从第一个 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 片段每次查询都不同，连工具层也会被破坏。

## 如何在代码中构建利于缓存的请求？

让每一层只由稳定的输入生成，并确定性地序列化：

```python
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。持续未命中才能。在你的[用量日志](https://broadrouter.com/zh/blog/llm-api-usage-logging/)中跟踪每个请求缓存 token 与提示词 token 的比例，并用[提示词缓存计算器](https://broadrouter.com/tools/prompt-caching-calculator/)看看更高的命中率能省多少。

## 对智能体和长上下文来说有什么不同？

智能体受益最大，因为它们每个任务都要把同一个大前缀重新发送几十次。有两个习惯很重要：

-   \*\*一个任务一个对话。\*\*每个子步骤都开一个新对话，就等于把前缀扔掉了。
-   \*\*文件只读一次，放在靠前的位置。\*\*如果智能体重新读取了某个文件，就把新副本追加到后面，而不是替换旧的，除非文件确实变了。

有了 [100 万 token 上下文窗口](https://broadrouter.com/zh/blog/million-token-context-window-guide/)，第 3 层可以容纳整个代码仓库。在按 token 计费的密钥上，只有被缓存时这才负担得起，这也是为什么提示词越长，分层顺序越重要。被缓存的前缀通常还能缩短首 token 时间；参见 [TTFT 与吞吐量](https://broadrouter.com/zh/blog/llm-latency-ttft-throughput/)。

## BroadNet Inference 适合什么场景

在 BroadNet Inference 上，模型报告缓存数据时，usage 块会给出 `prompt_tokens_details.cached_tokens`，[DeepSeek V4.1 Flash](https://broadrouter.com/zh/models/deepseek-v4.1-flash/)、[GLM 5.3](https://broadrouter.com/zh/models/glm-5.3/) 和 [Qwen3.8 27B](https://broadrouter.com/zh/models/qwen3.8-27b/) 的缓存输入按[价格页](https://broadrouter.com/zh/pricing/)上列出的较低价格计费。BroadNet 的文档没有提供显式缓存断点或缓存键参数，所以上面的布局就是全部技巧。在不限量套餐上，缓存不影响账单，因为会话不计 token，但同样的结构仍然有助于降低延迟。

相关免费工具（英文）

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[免费工具（英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[系统提示词（system prompt）](https://broadrouter.com/zh/glossary/system-prompt/)

系统提示词是应用在对话开始前发给语言模型的指令文本，通常是一条 system 或 developer 角色的消息。它设定模型的角色、规则、语气和输出格式，当用户消息与它冲突时，模型应当优先遵循它。

[缓存输入 token（cached input tokens）](https://broadrouter.com/zh/glossary/cached-input-tokens/)

缓存输入 token 是大模型服务商近期已处理过、可以直接从缓存中复用而无需重新计算的提示词 token，通常是重复的前缀，例如系统提示词或文档。服务商对它们按低于新输入 token 的单价计费。

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[首 token 延迟（TTFT，time to first token）](https://broadrouter.com/zh/glossary/time-to-first-token/)

首 token 延迟（TTFT）是从向语言模型发出请求到第一个输出 token 到达的时间。它包括网络时间、服务器上的排队时间和预填充（模型读取整个提示词的步骤），所以会随提示词长度和负载增加。

[输入 token 与输出 token](https://broadrouter.com/zh/glossary/input-and-output-tokens/)

输入 token 是语言模型在一次请求中读取的 token，包括系统提示词、对话历史、工具定义和图片。输出 token 是模型生成回复的 token，包括思考内容。大模型 API 通常分别计价，输出一般更贵。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

## 常见问题

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

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

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

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

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

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

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

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

## 继续阅读

-   [缓存输入 token 详解：如何降低大模型 API 账单](https://broadrouter.com/zh/blog/cached-input-tokens-explained/)
-   [百万 token 上下文窗口什么时候值得用（什么时候不值得）](https://broadrouter.com/zh/blog/million-token-context-window-guide/)
-   [大模型 API 包月还是按 token 付费：盈亏平衡怎么算](https://broadrouter.com/zh/blog/flat-rate-vs-pay-per-token-llm-api/)
-   [BroadNet 的 GPU 硬件与推理部署方式（据 BroadNet 自述）](https://broadrouter.com/zh/blog/broadnet-gpu-fleet-and-serving/)
-   [缓存大模型 API 响应以降低成本：用 Python 实现精确匹配缓存](https://broadrouter.com/zh/blog/cache-llm-responses-cut-cost/)
-   [指南：对话补全的流式输出，以及连接中断的处理](https://broadrouter.com/zh/guides/streaming-chat-completions/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-prompt-structure-for-caching&utm_content=page-cta) ·

**来源**

-   [BroadNet Inference API 参考：usage 中的缓存 token（2026-11-16 查阅）（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-prompt-structure-for-caching&utm_content=sources)
-   [OpenAI 提示词缓存指南：前缀匹配与结构建议（2026-11-14 获取）](https://developers.openai.com/api/docs/guides/prompt-caching)
-   [Anthropic 提示词缓存文档：缓存顺序为工具、系统、消息（2026-11-16 查阅）](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
-   [DeepSeek API 文档：上下文硬盘缓存（2026-11-14 获取）](https://api-docs.deepseek.com/guides/kv_cache)
