Qwen4-Max-Preview 即将下线:正式版已经上线,开发者如何用 8 步完成迁移

Qwen4-Max-Preview 即将下线:正式版已经上线,开发者如何用 8 步完成迁移

摘要:本文比较 Qwen4-Max-Preview 与正式版 Qwen4-Max 的输出预算、推理默认值和计费方式,并给出 11 月 25 日 Preview 下线前可以逐项执行的迁移检查步骤。

Qwen4-Max-Preview 将于 2026 年 11 月 25 日 24:00(UTC+8)结束预览并下线。正式版 Qwen4-Max 已于 11 月 16 日上线,模型 ID 为 qwen4-max。迁移到正式版时,需要同时检查接入产品、输出预算、推理默认值、工具行为和成本这五项。两个版本都提供 100 万 Token 上下文,但正式版思考模式下的输出上限从 393,216 降到 262,144,默认推理力度从 xhigh 变为 high,计费也从 Token Plan Credits 扩展到按量付费。只修改模型 ID,无法保证生产任务表现一致。

下文先梳理 Preview 与正式版的时间线和规格差异,再介绍正式版的 API 协议、地域、价格与缓存。随后按“保存基线、接入配置、请求参数、功能验证、账单观察、灰度切换”的顺序给出迁移清单,最后列出长报告、代码生成、多轮 Agent 等任务的验收要点。读完后,你可以把这次切换整理成团队可复用的模型版本管理流程。

qwen4-max-preview-offline-migrate-to-qwen4-max-image-0

To Know:Qwen4-Max 迁移术语

术语 解释
Model ID 请求中用来指定具体模型版本的标识,例如 qwen4-max。
Base URL 客户端连接某个产品、某个地域服务时使用的接口基础地址。
上下文窗口 一次请求中模型可以处理的总容量,包括输入、历史和生成内容。
输出预算 单次请求允许生成的 Token 上限。思考模式下,推理内容和最终回答共用这份预算。
reasoning_effort 控制推理力度的请求参数。Preview 与正式版的默认值不同。
thinking_budget 控制思考 Token 预算的参数。在 Preview 中,它不能与 reasoning_effort 同时设置。
Token Plan 阿里云百炼的订阅服务,使用 Credits 计量,也是 Preview 唯一的接入渠道。
Function Calling 模型根据工具定义返回调用请求,由应用执行工具并回传结果的机制。
JSON Schema 描述 JSON 数据结构、字段和约束的规范,用于约束模型输出格式。
TTL 缓存的保留时长,会影响缓存复用的范围和相应费用。
回归验证 用已有的代表性任务,检查版本切换后功能、结果和成本的变化。

1 Qwen4-Max-Preview 何时结束,正式版何时上线

1.1 Qwen4-Max 版本时间线

阿里云 Token Plan 的功能更新记录列出了两个独立事件:11 月 11 日 Preview 上线,11 月 16 日正式版上线。正式版发布后,Preview 的原定下线时间没有变化。Preview 官方文档顶部也已提示“正式版 Qwen4-Max 已上线,建议使用正式版”。

时间(UTC+8) 事件 对开发者的含义
2026-11-11 10:00 Qwen4-Max-Preview 开放 只能通过 Token Plan 个人版或团队版调用
2026-11-16 Qwen4-Max 正式版上线 支持按量付费 API,也可通过 Token Plan 使用
2026-11-25 24:00 Preview 预览结束并下线 qwen4-max-preview 无法继续调用,也不能作为回退目标

qwen4-max-preview-offline-migrate-to-qwen4-max-image-1

1.2 两个 Model ID 与各自渠道

Preview 的模型 ID 是 qwen4-max-preview,别名 qwen4.0-max-preview。两个 ID 都能调用,账单中统一显示为 qwen4.0-max-preview。Preview 的接入方式是 Token Plan 专用 API Key 加专用 Base URL https://token-plan.cn-beijing.maas.aliyuncs.com,不支持按量付费。

正式版的模型 ID 是 qwen4-max。正式版提供两条使用路径:一是 Token Plan 个人版或团队版,二是百炼按量付费 API。这两条路径的 Key、Base URL 和计费方式各不相同,迁移时需要先确定走哪条。

2 Qwen4-Max-Preview 与正式版的规格差异

2.1 Qwen4-Max 规格对照表

以下数据来自 Preview 和正式版的官方模型文档。

