Qwen4-Max 这类旗舰模型的能力上限高,但按 token 计费的价格也高。真正落地时,问题往往不是“能不能调通”,而是“哪些任务值得用 Max,哪些用轻量档就够了”。这篇教程带你把三件事一次做完:跑通 API、搭一套任务分层路由、用同一批任务实测两档的延迟与花费。
这篇能做出什么
跟着做完,你会得到一个可复用的最小工程:
- 一个统一的模型调用层,带超时、重试、用量记录;
- 一个按任务类型自动选择档位的路由函数,Max 只处理真正需要它的请求;
- 一份本地 benchmark 脚本,对同一组任务分别跑 Max 档和轻量档,输出耗时、首 token 延迟、token 用量与估算费用;
- 一套判断标准,让你在“效果差一点但便宜很多”和“贵但一次做对”之间做出有依据的选择。
最终你能回答的问题很具体:你手上这条业务,用轻量档的返工率是多少,换成 Max 之后省下的返工时间值不值这个差价。
前置条件清单
动手前确认这几项:
1. 一个可用的模型服务平台账号(例如阿里云百炼 / DashScope,或你使用的其他兼容 OpenAI 协议的服务),并已开通对应模型的调用权限。
2. 已创建 API Key,并且知道它存在哪个环境变量里。
3. Python 3.9+ 环境,能 pip install openai。
4. 从控制台的模型列表里抄下两个模型 ID:一个是 Qwen4-Max 对应的 ID,一个是轻量档(如 Qwen-Plus / Qwen-Turbo 系列)对应的 ID。命名以官方文档当前版本为准,不要凭印象猜。
5. 从官方定价页抄下两档的输入、输出单价(每百万 token)。价格会调整,用之前现查一次。
准备工作只有一句提醒:模型 ID 和单价都别写死在代码里,用环境变量传,后面换档、调价不用改代码。
第一步:配置环境变量并跑通第一个请求
先把手动调通放在最前面,避免带着一堆封装去 debug。
```bash
export DASHSCOPE_API_KEY="sk-你的key"
export BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export MODEL_MAX="控制台里的 Qwen4-Max 模型ID"
export MODEL_LITE="控制台里的轻量档模型ID"
```
BASE_URL 以官方文档当前给出的 OpenAI 兼容地址为准,不同平台路径不同,写错会直接 404。
然后用 curl 打一发,确认鉴权和模型 ID 都没问题:
```bash
curl -s "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"$MODEL_MAX\",
\"messages\": [{\"role\": \"user\", \"content\": \"用三句话解释什么是幂等性\"}]
}"
```
返回体里重点看两处:choices[0].message.content 是否有内容,usage 里的 prompt_tokens 和 completion_tokens 是否有值。后者是你后面算钱的基础。
第二步:封一个统一调用层
后面所有任务都走这个函数,好处是超时、重试、用量记录只写一次。
```python
llm.py
import os
import time
import random
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["BASE_URL"],
)
MODEL = {
"max": os.environ["MODEL_MAX"],
"lite": os.environ["MODEL_LITE"],
}
def call(tier: str, messages: list, temperature: float = 0.3,
max_tokens: int = 1024, retries: int = 3) -> dict:
"""tier: 'max' | 'lite'。返回文本、用量与耗时。"""
last_err = None
for attempt in range(retries):
try:
t0 = time.time()
resp = client.chat.completions.create(
model=MODEL[tier],
messages=messages,
temperature=temperature,
max_tokens=max_tokens,
timeout=120,
)
cost_s = time.time() - t0
u = resp.usage
return {
"tier": tier,
"text": resp.choices[0].message.content,
"prompt_tokens": u.prompt_tokens,
"completion_tokens": u.completion_tokens,
"latency_s": round(cost_s, 3),
"finish_reason": resp.choices[0].finish_reason,
}
except Exception as e:
last_err = e
指数退避 + 抖动,缓解限流
time.sleep((2 ** attempt) + random.random())
raise RuntimeError(f"调用失败,重试 {retries} 次: {last_err}")
```
两个细节值得注意:finish_reason 如果是 length,说明输出被 max_tokens 截断了,这条结果不能直接拿去比效果;timeout 要设得比默认值宽松,长文生成容易在几十秒量级。
第三步:设计任务分层路由
分层不要靠“感觉这个任务重要”,要靠可判断的信号。下面这套规则可以直接拿来改:
```python
router.py
def route(task: dict) -> str:
"""根据任务特征返回档位。"""
1. 明确要求高质量输出的场景走 max
if task["kind"] in {"architecture", "refactor", "code_review", "planning"}:
return "max"
2. 上下文很长(例如整仓库片段、长文档)走 max
if task.get("context_tokens", 0) > 8000:
return "max"
3. 需要多步推理、调用工具做决策的走 max
if task.get("needs_reasoning") and task.get("steps", 1) > 2:
return "max"
4. 其余:格式化、摘要、分类、单文件小改动、参数生成
return "lite"
```
context_tokens 不需要精确,用字符数除以 1.5 粗估即可,它只用来做阈值判断。
再加一条“升级”策略,比一开始就用贵的更省钱:
```python
def call_with_escalation(task, messages):
result = call(route(task), messages, max_tokens=task.get("max_tokens", 1024))
need_upgrade = (
result["finish_reason"] == "length"
or result["text"].strip() == ""
or task.get("validator") and not task"validator"
)
if need_upgrade and result["tier"] == "lite":
result = call("max", messages, max_tokens=task.get("max_tokens", 1024) * 2)
result["escalated"] = True
return result
```
validator 是你自己的校验函数,比如“输出必须是合法 JSON”“必须包含某个函数签名”。这个钩子是整套方案里性价比最高的部分:先让便宜的档位试,校验不过再升级。
第四步:智能体任务怎么分层
智能体一轮里其实混了好几种不同难度的调用,一刀切用 Max 会浪费很多钱。按角色拆开:
| 环节 | 建议档位 | 理由 |
|---|---|---|
| 任务拆解、制定计划 | Max | 规划错了后面全错,成本占比小但影响大 |
| 单步工具调用的参数生成 | 轻量档 | 结构化输出,轻量档通常够用 |
| 工具返回结果的摘要压缩 | 轻量档 | 只是信息压缩,不需要推理 |
| 遇到失败后的反思与重规划 | Max | 需要跳出原思路 |
| 最终答复的组织 | 轻量档或中档 | 内容已定,主要是表达 |
对应的循环骨架:
```python
def agent_step(state, user_goal):
if state["plan"] is None:
state["plan"] = call("max", build_plan_prompt(user_goal))["text"]
step = state["plan_steps"][state["i"]]
args = call("lite", build_tool_args_prompt(step, state["history"]))["text"]
ok, observation = run_tool(step["tool"], args)
if not ok:
state["plan"] = call("max", build_replan_prompt(state, observation))["text"]
state["i"] = 0
return state
state["history"].append(call("lite", build_summary_prompt(observation))["text"])
state["i"] += 1
return state
```
这样做的好处是:一个 20 步的智能体任务里,可能只有 2~3 次调用落在 Max 上,其余全走轻量档。总花费能降一个量级,而决定成败的规划环节仍然用最强的模型。
要注意的风险:轻量档生成工具参数时更容易出现格式错误。务必在 run_tool 里做 schema 校验,失败就重试一次,再失败就升级到 Max 重新生成参数。
第五步:编程任务怎么分层
编程任务是分层收益最明显的场景,因为不同编码动作的难度差异极大:
- 补全与单行修改:轻量档。上下文短、目标明确。
- 写单元测试、写注释、写 commit message:轻量档。
- 单文件内的函数实现:可先轻量档,测试跑不过再升级。
- 跨文件重构、接口设计、技术选型:Max。这类任务需要同时把握多处约束。
- Code Review 与找 bug:Max。漏掉一个边界条件的代价远高于一次调用费。
- 报错排查:先用轻量档做日志归类,定位不到再上 Max 分析根因。
用测试结果当升级信号,是最靠谱的自动化判据:
```python
def fix_until_green(file_path, test_cmd, max_rounds=3):
for rnd in range(max_rounds):
tier = "lite" if rnd == 0 else "max" # 第一轮便宜,之后升级
context = read_file(file_path)
out = call(tier, build_fix_prompt(context, last_error), max_tokens=2048)
write_file(file_path, extract_code(out["text"]))
ok, last_error = run(test_cmd)
if ok:
return True, tier, rnd + 1
return False, "max", max_rounds
```
关键点:把“测试是否通过”作为唯一的成功标准,不要靠肉眼看着像对。这样即使轻量档失败了,你也只是损失一次便宜的调用。
第六步:做一次自己的成本与延迟实测
别人的跑分参考价值有限,你需要自己这批任务上的数据。写一个脚本,同一组任务分别跑两档。
```python
bench.py
import os, time, json
from openai import OpenAI
client = OpenAI(api_key=os.environ["DASHSCOPE_API_KEY"], base_url=os.environ["BASE_URL"])
MODEL = {"max": os.environ["MODEL_MAX"], "lite": os.environ["MODEL_LITE"]}
单价:从官方定价页抄当前值,单位 元/百万 token
PRICE = {
"max": {"in": float(os.environ["P_MAX_IN"]), "out": float(os.environ["P_MAX_OUT"])},
"lite": {"in": float(os.environ["P_LITE_IN"]), "out": float(os.environ["P_LITE_OUT"])},
}
TASKS = [
{"id": "json_extract", "prompt": "从下面文本抽取字段并输出 JSON:……"},
{"id": "summary", "prompt": "把下面的会议记录压缩成 5 条要点:……"},
{"id": "bug_hunt", "prompt": "下面这段代码在并发下有问题,指出并给出修复:……"},
{"id": "refactor", "prompt": "把下面这个函数拆成三个可测试的小函数:……"},
]
def run_one(tier, prompt):
t0 = time.time()
ttft = None
chunks = []
stream = client.chat.completions.create(
model=MODEL[tier],
messages=[{"role": "user", "content": prompt}],
temperature=0.2,
max_tokens=1024,
stream=True,
stream_options={"include_usage": True},
)
usage = None
for ch in stream:
if ch.choices and ch.choices[0].delta.content:
if ttft is None:
ttft = time.time() - t0
chunks.append(ch.choices[0].delta.content)
if getattr(ch, "usage", None):
usage = ch.usage
total = time.time() - t0
text = "".join(chunks)
p_tok = usage.prompt_tokens if usage else 0
c_tok = usage.completion_tokens if usage else 0
cost = p_tok / 1e6 * PRICE[tier]["in"] + c_tok / 1e6 * PRICE[tier]["out"]
return {
"tier": tier, "id": None, "ttft_s": round(ttft or 0, 3),
"total_s": round(total, 3), "prompt_tokens": p_tok,
"completion_tokens": c_tok, "cost_yuan": round(cost, 6),
"chars": len(text), "output": text,
}
rows = []
for t in TASKS:
for tier in ("lite", "max"):
r = run_one(tier, t["prompt"])
r["id"] = t["id"]
rows.append(r)
with open("bench_result.json", "w", encoding="utf-8") as f:
json.dump(rows, f, ensure_ascii=False, indent=2)
for r in rows:
print(f'{r["id"]:12s} {r["tier"]:5s} ttft={r["ttft_s"]:>6.2f}s '
f'total={r["total_s"]:>6.2f}s tok={r["prompt_tokens"]}+{r["completion_tokens"]} '
f'cost={r["cost_yuan"]:.5f}元')
```
stream_options={"include_usage": True} 是为了在流式模式下也拿到 usage,否则你只能靠估算。这个参数在 OpenAI 兼容实现里的支持情况以官方文档为准,如果不生效就退回非流式统计。
跑完之后还有一步不能省:人工打分。打开 bench_result.json,给每条输出打 1~5 分,重点关注三类情况——轻量档完全做对的(说明这档任务可以降级)、轻量档看着像对但实际有错的(最危险,说明校验器不够)、Max 明显更好的(说明该升级)。
第七步:读结果,做取舍
把数据整理成两列就够做决策了:
- 单价差距:Max 的输入/输出单价通常是轻量档的数倍,具体倍数以官方定价页当前值为准。
- 总成本差距:注意不是单价对比,而是“完成同一件事的总花费”。轻量档失败一次重试,成本翻倍;如果失败三次后还得升级到 Max,那还不如一开始就用 Max。
一个实用的判断口径:如果某个任务上轻量档的一次通过率很高(比如十次里九次都对),且失败可以自动检出并重试,那就留在轻量档。如果失败无法自动检出、必须靠人看,那这类任务直接上 Max 更划算,因为人力比 token 贵得多。
延迟方面同理:Max 的响应通常更慢,但如果你要的是“一次做对”,慢几秒远好过返工十分钟。交互式场景(比如补全、聊天)对首 token 延迟敏感,可以优先留在轻量档;批处理场景(夜间生成、离线分析)对延迟不敏感,可以放心用 Max。
常见坑与排错
404 / 路径错误:base_url 少了或多了版本路径,或者用了平台专属地址而非 OpenAI 兼容地址。以官方文档当前给出的地址为准,逐字符核对。
401 / 鉴权失败:环境变量没导出到当前 shell,或者复制 Key 时带了空格和换行。用 echo ${DASHSCOPE_API_KEY:0:6} 检查前几位是否符合预期。
模型不存在:模型 ID 写成了展示名。控制台里的显示名称和 API 里要传的 ID 常常不一样,以后者为准;不同地域的可用模型也可能不同。
429 限流:并发开太高。上面 call 函数里的指数退避加重试能缓解,但根本解法是加并发上限或排队队列,不要靠无限重试。
费用比预期高:多半是上下文太长。多轮对话里把完整历史每轮都重发,token 会随轮次线性增长。做法是保留最近 N 轮原始消息,更早的用轻量档压缩成摘要。
流式拿不到 usage:检查是否传了 stream_options,以及该平台是否支持。不支持就在非流式模式下跑统计,或按字符数粗估。
输出被截断:finish_reason 为 length。调大 max_tokens,或让模型分段输出。被截断的结果不要拿去比对效果。
两档对比不公平:temperature、max_tokens、prompt 必须完全一致,否则数据没意义。另外同一任务建议重复跑 3 次取中位数,单次结果受网络和服务负载影响较大。
轻量档“看起来对”:这是最隐蔽的坑。务必用结构化校验(JSON schema、单元测试、正则断言)代替肉眼判断,否则错误会悄悄流到下游。
升级逻辑死循环:validator 始终不通过时会反复升级。给升级次数设硬上限,并把失败样本记下来人工看。
下一步建议
跑通这套之后,按投入产出排序,可以继续做这几件事:
1. 加缓存。相同或高度相似的 prompt 命中缓存直接返回,批处理和重跑场景收益很大。
2. 把 validator 做扎实。分层省钱的多少,几乎完全取决于你能不能自动判断“这次输出对不对”。先把校验做厚,再谈降级。
3. 加可观测性。每次调用记下档位、耗时、token、是否升级、是否通过校验,按天汇总。有了这张表,调阈值就不用拍脑袋。
4. 做预算护栏。给不同任务设 token 上限和日预算,超限降级或排队,避免一次异常循环刷掉整月额度。
5. 定期复测。模型和价格都会更新,把 benchmark 脚本放进定时任务,每月跑一次,用新数据重新校准路由规则。
最后一句提醒:分层不是为了省钱而省钱,而是把贵的算力花在真正决定结果的那几步上。先测出自己的数字,再决定哪一档留给谁。
