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

# GPT 提示词缓存

> GPT 提示缓存（Prompt Caching）用法与计费：GPT-5.6 系列 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna 缓存写入按 1.25 倍输入价、读取按 0.1 倍计费，支持 prompt_cache_key 与显式缓存断点，含接口示例与命中排查。

GPT 系列模型（gpt-4o 及之后）的提示缓存（Prompt Caching）自动生效：请求前缀达到 1,024 Token、且与近期请求逐字一致时，命中部分按缓存读取价计费，同时降低首 Token 延迟。GPT-5.6 系列（`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`）对缓存机制做了升级：缓存写入开始独立计费（1.25 倍输入价）、缓存读取为 0.1 倍输入价、缓存至少保留 30 分钟，并新增 `prompt_cache_key` 可靠匹配与显式缓存断点参数。

两代模型的缓存行为速览：

|                    | GPT-5.6 之前                       | GPT-5.6 及之后                                   |
| :----------------- | :------------------------------- | :-------------------------------------------- |
| 缓存方式               | 自动                               | 自动 + 显式断点                                     |
| 最小缓存长度             | 1,024 Token                      | 1,024 Token                                   |
| 缓存写入计费             | 不另计费                             | 1.25x 基础输入价                                   |
| 缓存读取计费             | 按对应模型的缓存读取价                      | 0.1x 基础输入价                                    |
| 缓存保留时间             | 不活跃 5–10 分钟后清除，最长 1 小时           | 至少保留 30 分钟                                    |
| `prompt_cache_key` | 可选，用于提高命中率                       | 官方要求设置，以启用更可靠的缓存匹配                            |
| 24 小时扩展保留          | 部分模型支持（`prompt_cache_retention`） | 由 `prompt_cache_options.ttl` 取代，当前仅支持 `"30m"` |

## 快速开始

提示缓存无需额外配置：用相同的长前缀连续请求两次，第二次响应的 `usage.prompt_tokens_details.cached_tokens` 大于 0 即为命中。GPT-5.6 系列建议同时设置 `prompt_cache_key`：

<CodeGroup>
  ```shell Curl theme={null}
  curl https://aihubmix.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -d '{
      "model": "gpt-5.6-sol",
      "prompt_cache_key": "my-app-report-assistant-v1",
      "messages": [
        {
          "role": "system",
          "content": "You are a meticulous assistant for analyzing quarterly financial reports... [此处放置固定不变的长指令或参考资料，≥1024 Token]"
        },
        {
          "role": "user",
          "content": "Summarize the key figures in one sentence."
        }
      ]
    }'
  ```

  ```py Python (OpenAI SDK) theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AIHUBMIX_API_KEY"],  # 密钥从环境变量读取
      base_url="https://aihubmix.com/v1",
  )

  long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [固定不变的长指令或参考资料，≥1024 Token]"

  # 相同前缀连续请求两次，第二次命中缓存
  for i in range(2):
      completion = client.chat.completions.create(
          model="gpt-5.6-sol",
          prompt_cache_key="my-app-report-assistant-v1",
          messages=[
              {"role": "system", "content": long_context},
              {"role": "user", "content": "Summarize the key figures in one sentence."},
          ],
      )
      print(completion.usage.prompt_tokens_details)
  ```
</CodeGroup>

两次调用的实测 usage（2026-07-10，`gpt-5.6-sol`）：

```json theme={null}
// 第 1 次调用：无命中
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 第 2 次调用：前缀命中缓存
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}
```

## 缓存计费

GPT-5.6 系列的缓存计费规则：

| 计费项        | 费率          |
| :--------- | :---------- |
| 常规输入 Token | 按平台定价       |
| 缓存写入 Token | 1.25x 基础输入价 |
| 缓存读取 Token | 0.1x 基础输入价  |
| 输出 Token   | 按平台定价       |