技术指标 Qwen4-Max-Preview Qwen4-Max 正式版
Model ID qwen4-max-preview qwen4-max
上下文窗口 1,000,000 1,000,000
最大输入(非思考 / 思考) 文档未单独列出 991,808 / 983,616
最大输出(非思考模式) 文档未单独列出 131,072
思考 + 回答最大合计 393,216 262,144
默认推理力度 xhigh high
默认思考预算 依 Preview 接口参数 131,072
API 协议 OpenAI Chat Completions、Responses、Anthropic Messages 前三者 + DashScope
计费方式 仅 Token Plan Credits 按量付费 API,或 Token Plan

2.2 上下文、输入、输出、思考预算的区别

这四个数字衡量的对象不同,迁移时最容易混淆。上下文窗口是一次请求能处理的总容量,两个版本都是 100 万。最大输入决定一次最多能放入多少资料,正式版在思考模式下为 983,616,比非思考模式少一些,余量留给推理。最大输出决定单次最多生成多少 Token,思考预算则决定其中可以有多少用于推理。

最大的变化在输出侧。Preview 的思考与回答共享 393,216 Tokens,正式版在思考模式下合计上限为 262,144,默认思考预算为 131,072。按默认配置估算,正式版留给最终回答的空间约为 13 万 Tokens。如果业务在 Preview 上依赖单次 20 万以上的长输出,切换后需要重新设计输出方式。

3 Qwen4-Max 正式版的 API 接入能力与成本

3.1 协议与功能

正式版支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 DashScope 四种协议。功能方面,官方列出了 Function Calling、并行工具调用、联网搜索、JSON Object、JSON Schema、显式缓存、隐式缓存,以及思维链摘要与加密。

相比 Preview,正式版文档新增了 DashScope 协议、并行工具调用和两类缓存的说明。如果应用原来只处理单个 tool_call,现在需要确认代码能正确处理一次响应中返回多个工具调用的情况。

3.2 地域与按量价格

正式版按量 API 覆盖六个地域。选择地域时,除了价格,还要考虑网络延迟、数据驻留要求和业务部署范围。各地域的具体能力以官方能力矩阵为准。

地域 部署范围 输入(元/百万 Token) 输出(元/百万 Token,含思考)
华北2(北京) 中国内地 10 30
美国(弗吉尼亚) 全球 10 30
德国(法兰克福) 全球 10 30
日本(东京) 全球 10 30
中国香港 全球 10 30
新加坡 国际 10.938 32.813

北京地域官方页面列有 100 万 Token 免费额度,有效期 90 天。起算时间取开通百炼、模型发布、申请通过等条件中较晚的一个。以上价格只适用于正式版。Preview 的 2 折和夜间叠加后的 8% 费率属于 Token Plan Credits 优惠,不能沿用到正式版的成本测算中。

3.3 显式缓存与隐式缓存

正式版的缓存单独计费。显式缓存由开发者主动创建,适合放入系统提示词、工具说明、固定参考资料等长期不变的前缀,TTL 可选 5 分钟或 1 小时,支持 Chat Completions、Responses 和 Anthropic Messages。隐式缓存由平台根据重复前缀等条件自动处理,不需要额外配置。

多轮 Agent 每轮都会携带同样的工具定义和背景材料,合理使用缓存可以明显降低重复输入的费用。TTL 应根据会话间隔来选:交互密集的会话用 5 分钟,间隔较长的批处理流程可以考虑 1 小时。

4 从 Qwen4-Max-Preview 迁移到正式版的操作步骤

以下 8 步是根据官方规格整理的开发者检查流程。官方没有提供自动迁移工具,也没有声明所有请求参数可以无缝兼容,因此每一步都需要在自己的业务上实际验证。

步骤 检查项 验收标准
1 保存旧配置与代表任务 Preview 的请求参数、输出样本、耗时、用量已归档
2 选择接入产品,核对地域、Key、Base URL 后端服务使用按量 API,交互式工具使用 Token Plan
3 替换 model 为 qwen4-max 冒烟请求返回正常,账单中的模型名称正确
4 显式设置推理力度 按任务写明 reasoning_effort 或对应字段,不依赖默认值
5 重算输出预算 思考模式总量 ≤ 262,144,非思考模式 ≤ 131,072
6 验证工具调用、JSON 结构、长输出、多轮历史 代表任务的通过率与 Preview 基线持平
7 观察用量与缓存账单 输入、输出、缓存各项费用符合预期
8 小流量切换并准备回退配置 回退目标是仍然有效的模型,Preview 不在其中

