prompt-caching

# 提示词缓存 — 设计与优化 本文档涵盖了如何设计提示词构建代码以实现有效缓存。有关特定语言的语法，请参阅各语言 README 或单文件文档中的 `## 提示词缓存` 部分。 ## 所有规则遵循的唯一不变原则 **提示词缓存是前缀匹配。前缀中任何位置的任何更改都会使之后的所有内容失效。** 缓存键源自渲染后的提示词的精确字节，直到每个 `cache_control` 断点。位置 N 处的一个字节差异（时间戳、重新排序的 JSON 键、列表中的不同工具）都会使位置 ≥ N 的所有断点的缓存失效。 渲染顺序为：`tools` → `system` → `messages`。在最后一个系统块上设置断点会同时缓存工具和系统提示词。 围绕此约束设计提示词构建路径。顺序正确，大部分缓存即可自动生效。顺序错误，再多的 `cache_control` 标记也无济于事。 --- ## 优化现有代码的工作流 当被要求添加或优化缓存时： 1. **追踪提示词组装路径。** 找到 `system`、`tools` 和 `messages` 的构建位置。识别流入其中的每一个输入。 2. **按稳定性对每个输入进行分类：** - 从不更改 → 属于提示词早期，在任何断点之前 - 按会话更改 → 属于全局前缀之后，按会话缓存 - 按轮次更改 → 属于末尾，在最后一个断点之后 - 按请求更改（时间戳、UUID、随机 ID） → **消除或移至最末尾** 3. **检查渲染顺序是否与稳定性顺序匹配。** 稳定内容必须在物理上先于易变内容。如果时间戳被插入到系统提示词头部，那么无论标记如何，其后的所有内容都无法缓存。 4. **在稳定性边界处放置断点。** 请参阅下方的放置模式。 5. **审计静默失效因素。** 请参阅反模式表。 --- ## 放置模式 ### 跨多个请求共享的大型系统提示词 在最后一个系统文本块上放置断点。如果有工具，它们会在系统提示词之前渲染 — 最后一个系统块上的标记会将工具和系统一起缓存。 "system": [ {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} ] ### 多轮对话 在最近添加的轮次的最后一个内容块上放置断点。每个后续请求都会重用整个之前的对话前缀。更早的断点保持有效