通过前缀复用降低成本
上下文缓存(Context cache)将重叠请求的公共前缀进行缓存,避免重复计算,从而在不影响回答质量的前提下加快响应速度、降低使用成本。
上下文缓存提供三种模式,适用于不同场景。请根据对便捷性、确定性和成本的需求选择合适的模式:
相较于隐式缓存,显式缓存需要手动创建且有额外开销,但能提供更高的缓存命中率和更低的访问延迟。
在
以下示例展示了缓存块的创建和命中过程。
对同一代码仓库的后续请求会复用已有的缓存块,从而获得更快的响应速度和更低的成本。
在复杂场景中,prompt 通常由多个复用频率不同的部分组成。您可以使用多个缓存标记来实现精细化控制。
例如,智能客服的 prompt 通常包括:
显式缓存仅影响输入 token 的计费,规则如下:
仅
其他消息类型的结构同理。
文本生成模型
视觉理解模型
当您向支持隐式缓存的模型发送请求时,该功能自动开启。系统的工作流程如下:
隐式缓存通过识别不同请求之间重复的前缀内容来工作。要提高命中率,应将静态内容放在 prompt 开头,将可变内容放在末尾。
隐式缓存无额外费用。
当请求命中缓存时,命中的输入 token 按
您可以从返回结果的
在
在
后续请求的 message 数组
尽管问题不同,但引用的是同一篇文章。由于 system prompt 和文章内容保持不变,每次请求共享大量重叠前缀,因此缓存命中的可能性很高。
第二轮对话的 message 数组
随着对话轮数增加,缓存带来的推理加速和成本降低效果越发显著。
借助上下文缓存,即使用户频繁更换询问的产品类型(如从智能手表切换到笔记本电脑),一旦命中缓存,系统就能快速响应。
会话缓存是一种面向使用 Responses API 进行多轮对话的缓存模式。与需要手动添加
在请求头中添加以下字段来控制会话缓存:
第二轮响应示例(缓存命中)
第二轮对话的
会话缓存的计费规则与显式缓存一致:
无法关闭。隐式缓存对所有支持的模型自动开启,因为它不影响回答质量,且在命中缓存时能降低成本、提升响应速度。
可能有以下原因:
会。每次命中都会将该缓存块的有效期重置为 5 分钟。
不会。隐式缓存和显式缓存的数据都按账号隔离,不会跨账号共享。
不会。缓存数据按模型隔离,不会跨模型共享。
为了保证模型输出质量,后端服务会在用户提供的 prompt 之后附加少量 token(通常不超过 10 个)。这些 token 位于
- 显式缓存:需手动开启的缓存模式。对指定内容创建缓存,可实现确定性命中。缓存有效期为 5 分钟。创建缓存所用的 token 按标准输入 token 价格的 125% 计费,后续命中按标准价格的 10% 计费。
- 隐式缓存:无需额外配置、无法关闭的自动模式,适用于追求便捷性的通用场景。系统自动识别并缓存请求的公共前缀,但不保证命中。命中部分按标准输入 token 价格的 20% 计费。
- 会话缓存:专为使用 Responses API 的多轮对话场景设计。只需在请求头中添加
x-dashscope-session-cache: enable,服务端即自动缓存对话上下文。计费规则与显式缓存一致:创建缓存按标准输入 token 价格的 125% 计费,命中按 10% 计费。
| 项目 | 显式缓存 | 隐式缓存 | 会话缓存 |
|---|---|---|---|
| 是否影响回答质量 | 无影响 | 无影响 | 无影响 |
| 缓存创建 token 计费 | 标准输入 token 价格的 125% | 标准输入 token 价格的 100% | 标准输入 token 价格的 125% |
| 缓存命中 token 计费 | 标准输入 token 价格的 10% | 标准输入 token 价格的 20% | 标准输入 token 价格的 10% |
| 最少缓存 token 数 | 1024 | 256 | 1024 |
| 缓存有效期 | 5 分钟(命中后重置) | 不保证,系统会定期清理未使用的缓存数据 | 5 分钟(命中后重置) |
- 使用 Chat Completions API 或 DashScope API 时,显式缓存与隐式缓存互斥,单次请求只能使用其中一种模式。
- 使用 Responses API 时,如果未开启会话缓存,且模型支持隐式缓存,则自动使用隐式缓存。
显式缓存
相较于隐式缓存,显式缓存需要手动创建且有额外开销,但能提供更高的缓存命中率和更低的访问延迟。
支持的模型
| 类别 | 模型 |
|---|---|
| 千问 Max | qwen3.6-max-preview、qwen3-max |
| 千问 Plus | qwen3.6-plus、qwen3.5-plus、qwen3.5-plus-2026-04-20、qwen-plus |
| 千问 Flash | qwen3.6-flash、qwen3.5-flash、qwen-flash |
| 千问 Coder | qwen3-coder-plus、qwen3-coder-flash |
| 千问 VL | qwen3-vl-plus、qwen3-vl-flash |
| DeepSeek | deepseek-v3.2 |
| Kimi | kimi-k2.6、kimi-k2.5 |
| GLM | glm-5.1 |
使用方式
在 messages 数组中添加 "cache_control": {"type": "ephemeral"} 标记。系统会从每个 cache_control 标记的位置向前检索最多 20 个 content 块,并尝试与已有的缓存块进行匹配。
单次请求最多支持四个缓存标记。
-
缓存未命中
系统会使用从
messages数组开头到cache_control标记之间的内容创建新的缓存块。缓存块有效期为 5 分钟。- 缓存创建发生在模型响应之后。建议等待创建请求完成后再发送后续请求。
- 缓存块至少需要包含 1024 个 token。
- 缓存命中 系统会选择最长匹配的前缀作为命中的缓存块,并将该缓存块的有效期重置为 5 分钟。
1
发送第一个请求
发送一条包含超过 1024 个 token 的文本 A 的 system 消息,并添加缓存标记。系统创建第一个缓存块,称为缓存块 A。
2
发送第二个请求
发送如下结构的请求:
- 如果"其他消息"不超过 20 条,缓存块 A 被命中,有效期重置为 5 分钟。同时系统基于 A、其他消息和 B 创建新的缓存块。
- 如果"其他消息"超过 20 条,缓存块 A 不会被命中。系统基于完整上下文(A + 其他消息 + B)创建新的缓存块。
快速开始
以下示例展示了缓存块的创建和命中过程。
使用多个缓存标记实现精细化控制
在复杂场景中,prompt 通常由多个复用频率不同的部分组成。您可以使用多个缓存标记来实现精细化控制。
例如,智能客服的 prompt 通常包括:
- 系统设定:非常稳定,几乎不会改变。
- 外部知识:半稳定。从知识库检索或调用工具获取,在一段连续对话中可能保持不变。
- 对话历史:动态增长。
- 当前问题:每次都不同。
计费
显式缓存仅影响输入 token 的计费,规则如下:
-
缓存创建:新创建的缓存内容按标准输入价格的 125% 计费。如果新缓存内容包含已有缓存作为前缀,则仅对增量部分收取创建费用(新缓存 token 数减去已有缓存 token 数)。
例如,假设已有缓存块 A 包含 1200 个 token,新请求需要缓存内容 AB,共 1500 个 token,则前 1200 个 token 按缓存命中计费(标准价格的 10%),新增的 300 个 token 按缓存创建计费(标准价格的 125%)。
可通过
cache_creation_input_tokens参数查看用于缓存创建的 token 数。 -
缓存命中:按标准输入价格的 10% 计费。
可通过
cached_tokens参数查看命中缓存的 token 数。 - 其他 token:未命中任何缓存且未用于创建缓存的 token 按标准价格计费。
可缓存内容
仅 messages 数组中的以下消息类型支持添加缓存标记:
- System 消息
- User 消息
- Assistant 消息
-
Tool 消息(工具执行后的结果)
如果请求中包含
tools参数,在messages中添加缓存标记也会同时缓存请求中定义的工具描述。
content 字段改为数组格式并添加 cache_control 字段:
缓存限制
- 最小可缓存的 prompt 长度为 1024 个 token。
-
缓存使用向前前缀匹配策略。系统自动检查最近的 20 个 content 块。如果待匹配的内容与包含
cache_control标记的消息之间相隔超过 20 个 content 块,则不会命中缓存。 -
type仅支持设置为ephemeral,即有效期为 5 分钟。 -
单次请求最多可包含 4 个缓存标记。
如果缓存标记超过四个,仅最后四个生效。
使用示例
对长文本提出不同问题
对长文本提出不同问题
连续多轮对话
连续多轮对话
在日常多轮对话场景中,您可以在每次请求的 messages 数组末尾的最后一条内容上添加缓存标记。从第二轮对话开始,每次请求都会命中并刷新上一轮创建的缓存块,同时创建新的缓存块。运行上述代码并输入问题与模型交流。每个问题都会命中上一轮创建的缓存块。
隐式缓存
支持的模型
文本生成模型
| 类别 | 模型 |
|---|---|
| 千问 Max | qwen3-max、qwen3-max-preview、qwen-max |
| 千问 Plus | qwen-plus |
| 千问 Flash | qwen-flash |
| 千问 Turbo | qwen-turbo |
| 千问 Coder | qwen3-coder-plus、qwen3-coder-flash |
| DeepSeek(千问云部署) | deepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2、deepseek-v3.1、deepseek-v3、deepseek-r1 |
| DeepSeek(快手万擎部署) | vanchin/deepseek-v3.2-think、vanchin/deepseek-v3.1-terminus、vanchin/deepseek-r1、vanchin/deepseek-v3 |
| Kimi(千问云部署) | kimi-k2.6、kimi-k2.5、kimi-k2-thinking、Moonshot-Kimi-K2-Instruct |
| Kimi(月之暗面部署) | kimi/kimi-k2.6、kimi/kimi-k2.5 |
| GLM | glm-5.1、glm-5、glm-4.7、glm-4.6 |
| MiniMax(千问云部署) | MiniMax-M2.5、MiniMax-M2.1 |
| MiniMax(稀宇科技部署) | MiniMax/MiniMax-M2.7、MiniMax/MiniMax-M2.5、MiniMax/MiniMax-M2.1 |
稀宇科技部署的 MiniMax 模型触发隐式缓存的最少 Token 数为 512,千问云部署的模型为 256。
| 类别 | 模型 |
|---|---|
| 千问 VL | qwen3-vl-plus、qwen3-vl-flash、qwen-vl-max、qwen-vl-plus |
| 行业模型 | qwen-doc-turbo |
工作原理
当您向支持隐式缓存的模型发送请求时,该功能自动开启。系统的工作流程如下:
- 查找:收到请求后,系统基于前缀匹配原则,在缓存中查找与请求
messages数组内容的公共前缀。 - 判定:
- 如果缓存命中,系统直接使用缓存结果进行后续推理。
- 如果缓存未命中,系统正常处理请求,并将当前 prompt 的前缀存入缓存供后续请求使用。
系统会定期清理未使用的缓存数据,少于 256 个 token 的内容不会被缓存。命中率不保证为 100%——即使请求上下文完全相同,也可能发生缓存未命中的情况。
提高命中率
隐式缓存通过识别不同请求之间重复的前缀内容来工作。要提高命中率,应将静态内容放在 prompt 开头,将可变内容放在末尾。
- 纯文本场景:如果系统已缓存"ABCD",请求"ABE"可以匹配"AB"前缀,而请求"BCD"则无法匹配任何缓存。
- 视觉理解场景:
- 对同一张图片或视频提出多个问题时:将图片或视频放在文本之前,有助于提高命中率。
- 对不同图片或视频提出相同问题时:将文本放在图片或视频之前,有助于提高命中率。
计费
隐式缓存无额外费用。
当请求命中缓存时,命中的输入 token 按 cached_token 计费,折扣比例因模型来源不同而有差异;未命中缓存的输入 token 按标准 input_token 价格计费。输出 token 按标准价格计费。
- 千问云部署的模型(deepseek-v4-pro 除外):
cached_token单价为input_token单价的 20% - deepseek-v4-pro:
cached_token单价不是input_token单价的 20%,具体价格请参见模型广场 - DeepSeek(快手万擎部署):vanchin/deepseek-v3.2-think 为 10%;vanchin/deepseek-v3.1-terminus、vanchin/deepseek-r1、vanchin/deepseek-v3 为 40%
- Kimi(月之暗面部署):kimi/kimi-k2.6 为 16.9%;kimi/kimi-k2.5 为 17.5%
- MiniMax(稀宇科技部署):MiniMax/MiniMax-M2.7 为 20%,MiniMax/MiniMax-M2.5、MiniMax/MiniMax-M2.1 为 10%
- 未命中 token(5,000):按单价的 100% 计费
- 命中 token(5,000):按单价的 20% 计费

