这篇教程带你把 MiniMax M3.1 Flash 真正跑起来，而不只停留在看文档。做完之后你手里会有四样东西：一个能跑通的最小调用脚本；一个带计时与 token 统计的通用调用函数；一套用三个真实编码任务做的评测流程；一张能直接用于选型的对照表。全程不写死价格和模型名——这类信息变动快，一律以官方文档当前版本为准，从控制台复制。
一、前置条件清单
动手前把这些准备好，后面不会卡壳：
1. 账号与 API Key：在 MiniMax 开放平台控制台创建 Key，确认账户余额或免费额度状态。Key 只在创建时完整显示一次，先存到密码管理器。
2. Python 3.9+：python --version 能输出版本号即可。用虚拟环境隔离依赖。
3. 一个 OpenAI 兼容的 SDK：MiniMax 提供 OpenAI 兼容接口，用 openai 这个包最省事。具体推荐哪个 SDK、哪个版本，以官方文档当前版本为准。
4. 两个对照模型：至少再准备一个其他厂商的 Flash 档（低延迟、低价位）模型，选型需要横向比较。
5. 三份价格数据：把你打算对比的每个模型的「输入单价」「输出单价」抄到一张表里，注意单位是每千 token 还是每百万 token，这两者差 1000 倍，最容易算错。
6. 一个计时环境：本机网络状况会污染延迟数据，尽量在和你生产环境同区域、同网络的机器上测。
二、分步骤实操
步骤 1：把密钥、地址、模型名放进环境变量
不要硬编码进代码，一是容易泄露，二是换模型时改一处就够。
```bash
终端里执行，仅当前会话有效
export MM_API_KEY="sk-你的密钥"
export MM_BASE_URL="https://你的控制台给出的域名/v1"
export MM_MODEL="控制台模型列表里的 Flash 档模型标识"
```
MM_BASE_URL 和 MM_MODEL 都从控制台的「API 文档 / 模型列表」页面复制，别凭记忆手敲。写成 .env 文件也行，记得把 .env 加进 .gitignore。
步骤 2：跑通第一次调用
```bash
python -m venv .venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
pip install openai
```
```python
hello.py
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MM_API_KEY"],
base_url=os.environ["MM_BASE_URL"],
timeout=60,
max_retries=2,
)
resp = client.chat.completions.create(
model=os.environ["MM_MODEL"],
messages=[
{"role": "system", "content": "你是一个简洁的编程助手。"},
{"role": "user", "content": "用一句话解释什么是幂等性。"},
],
temperature=0.2,
max_tokens=256,
)
print(resp.choices[0].message.content)
print(resp.usage) # 输入/输出 token 数在这里
```
能打印出内容，说明鉴权、地址、模型名三件事都对上了。resp.usage 里的两个数字是后面算钱的唯一依据，务必确认它不是空的。
步骤 3：封装一个带计时和用量统计的调用函数
评测要靠数据说话，裸调用拿不到这些。非流式版本测的是「总时长」，流式版本才能测「首 token 延迟」——这两个指标在选型时含义完全不同。
```python
bench.py
import os, time
from openai import OpenAI
client = OpenAI(api_key=os.environ["MM_API_KEY"],
base_url=os.environ["MM_BASE_URL"],
timeout=120, max_retries=1)
def call_once(model, prompt, system="你是一个严谨的编程助手。",
max_tokens=1024, temperature=0.2):
t0 = time.perf_counter()
r = client.chat.completions.create(
model=model,
messages=[{"role": "system", "content": system},
{"role": "user", "content": prompt}],
temperature=temperature,
max_tokens=max_tokens,
)
elapsed = time.perf_counter() - t0
usage = r.usage
return {
"text": r.choices[0].message.content,
"finish_reason": r.choices[0].finish_reason,
"total_s": round(elapsed, 3),
"in_tok": getattr(usage, "prompt_tokens", 0) if usage else 0,
"out_tok": getattr(usage, "completion_tokens", 0) if usage else 0,
}
def call_stream(model, prompt, system="你是一个严谨的编程助手。",
max_tokens=1024, temperature=0.2):
t0 = time.perf_counter()
first_at, parts = None, []
stream = client.chat.completions.create(
model=model,
messages=[{"role": "system", "content": system},
{"role": "user", "content": prompt}],
temperature=temperature, max_tokens=max_tokens, stream=True,
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
piece = getattr(delta, "content", None)
if piece:
if first_at is None:
first_at = time.perf_counter() - t0
parts.append(piece)
return {
"text": "".join(parts),
"ttft_s": round(first_at, 3) if first_at else None,
"total_s": round(time.perf_counter() - t0, 3),
}
```
finish_reason 一定要记录：如果结果是 length，说明答案被 max_tokens 截断了，这条数据不能用来评价模型质量，只能说明你预算给少了。
步骤 4：把 token 换算成钱
公式本身只有一行，坑都在单位上：
```
单次成本 = 输入token / 1e6 × 输入单价(每百万token)
+ 输出token / 1e6 × 输出单价(每百万token)
```
```python
单价从环境变量读，避免把可能过期的数字写死在代码里
PRICES = { # 单位：元 / 百万 token
os.environ["MM_MODEL"]: {
"in": float(os.environ["MM_PRICE_IN"]),
"out": float(os.environ["MM_PRICE_OUT"]),
},
os.environ["ALT_MODEL"]: {
"in": float(os.environ["ALT_PRICE_IN"]),
"out": float(os.environ["ALT_PRICE_OUT"]),
},
}
def cost(model, in_tok, out_tok):
p = PRICES[model]
return in_tok / 1e6 * p["in"] + out_tok / 1e6 * p["out"]
```
两个常见误区：一是很多厂商的输出单价明显高于输入单价，所以长输出的任务成本差距会被放大；二是部分平台提供上下文缓存、批处理的折扣，但触发条件和计费口径各不相同，别默认自己的请求能吃到折扣，规则以官方定价页为准。
步骤 5：设计三个真实的编码任务
别用「写个快速排序」这种题，它区分不出 Flash 档模型的差距。用下面三个更贴近日常工作的任务，每个任务都给了可复制的 prompt 模板。
任务 A：单文件重构（考察约束遵守）
把一段命名混乱、没有类型注解的 Python 函数贴进去：
```
下面这段 Python 函数逻辑是对的，但命名混乱、没有类型注解。
请在不改变任何行为的前提下重构：重命名变量、加类型注解、拆分超过 20 行的分支。
只输出完整的重构后代码，不要解释，不要引入新的第三方依赖。
```python
<粘贴你的函数>
```
```
判定标准：代码能不能直接跑通、行为是否等价、有没有偷偷引入新依赖（这是模型最爱犯的错）。
任务 B：补单元测试（考察边界意识）
```
下面是一个 Python 函数。请用 pytest 写一组单元测试，必须覆盖：
空输入、None、超大数值、类型错误输入、正常路径。
只输出测试文件内容，不要 mock 掉被测函数本身。
```python
<粘贴你的函数>
```
```
判定标准：测试能不能一次跑过、边界是否真覆盖到、有没有写出根本不存在的 API。
任务 C：跨文件定位 bug（考察长上下文与推理）
把两三个相关文件的片段和报错栈一起给：
```
这是三个文件的代码片段和运行时的报错栈。请指出根因（哪一行、为什么），
并给出最小改动的 patch（unified diff 格式）。不要重写整个文件。
报错栈：
<粘贴 traceback>
文件 1：<代码>
文件 2：<代码>
```
判定标准：根因判断对不对、patch 能不能直接 git apply、改动行数是否克制。
步骤 6：跑对照实验，填表
同一份脚本，只换模型名。控制变量：temperature、max_tokens、system prompt、user prompt 全部逐字相同；每个任务跑 3 次，取中位数，别用单次结果下结论。
```python
import json
results = []
for task_name, prompt in TASKS.items():
for model in [os.environ["MM_MODEL"], os.environ["ALT_MODEL"]]:
for i in range(3):
out = call_once(model, prompt, max_tokens=2048)
results.append({
"task": task_name, "model": model, "run": i,
"total_s": out["total_s"],
"in_tok": out["in_tok"], "out_tok": out["out_tok"],
"cost": round(cost(model, out["in_tok"], out["out_tok"]), 6),
"truncated": out["finish_reason"] == "length",
})
print(json.dumps(results, ensure_ascii=False, indent=2))
```
结果整理成一张表，长这样：
| 任务 | 模型 | 首 token (s) | 总时长 (s) | 输入 token | 输出 token | 单次成本 | 一次跑通 | 需人工改 |
|---|---|---|---|---|---|---|---|---|
| A 重构 | M3.1 Flash | |||||||
| A 重构 | 对照 Flash | |||||||
| B 测试 | M3.1 Flash |
「一次跑通」和「需人工改」这两列最重要，它们决定你每天要花多少时间返工，往往比单价差的那点钱影响大得多。
步骤 7：怎么读结果，怎么选型
延迟分两种场景看。 聊天式交互、IDE 补全这类场景，用户感知的是首 token 延迟，看流式数据；批量生成文档、离线跑测试这类场景，看总时长和吞吐。别拿非流式的总时长去评判交互体验。
成本要和重试率一起算。 真实成本 ≈ 单次成本 ×（1 + 重试率）。一个便宜但经常输出被截断、需要重问的模型，实际花费可能更高。
质量看「能不能直接用」。 编码任务的评价标准是 diff 能不能提交，不是文字写得漂不漂亮。
据此给出选型建议：
- 改错别字、格式化、写注释、简单补全：用最小最快的档位就够，别为这类任务付高价。
- 单文件重构、补单元测试、解释报错栈：Flash 档模型（M3.1 Flash 属于这一档）是甜点区，延迟和成本都可控，质量通常够用。
- 跨多个文件重构、架构设计、超长上下文代码库问答：直接上更高一档的模型，省下的返工时间远超差价。
- 高并发批量任务：先做限流压测，确认并发配额和降级策略，再谈单价。配额打满时的排队时间也是成本。
- 对延迟极敏感的场景：优先看首 token 延迟和流式体验，而不是模型榜单分数。
三、常见坑与排错
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 401 / 鉴权失败 | Key 复制时带了空格或引号；环境变量没在当前 shell 生效 | 重新 export，用 echo $MM_API_KEY 确认非空 |
| 404 model not found | 模型标识拼错，或该模型未开通 | 从控制台模型列表原样复制，注意大小写 |
| 400 参数错误 | max_tokens 超过模型上限；messages 结构不合法 | 先把 max_tokens 调小验证通路 |
| 请求超时 | 网络问题或输出过长 | 设 timeout，配 max_retries；注意重试会重复计费 |
| 结果被截断 | finish_reason == "length" | 提高 max_tokens，或要求模型精简输出 |
| 流式拼接内容乱 | 只取了 content，忽略了推理内容字段或 finish_reason | 按文档确认字段含义后再拼接 |
| 成本算出来差 1000 倍 | 混淆「每千 token」和「每百万 token」 | 统一换算到每百万 token 再算 |
| 评测结论站不住 | 温度不同、prompt 不同、只跑一次 | 固定变量，多次取中位数 |
| Key 泄露 | 提交到了 Git 仓库 | 立即在控制台吊销重建，改用 .env |
四、下一步建议
1. 把这套脚本变成常驻的回归测试：模型会更新，价格会调整，把三个编码任务固化成每周跑一次的脚本，记录趋势，比看一次榜单有用。
2. 加一层路由：简单的分类、抽取、格式化走小模型，复杂推理走大模型，用代码里的 if/else 或轻量规则判断，成本能降下来一截。
3. 做灰度而不是一刀切：新模型先接 10% 流量，对比人工返工率和用户反馈，再决定是否全量。
4. 准备降级方案：主模型限流或超时时自动切到备用模型，接口层面做好封装，别让业务代码直接调 SDK。
5. 定期回看官方定价页和模型列表：本文所有价格、模型标识都留了占位符，就是为了让你能从官方文档当前版本重新抄一遍，而不是照抄一篇可能已经过期的教程。