跳转到主要内容
上下文管理

显式缓存(Qwen4)

仅适用于 Qwen4 系列模型的显式缓存。通过自动缓存或缓存断点指定需要复用的输入前缀,并按 5 分钟或 1 小时设置缓存有效期,减少重复计算,降低延迟和输入成本。

在多轮对话、长文档问答、Agent 等场景中,连续请求往往包含大量相同的开头内容,例如系统提示词、工具说明或参考文档。使用显式缓存(Qwen4)后,有效期内的后续请求可以直接读取这部分内容的缓存,无需重复计算,从而降低响应延迟和输入成本。 显式缓存通过缓存断点指定需要复用的内容前缀,命中是确定的:只要前缀完全相同且在有效期内,后续请求就能读取缓存。系统自动识别公共前缀的隐式缓存不保证命中。 Qwen4 在基础用法之上提供自动缓存和缓存有效期(TTL)两项进阶用法,详见进阶用法。 本功能支持 Chat Completions、Responses 和 Anthropic Messages API。DashScope API 不支持 Qwen4 新显式缓存。
本文介绍原有显式缓存在 Qwen4 上的版本:内容块断点的用法保持不变,并新增自动缓存与缓存有效期(TTL)。与上下文缓存中两种缓存方式的关系:
  • 显式缓存:通过缓存断点指定输入前缀,命中确定,即本文介绍的内容。
  • 隐式缓存:不设置任何缓存参数时自动识别公共前缀,不保证命中,详见隐式缓存。
  • OpenAI 兼容 Chat Completions 接口原有的 cache_control 内容块标记继续兼容,用法与 prompt_cache_breakpoint 相同,详见基础用法。

工作原理

缓存以断点为单位创建和读取。自动缓存的断点由系统设置在输入末尾,缓存断点由您在内容块上标记。每个断点对应的缓存前缀是从请求开头到断点所在内容块末尾的全部输入。 收到请求后,系统以每个断点为终点,向前查找最多 20 个内容块,选取已缓存的最长相同前缀:
  • 命中缓存:读取已缓存的前缀,并按本次请求的 TTL 续期。
  • 未命中缓存:从请求开头到断点处的内容创建为新的缓存。若前缀中有部分内容已命中缓存,仅对新增部分创建缓存。
缓存前缀需完全相同才能命中,且仅在同一用户的请求之间复用。将固定不变的内容放在前面、每次变化的内容放在断点之后,可以提高命中率。 未设置任何缓存参数时,系统使用隐式缓存自动识别请求的公共前缀,但不保证命中。需要稳定复用指定内容时,请开启自动缓存或设置缓存断点。

基础用法

在请求中需要复用的内容块上设置缓存断点。系统以该内容块的末尾作为断点,把从请求开头到该处的全部输入作为缓存前缀:第一次请求创建缓存,有效期内前缀相同的后续请求读取缓存。缓存前缀至少为 1,024 Token。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic兼容
在 messages 中需要缓存的内容块上添加 prompt_cache_breakpoint,值为 {"mode": "explicit"}。添加断点的消息,其 content 需使用数组形式:
messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- 缓存断点
      },
      {"type": "text", "text": "请概括这份文档。"},  # 断点之后的内容不参与该缓存
    ],
  }
],
原有的 "cache_control": {"type": "ephemeral"} 内容块标记继续兼容,用法与 prompt_cache_breakpoint 相同。同一用户的相同前缀可以在两种标记之间复用缓存。新接入推荐使用 prompt_cache_breakpoint。
同一请求中请只使用 prompt_cache_breakpoint 和 cache_control 中的一种。
以下示例连续发送两次请求:第一次请求创建缓存,第二次请求保持前缀不变、只修改问题,从而读取缓存。
Python
import os
from openai import OpenAI

client = OpenAI(
  # 若没有配置环境变量,请将下行替换为:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
)

# 需要复用的长文档,缓存前缀最少为 1024 Token
long_text = "<固定的长文档>" * 400

