Draft

Control Qwen4-Max Thinking With reasoning_effort

  • Not yet verified
  • Versions not pinned
  • 14 min read

Task

What you will complete

Set qwen4-max reasoning_effort to none, low, high, and xhigh on Alibaba Model Studio in Beijing, on that model's 1,000,000-token free grant with 免费额度用完即停 / Free Quota Only turned on, send the same Northwharf invoice prompt four times, and score each reply with the local checker.

Success criteria

  • sweep_reasoning_effort.py sends the same Northwharf prompt four times, with reasoning_effort set to none, low, high, and xhigh in turn, and never adds thinking_budget.
  • Each reply is scored by examples/northwharf.py against the expected invoice JSON (booking NW-4419, total_cny 4495.00, plus the line items). A correct total with a missing line item still fails.
  • For each call, the raw response or error body, finish_reason, usage including reasoning_tokens, and whether reasoning_content was present can be recorded. If reasoning_effort="none" is rejected, that error is kept; no fallback is invented from this draft.

What this is not

Not a tool-calling audit, a unit-test extract, an image job, or a three-model bake-off. Skip this comparison if you do not have a Beijing qwen4-max grant, if you needed a different model, or if the task is image or video understanding.

Prerequisites

  • A China-site (aliyun.com) Beijing Model Studio key and workspace ID, with a remaining qwen4-max grant and 免费额度用完即停 turned on.
  • Python and the official openai package.
  • The Northwharf checker and expected invoice JSON shipped with this tutorial.

Environment

DASHSCOPE_API_KEY
Beijing Model Studio API key
DASHSCOPE_BASE_URL
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 (replace WorkspaceId before calling)
QWEN_MODEL
qwen4-max (default in the example code)

qwen4-max thinks before it answers. In Alibaba Cloud Model Studio, China (Beijing) / 华北2, a Chat Completions call that omits the thinking controls starts at reasoning_effort=high and thinking_budget=131072. The chain of thought is billed as output, and it shares the model’s own 1,000,000-token new-user grant with the visible reply. Leave those defaults in place, and a short, checkable invoice can still spend a long private reasoning pass before you ever see a total.

This tutorial stays on that one model and that one Beijing grant. It shows what the official reasoning_effort values are documented to do — including none, which turns thinking off — how that parameter relates to enable_thinking and thinking_budget, and how to score four settings against a fictional yard invoice whose correct total is already known.

reasoning_effort you send Documented effective level on qwen4-max
low, or the compatibility alias minimal low
high (the default), or the alias medium high
xhigh, or the alias max xhigh
none Thinking off

The mappings, the grant rules, and the request shapes below come from official Model Studio pages opened on 2026-11-17 (Asia/Shanghai). Nobody at Actually Ran has sent these requests to qwen4-max. There is no captured transcript, latency, token count, or thinking trace on this page, and the comparison table later on is empty on purpose. Every command is planned. Not yet verified.

The effort sweep has no live scores yet

A later section describes a planned script that sends the same Northwharf invoice prompt four times, changing only reasoning_effort. Until that script is run on a real China-site Beijing key, treat every quality or cost comparison as a procedure, not a result. If a live call rejects reasoning_effort="none", or returns an error when thinking_budget is omitted, keep the error. Do not invent a fallback from this draft.

What does reasoning_effort actually change on qwen4-max?

On Chat Completions and DashScope, reasoning_effort selects a thinking intensity for qwen4-max. The qwen4-max model page lists the supported values as low, high, and xhigh, with a default of high. The OpenAI-compatible Chat Completions parameter reference adds the compatibility aliases in the table above, and it is also the page that maps none to thinking disabled. The model card’s “supported values” column does not itself list none.

medium is not a distinct middle tier on this model: it is documented as mapping to high. minimal maps to low, and max maps to xhigh. If you carry those OpenAI-style names over unchanged, you still only get the three Qwen levels, plus the off switch.

