Tabbit
活动资源博客模型
Tabbit LogoTabbit

Tabbit — 为你工作的 AI 浏览器

主题资源

  • 浏览器排行榜
  • AI 浏览器指南
  • 浏览器对比
  • 浏览器测评
  • 浏览器替代方案
  • 浏览器专题目录
  • Agentic 浏览器
  • 下载与安装
  • 浏览器效率
  • SillyTavern 模型指南

热门指南

  • Best Browsers 2026: Top 10 Ranked & Compared
  • Best Free AI Browsers 2026: Plans & Prices Compared
  • Rabbit Browser: What It Is & Why Tabbit Is Better
  • Firefox vs Chrome 2026: Privacy, RAM & Speed Compared
  • Best Lightweight Browsers 2026: 7 Tested for RAM & Speed
  • AI Browser List 2026: 10 Browsers Compared
  • Neobrowser: Norton Neo, Download & Alternatives
  • Edge vs Chrome 2026: Speed, RAM & Battery Tested
  • Best Internet Browser for Android 2026
  • Best AI Browser 2026: Top 9 Tested & Ranked

活动

  • 别装了,你在《牛来》里早有原型
  • Tabbit 妙招大赛
  • KPOP SBTI 饭圈人格测试
  • Tabbit 校园共创者计划
  • fifi 的论文文献妙招精选
  • 用户问卷

关于

  • Tabbit 博客
  • 媒体报道
简体中文
简体中文English
提示词与案例展示
媒体Qwen4-Max

QwenCloud:Qwen4-Max 显式缓存复用配置

原始来源

QwenCloud 官方文档

作者未注明

Tabbit 整理2026-11-17

查看原文

一句话结论

对 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,且前缀和断点位置保持一致。

测试或工作流步骤

  1. 获取与新加坡区域匹配的 QwenCloud API Key,安全设置 DASHSCOPE_API_KEY。

  2. 确保断点前的固定前缀至少 1,024 tokens;不要在该前缀中放每轮变化的问题、时间戳等内容。

  3. 发送首个请求创建缓存,再以相同用户身份发送相同前缀、不同问题的请求。

  4. 从响应的 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 发起请求。

Tabbit 小编提醒

提示词与案例来自公开资料,由 Tabbit 编辑整理。引用前请查看原文授权与适用范围。

Qwen4-Max

在 Tabbit 中使用

Qwen4-Max

相关提示词与案例

媒体阿里云 Model Studio 官方文档2026-11-16

阿里云 Model Studio:Qwen4-Max OpenAI Chat Completions 配置

媒体QwenCloud 官方文档

QwenCloud Token Plan:Qwen4-Max Codex 配置

媒体QwenCloud 官方文档

QwenCloud:Claude Code 接入 Qwen4-Max 正式版

媒体QwenCloud 官方文档、OpenCode 官方文档

QwenCloud:在 OpenCode 中配置 GA 版 Qwen4-Max 输出上限

Qwen4-Max

相关测评

媒体Qwen 官方博客2026-11-16

Qwen4-Max 官方发布基准与 Work360

媒体Atomic Agent Blog2026-11-16

Atomic Agent:Qwen 4 Max 推理档位与单任务 Agent 实测

媒体Plotly Blog2026-11-16

Plotly:Qwen4 Max 数据分析基准与图表实测

媒体Vals AI2026-11-15

Vals AI:Qwen4 Max 行业任务指数、分项成绩与成本