Source: https://aiprimetech.io/zh/docs/guides/prompt-caching/

[首页](/zh/) / [文档](/zh/docs/) / 提示词缓存 

# 提示词缓存 

以输入价格的一小部分重新读取固定前缀——该缓存什么、不该缓存什么，以及如何验证缓存是否生效。 

 复制页面 [ 以 Markdown 查看](/zh/docs/guides/prompt-caching.md) [ 向 ChatGPT 提问](https://chatgpt.com/?q=Read%20https%3A//aiprimetech.io/docs/guides/prompt-caching.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.) [ 在 Claude 中提问](https://claude.ai/new?q=Read%20https%3A//aiprimetech.io/docs/guides/prompt-caching.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.)   

提示词缓存会存储请求的前缀，让后续共享该前缀的调用按更低的输入费率计费。对于包含大量稳定前置内容的请求——例如系统提示词、工具模式定义或用于问答的文档——这是回报最高的改进措施。 

## 适合缓存的内容 

 | 适合 | 原因

 | 系统提示词 | 在会话中的每次调用里都逐字节一致

 | 工具 / 函数定义 | 在整个智能体运行过程中保持稳定，而且通常较大

 | 被反复提问的文档 | 一次上传，多次提问

 | 少样本示例 | 固定，而且通常较长 

 | 不适合 | 原因

 | 用户的最新消息 | 每次都不同——永远不会命中缓存

 | 靠近开头的位置含有时间戳或请求 ID 的任何内容 | 前缀靠前位置的一个字节发生变化，就会使其后所有内容的缓存失效

 | 简短的提示词 | 低于可缓存的最小长度，因此无法获益 

## 标记前缀 

```
Copy{
  "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 次；使用缓存时，则大致只计费一次。 

[费用控制另外三种调节手段](/zh/docs/guides/cost-control/)[工具使用为什么 schema 占据了大部分输入](/zh/docs/api-reference/tool-use/)[消息 APIcache_control 应放在哪里](/zh/docs/api-reference/messages/) 

[上一页费用控制](/zh/docs/guides/cost-control/)[下一页上下文管理](/zh/docs/guides/context-management/)