The official pages describe intensity, not a guaranteed token count, for a lone reasoning_effort on qwen4-max. The China-site Chat Completions reference does publish a token mapping when you set only thinking_budget, and it states the defaults when you set neither parameter. It does not, on the pages opened for this draft, publish a qwen4-max table that converts low / high / xhigh into a specific budget the way it does for the Qwen3.8 family. Do not assume those Qwen3.8 numbers (4,096 / 16,384 / 262,144) apply here.

A short contrast, if you are not on Chat Completions: the model card places the same three levels on OpenAI Responses as reasoning.effort, and on Anthropic Messages as output_config.effort (Anthropic’s documented aliases are medium → high and max → xhigh). This page does not walk through a protocol swap.

How do you turn thinking off for a single request?

Two official switches are documented for qwen4-max, which the deep-thinking guide classifies as a hybrid thinking model (thinking is on by default, and it can be turned off per request).

The Chat Completions parameter reference maps reasoning_effort="none" to thinking disabled. That is the switch the planned sweep uses, because the rest of the comparison is also expressed as reasoning_effort values.

The same deep-thinking guide, and the official OpenAI-compatible examples that already use model="qwen4-max", turn thinking off with enable_thinking set to false. In the OpenAI Python SDK that field is not a standard argument, so the docs put it in extra_body:

# Documented shape; not run on a live key.
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "…"}],
    extra_body={"enable_thinking": False},
)

On a raw HTTP body there is no extra_body wrapper: enable_thinking sits next to model and messages. Official docs do not, in the pages opened for this draft, define what happens if you send reasoning_effort="none" and enable_thinking=true on the same request. Use one documented off switch at a time, and record the live response if you ever test both.

Can reasoning_effort and thinking_budget go on the same call?

No. The Chat Completions parameter reference, in both the Chinese and English versions opened on 2026-11-17, states that qwen4-max cannot set reasoning_effort and thinking_budget together. The planned sweep therefore never sends both.

thinking_budget is the cap on thinking tokens, in tokens, not the cap on the final answer. The deep-thinking guide says that once the cap is reached, the model stops thinking and starts the reply. For qwen4-max the documented default is 131,072. The same parameter reference requires a positive integer; 0 is not accepted.

If you set only thinking_budget, the Chat Completions reference keeps the number you sent and maps it to an effort level:

thinking_budget alone Documented effective level
1–4,096 low
4,097–131,072 high
131,073–262,144 xhigh

If you set neither parameter, the documented defaults are reasoning_effort=high and thinking_budget=131072. That pair is the model’s starting point, not a combination you are supposed to resend on every call.

thinking_budget is also a Model Studio extension. In the Python SDK it belongs in extra_body (extra_body={"thinking_budget": 4096}). On curl, it is a top-level JSON field. The planned invoice sweep does not use it, so a failed effort-only call is not confused with a two-parameter rejection.

What checkable job will tell you if the setting mattered?

The comparison task is a fictional storage invoice at a yard called Northwharf, booking NW-4419. It is not a tool-calling audit, a unit-test extract, an image job, or a three-model bake-off. The rate card mixes free time, a step-up daily rate, a weekend multiplier, a hazardous surcharge that applies only to storage, and a reefer plug fee that runs through the free-storage days. The correct total can be computed without the model.

The booking, restated so you can check the arithmetic yourself:

  • Gate-in 2026-03-10, gate-out 2026-03-23. Charge every calendar date from gate-in inclusive to gate-out exclusive: 13 days. 10 March 2026 is a Tuesday; 23 March is a Monday.
  • 3 TEU, of which 1 TEU is on reefer plug for the whole stay. The booking is hazardous.
  • First 3 stay days are free storage. Stay days 4–7 cost CNY 48.00 per TEU per day; stay day 8 onward costs CNY 96.00. Weekend charged days are billed at 1.25× that day’s rate, rounded to the nearest fen before summing.
  • Hazardous cargo multiplies the storage subtotal by 1.50, not the plug fee. Plug is CNY 55.00 per reefer TEU per charged day, including the free-storage days.

