提示词缓存
以输入价格的一小部分重新读取固定前缀——该缓存什么、不该缓存什么，以及如何验证缓存是否生效。
提示词缓存会存储请求的前缀，让后续共享该前缀的调用按更低的输入费率计费。对于包含大量稳定前置内容的请求——例如系统提示词、工具模式定义或用于问答的文档——这是回报最高的改进措施。
适合缓存的内容
| 适合 | 原因 |
|---|---|
| 系统提示词 | 在会话中的每次调用里都逐字节一致 |
| 工具 / 函数定义 | 在整个智能体运行过程中保持稳定，而且通常较大 |
| 被反复提问的文档 | 一次上传，多次提问 |
| 少样本示例 | 固定，而且通常较长 |
| 不适合 | 原因 |
|---|---|
| 用户的最新消息 | 每次都不同——永远不会命中缓存 |
| 靠近开头的位置含有时间戳或请求 ID 的任何内容 | 前缀靠前位置的一个字节发生变化，就会使其后所有内容的缓存失效 |
| 简短的提示词 | 低于可缓存的最小长度，因此无法获益 |
标记前缀
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}从开头到被标记块（含该块）的所有内容都会成为缓存前缀。顺序很重要：将稳定内容放在前面，易变内容放在最后。
验证缓存是否生效
检查 usage 对象。缓存命中时，令牌会计入缓存读取，而非普通输入。如果重复调用后缓存读取仍为零，说明你的前缀实际上并不完全一致——常见原因是前置内容中包含时间戳、会话 ID 或不确定的 JSON 键排序。
以确定性的方式序列化缓存内容。
json.dumps(obj) 不带 sort_keys=True 可能会在不同运行之间重新排列键的顺序，从而改变字节内容，并在不知不觉中让你失去每一次缓存命中。最重要的应用场景
智能体工具在每一轮都会重新发送相同的系统提示词和工具 schema。在一个包含 50 轮的会话中，不使用缓存时，这段前置内容会被计费 50 次；使用缓存时，则大致只计费一次。