对 qwen4-max,在固定输入内容块上设置 prompt_cache_breakpoint: {"mode":"explicit"},并在有效期内重复相同前缀,可确定性复用;前缀至少 1,024 tokens,TTL 默认 5 分钟,也可设为 1 小时。
适合的任务:多轮对话、长文档问答、Agent 等重复发送相同长前缀的请求
不适合的任务:请求前缀经常改写,或可缓存部分少于 1,024 tokens
适用的模型版本:Qwen4 系列;官方示例使用正式模型 ID qwen4-max
适用的客户端、Agent 或 API:OpenAI 兼容 Chat Completions、Responses、Anthropic Messages API;本文示例使用 OpenAI Python SDK
推荐的推理档位和参数:固定内容放在变化内容之前;TTL 按复用间隔选 5m 或 1h
示例使用新加坡 QwenCloud OpenAI 兼容端点。先设置对应区域的 API Key:
export DASHSCOPE_API_KEY="YOUR_QWENCLOUD_API_KEY"安装 OpenAI Python SDK:
python -m pip install openai以下请求把固定资料设为缓存前缀、把问题放在断点之后,并设置 1 小时 TTL。连续发送两次时,第二次只改变问题:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
# 示例占位资料;实际使用时换成每次请求保持不变的参考资料。
# 确保断点前的前缀至少有 1,024 tokens,否则不会创建缓存。
fixed_text = "This is fixed reference text. " * 600
def ask(question):
response = client.chat.completions.create(
model="qwen4-max",
messages=[{
"role": "user",
"content": [
{
"type": "text",
"text": fixed_text,
"prompt_cache_breakpoint": {"mode": "explicit"},
},
{"type": "text", "text": question},
],
}],
extra_body={
"enable_thinking": False,
"prompt_cache_options": {"mode": "explicit", "ttl": "1h"},
},
)
return response.usage.prompt_tokens_details
print("首个请求:", ask("Summarize the reference text."))
print("复用请求:", ask("List three key points from the reference text."))第二次请求查看 cached_tokens(缓存读取)与 cache_write_tokens(缓存写入)。请求成功本身不代表命中;确认 cached_tokens 大于 0,且前缀和断点位置保持一致。
获取与新加坡区域匹配的 QwenCloud API Key,安全设置 DASHSCOPE_API_KEY。
确保断点前的固定前缀至少 1,024 tokens;不要在该前缀中放每轮变化的问题、时间戳等内容。
发送首个请求创建缓存,再以相同用户身份发送相同前缀、不同问题的请求。
从响应的 usage.prompt_tokens_details 检查 cached_tokens 与 cache_write_tokens。首次通常写缓存;有效期内复用时读取计数增加、写入计数为 0。
文档示例对模型参数使用 qwen4-max,并说明显式缓存仅支持 Qwen4 系列。该页面支持 Chat Completions、Responses 和 Anthropic Messages API;DashScope API 不支持新版 Qwen4 显式缓存。
显式断点标记为 prompt_cache_breakpoint: {"mode":"explicit"},标记所在内容块末尾作为断点;从请求开头到断点的内容构成缓存前缀。新接入建议使用此字段;兼容字段 cache_control: {"type":"ephemeral"} 行为相同,但一个请求只能选一种标记。
缓存前缀至少 1,024 tokens。命中要求前缀完全一致、请求来自同一用户且缓存仍在有效期内;系统按断点回看最多 20 个内容块,每个请求最多保留最近 4 个有效断点。
TTL 只能是 5m 或 1h,默认 5m。命中时会按当前请求的 TTL 续期;有效期从当前请求开始处理时计时,生成耗时计入有效期。
prompt_tokens_details.cached_tokens 是读取的缓存 token 数;cache_write_tokens 是写入数,和 cache_creation_input_tokens 相等,不应重复相加。
显式缓存:设置内容块断点,缓存的前缀明确且相同即可确定性复用。TTL 设置在顶层 prompt_cache_options.ttl,作用于请求内所有断点;设置 TTL 时也必须设置缓存断点或启用自动缓存。
隐式缓存:完全不设置缓存参数时,服务自动识别公共前缀,但命中不保证。不要把“无参数隐式缓存”与 prompt_cache_options.mode="implicit" 混淆;后者会在本次请求输入末尾自动放置断点,按此页显式缓存的 TTL 和计费规则工作。
若仅移动断点而未保留旧断点,旧断点不会因读取而续期;同一前缀并发写入时,文档不保证保留最晚过期时间。
示例中的 enable_thinking=False 仅为控制示例配置;它不是开启缓存的必要字段。API Key 与区域端点应匹配。
于 2026-11-17 通过 Tabbit 打开并核对 QwenCloud 官方 Qwen4 显式缓存文档。示例参考官方 OpenAI 兼容 Chat Completions Python 用法;未使用真实 API Key 发起请求。
Qwen4-Max