qwen3-max的上下文限制

很多人拿到 Key 想接 Qwen3-Max，第一反应是「它能吃多长的文档」，结果文档里翻不到准数，或者记了个旧数字，上线才发现请求被截断。这篇不写死具体数字，只给一套查证口径和容量估算方法：先确认窗口口径，再按输入输出配比算余量，最后给出超限的表现和排查顺序，供接入与长文场景参考。

很多人拿到 Key 想接 Qwen3-Max，第一反应就是「它能吃多长的文档」。结果翻官方文档找不到准数，或者脑子里记了个旧数字，上线才发现请求被截断、返回内容缺一半。这篇不写死任何具体数字，只给一套查证口径和容量估算方法：先确认窗口到底限的是什么，再按输入输出配比算余量，最后给出超限的常见表现和排查顺序。

整套流程就三步：确认口径、现查上限、按业务反推容量。口径错了，后面算得再细也是白搭；数字背错了，比不知道还危险。下面按这三点拆开讲，中间穿插可落地的清单和排查顺序。

先分清「上下文限制」到底限的是什么

上下文窗口通常指单次请求里输入加输出共享的总预算，不是只算你贴进去的正文。很多人以为窗口是「输入上限」，于是把整篇文档塞进去，还指望模型回一大段总结，结果在输出侧就撞墙了。接入前先把口径对齐，比背数字重要得多。

• 窗口是输入输出合计还是分开计：合计的话，输出越长，能给输入的预算越少
• 超长是直接报错，还是静默截断：报错好排查，静默截断最坑，容易让你误判是模型能力问题
• 是否有单独的输入上限：有些实现输入和输出各有一个封顶，取小者才是你的真实天花板
• 渠道口径差异：官方直连、云厂商托管、中转站对同一模型的说法可能不一致，以你实际调用那条链路的文档为准

口径这类定义差异，不用自己猜。站内 /ai-dict/category/basics 有一批基础概念的对照解释，适合接入前扫一遍。重点是别拿别家模型的窗口直接套到 Qwen3-Max 上，同名「上下文窗口」在不同厂商那里定义范围就不一样。

上限数字去哪核，别背数字

模型规格和版本变动很频繁，写进文章的数字很快过期，所以正确做法是每次接入前现查，而不是记住某个数。查的顺序也有讲究：先看模型官方页的规格说明，再看你实际走的那条链路的接口文档。如果是走云厂商或聚合平台，后者的说明优先级更高，因为它才是卡你请求的那一层。

预算和价格这类会变的数字，到 /price-watch 核对当时的数字，别拿几个月前的截图做容量规划。窗口上限本身同理，站内 /models 和 /official-api/providers/alibaba 两处对照着看，比只看一个来源更稳。

按业务算容量：一次能塞多少文档

知道上限之后，真正要回答的是「我一次能塞几篇文档」。这里最容易踩的坑是拿标称窗口直接除以文档字数，忽略了 token 密度差异。中文、代码、表格、PDF 抽取文本，同样字数对应的 token 数差得很远，必须先量一遍再算。

1. 量输入密度先用 /tools 里的换算工具把一段真实样本转成 token 数，算出你这类内容每千字大概占多少 token，别用理论值硬套
2. 扣输出预算如果你的场景要模型写长报告，输出侧要单独扣掉一大块，不能把整个窗口都分给输入
3. 留安全垫真实请求里还有提示词模板、系统指令、历史轮次，实际可用输入往往明显小于标称窗口，按你的业务留出余量
4. 反推篇数用「单篇文档 token × 轮次」反推一次能放几篇，超了就拆块或走检索

如果反推下来发现必须拆块，检索方案就得提前选型。站内 /stacks/vector-dbs 有向量库相关的整理，适合在做容量规划时一并评估，免得窗口不够了临时找方案。

• 短问答、单轮改写：窗口基本不会成为瓶颈，别在这上面过度设计
• 长文档总结：先把输出预算扣掉再分配输入，否则总结写到一半被截断
• 多轮对话：历史轮次会吃掉预算，要定清楚保留几轮、超出怎么压缩
• 批量处理：按单篇 token 乘篇数估算，超限就分批或走异步

超限与接近上限时的表现和排查顺序

超限不总是一个干脆的报错。常见的有三种表现：请求直接报参数错误、返回内容被砍半、前面贴的资料模型「装作没看见」。第三种最容易被误判成模型能力差，其实是内容根本没进上下文。排查时要按顺序走，别一上来就怀疑渠道。

1. 看报错文本先判断是参数类错误还是限流类错误，两者处理方式完全不同
2. 查历史轮次多轮场景里最常见的原因是历史累积撑爆，先确认是不是轮次太多
3. 比对渠道口径前两步都排除后，才怀疑你走的这条链路的窗口口径和官方不一致
4. 定位日志把错误码和原始请求文本记下来，方便区分是内容太长还是额度问题

报错语义的细分可以互链 /api-errors，它按状态码分类讲，适合前端和网关侧看。如果是想按 error code 文本理解含义，站内另有一篇专门讲文本解释的，两篇各管一段，别混着看。开发侧还有一个动作值得常备：对输入做 token 预估，在超过阈值前就拆分，别等报错再补救。

什么情况下这套算法不适用

这套容量估算不是万能的。如果你做的是短问答、单轮改写，窗口基本不会成为瓶颈，这时候花时间抠上限，不如先看延迟和成本。判断标准很简单：单次请求的输入加输出离窗口上限还很远，就说明这个维度不是你的主要矛盾。

• 任务本身很短：窗口不构成约束，关注点应转向响应速度和调用成本
• 长上下文的中段召回不稳定：即使没超限效果也会掉，这时该换检索方案而不是继续堆内容
• 走第三方中转：标称窗口和实际可用窗口可能不一致，需要以实测为准
• 对稳定性要求极高：宁可保守拆分，也别贴着上限跑

如果确实需要验证第三方渠道的实际可用窗口，可以参考站内 /tools/verify 的在线实测思路做交叉验证，用真实请求去探边界，比只看文档描述可靠。这类验证适合在接入初期做一次，之后定期抽检。