> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 缓存

> 安全复用模型响应，降低延迟和上游成本

Alephant AI Gateway 可以复用符合条件的模型响应，让重复请求避免不必要的上游调用。这可以降低稳定、可重复工作负载的延迟和 provider 成本。

缓存控制项是可选的 Gateway 请求头。Gateway 在处理请求时使用这些请求头，不会把它们发送给上游模型 provider。应用仍需自行判断响应是否适合安全复用。

## 缓存模式

Alephant 使用“缓存”描述多种不同机制。它们的行为和生命周期并不相同。

| 模式                         | 作用                                                                               |
| -------------------------- | -------------------------------------------------------------------------------- |
| 精确匹配响应缓存                   | 当请求产生相同缓存身份时复用响应。                                                                |
| 语义缓存                       | 当 workspace 已配置语义缓存和 embedding 支持时，查找相似度达到要求的请求。                                 |
| Provider 原生 prompt caching | 在上游 provider 内复用 prompt token。该行为通过 provider 用量和价格体现，不是 Alephant Gateway 响应缓存命中。 |
| 内部运行状态                     | 支持路由、策略上下文、幂等、session 和 Gateway 保护，不是可复用的模型响应。                                   |

## 何时使用缓存

适合缓存的请求通常具有稳定输入，并且响应可以在多次请求之间保持有效：

* 基于低频变更内容的知识问答
* 重复的分类、提取或摘要
* 使用可重复变量的固定 prompt 模板
* 对低延迟有要求的读密集型工作负载

以下情况应谨慎使用缓存：

* 答案必须反映实时数据
* 请求包含敏感信息或用户特有信息
* 请求可能调用工具或产生外部副作用
* 授权或业务状态可能在两次请求之间发生变化
* 应用依赖刻意生成的随机输出

Gateway 无法判断每一种业务特有的复用边界。当响应必须基于当前请求重新生成时，请关闭缓存读取和写入。

## 配置响应缓存

### 核心缓存请求头

| 请求头                              | 用途                                |
| -------------------------------- | --------------------------------- |
| `Alephant-Cache-Enabled`         | 设为 `true` 时启用缓存行为。                |
| `Alephant-Cache-Read`            | 设为 `true` 时允许从缓存读取。               |
| `Alephant-Cache-Save`            | 设为 `true` 时允许保存符合条件的响应。           |
| `Alephant-Cache-Bucket-Max-Size` | 可选的 bucket 数量，有效范围为 `1-20`。       |
| `Alephant-Cache-Seed`            | 参与缓存身份派生的可选 seed，可用于隔离明确的应用上下文。   |
| `Alephant-Cache-Control`         | 可选缓存控制，例如 `max-age` 或 `s-maxage`。 |

### 读取与保存行为

当应用需要可预期的行为时，请显式设置读取和保存控制项。

| Enabled | Read    | Save    | 行为                      |
| ------- | ------- | ------- | ----------------------- |
| `true`  | `true`  | `true`  | 先尝试读取缓存；符合条件的未命中响应可以保存。 |
| `true`  | `true`  | `false` | 读取已有响应，但不保存未命中响应。       |
| `true`  | `false` | `true`  | 跳过缓存查找，并允许写入符合条件的响应。    |
| 未启用     | 任意      | 任意      | 不使用其他控制项激活响应缓存。         |

Workspace 和 Gateway 配置可能影响缓存可用性。当应用依赖特定读写行为时，不应依赖未公开的默认值。

### 语义缓存请求头

语义缓存属于高级控制项。仅当 workspace 已配置语义缓存和 embedding 服务时使用。

| 请求头                                 | 用途                             |
| ----------------------------------- | ------------------------------ |
| `Alephant-Embeddings-Model`         | 语义缓存查找使用的 embedding model。     |
| `Alephant-Embeddings-Key`           | Gateway 执行查找时使用的 embedding 凭据。 |
| `Alephant-Cache-Semantic-Threshold` | 语义匹配的相似度阈值。                    |
| `Alephant-Cache-Ttl`                | 语义缓存使用的 TTL。                   |

请把 embedding 凭据视为 secret，不要提交到源码仓库，也不要写入应用日志。

## 示例

以下请求显式启用缓存读取和写入，并把缓存响应的最长有效时间设置为一小时：

```bash
curl "$ALEPHANT_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Alephant-Cache-Enabled: true" \
  -H "Alephant-Cache-Read: true" \
  -H "Alephant-Cache-Save: true" \
  -H "Alephant-Cache-Control: max-age=3600" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the refund policy in three bullets."
      }
    ]
  }'
```

再次发送相同的稳定输入，然后比较缓存响应元数据和 **Logs** 中的请求。`max-age=3600` 是本示例显式设置的值，并不表示 Gateway 存在某个隐含的默认生命周期。

## 请求生命周期

启用缓存的请求遵循以下逻辑流程：

1. 验证 Virtual Key，并解析 workspace、model 和请求上下文。
2. 根据适用的请求内容和缓存控制项派生缓存身份。
3. 如果允许读取，则尝试精确匹配查找或已配置的语义查找。
4. 查找成功时返回可复用响应和缓存元数据。
5. 未命中时，把请求发送给选定的上游 provider。
6. 如果允许保存且响应符合条件，则将其写入响应缓存。
7. 继续在已配置的 Logs、Analytics 和成本归因链路中记录请求。

