阿里云 11 月 16 日开放 Qwen4-Max 之后,qwen4-max 的 JSON 该如何设置 reasoning_effort、prompt_cache_options 和 thinking_display,并把缓存写入与输入分开记账?

模型 id 不决定力度、缓存和摘要。决定它们的是 reasoning_effort、prompt_cache_options 和 thinking_display。账上的写入只记一个缓存字段。

把 model 设为 qwen4-max,思考就是开着的。 2026 年 11 月 16 日,阿里云在 QwenCloud 开放了 Qwen4-Max。模型 id 是 qwen4-max。思考从 reasoning_effort high 和 thinking_budget 131072 开始。要复用的前缀写 prompt_cache_options。要可读的思考过程,把 thinking_display 设为 summarized。

本文写于 2026 年 11 月 17 日,依据 11 月 16 日的模型更新日志、Qwen4-Max 模型页、显式缓存指南、思考摘要指南、Chat 与 Responses 参考,以及价格页。昨天写过 DeepSeek 网页工具。会改请求和账单的字段是 reasoning_effort、prompt_cache_options 和 thinking_display。

11 月 16 日开放了什么

阿里云把它写成稀疏混合专家:总参数 2.4 万亿,每个 token 激活 710 亿。在它自己的 Work360 上,High 力度比 Qwen3.8-Max 少用大约 35% 的 token,单任务平均成本大约低 60%,Code Arena 排名第 6。这些是阿里云自己的数字。11 月 11 日开放的预览 id qwen4-max-preview 仍是另一个 Token Plan 模型。这次请求用 qwen4-max。

上限token
上下文1,000,000
最大输入,关闭思考991,808
最大输入,打开思考983,616
思考加回答的上限262,144
最大输出,关闭思考131,072
默认思考预算131,072

新加坡示例的地址是 https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1。密钥按地域分开。北京和全球地域(法兰克福、中国香港、东京、美国弗吉尼亚)共用一张价目。新加坡单独一张。Chat Completions、Responses 和 Anthropic Messages 接受这套新的显式缓存。DashScope 不接受。不支持批量推理。代码解释器只在思考打开时运行。新加坡按量付费另有 100 万 token 额度,和 Token Plan 积分分开。下面是牌价。

三个端点上的 reasoning_effort

reasoning_effort 和 thinking_budget 只能写一个。thinking_budget 必须是正整数。0 会被拒绝。只写力度时,预算保持 131072。只写预算时,1–4096 对应 low,4097–131072 对应 high,131073–262144 对应 xhigh,你写的预算会保留。两个都不写,就是 high 和 131072。max_completion_tokens 把思考和回答加在一起封顶:思考打开时 262144,关闭时 131072。省略它,就用该模式的最大值。preserve_thinking 默认 true,下一轮要带回上一轮助手的思考。这段文字按输入计费。

接口字段取值
Chat Completions / DashScopereasoning_effortlow, high, xhigh. 默认 high。minimal 和 low 都变成 low。medium 和 high 都变成 high。xhigh 和 max 都变成 xhigh。none 关闭思考。Chat 也可以写 enable_thinking false。
Responsesreasoning.effort同样三个值,映射相同。none 关闭思考。优先写 reasoning.effort。Responses 上的 enable_thinking 已标明将移除。
Anthropic Messagesoutput_config.effortlow, high, xhigh. 默认 high。medium 变成 high。max 变成 xhigh。

采样默认值随模式变化。

参数思考关闭思考
temperature1.00.7
top_p0.950.8
presence_penalty0.01.5
top_k2020

直接发 HTTP 时,这些字段和 model 平级。Python 的 OpenAI SDK 把非标准字段放进 extra_body:enable_thinking、thinking_budget、preserve_thinking、thinking_display 和 prompt_cache_options。下面这份 Chat 正文保留手动断点、5 分钟缓存和摘要。

{
  "model": "qwen4-max",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<document of at least 1024 tokens>",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        { "type": "text", "text": "Summarize the document." }
      ]
    }
  ],
  "reasoning_effort": "high",
  "thinking_display": "summarized",
  "prompt_cache_options": { "mode": "explicit", "ttl": "5m" }
}

Responses 用 input_text 块,并把 reasoning.summary 设为 auto。被缓存的前缀仍然至少要 1,024 个 token。

{
  "model": "qwen4-max",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "<document of at least 1024 tokens>",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        { "type": "input_text", "text": "Summarize the document." }
      ]
    }
  ],
  "reasoning": { "effort": "high", "summary": "auto" },
  "prompt_cache_options": { "mode": "explicit", "ttl": "5m" }
}