The local checker, examples/northwharf.py, applies those same rules and expects:

{
  "booking_id": "NW-4419",
  "storage_days": 13,
  "free_days": 3,
  "chargeable_storage_days": 10,
  "plug_days": 13,
  "storage_subtotal_cny": "3780.00",
  "plug_subtotal_cny": "715.00",
  "total_cny": "4495.00"
}

That JSON was produced by the checker on this machine. It is not a model output. A reply that gets total_cny right but misses a line item still fails the check. A reply that reasons at length and then emits the wrong total also fails.

How should a Beijing Chat Completions request set the effort?

Sign up at the China-site portal, aliyun.com, and finish 实名认证 so the account can be used from mainland China. Activate Model Studio and issue a regular API key in the 华北2 / China (Beijing) region; you do not need a foreign legal entity for that key. Before sending the sweep, open the Beijing 免费额度 console and enable 免费额度用完即停 on qwen4-max — English pages label the same control Free Quota Only. The free-quota guide treats the control as opt-in: it stays inactive until you flip it.

Point the OpenAI SDK at https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1, substituting the workspace ID shown in the console. Official Chat Completions docs still list the legacy endpoint https://dashscope.aliyuncs.com/compatible-mode/v1 as a working alternative. Use a regular Model Studio key. The free-quota guide says a Token Plan key does not draw from the new-user allowance.

The Chat Completions reference documents reasoning_effort as a request field next to model and messages. Unlike enable_thinking and thinking_budget, that page does not attach a “non-standard, put this in extra_body” note to it. The planned Python script therefore sends reasoning_effort as a keyword argument. If a particular SDK version rejects the keyword, the same field can go in extra_body so it still appears in the JSON body. That fallback has not been tried here.

examples/sweep_reasoning_effort.py is the planned driver. It sends the Northwharf prompt four times, with reasoning_effort set to none, low, high, and xhigh in turn, and never adds thinking_budget. It also pins temperature=0, top_p=1, and presence_penalty=0. That pinning is a planned experimental control, not an official requirement: the model card uses different defaults in thinking mode (temperature 1.0, top_p 0.95, presence_penalty 0.0) and non-thinking mode (0.7, 0.8, and 1.5). If you leave those unset, a none call and a high call are not the same experiment with one knob moved.

The script also sets max_completion_tokens=8192 and streams the response with stream_options={"include_usage": True}. The cap is a grant guardrail. The official thinking-mode output limit for qwen4-max is 262,144 tokens for the chain of thought plus the answer, which is a large share of a 1,000,000-token grant if a request runs away. Streaming is the shape the deep-thinking guide recommends, and it is how the script plans to read reasoning_content and the final usage block. None of this has been executed.

# Planned; no Model Studio key has been used.
export DASHSCOPE_API_KEY='YOUR_BEIJING_KEY'
export DASHSCOPE_BASE_URL='https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1'
python3 northwharf.py --print-expected
python3 sweep_reasoning_effort.py --out ./effort-sweep-results

The results table stays empty until those calls exist:

reasoning_effort Invoice match? total_cny reasoning_tokens completion_tokens finish_reason
none Not yet run — — — —
low Not yet run — — — —
high Not yet run — — — —
xhigh Not yet run — — — —

If you use an assistant such as Grok Bot or Codex to launch the script, keep northwharf.py in your own process so a wrong total cannot be waved through.

How do thinking tokens come out of the 1,000,000-token grant?

They come out of the same pool as every other input and output token on qwen4-max. Official pricing for China (Beijing) lists a new-user grant of 1,000,000 tokens, shared by input and output, valid for 90 days starting from the later of Model Studio activation, model listing, or approval. The model listing page records qwen4-max as listed in 华北2 (Beijing) on 2026-11-16. Ninety days after that listing date is 2027-02-14. If the account was already open on listing day, the clock may start then; as of 2026-11-17 that window is still early. Trust the date the Beijing console shows for this model, not a date computed by hand.