def ask(question):
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
      {
        "role": "user",
        "content": [
          {"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}},  # <-- 缓存断点
          {"type": "text", "text": question},  # 断点之后的内容每次可以不同
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("请概括这份文档。")  # 第一次请求:创建缓存
details = ask("请列出文档的三个要点。")  # 第二次请求:读取缓存
print(f"读取缓存 {details.cached_tokens} Token,创建缓存 {details.cache_write_tokens} Token")
第二次请求的 cached_tokens 为读取的缓存量,cache_write_tokens 为本次创建的缓存量。前缀不变时,cache_write_tokens 为 0。数字为示意,实际取决于文档长度。

使用多个断点

当提示词由变化频率不同的几部分组成时,可以为每一部分分别设置断点。例如智能客服的提示词通常包括系统人设(几乎不变)、知识库检索结果(随咨询主题变化)和对话历史(持续增长)。在每部分末尾设置断点后,即使知识库内容发生变化,系统人设部分仍可命中缓存。 每个请求最多保留最后 4 个有效断点,超出的断点不生效。开启自动缓存时,自动断点占用其中 1 个。

断点位置变化时的续期

系统只创建或续期本次请求中的断点。断点位置改变后,即使读取了旧断点的缓存,旧断点的有效期也不会延长。 例如,在 TTL 不变的情况下,上次请求的断点位于第 2,048 Token 处,本次请求将断点移到第 3,072 Token 处且未保留旧断点。若旧断点在查找范围内且未过期,本次请求读取前 2,048 Token 的缓存,并为后续 1,024 Token 创建缓存;系统只创建或续期第 3,072 Token 处的断点,第 2,048 Token 处的缓存不续期。

进阶用法

Qwen4 在基础用法之上提供以下两项能力,可以组合使用:
  • 自动缓存:由系统自动在输入末尾设置断点,适合多轮对话。
  • 缓存有效期(TTL):可选 5 分钟或 1 小时。

自动缓存

开启自动缓存后,系统自动在每次请求的输入末尾设置断点,无需随对话增长逐轮移动断点。自动断点不包含用于开始生成回复的模板后缀。自动缓存可以与基础用法中的缓存断点同时使用;若输入末尾已有手动断点,不会重复设置。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic兼容
在请求顶层设置 prompt_cache_options,并将 mode 设置为 implicit。使用 OpenAI Python SDK 时通过 extra_body 传入:
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "请概括这份文档:" + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- 开启自动缓存
  },
)
prompt_cache_options.mode 的取值与对应行为如下:
设置自动断点缓存行为
mode 为 implicit设置输入末尾的自动断点和手动断点同时生效
mode 为 explicit,有手动断点不设置按手动断点创建或读取缓存
mode 为 explicit,无手动断点不设置使用隐式缓存
不传 prompt_cache_options、传 null 或 {},或只设置 ttl不设置有手动断点时按手动断点缓存,否则使用隐式缓存
mode 为 implicit 时使用的是自动断点缓存,按本文的 TTL 与计费规则处理,与不传缓存参数时的隐式缓存不同。mode 为 explicit 只表示不自动设置断点,不会关闭隐式缓存。mode 仅对当前请求生效。
以下完整示例开启自动缓存,并连续发送两次相同的长文档请求:第一次请求创建缓存,第二次请求读取缓存。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic兼容
import os
from openai import OpenAI

client = OpenAI(
  # 若没有配置环境变量,请将下行替换为:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
)

# 需要复用的长文档,缓存前缀最少为 1024 Token
long_text = "<固定的长文档>" * 400

def ask():
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "请概括这份文档:" + long_text}],
    extra_body={
      "enable_thinking": False,
      "prompt_cache_options": {"mode": "implicit"},  # <-- 开启自动缓存
    },
  )
  return completion.usage.prompt_tokens_details

for i in range(1, 3):
  details = ask()
  print(f"第 {i} 次请求:读取缓存 {details.cached_tokens} Token,创建缓存 {details.cache_write_tokens} Token")