qwen4-max-preview-offline-migrate-to-qwen4-max-image-2

4.1 保存旧配置与代表任务

在 Preview 下线前,导出当前所有调用 qwen4-max-preview 的配置,包括 max_tokens、reasoning_effort 或 thinking_budget、工具定义、response_format 和系统提示词。同时挑选 10 到 30 个代表性任务,保存 Preview 的输出、耗时和用量作为对比基线。11 月 25 日之后将无法再获取 Preview 的结果。

4.2 选择接入产品并核对 Key 与 Base URL

Token Plan 只允许在 Claude Code、Cursor、Qwen Code、Qoder 等编程工具或智能体工具中交互式使用。自动化脚本、自建应用后端、工作流平台批量调用都不在允许范围内,违规可能导致订阅暂停或 Key 被封禁。如果 Preview 只是在 Qoder 等工具中使用,可以继续通过 Token Plan 切换到正式版。如果要接入自己的后端,应改用正式版按量 API,并使用控制台中对应地域的 Key 和 Base URL。

Token Plan 个人版还包含数据授权条款:使用期间,输入和生成内容会用于服务改进。处理机密资料的团队,在选择接入产品时需要把这一条纳入评估。

4.3 替换 Model ID:Qwen4-Max 快速上手

模型 ID 改为 qwen4-max 即可发出第一个请求。下面是一个使用 OpenAI 兼容接口的最小示例,先确认请求能通,再进入参数调整:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # API易 统一接口,也可替换为百炼对应地域的 Base URL
)

resp = client.chat.completions.create(
    model="qwen4-max",                   # 原值为 qwen4-max-preview
    messages=[{"role": "user", "content": "用三句话说明你的版本信息"}],
    reasoning_effort="high",             # 显式写明,不依赖默认值
    max_tokens=8192
)
print(resp.choices[0].message.content)

同一 OpenAI 兼容接口下有哪些可用模型,以平台的实时模型列表为准。生产环境请在发布前再确认一次。

4.4 显式设置推理参数

Preview 默认 xhigh,正式版默认 high。如果原来的代码没有写推理力度,切换后的推理强度会自动下降,复杂任务的质量、耗时和 Token 用量都可能随之变化。建议按任务类型写明推理力度:复杂代码和科研推理先用与 Preview 相同的强度做基线对比,简单抽取和格式化任务再尝试降低。

Preview 文档规定,reasoning_effort 和 thinking_budget 不能同时设置。正式版在 Chat Completions、Responses、Anthropic Messages、DashScope 四种协议中的字段名和取值,应以对应协议文档为准。在 Preview 中,多轮对话默认开启 preserve_thinking,历史思考内容要放回 reasoning_content 字段。如果你的应用回传了思考内容,也需要在正式版上验证历史消息格式能被正确接收。

4.5 按新上限重算输出预算

在 Preview 中,max_tokens 和 max_completion_tokens 等价,思考与回答共享 393,216 的总预算。到了正式版,思考模式的总预算为 262,144,非思考模式的输出上限为 131,072。所有在 Preview 上设置超过 262,144 的请求都必须调低。原来预算偏紧的请求,还要考虑默认思考预算 131,072 会占用的部分。

查看完整迁移配置代码(预算校验 + 回退)
from openai import OpenAI

# 正式版官方上限(思考模式为思考与回答合计)
LIMITS = {
    "qwen4-max": {"thinking": 262_144, "non_thinking": 131_072},
}

def plan_max_tokens(model: str, thinking: bool,
                    answer_tokens: int, thinking_tokens: int = 0) -> int:
    """按模式计算 max_tokens,超出官方上限时直接报错,避免静默截断"""
    limit = LIMITS[model]["thinking" if thinking else "non_thinking"]
    need = answer_tokens + (thinking_tokens if thinking else 0)
    if need > limit:
        raise ValueError(f"{model} 预算 {need} 超过上限 {limit},请拆分任务")
    return need

PRIMARY = {
    "model": "qwen4-max",
    "base_url": "https://api.apiyi.com/v1",  # API易 OpenAI 兼容地址
    "reasoning_effort": "high",
}
# 回退目标必须是仍在服务的模型,qwen4-max-preview 下线后不可用
FALLBACK = {
    "model": "YOUR_FALLBACK_MODEL",
    "base_url": "https://api.apiyi.com/v1",
}