After the allowance is exhausted, the Beijing card prices qwen4-max at CNY 10 per million input tokens and CNY 30 per million output tokens. The output column is labeled 思维链+回答 — chain of thought plus the answer — in both thinking and non-thinking mode. Thinking tokens are ordinary output. There is no separate meter, and hiding them from message.content does not keep them off the grant.

The Chat Completions reference describes usage.completion_tokens_details.reasoning_tokens as the thinking subset of text_tokens. Subtracting reasoning_tokens from text_tokens is the documented way to isolate the visible reply. That details object is described as usually present only when the model actually emits a thinking process; with thinking off it may be null or omitted. After a live sweep, record those fields next to the invoice score. Do not estimate them in advance.

Two documented ceilings can still cut a reply short, even on the free grant. thinking_budget caps only the thinking phase. max_completion_tokens caps thinking and the answer together — and on qwen4-max, the same reference says max_tokens is equivalent to that combined cap. If thinking fills the cap, the visible total can be empty or truncated, with finish_reason equal to length. That is a failed invoice, not a reason to raise the cap all the way to 262,144 on a first attempt.

This walkthrough is a single-turn job, so it does not replay prior thinking. If you later build a multi-turn client, note that preserve_thinking defaults to true on qwen4-max. Official docs say historical reasoning_content must be returned in that field, not folded into content, and that those replayed thinking tokens are counted and billed as input.

Streaming thinking is supported: the deep-thinking guide and the Chat Completions reference both describe incremental reasoning_content on stream deltas. qwen4-max can also return a thinking summary plus encrypted ciphertext instead of the raw chain, by sending thinking_display="summarized" (see 思维链摘要与加密). The planned sweep leaves that off, so a run can still inspect plaintext reasoning_content and reasoning_tokens. Encrypted summaries are a different feature, not a fifth effort level.

When should you leave thinking off — or skip xhigh?

Turn thinking off when the call is a smoke test, a classification, or any job you can already check and you do not want the grant to pay for a chain of thought. reasoning_effort="none" is the documented off switch that stays in the same parameter family as the intensity levels. enable_thinking=false is the documented hybrid-mode switch from the deep-thinking guide. Either is a better first move than hoping a tiny thinking_budget will act as “off”; 0 is rejected.

Stay at low or at the default high when you are still measuring how hard the invoice, or a job like it, actually is. high is the official default, so it is also the honest baseline for “what happens if I change nothing.”

Reserve xhigh for cases where high already failed the checker, or where you have a deliberate reason to spend more thinking tokens. It is not a free upgrade. Every extra reasoning token still decrements the same 1,000,000-token grant, and four unattended xhigh calls can consume more of that grant than the length of the JSON makes obvious.

If you leave 用完即停 disabled, calls that outrun the grant continue and are billed at those CNY 10 / 30 list rates. If you enable it, official docs say the next request after the grant is rejected with HTTP 403 and the code AllocationQuota.FreeTierOnly. Nothing in this tutorial asks you to top up, start a subscription, or buy a Token Plan.

Skip this whole comparison if you do not have a Beijing qwen4-max grant, if you needed a different model, or if the task is image or video understanding. Those jobs belong on other pages.

What a verified revision still has to capture

A later revision of this page should attach, for each of the four planned calls, the raw response (or the error body), finish_reason, usage including reasoning_tokens, whether reasoning_content was present, the parsed invoice JSON, and the checker’s pass or fail line. If reasoning_effort="none" is rejected, or if thinking tokens appear anyway, that belongs in the open record. Until then, the empty table above is the result.

Sources