预期输出类似如下,具体 Token 数取决于文档长度:
第 1 次请求:读取缓存 0 Token,创建缓存 2048 Token
第 2 次请求:读取缓存 2048 Token,创建缓存 0 Token
第二次请求的输入与第一次相同,因此读取了第一次创建的缓存。

设置缓存有效期

缓存有效期(TTL)可选 5m(5 分钟)或 1h(1 小时),默认为 5m。缓存在有效期内被命中时会自动续期,续期方式见续期规则。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic兼容
在请求顶层的 prompt_cache_options.ttl 中设置,对本次请求的全部断点生效:
extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- 缓存有效期为 1 小时
  },
},
未设置 prompt_cache_options.ttl 时,使用请求中最后一个 cache_control 标记的 ttl;该标记未设置 ttl,或请求中没有 cache_control 标记时,TTL 为 5m。TTL 只对显式缓存生效,设置 ttl 时需同时设置缓存断点或开启自动缓存。

续期规则

首次请求或缓存已过期时,按本次请求的 TTL 创建缓存。命中有效缓存时,按以下规则续期和计费:
  • 到期时间取较晚值,并保留较高的档位。 新的到期时间约为“原到期时间”与“本次缓存处理开始时间 + 本次 TTL”中较晚的一个。例如,12:03 命中 12:05 到期的 5m 缓存,新的到期时间约为 12:08。又如,5m 请求命中有效的 1h 缓存时,按 5m 计算续期,但缓存仍保留 1h 档位,后续 1h 请求在有效期内仍按读取缓存计费。
  • 从 5m 升级为 1h 时,升级部分按 1h 创建缓存计费。 1h 请求命中有效的 5m 缓存时,命中部分按 1h 重新创建,不再计为读取。若部分前缀已有有效的 1h 缓存,这部分仍按读取计费,仅剩余部分和新增前缀按创建计费。其他情况(5m 请求命中 5m 缓存、5m 请求命中 1h 缓存、1h 请求命中 1h 缓存)的命中部分均按读取计费。
有效期从本次缓存处理开始时计算,不在原到期时间上累加,也不从回复结束时重新计时。生成回复的耗时计入有效期,实际到期时间会预留少量处理时间。 以下示例为对同一份缓存的连续请求,该缓存于 12:00 按 1h 创建,原到期时间为 13:00:
请求本次 TTL请求前的到期时间请求后的到期时间(约)计费与档位
12:20 发起5m13:0013:00读取缓存。12:25 早于原到期时间,到期时间不变,既不缩短,也不续到 13:20
12:58 发起5m13:0013:03读取缓存。到期时间延长至本次开始后 5 分钟,仍保留 1h 档位
13:01 发起1h13:0314:01读取缓存。缓存已是 1h 档位,不产生升级创建
以上示例基于相同前缀的串行请求。多个请求并发写入同一缓存时可能相互覆盖,不保证保留最晚的到期时间。

查看缓存用量

响应的 usage 中返回读取缓存和创建缓存的 Token 数。流式输出时,OpenAI 兼容 Chat Completions 接口需设置 stream_options 为 {"include_usage": true},从最后一个包含 usage 的数据块中读取。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic兼容
以下为首次创建缓存时的 usage(纯文本输入、非思考模式):
{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "text_tokens": 2304,
      "cached_tokens": 0,
      "cache_write_tokens": 2048,
      "cache_creation_input_tokens": 2048,
      "cache_type": "ephemeral",
      "cache_creation": {
        "ephemeral_5m_input_tokens": 2048,
        "ephemeral_1h_input_tokens": 0
      }
    },
    "completion_tokens_details": {}
  }
}
字段说明
prompt_tokens全部输入 Token 数,包含读取缓存、创建缓存和未使用缓存的部分,命中缓存后不扣减
total_tokensprompt_tokens 与 completion_tokens 之和
prompt_tokens_details.cached_tokens读取缓存的 Token 数
prompt_tokens_details.cache_write_tokens创建缓存的 Token 数
prompt_tokens_details.cache_creation_input_tokens创建缓存的 Token 数,与 cache_write_tokens 相等,统计时不要重复相加
prompt_tokens_details.cache_type显式缓存的类型,固定为 ephemeral
prompt_tokens_details.cache_creation按 TTL 统计的创建缓存 Token 数,ephemeral_5m_input_tokens 与 ephemeral_1h_input_tokens 之和等于创建缓存的 Token 数
上例中未使用缓存的输入为 2304 − 0 − 2048 = 256 Token。各缓存字段均为原始 Token 数,不含计费倍率。有效期内以相同前缀再次请求时,cached_tokens 为 2048,cache_write_tokens、cache_creation_input_tokens 及 cache_creation 中的两项均为 0,prompt_tokens 仍为 2304。图像、音频、视频等输入明细按实际输入返回,思考等输出明细按模型与配置返回;不适用的字段不会返回,而不是返回 0。

