Hy3-oQ2性能优化指南:M5 Max实测33.6 tok/s的调优参数清单
Hy3-oQ2性能优化指南:M5 Max实测33.6 tok/s的调优参数清单
想在 Mac 上全速跑 295B 参数的 Hy3(Hunyuan 3.0)MoE 大模型?这篇 Hy3-oQ2 性能优化指南以 M5 Max(128GB 统一内存)实测为准绳:生成速度 33.6 tok/s、峰值内存 99 GB。下面是一份可直接照做的调优参数清单。
⚡ 实测数据:33.6 tok/s 是怎么来的
在 MacBook Pro M5 Max(128GB 统一内存、40 核 GPU) 上的官方冒烟测试结果:
| 指标 | 实测值 |
|---|---|
| 生成速度 | 33.6 tok/s |
| Prompt 预填充速度 | 5.05 tok/s |
| 峰值内存 | 99 GB |
| 测试条件 | 短 Prompt |
数据来源:README.md 的 "Conversion check" 一节。
两个数字值得解释:
- 为什么生成快:Hy3 是 MoE(混合专家)架构——总参数 295B,每个 token 仅激活约 21B(295B-A21B)。每生成一个 token 实际只做约 21B 的矩阵运算,带宽压力小,33.6 tok/s 正是这种"稀疏计算"的体现。
- 为什么预填充只有 5 tok/s:Prefill 阶段一次性处理整个 Prompt,属于算力密集环节,对 295B 级 MoE 模型尤为明显。→ 调优策略:Prompt 尽量短。
✅ 环境准备清单:先跑稳,再谈优化
性能优化建立在"跑得起来"之上,三个最常见的坑:
- 统一内存 ≥ 128 GB:模型文件 92 GB(model.safetensors.index.json 中
total_size≈ 92 GB),运行峰值约 99 GB,再加 KV 缓存余量,128 GB 是起步线。 - mlx-lm 需支持
hy_v3架构:官方发布版尚未支持(社区 PR #1211 跟进中),需先安装包含该 PR 的构建版本;官方合入后可直接标准安装。详见 README.md。 - Metal 内存上限不用动:128 GB 机器的默认 Metal working-set 上限为 107.5 GB,99 GB 峰值完全容纳,无需修改
sysctl iogpu.wired_limit_mb。(对照:中间量化模型mixed_2_6峰值 116 GB,就必须提上限。)
🎛️ 调优参数清单:直接照抄
1. 模型变体:oQ2 最均衡
Hy3-oQ2 是 oQ2 校准式 2-bit 量化版:数据驱动的混合精度,按实测敏感度图为每个张量分配位宽,等效 2.7 bits/weight。敏感层(lm_head、部分注意力投影、共享 MLP)保留 8-bit,在 config.json 的 quantization 字段中可见。
相比更小的 oQ2e 系列变体,oQ2 体积略大但质量更稳:
| Benchmark(300 样本) | oQ2 · 2.68 bpw(本模型) | oQ2e · 2.43 bpw | oQ2e · 2.31 bpw |
|---|---|---|---|
| mathqa | 0.63 | 0.65 | 0.60 |
| mmlu_pro | 0.65 | 0.61 | 0.55 |
| winogrande | 0.74 | 0.68 | 0.65 |
以上为种子样本结果,差异应视为噪声;选型前建议用自己的负载实测。数据源:README.md。
选择建议:内存允许优先 oQ2;只有内存余量极度紧张时才考虑 oQ2e。
2. 采样与生成参数
generation_config.json 的默认采样参数为 do_sample: true、temperature: 0.9、top_p: 1。按使用场景调整:
| 参数 | 默认值 | 推荐值 | 作用 |
|---|---|---|---|
temperature |
0.9 | 任务型 0.6~0.8 | 输出更确定、更易按预期收尾 |
--max-tokens |
不限 | 300 | 限制输出长度,控制单次生成耗时 |
--prompt |
— | 尽量短 | 预填充仅 5.05 tok/s,Prompt 每多一个 token 都在烧时间 |
3. reasoning_effort:最大的提速杠杆
对话模板 chat_template.jinja 支持三档推理强度,默认 no_think:
no_think— 不输出思考过程,速度最快low— 轻度思考high— 深度思考,回答更完整但输出 token 大幅增加
只取答案的场景保持 no_think;思考 token 计入生成时长,直接影响体感速度。这是 295B 级 MoE 模型上最容易被忽视、却最影响吞吐的"参数"。
💾 内存优化:长上下文别超 107.5 GB
99 GB 峰值已包含模型运行与短上下文 KV 缓存。长上下文时 KV 余量非常紧,作者强烈建议启用 TurboQuant KV(3-bit 实测效果好):压缩 KV 缓存、保住长上下文内存,同时维持质量。
128 GB 机器的内存预算参考:
- 模型权重驻留:约 92 GB
- 运行时峰值(短上下文):约 99 GB
- 默认 Metal 上限:107.5 GB
- 结论:短上下文安全;长上下文务必开启 KV 压缩
🔍 30 秒自检:部署是否健康
跑一次官方冒烟测试。健康的 oQ2 应输出连贯、不陷入重复循环(纯 2-bit 与 2-bit+8-bit-router 量化在该项上均崩溃,校准版 oQ2 通过):
python -m mlx_lm generate --model mlx-community/Hy3-oQ2 \
--prompt "Explain Bayes' theorem in two sentences." --max-tokens 300
再追问一步 17 * 24 = ? 的逐步推理,确认中间步骤无幻觉,即可放心投入使用。
📌 总结:一张表带走
| 目标 | 关键参数 |
|---|---|
| 稳定跑起来 | 128 GB 统一内存 + 支持 hy_v3 的 mlx-lm |
| 输出更快 | 短 Prompt + no_think + 限制 --max-tokens |
| 长上下文 | 启用 TurboQuant KV(3-bit) |
| 系统层 | 默认 Metal 上限够用,无需改 sysctl |
| 质量兜底 | 冒烟测试 + 300 样本基准,见 README.md |
用这份清单,你可以在 M5 Max 上稳定复现 33.6 tok/s。对 2-bit 量化模型而言,性能优化的关键不是"压榨速度",而是守住内存上限、砍掉不必要的思考 token——这正是本次 Hy3-oQ2 性能优化指南的核心结论。