Qwen4 提示词缓存怎么用?复用 Agent 上下文并排查未命中

设置 Qwen4 缓存断点,对比两次请求并正确读取缓存用量。附本地请求生成脚本,以及缓存未命中的排查清单。

可重复使用的印版印出一致图案,只有一处橙色细节发生变化。

Agent 反复读取相同参考资料时,把固定上下文放在缓存断点之前,把变化的问题放在之后,再检查响应报告的缓存读取量。 发送相似提示词、观察到回答更快,还不足以证明缓存生效。

本文核查于 2026 年 11 月 16 日,介绍 QwenCloud 的 Qwen4 直连 API,承接Qwen4-Max 接入与迁移指南。下面的请求生成脚本无需 Key,可在本地运行。我们未为本文执行付费缓存请求,因此示例是一套可复现的实验方法,不是已测得的节省比例或延迟结果。

先确定哪些内容必须保持相同

以客服分析 Agent 为例:每轮接收相同产品手册,但回答不同客户问题,手册适合复用。如果在手册前插入时间戳、随机 ID 或变化的问题,请求开头就会发生变化。

把输入明确拆成两部分:

固定上下文变化的任务
已确认的手册版本当前客户问题
固定工具定义当前任务的工具结果
一致的指令顺序本轮要求的输出
固定的文档序列化方式会改变分析的新证据

不要为了命中率而冻结错误信息。手册更新时,使用新前缀是合理的。记录文档版本及哈希,区分有意更新引起的未命中与意外格式变化。

Qwen4 官方缓存指南(英文)规定缓存前缀至少 1,024 token,同一用户范围内按完全一致的前缀匹配,支持 Chat Completions、Responses 和 Anthropic Messages。DashScope 不支持这一版 Qwen4 显式缓存。字数或字符数不能代替精确 token 数。

在本地生成两份请求

使用合成资料,或你有权发送给所选供应商的非敏感参考文档,保存为 reference.txt。第一次和第二次请求之间保持文件内容不变。

将以下内容保存为 build_cache_requests.py:

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

运行 python3 build_cache_requests.py 后检查 JSON:第一个内容块及其断点必须完全一致,只有第二块的问题应不同。脚本不计算参考文档的 token 数。发送计费请求前,使用供应商的 token 计数能力或已确认适用于该模型的分词器检查最低长度。

断点属于内容块,因此消息的 content 必须是数组。本例只用一种断点标记,不要在同一请求中混用另一种缓存标记语法。第一次调用用于建立可复用上下文,第二次用于复用;是否真的发生,最终以响应的用量数据为准。

在正确通道上依次发送请求

按官方 Key 文档(英文)配置目标地区的 QwenCloud 按量 Key。下面使用新加坡 Chat Completions 端点,Ofox Key 和 Token Plan Key 不能随意替换使用。

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

继续之前检查 HTTP 结果、响应正文和用量。第一次请求成功完成后,将命令中的文件名改为 request-2.json 和 response-2.json 再执行,并确保仍处于文档规定的缓存有效期内。这个实验不要同时发出两次请求,串行更便于区分创建与复用。

超时不代表供应商没有处理请求。重试前检查请求记录,并为实验明确设置预算。本文不会替你执行任何一次请求。

默认缓存有效期为五分钟,官方也提供一小时选项。第一次实验先保留默认值,同时改变有效期和前缀会增加排错难度。生成回答的耗时也会占用有效期。

按实际协议读取用量

上面的 Chat Completions 实验应检查 usage.prompt_tokens_details,区分缓存读取、缓存写入和普通输入。字段出现不等于整份文档都已复用。

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

缺失值保持为 None,脚本不会悄悄把未报告的数据当作零。私密保存两次原始响应。如果供应商返回另一协议的用量结构,应按相应协议文档读取,不要为了让脚本能运行而随意改字段名。

例如,QwenCloud 的 Responses 缓存详情位于 input_tokens_details,Anthropic 兼容接口则有自己的读取和创建字段。部分字段互为别名,把别名与原计数相加会高估用量。具体见缓存用量参考(英文)中的协议表格。

缓存未命中时,不要一次改动所有设置

观察到的现象检查项下一轮可控实验
首次请求未报告可复用前缀最低 token 数、断点位置、支持协议固定通道,检查序列化请求
第二次请求没有缓存读取前缀是否完全一致、用户范围、间隔时间逐字节对比第一个内容块
只有部分输入命中断点结束位置、哪些内容发生变化分离固定文档和当前问题
原本正常的请求序列不再命中文档版本、工具定义、客户端序列化与上次正常请求对比
用量字段缺失协议、响应格式、流式行为先使用完整非流式响应
返回参数错误当前通道的参数支持、JSON 结构缩减为官方单一标记示例

长对话 Agent 还有额外边界:官方规定每个断点最多向前查找 20 个内容块,仅保留最后四个有效断点,自动断点也占其中一个。如果历史增长使可复用前缀超出查找窗口,检查内容块布局,并在固定内容边界明确设置断点。不要仅为强行命中而删除必需的工具结果或推理历史。保存修改前后请求快照,再通过用量验证结果。

不要把每次未命中都当成模型退化。执行框架可能重排工具、在前面添加动态系统文本,或改变文档格式。怀疑供应商之前,先记录脱敏后的固定前缀及其哈希。

标识符或端点问题可参考模型找不到排查指南(英文)。如果缓存正常,但多轮 Agent 丢失工具结果,那是另一个历史保留问题,参见多轮工具调用历史保留指南。

按完整且验收通过的任务计算节省

缓存写入、读取与普通输入可能采用不同费率。应把首次写入和每次生成回答都计入,与相同任务序列不使用缓存的情况比较。使用 QwenCloud 当前地区价格(英文),不要复制其他地区的价格或预览促销费率。

每次调用记录:文档版本、输入 token、缓存读取 token、缓存写入 token、普通输入、输出 token、耗时和验收结果。不要重复计算别名字段。缓存输入的折扣不等于整个 Agent 任务具有相同比例的折扣,输出和外部工具可能占据大部分成本。

账单之外还要检查回答。对于两次提问示例,应独立确认职责与审批要求确实出现在参考文档中。成本更低但没有依据的回答,不能算验收通过。

这是 QwenCloud 直连工作流。 11 月 16 日核查的 Ofox 目录没有 Qwen4。对于 Ofox 现有通道,应核查精确模型条目,遵循 Ofox 鉴权和错误处理文档。这些文档不证明 Ofox 已支持 QwenCloud 新增缓存参数。

常见问题

重复发送提示词,就能证明 Qwen4 使用了缓存吗?
不能。要检查供应商返回的缓存读取用量字段。响应变快或文本重复本身都不能证明命中缓存。
这些缓存参数可以直接用于 Ofox 吗?
本文介绍 QwenCloud 直连 Qwen4 API。11 月 16 日的 Ofox 目录未列出 Qwen4,不能假设 Ofox 支持同一型号或相同缓存协议。