千问 Qwen4-Max API 怎么接?正式版调用与预览版迁移指南

核对 Qwen4-Max 的模型 ID、地区和计费通道,完成首次请求与响应校验,并在迁移 Agent 前检查输出限制和工具历史。

折叠桥连接出一段连续通路,橙色小车驶在已确认安全的路段上,示意经过验证的迁移。

Qwen4-Max 已在官方文档中作为正式型号列出,API 标识符为 qwen4-max,与 qwen4-max-preview 不同。 如果旧文章仍说千问 4 只能通过预览订阅使用,配置应用前先核对最新官方文档。

本文核查日期为 2026 年 11 月 16 日,使用 QwenCloud 直连 API,解释迁移选择,并提供一个小型响应校验脚本。我们核对了文档并测试了本地合成响应,未为本文执行付费 Qwen4 调用,也未进行模型跑分。以下示例是可运行请求与验收条件,不是性能实测结论。

正式版变了什么,应该选哪个模型

官方模型页(英文)现在介绍的是 qwen4-max,预览资料使用另一个标识符。应使用目标调用通道实际支持的精确名称,不要添加无关网关的供应商前缀,也不要把客户端显示名当作 API ID。

正式版文档记录了文本生成、图片和视频理解、工具调用及结构化输出。办公工作流尤其要区分:理解图片不等于生成图片,模型输出幻灯片内容也不等于已创建可编辑演示文件。文件生成、执行与交付还需要工具,以及会检查结果的 Agent 执行框架。

决策修改配置前检查什么
正式版还是预览版本文使用 qwen4-max,预览配置单独保留
直连 API 还是网关核查该供应商自己的目录、凭据与协议
按量付费还是 Token Plan使用对应计费通道的端点和 Key
地区控制台地区、Key 与端点匹配
Agent 迁移验收任务和交付物,不只看 HTTP 请求成功

官方上下文上限为 1,000,000 token。正式版文档给出的非思考模式最大输出为 131,072 token,或思考与回答合计 262,144 token。这些是上限,不是首次请求推荐默认值。不要把预览版的旧输出数字复制到正式版配置中。

配置 QwenCloud 直连账号

按量 API 接入需要在计划使用的 QwenCloud 地区创建或选择 Key。按照官方 API Key 说明(英文)与地区及端点文档(英文)配置,发送请求前确认账号访问资格与计费状态。

下面使用新加坡地区:

Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions

Token Plan Key 使用单独通道,应按 Token Plan 文档(英文)设置,而不是直接放进按量示例。两个通道采用熟悉的协议,不代表权限或账单合并。

把 Key 保存在服务端环境变量 DASHSCOPE_API_KEY 中,不要提交到仓库或放进截图。可以只检查变量是否存在,不显示内容:

python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'

这只能证明变量有值。实际认证请求成功后,才能确认目标通道接受这个 Key。

发送小请求,并检查响应是否完成

保存为 request.json:

{
  "model": "qwen4-max",
  "messages": [
    {
      "role": "user",
      "content": "Return exactly three short checklist items for reviewing an API integration."
    }
  ],
  "enable_thinking": false,
  "max_completion_tokens": 1024
}

这个有限的连通性检查显式关闭思考,不代表所有编程或调研任务都应关闭。思考文档(英文)介绍各项控制。token 上限约束输出量,不是整个多轮工具工作流的总费用上限。

确认选中了正确的付费账号,再执行:

curl --silent --show-error --fail-with-body \
  --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -o response.json

超时后不要自动重复命令:即使响应没有回到终端,服务器也可能已经处理了请求。先检查供应商的请求与用量记录。这个示例有意不设置自动重试循环。

再把下面的代码保存为 check_response.py,运行 python3 check_response.py response.json:

import json
import sys
from pathlib import Path

payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
    raise SystemExit("API error: inspect response.json locally.")
choices = payload.get("choices") or []
if not choices:
    raise SystemExit("No choices returned; inspect the response format.")
choice = choices[0]
reason = choice.get("finish_reason")
message = choice.get("message") or {}
text = message.get("content")
if reason != "stop":
    raise SystemExit(f"Incomplete text check: finish_reason={reason!r}")
if not isinstance(text, str) or not text.strip():
    raise SystemExit("No usable final text returned.")
print(text)
print("Usage:", payload.get("usage", "not supplied"))

通过检查意味着响应包含非空文本,且有正常结束标记。仍需自行确认是否确实给出了要求的三项内容。 脚本专门检查第一次纯文本请求;合法的工具调用属于另一种中间结果,不能当作已完成回答通过验收。

为了复核结果,应记录请求日期、端点地区、返回模型标识、结束原因、用量和任务结果。原始响应如含用户数据,应保持私密。

迁移现有编程或办公 Agent