OpenAI 官方对该规则的表述（出自 [GPT-5.6 发布公告](https://openai.com/index/gpt-5-6/)）："For GPT‑5.6 and later models, cache writes are billed at 1.25x the model's uncached input rate, while cache reads continue to receive the 90% cached-input discount."。[官方提示缓存指南](https://developers.openai.com/api/docs/guides/prompt-caching)中该倍率的适用范围表述为 "GPT-5.6 models and later model families"（GPT-5.6 及之后的模型家族）。各模型的官方标价见 [OpenAI Pricing](https://developers.openai.com/api/docs/pricing)，AIHubMix 实际价格以[模型广场](https://aihubmix.com/models)为准。

由官方倍率可以直接算出盈亏：写入一段前缀比不缓存多付 0.25 倍输入价，此后每命中一次省 0.9 倍输入价。前缀只要被复用 1 次即净节省；复用次数越多节省越多。前缀完全不会复用的一次性请求会多付写入费，可以用 explicit 模式关闭缓存（见下文「GPT-5.6 缓存参数」）。

GPT-5.6 之前的模型缓存写入不另计费，缓存读取按对应模型的缓存读取价计费，各模型价格以[模型广场](https://aihubmix.com/models)为准。

<Note>
  GPT-5.6 系列区分长短上下文档位：单次请求输入超过 272K Token 时，整个请求按长上下文档计费（输入 2 倍、输出 1.5 倍）。缓存写入 1.25x、读取 0.1x 的倍率在长上下文档下同样成立，基数为长上下文档的输入价。
</Note>

## 缓存如何自动生效

发送请求时，系统会检查请求前缀（按 messages、tools 等序列化后的顺序）是否与近期请求的前缀逐字一致：

1. 前缀达到 1,024 Token 且找到一致的缓存前缀时，命中部分按缓存读取价计费，并降低首 Token 延迟；
2. 未找到时按常规输入处理，并把前缀写入缓存（GPT-5.6 及之后按 1.25x 计写入费）；
3. 命中要求前缀逐字节一致，前缀中任何一处变化都会使该位置之后的缓存全部失效。

以下场景收益最明显：

* 固定的长系统指令或大量 few-shot 示例
* RAG 场景中重复引用的长参考资料
* 携带大量工具定义（tools）的 Agent 工作流
* 只往后追加消息的长多轮对话

缓存保留时间：GPT-5.6 之前的模型在不活跃 5–10 分钟后清除、最长 1 小时；GPT-5.6 及之后至少保留 30 分钟，实际可能保留更久。缓存不跨组织共享，且缓存对输出内容没有影响。

## GPT-5.6 缓存参数

GPT-5.6 系列新增了三个缓存相关参数（Chat Completions 与 Responses API 通用）：

| 参数                        | 类型 / 位置      | 取值                                                     | 默认                              |
| :------------------------ | :----------- | :----------------------------------------------------- | :------------------------------ |
| `prompt_cache_key`        | string，请求体顶层 | 自定义稳定标识，建议按业务或租户划分；单个 key 的总流量建议控制在约 15 次/分钟内          | 无                               |
| `prompt_cache_options`    | object，请求体顶层 | `mode`: `"implicit"` / `"explicit"`；`ttl`: 仅支持 `"30m"` | `mode: "implicit"`、`ttl: "30m"` |
| `prompt_cache_breakpoint` | object，内容块内  | `{"mode": "explicit"}`，标记缓存前缀的结束位置                     | 不设置断点                           |

GPT-5.6 之前的模型不支持这三个参数中的 `prompt_cache_options` 与 `prompt_cache_breakpoint`，请求会被拒绝；旧模型的 24 小时扩展保留参数 `prompt_cache_retention`（`"24h"` / `"in_memory"`）在 GPT-5.6 及之后由 `prompt_cache_options.ttl` 取代。

三种缓存控制方式的关系：

1. **默认（implicit 模式）**：不传任何缓存参数也会自动写缓存——系统在最新一条消息的位置自动设置断点。GPT-5.6 及之后，自动发生的缓存写入同样按 1.25x 计费。
2. **implicit 模式 + 显式断点**：在自动断点之外，可在内容块上设置 `prompt_cache_breakpoint`，把缓存边界固定在稳定内容的末尾；断点之后的内容变化不会破坏断点之前的前缀缓存。
3. **explicit 模式**：`prompt_cache_options.mode` 设为 `"explicit"` 后只使用手动断点；完全不设置断点时该请求不使用缓存、也不产生缓存写入费。[官方原文](https://developers.openai.com/api/docs/guides/prompt-caching)："If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges."

用 explicit 模式关闭一次性长请求的缓存写入费：

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[不会复用的一次性长内容]"}
  ]
}
```

显式断点的官方规范用法（断点设置在固定长内容块的末尾）：

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[固定不变的长指令或参考资料，≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}
```

硬约束（官方口径）：

* 每个请求最多创建 4 个新的缓存写入；implicit 模式下自动断点占用其中 1 个；
* 断点之前的前缀仍需达到 1,024 Token 才会被缓存；
* 读取时在最近 50 个断点中取最长匹配前缀；
* 断点设置在不支持的内容块上会返回 `400 invalid_request_error`。Chat Completions 支持 `text` / `image_url` / `input_audio` / `file` / `refusal` 块，Responses API 支持 `input_text` / `input_image` / `input_file` 块。

<Note>
  AIHubMix 对 `prompt_cache_breakpoint` 内容块断点及 Responses API 缓存命中的支持正在完善中。现阶段推荐通过 Chat Completions 使用自动缓存并设置 `prompt_cache_key`（本页快速开始示例，已验证可命中）；`prompt_cache_options` 的 explicit 模式可正常用于关闭缓存写入。本页将随支持进度更新。
</Note>

## 为什么缓存没有命中

命中要求断点位置之前的所有内容逐字节一致。第二次请求 `cached_tokens` 仍为 0 时，按以下清单排查：

* **前缀不足 1,024 Token**：低于最小缓存长度的请求按常规输入处理；
* **前缀中混入了变化内容**：时间戳、会话 ID、用户变量等应放到固定内容之后，前缀中任何一处变化都会使之后的缓存失效；
* **tools 定义或顺序变化**：工具列表参与前缀计算，定义与排列顺序都必须完全一致；
* **图片 detail 参数不一致**：`detail` 影响图片 Token 化结果，需保持相同；
* **结构化输出 schema 变化**：`response_format` 的 JSON Schema 作为系统消息前缀参与缓存，schema 变化即前缀变化；
* **`reasoning_effort` 变化**：官方将其列为缓存命中率降低的常见原因之一（"Changes to reasoning effort"）；
* **超过缓存保留期**：GPT-5.6 之前不活跃 5–10 分钟后清除，GPT-5.6 及之后至少保留 30 分钟；
* **未设置 `prompt_cache_key`（GPT-5.6）**：不设置时仍可能自动命中，但不使用更可靠的匹配机制。

## 最佳实践

* 固定内容（系统指令、示例、参考资料、工具定义）放在请求最前面，每轮变化的内容放在最后；
* 为共享同一前缀的流量设置同一个稳定的 `prompt_cache_key`，单个 key 的总流量控制在约 15 次/分钟内，超出时按业务拆分更多 key；
* 多轮对话只向后追加消息，避免修改历史消息；
* 保持相同前缀的请求有持续流量，减少缓存被清除；
* 前缀不会复用的一次性长请求，用 explicit 模式避免缓存写入费（GPT-5.6 及之后）；
* 通过 `usage.prompt_tokens_details.cached_tokens` 持续监控命中情况。

## 常见问题

### GPT 的提示缓存需要手动开启吗？

无需手动开启：前缀达到 1,024 Token 即自动缓存。GPT-5.6 及之后建议同时设置 `prompt_cache_key` 以获得更可靠的缓存匹配。

### GPT-5.6 的缓存写入费如何计算？如何避免不必要的写入费？

缓存写入按基础输入价的 1.25 倍计费，读取按 0.1 倍计费；前缀被复用 1 次即净节省。前缀不会复用的一次性长请求，把 `prompt_cache_options.mode` 设为 `"explicit"` 且不设置断点，该请求即不使用缓存、不产生写入费。

### 缓存能保留多久？

GPT-5.6 及之后至少保留 30 分钟（`ttl` 当前仅支持 `"30m"`，实际可能保留更久）；GPT-5.6 之前的模型在不活跃 5–10 分钟后清除、最长 1 小时，部分旧模型支持 `prompt_cache_retention: "24h"` 扩展保留。

### GPT-5.6 的显式断点和 Claude 的 cache\_control 有什么区别？

两者都用于把缓存边界固定在稳定内容末尾。主要区别：GPT-5.6 无需任何参数即自动缓存、断点为可选精细控制，Claude 需在请求中启用缓存（顶层 `cache_control` 自动断点或内容块级显式断点）；GPT-5.6 缓存至少保留 30 分钟，Claude 默认 5 分钟、可选 1 小时；两者的缓存读取都按 0.1 倍输入价计费。Claude 的用法见 [Claude 提示词缓存](/cn/api/Claude-Cache)。

### 缓存会影响输出内容吗？

没有影响。官方口径：提示缓存只影响输入侧的处理与计费，模型生成输出的方式与不使用缓存时完全相同。

## 官方参考

本页机制、倍率与参数口径均来自以下 OpenAI 官方来源：

* [GPT-5.6 发布公告](https://openai.com/index/gpt-5-6/)：缓存写入 1.25x / 读取 90% 折扣的计费规则
* [提示缓存指南](https://developers.openai.com/api/docs/guides/prompt-caching)：机制、参数、usage 字段与限制
* [OpenAI Pricing](https://developers.openai.com/api/docs/pricing)：各模型官方标价
* [GPT-5.6 模型文档](https://platform.openai.com/docs/models/gpt-5.6-sol)：上下文窗口、长上下文计费阈值

AIHubMix 各模型实际价格以[模型广场](https://aihubmix.com/models)为准。

***

更新时间：2026-07-10