def call(cfg: dict, messages: list, max_tokens: int):
    client = OpenAI(api_key="YOUR_API_KEY", base_url=cfg["base_url"])
    kwargs = {"model": cfg["model"], "messages": messages, "max_tokens": max_tokens}
    if "reasoning_effort" in cfg:
        kwargs["reasoning_effort"] = cfg["reasoning_effort"]
    return client.chat.completions.create(**kwargs)

def run(messages: list, answer_tokens: int = 60_000, thinking_tokens: int = 131_072):
    budget = plan_max_tokens("qwen4-max", True, answer_tokens, thinking_tokens)
    try:
        resp = call(PRIMARY, messages, budget)
    except Exception as e:
        print(f"主模型失败,切换回退:{e}")
        resp = call(FALLBACK, messages, min(budget, 32_000))
    choice = resp.choices[0]
    if choice.finish_reason == "length":
        print("警告:输出因长度被截断,需要拆分任务或调整预算")
    print("用量:", resp.usage)
    return choice.message.content

if __name__ == "__main__":
    print(run([{"role": "user", "content": "生成一份模型迁移回归报告的大纲"}]))

4.6 验证工具调用、结构化输出与长输出

使用代表任务逐项回放:Function Calling 是否返回相同的工具名和参数结构,并行工具调用是否被代码正确处理,JSON Schema 输出能否通过原有的校验器,长输出是否以 finish_reason == "length" 结束,多轮历史回传后上下文是否连贯。每一项都和 4.1 中保存的基线做对比,并记录差异。

4.7 观察用量与缓存账单

从 Credits 切换到按量计费后,成本要按输入、输出(含思考)、缓存三项分别核算。正式版的输出单价是输入的 3 倍,而思考 Token 也计入输出,所以推理力度设置直接影响账单。可以先用北京地域的免费额度跑完回归,再根据实际用量推算月度成本。

4.8 小流量切换并保留回退配置

先把 5% 到 10% 的流量切到 qwen4-max,观察错误率、截断率和单次任务成本,确认稳定后再全量切换。回退配置要指向仍在服务的模型,例如同系列的其他可用版本,或已经验证过的其他厂商模型。Preview 下线后不能作为回退目标。

🎯 技术建议:回退模型最好在灰度前就完成同一批代表任务的验证。通过 API易 apiyi.com 的 OpenAI 兼容接口,一个 Key 就能在多家主流模型之间切换,只需修改 model 字段即可完成回退演练。

5 Qwen4-Max 迁移后最容易出现的问题

5.1 输出截断

这是最常见的问题。Preview 上能完整生成的长报告或大文件,换到正式版后可能因为 262,144 的上限或默认思考预算的占用而被截断。处理办法是检查 finish_reason,对超长任务分章节或分文件生成,同时给回答部分预留明确的预算。

5.2 默认推理力度下降

从 xhigh 降到 high 后,复杂任务的表现可能变化,简单任务的耗时和费用则可能下降。不写推理参数的代码会在不知情的情况下改变行为。所有生产请求都应该显式设置推理力度,并通过 A/B 回放确定每类任务合适的档位。

5.3 工具调用与协议差异

正式版明确支持并行工具调用,一次响应中可能出现多个工具调用请求。只读取第一个 tool_call 的代码会漏执行工具,导致 Agent 流程中断。切换协议时,例如从 Chat Completions 换到 DashScope,字段命名和思考内容的回传方式也需要重新对照文档。

5.4 缓存与账单口径变化

Preview 的 Credits 消耗受计费系数、缓存命中、工具调用等因素影响,不能直接换算成每百万 Token 的单价。正式版采用元/百万 Token 计价,缓存单独计费。原来按 Credits 做的预算模型需要重建,并把显式缓存的写入成本和 TTL 选择纳入其中。

6 Qwen4-Max 正式版哪些任务必须重新测试

任务类型 重点验证项 关注的参数
长报告生成 是否截断、章节是否完整、事实前后是否一致 输出预算、finish_reason
复杂代码生成 编译与测试通过率、单文件长度、跨文件一致性 reasoning_effort、输出预算
多轮 Agent 工具调用顺序、并行调用处理、历史思考回传 tool_calls、reasoning_content
长文档检索 跨段落关联准确率、输入是否超出 983,616 或 991,808 最大输入、缓存命中
JSON 结构化输出 Schema 校验通过率、字段缺失与类型错误 response_format、JSON Schema

