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

# 缓存计费

> 提示缓存命中如何按更低倍率结算

主流厂商(OpenAI、Anthropic、DeepSeek、Google)都支持 **提示缓存(Prompt Caching)** —— 把长 system prompt / RAG 上下文标记后,后续相同前缀可命中缓存,按更低单价结算。

OpenPAI 完整透传缓存相关字段,缓存命中部分按更低倍率扣费,**对客户端无感**。

## OpenAI 自动缓存

OpenAI 自 GPT-4o 起对 ≥1024 token 的前缀 **自动缓存**,无需客户端任何配置。

* 缓存命中价格通常为输入价格的 **0.5×**(GPT-4o)或 **0.1×**(o3 / GPT-5)。
* 响应 `usage.prompt_tokens_details.cached_tokens` 字段显示命中数。

OpenPAI 同步透传该字段,并按相应倍率扣费。

## Claude `cache_control`

Claude 通过显式 `cache_control` 标记缓存段:

```json theme={null}
{
  "model": "claude-opus-4-8",
  "system": [
    {
      "type": "text",
      "text": "<长 system prompt 50000 字>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "..."}]
}
```

* **写入**:首次创建缓存按 **1.25×** 输入价格(贵 25%)。
* **命中**:后续 5 分钟内相同前缀按 **0.1×** 输入价格。
* TTL:5 分钟(可在 cache\_control 中通过 `ttl: "1h"` 延长,需对应产品支持)。

## DeepSeek 自动缓存

DeepSeek-V3 / R1 对长前缀自动缓存,缓存命中按官方公示的极低单价计费(通常约 0.1× 原价)。

* 命中数显示在 `usage.prompt_cache_hit_tokens` 字段。
* OpenPAI 透传并对应扣费。

## Google Gemini Context Caching

Gemini 2.5 系列支持显式 `cachedContents` 接口:

```python theme={null}
cache = client.caches.create(
    model="gemini-3.1-pro-preview",
    contents=["<长上下文>"],
    ttl="1h",
)

resp = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="基于上下文回答问题...",
    cached_content=cache.name,
)
```

OpenPAI 透传 `cached_content` 引用,命中部分按 Google 公示的缓存价格结算。

## 控制台展示

调用日志中可以看到:

| 字段         | 含义                   |
| ---------- | -------------------- |
| 输入 Token   | 客户端发送的原始输入           |
| 命中缓存 Token | 其中命中缓存的部分            |
| 缓存倍率       | 命中部分按此倍率计费           |
| 缓存写入 Token | 仅 Claude,首次写入的额外贵价部分 |

## 最佳实践

<CardGroup cols={2}>
  <Card title="把不变内容放前面" icon="arrow-up">
    System prompt、RAG 检索结果、Few-shot 示例 → 放到 messages 数组前面,后面追加用户问题。
  </Card>

  <Card title="批量请求共享前缀" icon="clone">
    同一长上下文下,多次问不同问题,缓存命中收益最大化。
  </Card>

  <Card title="控制变化" icon="lock">
    避免在前缀里插入时间戳、随机数,否则前缀对不上就无法命中。
  </Card>

  <Card title="测量收益" icon="chart-line">
    在日志中观察 `cached_tokens` 占比,优化 prompt 结构。
  </Card>
</CardGroup>

## 注意事项

* 缓存命中率受 **上游实际可用性** 影响,OpenPAI 不会人为伪造缓存命中。
* 跨通道路由的请求可能在两个上游账号之间切换,导致缓存失效 —— 高缓存依赖的场景可在控制台为模型 **绑定固定通道**。
* 缓存内容由上游厂商加密存储,OpenPAI 不存储任何 prompt 内容。