prompt_cache_options 和断点

显式缓存是确定的:同一用户、同一前缀、还在有效期内,就会读到缓存。什么缓存字段都不写时走的隐式缓存,不保证命中。mode 为 implicit 不是那种隐式缓存。它在输入末尾放一个自动断点,并按显式缓存的有效期和价格计费。对话变长时,这个断点跟着往前移,而且不含启动回答的模板后缀。最后一个不变内容块上的手动断点仍然有效。每次请求最多保留最后 4 个断点。自动断点占其中一席。从每个断点往回最多看 20 个内容块。

prompt_cache_options这次调用会怎样
mode = implicit在输入末尾放自动断点。手动断点也生效。
mode = explicit + 手动断点只在你标出的断点创建或读取缓存。
mode = explicit, 没有断点不放自动断点。请求退回隐式缓存。
省略、null、{},或只写 ttl缓存指南不会放自动断点。手动断点仍然缓存。否则就是隐式缓存。Chat 参数说明把空对象写成 mode implicit、ttl 5m。请自己写上 mode。

把断点放在最后一块保持不变的内容上。prompt_cache_breakpoint 是 {"mode":"explicit"}。旧的 cache_control {"type":"ephemeral"} 标的是同一刀。一次请求只用其中一种。带断点的 content 必须是数组。断点之后的文字不在这条缓存里。ttl 是 5m 或 1h,默认 5m。命中会续期。前缀短于 1,024 个 token 不会建缓存。请求仍然成功,按 TTL 分组的写入字段会被省略。Chat 里只写 ttl 不会启动显式缓存。要加断点,或把 mode 设为 implicit。

Chat 用两个相等的名字报告同一次写入。只存一个。prompt_tokens 已经包含读取、写入和未缓存的尾巴。命中不会让 prompt_tokens 变小。文档里的首次写入样例,未缓存尾巴是 2304 − 0 − 2048 = 256。同一前缀的下一次调用,cached_tokens 为 2048,两个写入字段都是 0。Responses 把同样的数放在 usage.input_tokens_details,并用 cache_write_tokens_details.ttl_5m_tokens 和 ttl_1h_tokens 分开。它的 input_tokens 也包含读取和写入。Anthropic 是拆开的:input_tokens 只是未缓存部分,cache_read_input_tokens 是读取,cache_creation_input_tokens 是写入。Anthropic 的输入总量是这三项之和。不要把三种形状混加。Chat 流式要 stream_options.include_usage 为 true,用量在最后一块。Responses 的用量在 response.completed。

{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "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
      }
    }
  }
}

用不上的字段会缺席,而不是返回 0。响应里可能回显 prompt_cache_options,带上 mode 和 ttl。

thinking_display 与 encrypted_content

默认返回完整思考的明文。thinking_display 为 summarized 时,明文换成可展示的摘要,外加密文形式的完整思考。每一轮都要打开。摘要给人看。密文给下一轮恢复思考。摘要不能代替密文。没有产生思考,或加密失败时,这两个字段都可能缺席。不要用摘要编造密文。原始图片和文档要自己留着。加密只存思考,不存这些输入。

接口开关摘要密文
Chatthinking_display = summarizedmessage.reasoning_contentmessage.encrypted_content
Responsesreasoning.summary = autosummary[].text (summary_text)encrypted_content
Anthropicthinking.display = summarizedthinkingsignature
DashScopeparameters.thinking_display = summarizedmessage.reasoning_contentmessage.encrypted_content

preserve_thinking 已经是 true。摘要模式的下一轮,把 encrypted_content 原样传回。存的是完整明文时,传回 reasoning_content。不要把这两个字段折进 content。回放时可以不带已存的摘要。历史思考按输入 token 计费。

{
  "role": "assistant",
  "content": "The answer text.",
  "encrypted_content": "<ciphertext from this turn, unchanged>"
}

Chat 流式里,摘要文字走 delta.reasoning_content。密文稍后以一整帧 encrypted_content 到来,不是增量。就算这一帧没有正文也要留下。不要把密文跨轮拼接,也不要为它再开一条助手消息。Responses 把 summary_text 放在 reasoning 项上,完成时把密文放在同一项。Anthropic 先流 thinking_delta,再来一帧 signature_delta。signature 可能是空的。

先记写入,再记读取