以上是逻辑阶段，不代表对内部线程顺序、Redis 操作或强一致性的承诺。

## 验证缓存命中

启用缓存的响应可能包含：

| 响应头                         | 用途                           |
| --------------------------- | ---------------------------- |
| `alephant-cache`            | 请求的缓存状态。                     |
| `alephant-cache-bucket-idx` | 返回缓存条目的 bucket 索引。           |
| `alephant-cache-latency`    | 缓存查找延迟。                      |
| `alephant-id`               | Alephant 请求标识符，对缓存返回的响应尤其有用。 |

验证方法：

1. 启用缓存读取和写入，对同一稳定请求发送两次。
2. 比较 `alephant-cache`、缓存延迟和 Alephant 请求标识符。
3. 打开 **Logs**，检查缓存状态、provider、token、成本和请求上下文。
4. 如果第二次请求仍未命中，比较 model、messages、参数、seed、TTL 和缓存控制项。

`alephant-cache` 报告的具体值可能取决于已部署的 Gateway 版本。请检查实际响应，不要依赖未公开的枚举。

## 故障排查

| 现象                | 检查项                                                                   |
| ----------------- | --------------------------------------------------------------------- |
| 看似相同的 prompt 仍未命中 | 比较完整请求、model、参数、seed、TTL、workspace 和缓存控制项。                            |
| 关闭保存后请求仍然命中       | `Alephant-Cache-Save: false` 不会阻止 `Alephant-Cache-Read: true` 读取已有条目。 |
| 未执行语义查找           | 确认 workspace、embedding model、embedding 凭据和相似度阈值均已配置。                  |
| 响应可能跨越业务边界        | 关闭读取和保存，或者使用显式 seed 隔离边界清晰的应用上下文。                                     |
| 不同部署的缓存行为不同       | 比较 Gateway 版本、workspace 配置和底层缓存服务。                                    |

## 内部缓存与状态

Gateway 还会保存短期或可复用的运行状态。这些机制支持请求处理，但不同于模型响应缓存。

| 类别                | 内部状态                                                               | 用户可感知的作用                                               |
| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| 请求与策略上下文          | Prompt Cache、PII Cache 开关、VK Enrichment Cache                      | 解析 prompt 模板，并使用 workspace 和 department 元数据补充策略或日志上下文。 |
| 模型与语义能力发现         | Model Catalog Cache、Embedding Base URL Cache                       | 加速模型支持情况查找，并选择已配置的 embedding 服务。                       |
| 异步任务一致性           | Image Task Affinity、Image Task Cost Claim                          | 复用图片任务创建时选定的 provider 路径，并防止重复成本认领。                    |
| Agent 与工具 session | MCP Session Cache、MCP Session Lock、Agent Step State                | 复用 MCP session、协调初始化，并检测重复或冲突 step。                    |
| Endpoint 与区域路由    | x402 Endpoint Snapshot、x402 Signing Secret、Regional Endpoint       | 解析 endpoint 配置、受保护的签名材料和已确定的区域路由。                      |
| Gateway 保护        | Workspace Concurrency、Client IP Rate Limit、Gateway In-flight Limit | 执行 workspace、客户端 IP 和 Gateway 全局流量保护。                  |

这些状态不共享统一的 TTL 或失效规则。未命中可能触发数据库查找或重新初始化，不一定表示故障。并发、限流、锁和幂等状态都不代表可复用的模型响应。其 key、value 和生命周期属于部署实现，而不是公开 API 合同。

## 缓存、日志与计费

Logs 和计费链路还会维护其他缓存与聚合数据，用于模型价格、自定义价格、workspace 或 department 消费、Virtual Key 消费、token 和请求计数、Agent 成本、用量限制决策、鉴权以及通用查询结果。

排查成本时，应区分以下事件：

* Provider 原生 cached token 事件通过 provider 用量和价格体现。
* Gateway 响应缓存命中会在再次生成上游响应之前复用已有响应。
* 内部价格缓存命中只会加速成本计算。
* 限流与消费聚合服务于执行和报告，不是响应缓存。

缓存命中仍应具有可观测元数据。请以实际 **Logs** 和 **Analytics** 记录为准，判断请求的 provider token、Gateway 费用、缓存节省和归因成本。

## 安全与运维建议

* 不要缓存授权决策、一次性结果，或不得跨请求复用的敏感响应。
* 不要把 secret、个人数据或受监管标识符放入 cache seed 或自定义可观测 metadata。
* 应用必须使用已公开的 Gateway 请求头和响应头，不应依赖内部 Redis key。
* Private deployment 应把 Redis 或 Valkey 作为受保护的基础设施：限制网络访问、要求身份验证、在支持时加密传输，并避免在日志中暴露运行值。
* 修改缓存配置后，应先使用非敏感测试请求验证行为，再扩大启用范围。

## 相关页面

* [Gateway 集成](/docs/overview/core-concepts/gateway-integration)
* [Prompt 管理](/ai-gateway/prompt-manage)
* [路由优化](/ai-gateway/routing-optimization)
* [Session](/ai-gateway/session)
* [日志](/docs/overview/security-compliance/audit-logs)
* [分析](/docs/overview/fin-ops-budget/cost-analytics)