> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipellm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 提示词缓存

> 让多次请求复用同一段长前缀，少付钱。

当很多请求共用一段长前缀——系统提示词、工具 schema、一份反复追问的文档——缓存能让上游
复用这部分计算，而不是每次重新处理。命中缓存的输入按远低于常规输入的价格计费。

PipeLLM 把缓存原样透传给上游并单独计量，所以省下的钱会落到你的账单上。怎么开启取决于协议。

## Anthropic：显式声明

Anthropic 的缓存要主动开。用 `cache_control` 标记你想缓存的前缀的末尾，这个点之前的全部
内容成为缓存键。

```json theme={"dark"}
{
  "model": "claude-sonnet-4-6",
  "system": [
    {
      "type": "text",
      "text": "<一份很长的文风指南>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "帮我重写这一段：..." }]
}
```

第一次请求付**写入**价，之后前缀匹配上的请求付便宜得多的**读取**价。缓存存活时间很短——
默认五分钟窗口，另有单独计价的一小时选项。

响应会告诉你实际发生了什么：

```json theme={"dark"}
"usage": {
  "cache_creation_input_tokens": 12043,
  "cache_read_input_tokens": 0
}
```

`cache_creation_input_tokens` 表示这次付的是写入，`cache_read_input_tokens` 表示命中了。

<Warning>
  **Bedrock 和 Vertex AI 最多接受 4 个 `cache_control` 块。** 超过时 PipeLLM 会保留最后
  四个——也就是最靠近提示词末尾、通常最有价值的那几个——并在转发前丢弃更早的。请求仍会
  成功，所以一个在 Anthropic 官方 API 上正常的请求，在这里可能悄悄少缓存了一部分。如果
  你会跨上游路由，断点控制在四个以内。
</Warning>

## OpenAI 和 Gemini：自动

没有需要设置的请求字段。上游自己识别重复前缀并对命中部分打折。OpenAI 在
`usage.prompt_tokens_details.cached_tokens` 里报告命中量。

既然是自动的，你唯一能控制的就是提示词的结构——见下。

## 怎么写出可缓存的提示词

缓存按前缀精确匹配，所以规则很简单：**稳定的放前面，变化的放后面。**

* 静态系统提示词、工具定义、参考文档放最上面。
* 用户当前这一轮放最下面。
* 前面不要放任何会变的东西。一个时间戳、一个请求 ID、一个顺序随机的列表出现在靠前位置，
  整段前缀就失效了，每次都按全价付。

缓存只有在存活期内被复用才划算。一次性请求如果还显式写了缓存，反而**更贵**——所以
`cache_control` 只用在你确实会在几分钟内再次命中的前缀上。

## 查价格

缓存费率因模型而异。用 [`GET /v1/models/pricing`](/zh/api-reference/model-pricing) 查询，
它和常规 token 价一起返回：

```json theme={"dark"}
"pricing": {
  "kind": "token",
  "text": { "prompt": "0.000003", "completion": "0.000015" },
  "cache": {
    "read": "0.0000003",
    "write": "0.00000375",
    "write_1h": "0.0000075"
  }
}
```

没有 `cache` 对象的模型，说明你被路由到的那条映射不支持缓存。

## 相关

* [查询模型定价](/zh/api-reference/model-pricing) —— 权威的缓存费率
* [Anthropic Messages](/zh/api-reference/anthropic/messages) —— `cache_control` 放在哪


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.