Draft
Control Qwen4-Max Thinking With reasoning_effort
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 valueslow/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_effortmappings includingnone→ thinking disabled, the rule thatqwen4-maxcannot setreasoning_effortandthinking_budgettogether,thinking_budgetrange and the budget-only effort map,enable_thinking/thinking_budgetviaextra_bodyin the Python SDK,max_completion_tokensas a combined thinking-plus-answer cap,reasoning_tokensaccounting, and streamedreasoning_content. - 深度思考:
qwen4-maxas hybrid thinking with thinking on by default,enable_thinkingto switch it,thinking_budgetas a thinking-phase cap,reasoning_contentversuscontent, 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.FreeTierOnlyrefusal; 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-maxlisted 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:
- Thinking (QwenCloud)
- Latest model: Qwen4-Max (QwenCloud)
- feat(alibaba): qwen4-max support (Vercel AI SDK pull request 25085)
- 使用 Qwen 文本模型的 enable_thinking (Infini-AI GenStudio)
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.
Related
Other tutorials in Integrate.
Connect a Local MCP Server to Cursor and Use It to Finish a Real Repo Task
Start a local MCP server, connect it in Cursor, and complete a repo task that requires that tool.
Not yet verified
1 min read
Add a Second Frontier Model to Claude Code with a Documented Fallback Path
Configure a second model and complete the same task via the fallback after a simulated failure.
Not yet verified
1 min read
Build a TypeScript MCP Server for a Real API, Test It with Inspector, and Call It from Claude Code
Implement the server, pass Inspector, then call it from Claude Code to finish a real API task.
Not yet verified
1 min read
Call Qwen4-Max Through the OpenAI-Compatible API and Finish a Tool-Calling Task
Call qwen4-max from the OpenAI SDK on Alibaba Cloud Model Studio in Beijing by changing only api_key, base_url, and model, stay on that model's official free quota with 免费额度用完即停 / Free Quota Only turned on, then finish a tool-calling job: a checked dependency report for an npm project.
Not yet verified
15 min read