阿里雲 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。