Official Model Studio pages opened on 2026-11-17 (Asia/Shanghai):

  • qwen4-max 模型页 and the English model page: model ID, hybrid thinking, default enable_thinking=true, reasoning_effort=high, thinking_budget=131072, preserve_thinking=true, thinking-effort values low / high / xhigh, sampling defaults that differ by mode, a 262,144-token thinking-plus-answer output limit, a 262,144-token maximum chain of thought, Beijing list prices CNY 10 / 30, and the 1,000,000-token free allowance.
  • OpenAI兼容-Chat and the English Chat Completions reference: Beijing workspace host, reasoning_effort mappings including none → thinking disabled, the rule that qwen4-max cannot set reasoning_effort and thinking_budget together, thinking_budget range and the budget-only effort map, enable_thinking / thinking_budget via extra_body in the Python SDK, max_completion_tokens as a combined thinking-plus-answer cap, reasoning_tokens accounting, and streamed reasoning_content.
  • 深度思考: qwen4-max as hybrid thinking with thinking on by default, enable_thinking to switch it, thinking_budget as a thinking-phase cap, reasoning_content versus content, and the recommendation to stream.
  • 思维链摘要与加密: default plaintext thinking, and thinking_display="summarized" for a display summary plus encrypted ciphertext.
  • 新人免费额度: grants exist only for Beijing models on the China site; the 90-day window; separate pools per model; 实名认证; the 用完即停 default; the 403 / AllocationQuota.FreeTierOnly refusal; a single pool for input and output; Token Plan keys excluded from the grant.
  • 模型调用价格: Beijing list prices for qwen4-max, with output priced as chain of thought plus the answer.
  • 模型上架与更新: qwen4-max listed on 2026-11-16 in 华北2 (Beijing).

These non-Aliyun pages were read only to see how the topic is already covered in search results. Their limits were not used:

Earlier tutorials in this series cover a first tool-calling job, a hosted 27B call, Qwen Image 3.0 generation, a three-model quota comparison, switching an existing OpenAI client, and image plus short-video understanding. The Northwharf sweep is self-contained: it does not import those examples or depend on reading those pages first.


Title tag: Control Qwen4-Max Thinking With reasoning_effort

Meta description: Set qwen4-max reasoning_effort to low, high, xhigh, or none on Alibaba Model Studio in Beijing, on that model’s 1,000,000-token free grant. Official mappings and a checkable invoice; the comparison has not been run.

Slug: qwen4-max-reasoning-effort-thinking-controls

Evidence it actually ran

This is the shape of the stamp. It has not been earned, and the example date that follows is a placeholder, not a run: Ran on YYYY-MM-DD (Asia/Shanghai) with the pinned versions.

Command output
None recorded. A verified revision will quote the output from the run, not a sample written in advance.
Tests, CI, or Inspector
Not run for this draft.
Repository or config
No link recorded.

Failure modes

Anticipated only. None of these has been checked against a run of this tutorial.

  • Unchecked

    reasoning_effort and thinking_budget are set on the same call

    Official docs say not to set those two together on qwen4-max. The planned sweep never adds thinking_budget.

  • Unchecked

    thinking_budget=0 is used as an off switch

    0 is rejected. reasoning_effort="none" is the documented off switch that stays in the same parameter family as the intensity levels; enable_thinking=false is the documented hybrid-mode switch.

  • Unchecked

    reasoning_effort="none" is rejected, or thinking tokens appear anyway

    Until a live call exists, treat that as an open possibility. If it happens, keep the error or the usage object. Do not invent a fallback from this draft.

  • Unchecked

    Unattended xhigh calls consume the grant faster than the JSON length suggests

    Every extra reasoning token still decrements the same 1,000,000-token grant. Reserve xhigh for cases where high already failed the checker, or where you have a deliberate reason to spend more thinking tokens.

  • Unchecked

    用完即停 is left off and the grant is outrun

    Calls that outrun the grant continue and are billed at the published CNY 10 / 30 list rates. If the switch is on, official docs say the next request after the grant is rejected with HTTP 403 and code AllocationQuota.FreeTierOnly.

Other tutorials in Integrate.