cached_tokens 字段获取命中缓存的 token 数。
OpenAI 兼容-Batch(文件输入)方式不享受缓存折扣。
缓存命中示例
文本生成
在 usage.prompt_tokens_details.cached_tokens 中查看命中缓存的 token 数(属于 OpenAI 兼容的 usage.prompt_tokens 或 DashScope 的 usage.input_tokens 的一部分)。
视觉理解
在 usage.prompt_tokens_details.cached_tokens(属于 OpenAI 兼容的 usage.prompt_tokens 的一部分)或 usage.cached_tokens(属于 DashScope 的 usage.input_tokens 的一部分)中查看命中缓存的 token 数。
当前使用
usage.cached_tokens 的模型将来会升级为使用 usage.prompt_tokens_details.cached_tokens。典型场景
- 基于长文本的问答 适用于需要对同一长文本(如小说、教材或法律文件)进行多次请求的场景。 第一次请求的 message 数组
- 代码自动补全 在代码自动补全场景中,模型基于已有的上下文自动补全代码。随着用户持续编码,代码的前缀部分保持不变。上下文缓存可以缓存前面的代码,从而提高补全速度。
- 多轮对话 在多轮对话中,前几轮的对话历史都包含在 messages 数组中。因此每一轮请求都与上一轮共享相同的前缀,缓存命中的概率很高。 第一轮对话的 message 数组
- 角色扮演或 few-shot 学习 在角色扮演或 few-shot 学习场景中,通常需要在 prompt 中包含大量信息来引导模型的输出格式。这会在不同请求间产生大量共享前缀。 例如,如果您希望模型扮演一位营销专家,system prompt 中会包含大量文本信息。以下是两次请求的消息示例:
-
视频理解
在视频理解场景中,如果对同一视频提出多个问题,将
video放在text之前可以提高缓存命中率。如果对不同视频提出相同问题,将text放在video之前可以提高缓存命中率。以下是对同一视频发出两次请求的消息示例:
会话缓存
支持的模型
qwen3-max、qwen3.6-plus、qwen3.5-plus、qwen3.6-flash、qwen3.5-flash、qwen-plus、qwen-flash、qwen3-coder-plus、qwen3-coder-flash
概述
会话缓存是一种面向使用 Responses API 进行多轮对话的缓存模式。与需要手动添加 cache_control 标记的显式缓存不同,会话缓存由服务端自动处理缓存逻辑。您只需通过 HTTP 请求头开启或关闭,然后像普通多轮对话一样进行调用即可。
当您使用
previous_response_id 进行多轮对话时,开启会话缓存可让服务端自动缓存对话上下文,从而降低推理延迟和使用成本。使用方式
在请求头中添加以下字段来控制会话缓存:
x-dashscope-session-cache: enable:开启会话缓存。x-dashscope-session-cache: disable:关闭会话缓存。如果模型支持隐式缓存,则使用隐式缓存。
default_headers(Python)或 defaultHeaders(Node.js)参数传递此请求头。使用 curl 时,通过 -H 参数传递。
代码示例
cached_tokens 字段显示命中缓存的 token 数:
input_tokens 为 1524,其中 cached_tokens 为 1305,说明第一轮的上下文被缓存命中,可以有效降低推理延迟和成本。
计费
会话缓存的计费规则与显式缓存一致:
- 缓存创建:按标准输入 token 价格的 125% 计费。
-
缓存命中:按标准输入 token 价格的 10% 计费。
可通过
usage.input_tokens_details.cached_tokens参数查看命中缓存的 token 数。 - 其他 token:未命中且未用于创建缓存的 token 按标准价格计费。
限制
- 最小可缓存的 prompt 长度为 1024 个 token。
- 缓存有效期为 5 分钟,命中后重置。
- 仅适用于 Responses API,需配合
previous_response_id参数进行多轮对话。 - 会话缓存与显式缓存、隐式缓存互斥。开启会话缓存时,其他两种模式不生效。
FAQ
如何关闭隐式缓存?
无法关闭。隐式缓存对所有支持的模型自动开启,因为它不影响回答质量,且在命中缓存时能降低成本、提升响应速度。
为什么创建了显式缓存却没有命中?
可能有以下原因:
- 缓存创建后 5 分钟内未被命中,系统在缓存块过期后将其清除。
- 如果最后一个
content块与已有缓存块之间相隔超过 20 个content块,则不会命中缓存。建议创建新的缓存块。
命中显式缓存会重置有效期吗?
会。每次命中都会将该缓存块的有效期重置为 5 分钟。
显式缓存是否在不同账号之间共享?
不会。隐式缓存和显式缓存的数据都按账号隔离,不会跨账号共享。
显式缓存是否在不同模型之间共享?
不会。缓存数据按模型隔离,不会跨模型共享。
为什么 input_tokens 不等于 cache_creation_input_tokens + cached_tokens?
为了保证模型输出质量,后端服务会在用户提供的 prompt 之后附加少量 token(通常不超过 10 个)。这些 token 位于 cache_control 标记之后,因此不计入缓存创建或命中的 token 数,但会包含在总的 input_tokens 中。
