Source: https://wiki.niceai.dev/guide/tech/prompt-caching

# 提示词缓存是怎么省钱的

提示词缓存（Prompt Caching）会把一次请求中**不变的前缀**（系统提示、工具定义、长文档、对话历史）缓存起来；之后的请求如果以完全相同的前缀开头，这部分 token 就按远低于普通输入的单价计费，响应也更快。对 Claude Code、Codex 这类每次都带大量固定上下文的工具，缓存命中率直接决定了花费。

## 为什么需要缓存

大模型 API 是无状态的：每次请求都要把完整的上下文重新发一遍。一个编程 Agent 的典型请求是这样的：

| 部分 | 特点 |
| --- | --- |
| 系统提示 | 几乎每次都一样 |
| 工具定义（读文件、执行命令、搜索……） | 几乎每次都一样 |
| 项目说明文件、已读入的代码 | 一段时间内不变 |
| 历史对话 | 只在末尾追加 |
| 本轮新问题 | 每次不同，通常很短 |

前四部分占了绝大多数 token，并且在多轮对话里反复出现。缓存要解决的就是「同样的前缀反复按全价计费」的问题。

## 缓存是怎么匹配的

无论 Anthropic 还是 OpenAI，缓存都是**前缀匹配**：从请求开头算起，逐 token 比对，只要中间有一个 token 不同，从这里往后的内容就都不能命中。

所以内容的**顺序**非常关键：

1. 把不变的内容放在最前面：系统提示 → 工具定义 → 长文档。
2. 会变的内容放在最后：本轮问题、时间戳、随机 ID。
3. 不要在系统提示里放当前时间、请求 ID 这类每次都变的值，它会让后面的内容全部失效。

## Anthropic：显式标记 cache_control

Anthropic 的 Messages API 需要在内容块上显式标记缓存断点：

```json
{
  "model": "<模型名>",
  "max_tokens": 1024,
  "system": [
    { "type": "text", "text": "你是一个代码助手……（很长的系统提示）",
      "cache_control": { "type": "ephemeral" } }
  ],
  "messages": [
    { "role": "user", "content": "这个函数为什么报错？" }
  ]
}
```

要点（以 Anthropic 官方文档为准）：

- `cache_control` 标在哪个块上，就把从开头到这个块为止的内容作为缓存前缀。
- 首次请求是**缓存写入**，单价略高于普通输入；之后命中是**缓存读取**，单价只有普通输入的一小部分。
- 缓存有存活时间，默认较短（分钟级），每次命中会刷新；也有更长存活时间的选项，写入价格更高。
- 前缀太短不会被缓存，最小长度因模型而异。
- 响应的 `usage` 中会分别返回 `cache_creation_input_tokens` 和 `cache_read_input_tokens`，可以据此判断是否命中。

Claude Code 会自动为系统提示、工具定义和历史对话打缓存标记，用户不需要手动设置。

## OpenAI：自动缓存

OpenAI 的缓存是自动的，不需要改请求：

- 达到一定长度（官方文档中为 1024 token 起）的提示会自动参与缓存。
- 同样是前缀匹配，命中部分按折扣后的输入价格计费。
- 响应的 `usage.prompt_tokens_details.cached_tokens`（Responses API 中为 `input_tokens_details.cached_tokens`）表示命中的 token 数。
- 缓存在一段时间不用后会被清除。

## 通过中转使用时

NiceAI 兼容上述两种协议，`cache_control` 和 `usage` 字段的写法与官方一致。在 NiceAI 中：

- 实际扣费 = 按官方价格（区分普通输入、缓存写入、缓存读取、输出）计算的费用 × 分组倍率，见 [分组与倍率说明](https://wiki.niceai.dev/guide/billing-groups)。
- 每次请求的缓存 token 数可以在控制台的使用记录中查看。
- 不同分组的线路不同，缓存表现可能不同，以实际使用记录为准。

## 提高命中率的实践

| 做法 | 原因 |
| --- | --- |
| 固定系统提示，不放时间戳等变量 | 前缀一变，后面全部失效 |
| 工具列表顺序固定 | 工具定义也是前缀的一部分 |
| 长文档放在问题前面 | 问题每次不同，放后面不影响前缀 |
| 连续对话不要中途切换模型 | 缓存按模型区分 |
| 编程工具里少用「清空上下文后重新读取同样文件」 | 新会话需要重新写入缓存 |
| 观察 `usage` 中的缓存字段 | 用数据判断是否命中，而不是猜 |

## 小结

- 缓存按前缀匹配，顺序比内容更重要。
- Anthropic 需要 `cache_control` 标记，OpenAI 自动缓存。
- 编程 Agent 的大部分输入都是重复前缀，命中缓存后花费会明显下降。

相关阅读：[为什么 Claude Code 一句话也要几千输入 token](https://wiki.niceai.dev/guide/tech/claude-code-input-tokens)。