最佳实践

  • 多轮对话优先使用自动缓存。 自动断点随对话增长后移,无需逐轮调整断点位置。
  • 将固定内容放在前面。 系统提示词、工具定义、参考文档等不变的内容放在输入开头,时间戳、用户问题等每次变化的内容放在最后。
  • 将断点设置在每次请求都相同的最后一个内容块上。 不要将断点设置在每次都会变化的内容块上,否则每次请求都会创建新缓存,无法读取。
  • 追加历史消息,不改写已有内容。 修改、删减或重新排序前面的消息或工具定义,会使之后的缓存无法命中。
  • 按变化频率使用多个断点。 例如工具定义很少变化、参考文档每天更新时,分别在两者末尾设置断点。
  • 单轮新增内容块较多时补充断点。 每个断点最多向前查找 20 个内容块,单轮新增内容超过该范围时,在中间位置增加断点。
  • 按复用间隔选择 TTL。 复用间隔在 5 分钟以内时使用 5m,命中即可续期;复用间隔在 5 分钟到 1 小时之间时使用 1h。
  • 通过用量字段观察命中情况。 缓存命中率可按读取缓存的 Token 数除以全部输入 Token 数计算,命中率偏低时,检查前缀和断点位置是否稳定。

计费说明

缓存断点仅影响输入 Token 的计费,输出 Token 按原价计费。 qwen4-max 单价,元/百万 Token:
计费项单价
输入10
缓存创建(5m)12.5
缓存创建(1h)20
显式/隐式缓存读取0.5
输出(思考与回答)30
创建缓存约为普通输入价的 125%(5m)或 200%(1h);计费以表中独立单价为准,不套用旧缓存的统一命中比例。显式读取与隐式缓存命中使用同一读取单价。完整价格见计费说明。 若本次缓存前缀包含已有的有效缓存,已有部分按读取缓存计费,仅新增部分按创建缓存计费。TTL 从 5m 升级为 1h 时的计费见续期规则。

使用限制

  • 仅 Qwen4 系列模型支持。
  • 缓存前缀最少为 1,024 Token。不足 1,024 Token 时不创建缓存,请求正常返回,按 TTL 统计的创建明细不返回。
  • 每个请求最多保留最后 4 个有效断点,开启自动缓存时自动断点占用其中 1 个。
  • 系统以每个断点为终点,最多向前查找 20 个内容块。待命中的缓存与断点之间间隔超过 20 个内容块时,无法命中。
  • TTL 仅可设置为 5m 或 1h。

常见问题

Q:不设置任何缓存参数,还能命中缓存吗?

可以。未设置缓存参数时使用隐式缓存,系统自动识别请求的公共前缀,但不保证命中。需要稳定命中时,请设置缓存断点或开启自动缓存。

Q:只设置了 TTL,为什么缓存有效期没有变化?

TTL 只对显式缓存生效。在 OpenAI 兼容 Chat Completions 接口中只设置 prompt_cache_options.ttl 时,请求使用隐式缓存。请同时添加手动断点,或将 prompt_cache_options.mode 设置为 implicit。

Q:使用 5m 请求命中 1h 缓存,会缩短缓存有效期吗?

不会。新的到期时间取原到期时间与本次续期时间中较晚的一个,且缓存保留 1h 档位。详见续期规则。