价格是每百万 token 的美元。思考和关闭思考用同一张价目。没有按输入长度分档。思考 token 就是输出 token。缓存字段是原始个数,不含 5 分钟或 1 小时的倍率。5 分钟写入大约是输入价的 125%,1 小时写入大约是 200%。按下面的行计价。前缀里已有有效缓存时,旧的部分按读取计,新的部分按写入计。5 分钟请求命中 1 小时缓存,仍然按读取计,条目保持 1 小时档。1 小时请求命中 5 分钟缓存,命中的那一段会按 1 小时创建价再写一次。

项目Singapore北京 / 全球
输入$1.5$1.413
缓存写入,5 分钟$1.875$1.767
缓存写入,1 小时$3$2.827
显式或隐式缓存读取$0.075$0.071
输出,思考加回答$4.5$4.24

新加坡按量付费另有 100 万 token 额度,和 Token Plan 积分分开。用完之后按这张表。qwen4-max 不支持批量推理,所以没有批量折扣。结构化 JSON 是另一个字段:response_format 的 type 为 json_schema,strict 为 true。见 结构化输出是什么。

上线前要核对的 JSON

  1. 请求体是 qwen4-max。不是 qwen4-max-preview。
  2. 请求体里 reasoning_effort 和 thinking_budget 只有一个。只有确定要关思考时才写 none 或 enable_thinking false。
  3. 摘要模式每一轮都发送 thinking_display summarized,或 reasoning.summary auto。encrypted_content 整段保存。
  4. 缓存 mode 是 implicit,或 explicit 再加一种断点写法。ttl 是 5m 或 1h。缓存前缀至少 1,024 个 token。
  5. 账单用一次 cached_tokens 和一个写入字段。5 分钟和 1 小时的个数来自 cache_creation,或来自 ttl_5m_tokens 与 ttl_1h_tokens。Chat 不要把 cache_write_tokens 和 cache_creation_input_tokens 相加。

在本地用 JSON 校验、JSONPath($.usage.prompt_tokens_details.cache_creation.ephemeral_5m_input_tokens)和 JSON 对比 核对上一份请求。数据不会上传。

常见问题

reasoning_effort 和 thinking_budget 能写在同一次请求里吗?

不能。qwen4-max 会拒绝这一对。只写力度时,thinking_budget 保持 131072。只写预算时,1–4096 对应 low,4097–131072 对应 high,131073–262144 对应 xhigh,并保留你写的预算。0 会被拒绝。两个都不写,就是 high 和 131072。

prompt_cache_options.mode 为 implicit 就是原来的隐式缓存吗?

不是。mode 为 implicit 会在输入末尾放一个自动的显式断点,并按 5 分钟或 1 小时的价格计费。省略缓存字段,或 mode 为 explicit 却没有断点时,才是不保证命中的隐式缓存。缓存指南和 Chat 参数说明对空对象的说法不一致,所以请自己写上 mode。

账单要把 cache_write_tokens 和 cache_creation_input_tokens 加起来吗?

不要。在 Chat 里它们是同一个数。只存一个。用 cache_creation.ephemeral_5m_input_tokens 和 ephemeral_1h_input_tokens 拆单价。Responses 用 input_tokens_details.cache_write_tokens,再加上 ttl_5m_tokens 和 ttl_1h_tokens。Anthropic 用 cache_creation_input_tokens,它的 input_tokens 只是未缓存的部分。

前缀不到 1,024 个 token,请求会失败吗?

不会。请求成功,不建缓存,按 TTL 分组的写入字段会被省略。每次请求最多保留最后 4 个断点,每个断点往回最多看 20 个内容块。

下一轮可以用摘要代替 encrypted_content 吗?

不能。密文要原样回放。不要截断、重新编码,或贴进 content。这一轮没有密文时,摘要恢复不了完整思考。每一轮都要打开 thinking_display summarized,或 reasoning.summary auto。

DashScope 接受 prompt_cache_options 吗?

不接受。Qwen4 这套新的显式缓存在 Chat Completions、Responses 和 Anthropic Messages 上。DashScope 不接受。这个模型即使用 DashScope 发纯文本,走的仍是多模态端点。

小结

2026 年 11 月 16 日的模型,改的是力度、缓存那一行,以及下一轮要存什么。 保持默认的 high 和 131072,或在 reasoning_effort 与 thinking_budget 里选一个。写上 prompt_cache_options.mode。要摘要时把 thinking_display 设为 summarized,并原样回放 encrypted_content。写入按 5 分钟或 1 小时的价格只记一个字段,读取记 cached_tokens。