> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/cn/compute/aig/gateway-features/cache-optimization.md).

# 缓存优化指南

## 1. 概述

为了帮助您获得更快的响应速度并降低 API 调用成本，Zenlayer AI 网关提供了强大的智能缓存机制。在多账号架构下，通过合理配置请求参数，可以显著提升缓存命中率与上下文连贯性。

***

## 2. 为什么需要提供关联标识？

Zenlayer 采用多账号并发模式以确保服务的高可用性。默认情况下，网关会根据请求内容（Request Key）进行 Hash 调度。

* **默认模式**：如果请求中不包含唯一标识，系统将随机或基于内容分发。由于 AI 模型的补全具有随机性，不同账号间的缓存无法完全共享，这会导致缓存命中率处于较低水平。
* **优化模式**：当您在请求中明确终端用户身份时，网关能将来自同一终端的请求精准路由至同一后端账号，从而最大化利用该账号的预热缓存（KV Cache）。

***

## 3. 如何优化：两种接入方式

您可以通过以下任一方式告诉网关：“这是一个连续的会话”。

### 3.1 方案 A：使用 Header 传递（推荐）

在 HTTP 请求头中添加 `X-Conversation-Id`。这种方式对原始 Body 侵入性小，适合标准的 API 调用。

**配置示例：**

```http
X-Conversation-Id: sess_abc123789
```

***

### 3.2 方案 B：使用 Body 传递

#### 3.2.1 metadata.user\_id 参数（Claude Code 会自动添加）

在请求体（JSON Body）`metadata` 参数中包含 `user_id` 字段。网关会自动解析该字段并锁定对应的后端链路。

**配置示例：**

```json
{
  "model": "claude-opus-4-6",
  "messages": [...],
  "metadata": {
    "user_id": "sess_abc123789"
  }
}
```

#### 3.2.2 prompt\_cache\_key 参数（OpenAI Codex 会自动添加）

在请求体（JSON Body）`prompt_cache_key` 参数。网关会自动解析该字段并锁定对应的后端链路。

**配置示例：**

```json
{
  "model": "gpt-5.5",
  "messages": [...],
  "prompt_cache_key": "sess_abc123789"
}
```

***

## 4. 性能预期与温馨提示

Zenlayer 致力于通过全球加速网络和多账号调度算法，为您提供优于直连原厂的稳定体验。

需要说明的是，由于 Zenlayer 运行在分布式平台模式下，为了兼顾高可用性与负载均衡，底层资源由多个高品质账号池共同承载。

**关于缓存率的说明：** 虽然通过上述优化手段（如携带 `X-Conversation-Id`）可以大幅提升响应速度，但受限于平台多链路并发调度的物理特性，其缓存命中率在极端高并发场景下，可能与单一原厂独立账号的极致缓存表现存在细微差异。

我们将持续通过算法优化，在确保业务永不掉线的同时，为您无限趋近于原厂的性能表现。