迁移需要回答两个问题:新通道能否执行当前协议,Agent 能否继续完成交付?一句简单问候既不能验证完整协议,也不能验证工作质量。

  1. 保存当前配置。 记录供应商、模型、端点、客户端版本和工具权限。做可撤回的配置变更,不要在所有环境直接覆盖正常配置。
  2. 从隔离任务开始。 使用小型仓库或合成办公文档。运行前定义交付物:通过测试的补丁、合计可对账的工作簿,或引用可核查的报告。
  3. 核对客户端专用设置。 QwenCloud 分别提供 Qwen Code、Codex、Claude Code接入文档(均为英文)。一种执行框架的配置不能视为通用 API 示例。
  4. 完成一次工具往返。 让 Agent 检查无害测试数据、调用只读工具、接收结果并用于回答。检查工具调用 ID 与历史是否完整保留。
  5. 检查实际交付物。 打开生成文件或审查补丁。独立核对公式、引用或测试,不只相信模型自称完成。
  6. 逐步扩大范围。 对相同输入,与当前配置比较成功任务成本、耗时和人工介入次数。一条好看的回答不足以支持替换生产工作流。

合成表格任务可复用下面的英文验收提示词:

Use only the supplied sales.csv. Calculate revenue by month from quantity
and unit_price. Flag missing values rather than inventing them. Deliver:
1. the calculation method;
2. the totals with the source row IDs;
3. a list of excluded rows and reasons.
Do not claim to have created an Excel file unless you actually create and
attach one. Stop and report any tool or file-access failure.

这是建议执行的测试,不代表 Qwen4 已通过。自行重算合计,再逐步加入重复行、币种差异等更难情况。

两个容易导致迁移结果异常的细节

输出预算的含义发生了变化。 API 兼容性公告(英文)说明,从 Qwen4 预览代际开始,max_tokens 按思考与最终回答合计限制。原来为可见文本留出充足空间的设置,开启思考后可能出现不同结果。不要直接提高上限,先看完成状态和用量;每次只改一个因素,并记录成本。

工具历史不只是可见回答。 函数调用文档(英文)和思考文档说明如何跨轮传回助手推理与工具结果。不要从纯文本对话重新构造历史时丢掉协议字段。更一般的接入模式可参考千问等模型多轮工具调用指南;其中旧型号的示例不能替代 Qwen4 当前协议要求。

先定位问题,再决定是否重试

现象先检查下一步
认证被拒绝Key 是否属于目标通道和地区修正 Key 与端点配对,不把密钥放入问题单
模型不可用或找不到精确 ID、账号权限和供应商目录确认该通道确实提供 qwen4-max,不猜别名
请求参数被拒绝客户端是否发送了其他型号或协议的参数先缩减为上面的最小请求,再逐项添加必要字段
最终回答截断或为空结束原因、思考预算和输出上限修改预算前先检查用量与原始响应
工具循环停住助手工具调用、对应结果和推理历史把序列化消息与官方多轮示例对照
触发限流账号配额、并发数、响应提示降低并发,对适合重试的情况采用有上限的退避
模型说完成却没有文件工具执行和文件存储要求提供文件并检查内容后再验收

这是诊断分支,不表示我们在 Qwen4 上逐项复现了这些故障。要区分错误 ID 和不支持的端点,可参考模型找不到排查指南(英文)。

费用和 Ofox 可用性要分开核查

QwenCloud 的当前价格说明(英文)区分地区、输入、输出和缓存操作。思考 token 计入输出费用。预览积分促销不是正式型号的通用价格,Token Plan 配额也不是按量单价。

不使用缓存时,将输入 token 数乘适用输入费率,再加输出 token 数乘适用输出费率;先把两种费率统一到相同 token 单位。工具循环中的每次模型调用都要计入。使用缓存时按供应商规则区分写入与读取,避免重复计算相同 token。结果旁边记录地区和价格核查日期。

11 月 16 日的 Ofox 公开目录快照没有列出 Qwen4-Max。 因此上面的 QwenCloud 直连步骤不是 Ofox 接入教程。如果现在需要 Ofox 上已有的通道,可检查 Qwen3.8 Max 0902 模型页,把它作为不同模型评估,不要当作 Qwen4 别名。

Ofox 请求应遵循 API Key 鉴权文档和错误处理文档。这些凭据与规则不能用于认证 QwenCloud 请求。迁移到网关前,先确认新型号的真实目录条目和支持协议。

常见问题

Qwen4-Max 仍然只有预览版吗?
不是。当前官方文档列出了 qwen4-max,支持按量 API 和 Token Plan。qwen4-max-preview 是独立标识符,应核查其自己的条款,不要把预览条件套到正式版。
能通过 Ofox 调用 Qwen4-Max 吗?
2026 年 11 月 16 日的公开目录核查未发现 Qwen4-Max。本文使用 QwenCloud 直连接口,不声称 Ofox 已上架。
百万上下文是否意味着能输出百万 token?
不是。正式版文档给出 1,000,000 token 上下文,输入与输出有各自限制。非思考模式最大输出 131,072 token;思考和回答合计最大 262,144 token。