长文档检索需要特别注意:正式版的最大输入因模式而异,思考模式比非思考模式少约 8,000 Tokens。紧贴上限装填资料的任务,切换模式后可能超出限制。代码类任务建议直接复用已有的单元测试集,以测试通过率作为验收指标,比人工阅读输出更可靠。

💡 选择建议:如果需要同时比较 Qwen4-Max 与其他旗舰模型在这些任务上的表现,可以用 API易 apiyi.com 的统一接口回放同一批任务,减少为每个厂商单独编写适配代码的工作量。

7 Qwen4-Max-Preview 迁移常见问题

Q1:Qwen4-Max-Preview 下线后,旧请求会自动转到正式版吗?

官方文档只说明 Preview 将下线并建议使用正式版,没有提到自动转发。请在 11 月 25 日 24:00 前手动把 model 改为 `qwen4-max`,并完成本文第 4 节的检查。

Q2:只把模型 ID 改成 qwen4-max 就够了吗?

不够。输出上限、默认推理力度和计费方式都变了。至少还要重算输出预算、显式设置推理力度,并对工具调用和结构化输出做回归验证。

Q3:Preview 的 2 折和夜间优惠在正式版上还有效吗?

这两项优惠只适用于 Preview 在 Token Plan 中的 Credits 消耗。正式版按量 API 以北京地域输入 10 元、输出 30 元/百万 Token 为准,成本需要重新测算。

Q4:后端服务能继续使用 Token Plan 的 Key 吗?

不能。Token Plan 只允许在指定的编程或智能体工具中交互式使用。自建应用后端应改用正式版按量 API,或使用 API易 apiyi.com 这类提供 OpenAI 兼容接口、按量计费的聚合服务。

Q5:迁移期间怎样快速搭建回归环境?

把代表任务整理成固定的请求集,用同一段代码切换 model 字段即可完成回放。API易 apiyi.com 为新用户提供免费测试额度,可用于验证回退模型和对比方案。

8 结语:把模型版本管理纳入 Qwen4-Max 生产流程

这次从 Qwen4-Max-Preview 到正式版的切换,涉及五个需要持续管理的维度:

  1. 模型 ID:集中维护在配置中心,不在代码里硬编码,并订阅模型生命周期公告。
  2. 接口参数:推理力度、思考预算、response_format 全部显式设置。
  3. 输出限制:为每个模型记录上下文、最大输入、最大输出、思考预算四个数字,在发请求前做校验。
  4. 成本:按输入、输出、缓存分别监控,计费模式变化时重建预算模型。
  5. 回归测试:保留代表任务集和基线结果,每次切换版本都完整回放一遍。

Preview 的生命周期只有两周,正式版之后同样会有新版本和下线计划。建立“基线保存、显式参数、灰度切换、可用回退”的固定流程,下一次版本更替时就能在几天内完成迁移。需要准备多模型回退方案的团队,可以通过 API易 apiyi.com 在同一接口下完成验证。

参考资料

  1. Qwen4-Max 正式版官方文档:上下文、输入输出上限、默认推理力度、地域、价格与缓存

    • 链接: help.aliyun.com/zh/model-studio/qwen4-max
    • 说明: 迁移参数的主要依据
  2. Qwen4-Max-Preview 官方文档:Preview 规格、接入方式、下线时间

    • 链接: help.aliyun.com/zh/model-studio/qwen4-max-preview
    • 说明: 保存旧配置时的对照依据
  3. Token Plan 功能更新:Preview 与正式版的上线记录

    • 链接: help.aliyun.com/zh/model-studio/token-plan-product-updates
    • 说明: 版本时间线来源
  4. Token Plan 权限与使用规范:交互式使用范围与禁止场景

    • 链接: help.aliyun.com/zh/model-studio/token-plan-permissions-and-usage
    • 说明: 选择接入产品时的合规依据
  5. Token Plan 个人版订阅与权益:套餐、Credits 与 Preview 优惠

    • 链接: help.aliyun.com/zh/model-studio/token-plan-personal-overview
    • 说明: 区分 Preview 优惠与正式版计费

作者:APIYI 技术团队
技术交流:欢迎通过 API易 apiyi.com 首页联系我们,更多接入资料可访问 docs.apiyi.com 文档中心

延伸阅读

类似文章