这篇能做出什么
照着做完,你会拿到三样能直接用的东西:
1. 一个跑得通的调用脚本:能分别调用 Code 2 和 Code 2 Flash,输出文本、耗时、输入输出 token 数。
2. 一张任务分层路由表:哪些活儿交给 Flash,哪些必须交给 Code 2,判据写死在代码里,而不是凭感觉。
3. 一份对照数据:用你自己项目里 12~20 个真实任务,把两个模型各跑一遍,得到“通过率、平均耗时、单任务成本、每通过一个任务花多少钱”四个数,用来决定以后怎么分流。
为什么值得这么做:写代码这件事的复杂度分布很偏。改名、补注释、写 commit message、解释一段报错,占了日常请求量的一大半,但这些任务用强模型是浪费;而跨文件重构、并发正确性、权限边界这类任务,省这点钱反而会付出更多返工。分层的目的不是省钱,是让钱花在会出错的地方。
前置条件清单
动手前先确认这几项,缺一项后面都会卡住:
- 一个能登录的控制台账号,且已开通 Code 2 与 Code 2 Flash 的调用权限
- 一组 API Key(建议单独建一个 key 给实验用,方便事后对账)
- 接口地址(Base URL),通常是形如
https://<域名>/v1的 OpenAI 兼容端点 - 两个模型的 model ID(注意大小写和连字符,两个 ID 不要混)
- Python 3.9 以上;依赖一个 HTTP/SDK 客户端,若官方给了独立 SDK 就用官方的,否则用兼容客户端即可
- 一笔小额预算,够跑几百次请求
- 你自己的 12~20 个真实任务样本(不要用“写个快排”这种玩具题,测不出区别)
重要提醒:模型 ID、接口域名、计费单价这三样,各平台写法不同且会调整,本文一律用环境变量占位,请以官方文档当前版本为准。下面所有代码里出现 <...> 的地方都要替换。
第一步:配置凭据,跑通一次请求
先把四个值放进环境变量,避免硬编码进代码:
```bash
export MAI_API_KEY="sk-xxxxxxxx"
export MAI_BASE_URL="https://<控制台给出的接口域名>/v1"
export CODE_MODEL="<Code 2 的 model ID>"
export FLASH_MODEL="<Code 2 Flash 的 model ID>"
```
用 curl 做一次连通性验证。这一步只关心“能不能通”,不关心答得好不好:
```bash
curl -s "$MAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $MAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$CODE_MODEL"'",
"messages": [{"role": "user", "content": "用一句话说明什么是幂等"}],
"max_tokens": 256,
"temperature": 0
}'
```
返回里应该能看到 choices[0].message.content 和 usage 字段。usage 里要重点看 prompt_tokens、completion_tokens 两个数——后面的成本计算全靠它,不要自己用字符数估。
如果返回 401,是 key 的问题;返回 404,十有八九是 model ID 或 Base URL 写错了(见后面排错章节)。
第二步:封装一个可切换模型的调用函数
不要让业务代码直接拼 HTTP。封一层,统一处理重试、计时、token 统计:
```python
mai_client.py
import os, time
from openai import OpenAI # 若官方提供独立 SDK,替换这里的 client 初始化即可
client = OpenAI(
api_key=os.environ["MAI_API_KEY"],
base_url=os.environ["MAI_BASE_URL"],
)
CODE = os.environ["CODE_MODEL"]
FLASH = os.environ["FLASH_MODEL"]
def call(model, prompt, system=None, max_tokens=1500, temperature=0):
msgs = []
if system:
msgs.append({"role": "system", "content": system})
msgs.append({"role": "user", "content": prompt})
t0 = time.time()
resp = client.chat.completions.create(
model=model,
messages=msgs,
max_tokens=max_tokens,
temperature=temperature,
)
elapsed = time.time() - t0
return {
"text": resp.choices[0].message.content or "",
"finish": resp.choices[0].finish_reason,
"in_tokens": resp.usage.prompt_tokens,
"out_tokens": resp.usage.completion_tokens,
"seconds": round(elapsed, 2),
}
def call_with_retry(model, prompt, tries=5, **kw):
for i in range(tries):
try:
return call(model, prompt, **kw)
except Exception as e:
if i == tries - 1:
raise
time.sleep(2 ** i) # 1s, 2s, 4s, 8s 指数退避
```
两个细节值得强调:
temperature=0。写代码、改代码、做判定,默认都要确定性输出,否则同一批评测跑两遍结果对不上,成本数据就没意义了。- 保留
finish_reason。如果它是length,说明输出被max_tokens截断了,此时拿到的代码是半截的,统计通过率会严重偏低。
第三步:写任务分层规则
这是整套流程的核心。规则要写成“可判定的特征”,不要写“感觉这个任务比较难”。下面是一份可以直接抄改的路由表:
```yaml
routing.yaml
to_flash:
- 单文件、单函数范围内的修改与重命名
- 补充注释、docstring、类型标注
- 生成 commit message、PR 描述、变更说明
- 解释单条报错信息、解释某段代码在做什么
- 写正则表达式、写简单 SQL、写 shell 单行命令
- 生成单元测试骨架(不含边界推理)
- 格式化、风格统一、日志文案改写
to_code:
- 跨文件、跨模块的重构与依赖调整
- 并发、事务、锁、幂等、缓存一致性
- 权限边界、鉴权链路、数据脱敏
- 性能优化,需要先定位瓶颈再改
- 需要同时读 3 个以上文件的上下文才能改对
- 输出无法快速验证(比如架构取舍、迁移方案)
- Flash 输出未通过编译 / 测试 / lint
escalate_rule: |
先走 Flash;若输出未通过自动校验,把「原任务 + Flash 的错误输出 + 校验报错」
一起交给 Code 2 重做一次。这比一开始就用 Code 2 更省,也比只用 Flash 更稳。
```
落到代码里就是一个判定函数。真实使用时,前几条可以靠规则自动判定(文件数、是否命中关键词、是否含测试),剩下的交给人工在提交时打标:
```python
STRONG_HINTS = ("并发", "事务", "锁", "鉴权", "跨文件", "重构", "迁移", "性能", "幂等")
def pick_model(task, touched_files=1, has_auto_check=True):
text = task.lower()
if any(h in text for h in STRONG_HINTS):
return CODE
if touched_files >= 3:
return CODE
if not has_auto_check:
return CODE # 无法验证的输出,不要赌
return FLASH
```
这条 not has_auto_check → CODE 的规则值得单独说:Flash 便宜的前提是“错了能马上被发现”。写注释写错了看得见,改名改错了编译器会报,但一份迁移方案少考虑了回滚路径,你可能两周后才知道。能自动验证的活儿才适合下放。
第四步:准备评测集并跑对照
评测集就是你项目里真实发生过的任务。每个任务配一条机器可判定的检查规则,这是让“质量”变成数字的唯一办法。
```json
[
{
"id": "rename-user-name",
"prompt": "把下面代码里的 user_name 全部改名为 username,只输出修改后的完整代码,不要解释。\n\n``python\nclass User:\n def __init__(self, user_name):\n self.user_name = user_name\n``",
"check": {"type": "contains", "value": "self.username = username"},
"max_tokens": 800
},
{
"id": "explain-traceback",
"prompt": "解释这条报错的原因并给出改法:KeyError: 'user_id'",
"check": {"type": "regex", "value": "user_id"},
"max_tokens": 600
}
]
```
跑对照的脚本:
```python
bench.py
import json, os, re, time
from statistics import mean
from mai_client import call_with_retry, call_with_retry as _c, CODE, FLASH
单价从官方定价页抄下来,单位:元 / 百万 token
PRICE = {
"flash": {"in": float(os.environ["FLASH_PRICE_IN"]), "out": float(os.environ["FLASH_PRICE_OUT"])},
"code": {"in": float(os.environ["CODE_PRICE_IN"]), "out": float(os.environ["CODE_PRICE_OUT"])},
}
def judge(rule, text):
t = rule["type"]
if t == "contains": return rule["value"] in text
if t == "not_contains": return rule["value"] not in text
if t == "regex": return re.search(rule["value"], text, re.S) is not None
return False
rows = []
for case in json.load(open("cases.json", encoding="utf-8")):
for tag, model in (("flash", FLASH), ("code", CODE)):
r = call_with_retry(model, case["prompt"], max_tokens=case.get("max_tokens", 1500))
ok = judge(case["check"], r["text"]) and r["finish"] != "length"
p = PRICE[tag]
cost = r["in_tokens"] / 1e6 * p["in"] + r["out_tokens"] / 1e6 * p["out"]
rows.append({"tag": tag, "id": case["id"], "ok": ok, "cost": cost,
"seconds": r["seconds"], "out": r["out_tokens"]})
time.sleep(0.5) # 别把限流打满
for tag in ("flash", "code"):
sub = [r for r in rows if r["tag"] == tag]
passed = sum(r["ok"] for r in sub)
print(
f"{tag:5s} 任务 {len(sub)} "
f"通过率 {passed / len(sub):.0%} "
f"平均 {mean(r['seconds'] for r in sub):.1f}s "
f"单任务成本 {mean(r['cost'] for r in sub):.5f} "
f"每通过一个 {sum(r['cost'] for r in sub) / max(passed, 1):.5f}"
)
```
注意最后一个指标 “每通过一个任务的成本”(总花费 ÷ 通过数)。它比“单任务成本”更能反映真实开销:如果 Flash 便宜一半但通过率只有六成,剩下的四成还得重跑,实际成本可能反超。这个数才是决定分流的依据。
把结果记成一张表,方便贴到团队文档里:
| 模型 | 任务数 | 通过率 | 平均耗时 | 平均输出 token | 单任务成本 | 每通过一个成本 |
|---|---|---|---|---|---|---|
| Code 2 Flash | 16 | 待填 | 待填 | 待填 | 待填 | 待填 |
| Code 2 | 16 | 待填 | 待填 | 待填 | 待填 | 待填 |
另外单独统计一下真正走分流的场景:先 Flash、失败再升级 Code 2 的混合策略,总成本是多少、通过率是多少。这个数字往往比两个纯策略都好,因为它把便宜模型的试错成本也算进去了。
第五步:接进日常流程
评测跑通后,把路由接进两个地方就够了:
命令行快捷方式,用来临时问一句:
```bash
#!/usr/bin/env bash
maiask.sh —— 用法: maiask.sh flash "把这段日志里的 IP 都打码"
level="${1:-flash}"
prompt="$2"
model=$([ "$level" = "code" ] && echo "$CODE_MODEL" || echo "$FLASH_MODEL")
jq -n --arg m "$model" --arg p "$prompt" \
'{model:$m, messages:[{role:"user", content:$p}], temperature:0}' \
| curl -s "$MAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $MAI_API_KEY" \
-H "Content-Type: application/json" \
-d @- \
| jq -r '.choices[0].message.content'
```
批量任务脚本,比如给一个目录下所有文件补 docstring,用小脚本循环调 Flash,跑完再抽查:
```python
from pathlib import Path
from mai_client import call_with_retry, FLASH
for f in Path("src").rglob("*.py"):
src = f.read_text(encoding="utf-8")
if len(src) > 20000: # 太长的文件先跳过,避免上下文被挤爆
continue
r = call_with_retry(FLASH, f"给下面代码补全 docstring,只输出完整文件内容,不要解释:\n\n{src}")
if r["finish"] != "length" and r["text"].lstrip().startswith(("class", "def", '"""', "#")):
f.write_text(r["text"], encoding="utf-8")
```
这里的 startswith 是一道很便宜的保险:模型有时会自作多情加一句“好的,以下是修改后的代码”,直接把这句话写回文件就毁了。凡是让模型“输出完整文件”的场景,都值得加一道这样的格式校验。
常见坑与排错
404 / model not found。 三个地方按顺序查:model ID 是否和文档完全一致(大小写、连字符、有没有带日期后缀)、Base URL 是否多了或少了一段 /v1、这个 key 是否真的开通了该模型权限。把返回体完整打出来,错误信息里通常直接写了“期望的模型列表”。
输出被截断,代码是半截的。 检查 finish_reason 是否为 length。写代码任务时 max_tokens 要给足,建议按“目标文件长度 × 1.3”估。截断的输出千万别当成失败样本去算通过率,会得出错误结论。
同一批任务两次跑出不同结果。 确认 temperature=0,并且没有在 prompt 里混入时间戳、随机 ID 这类变量。评测集要固定,改动之后要重新跑基线。
长上下文把成本吃掉了。 把整个仓库塞进 prompt,输入 token 会远超预期,而且模型对中间部分的注意力会下降。正确做法是先在本地检索出相关的 2~3 个文件再喂进去。输入 token 才是这类任务的主要成本项。
429 限流。 加指数退避(第二步的 call_with_retry 已经带了),并把批量脚本的并发压到个位数再逐步上调。别用固定间隔重试,容易越撞越死。
账单和脚本统计对不上。 常见原因有三个:失败重试的请求也计费但没记账、缓存命中的请求没算进去、以及按小时聚合的账单和按次统计的时间窗不同。记账时把重试次数也记下来,误差就有解释了。
只用 Flash 也只用 Code 2 是两种浪费。 只测一个模型,你不知道分层的收益在哪;只凭“这个看起来难”来分流,规则会越写越随意。评测集每加一条真实失败案例,路由表就准一分。
下一步建议
跑完第一轮对照,按这个顺序继续:
1. 把 routing.yaml 提进仓库,让分流规则和代码一起 review、一起演进,而不是散在每个人的脑子里。
2. 给升级路径加日志。每次“Flash 失败 → Code 2 重做”都记一条,一个月后看哪些任务反复触发升级,那些就是该直接归到 Code 2 的类型。
3. 加一层结果缓存。同一个 prompt 加同一个文件内容,重复调用的比例不低,按 hash(prompt + 文件内容) 做键缓存,命中直接返回。
4. 把评测集做成回归集。每次换模型或改路由规则,先跑一遍这 16 个任务,看通过率有没有掉。这比上线后发现改坏了要便宜得多。
5. 复盘成本结构,而不是只看总额。输入 token、输出 token、重试、缓存未命中,各占多少,决定了下一步该优化哪一块。
整套流程的核心其实只有一句:把“哪个模型更好”这个模糊问题,换成“在我的这批任务上,每通过一个任务花多少钱”这个可比较的数字。 单价和模型 ID 会变,这个方法不会。具体的价格、上下文上限、限流阈值,以官方文档当前版本为准。
