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


