Hy3-oQ2是腾讯混元 Hy3（295B MoE）大模型的MLX oQ 校准量化版本：以2.7 bits/weight的有效精度，把原本约 556 GB 的 BF16 模型压缩到约92 GB，可在 128 GB 的 Apple Silicon Mac 上本地运行。本文带你读懂这份模型卡：什么是 oQ 校准量化、2.7 bits/weight 是怎么算出来的，以及如何快速上手。

先记住这组核心数字：

一、Hy3-oQ2 是什么？先认识这份模型包里有什么

Hy3（Hunyuan 3.0）是腾讯的超大 MoE（混合专家）模型：总参数 295B，每 token 激活约 21B。它的结构特点是（可对照 config.json 查看）：

• 80 层 Transformer，隐层维度 4096，支持 262,144 token 长上下文；
• 每层 192 个专家，每个 token 只路由激活 8 个专家 + 1 个共享专家（见 config.json），所以"大参数、低激活"；
• 架构类型为hy_v3，许可证 Apache-2.0（继承自基座模型）。

本仓库则是它的MLX 量化版本，文件组成很清爽：

二、什么是 oQ 校准量化？从"一刀切"到"按需分配"

🧠先打个比方：量化就像给模型做"无损瘦身"——每个权重保留的比特数越少，文件越小，但信息丢失越多。

固定规则量化（一刀切）：所有权重统一用 2 bit。问题是模型里"重要的"和"不太重要的"张量被同等对待。模型卡的验证结果很直接：纯 2-bit、以及 2-bit+8-bit 路由的均匀量化版，在"17×24 等于多少"这种简单推理上都会陷入重复循环、答案崩坏，而校准后的 oQ2 能一步步算出正确答案（详见 README.md）。

oQ 校准量化的核心是"数据驱动的混合精度"：

1. 先测量：用真实数据跑一遍，测量每个张量对量化误差的敏感度，得到一张敏感度地图；
2. 再分配：按测量结果逐张量决定位宽——不敏感的降到 2 bit，敏感的保留 8 bit，而不是靠固定规则猜测。

这张"分配结果"就写在 config.json 里：全局默认2 bit、group_size 64、affine 模式，同时有562 个张量被单独提升为 8 bit，包括全部层的shared_mlp（共享专家）、大量注意力层的q/k/v/o_proj、lm_head、embed_tokens和第 0 层的稠密 MLP 等。

💡 一句话总结：oQ 校准量化 = 用数据测出哪些权重"输不起"，把宝贵的 8 bit 预算精准花在这些张量上。

三、2.7 bits/weight 是怎么算出来的？

bits/weight（bpw，每权重比特数）= 所有权重的总比特数 ÷ 总权重数，代表"平均每个权重保留多少位信息"。

Hy3-oQ2 的构成是：

• 绝大多数张量 2 bit（约 2300 个张量，主要是 192 个专家的主体权重）；
• 约 19.5% 的张量 8 bit（562/2876，见 config.json 的覆盖列表）。

按权重规模加权平均后，有效精度约为2.7 bits/weight。用它反推磁盘大小：2950 亿参数 × 2.7 bit ≈ 99.6 GB，与索引文件记录的总大小 98,817,602,182 字节（≈92 GiB）完全吻合。

对比一下压缩比：BF16 是 16 bits/weight，2.7 bits 意味着体积只有原来的约 1/6——这正是 295B 模型能"住进" 128 GB Mac 的原因。

四、量化是怎么做出来的？两步走的工程细节 🛠️

超大模型的量化本身也是个工程难题：556 GB 的 BF16 模型比 128 GB 机器的内存还大，oQ 没法把完整模型装进内存去测敏感度；而 omlx 默认的 4-bit 敏感度代理（约 150 GB）又会撑爆 Metal 的默认工作集上限，触发GPU Timeout看门狗。

最终采用的方案是两步（完整过程见 README.md）：

1. 中间产物mixed_2_6：先用mlx_lm.convert做一个"2 bit 打底 + 固定结构层 6 bit"的启发式混合量化（3.15 bpw，108 GB，峰值 116 GB，偏重且不够稳）；
2. oQ2 校准：把这个更小的mixed_2_6作为sensitivity_model_path传入 oQ——它装得进内存、以推理方式运行、不会触发看门狗。oQ 在它上面测出敏感度后，再逐张量流式产出最终量化结果。

结果：oQ2 比mixed_2_6更抗崩、内存占用还更低（峰值 99 GB vs 116 GB）。

五、内存与速度：我的 Mac 能跑吗？

⚡ 结论先行：推荐 128 GB 统一内存的 Apple Silicon 机型（如 M 系列 Max 芯片 128 GB）。

• 峰值内存99 GB，低于 128 GB 机器的默认 Metal 工作集上限（107.5 GB），不需要手动调sysctl iogpu.wired_limit_mb；
• 在 Macbook Pro M5 Max 128GB（40 GPU 核心）上实测：生成 33.6 tok/s，prompt 处理 5.05 tok/s，峰值 99 GB（短 prompt）；
• ⚠️ 长上下文时 KV cache 余量偏紧，模型卡强烈建议开启 3-bit 的 TurboQuant KV来省内存；
• 64 GB / 96 GB 机型：光磁盘就 92 GB，加 KV cache 后放不下，不建议。

六、基准对比：压到 2.7 bpw 值不值？📊

作者用 oMLX 智能测试套件（每个基准 300 条固定种子样本）对比了同系列的几个量化版本：

可以看到：bpw 越低分数掉得越多，2.68 bpw 的 oQ2 在三项中至少并列最优。注意作者在 README.md 中特意说明：这只是固定种子的抽样测试，不是完整基准，选型前建议用自己的真实任务实测。

七、快速上手：三步在 Mac 上跑起 Hy3-oQ2

第 1 步：安装支持hy_v3架构的 mlx-lm。官方 mlx-lm 尚未支持该架构（有一个待合并的 PR：mlx-lm#1211），在此之前需按 README.md 的说明从 PR 分支安装，否则模型无法加载；待 PR 合入发布版后即可直接安装。

第 2 步：命令行生成文本。

python -m mlx_lm generate --model mlx-community/Hy3-oQ2 \ --prompt "Explain Bayes' theorem in two sentences." --max-tokens 300

第 3 步（可选）：Python API 加载。

from mlx_lm import load, generate model, tokenizer = load("mlx-community/Hy3-oQ2")

生成参数遵循 generation_config.json：do_sample: true、temperature: 0.9、top_p: 1。

八、常见问题 FAQ

Q：2.7 bits/weight 和纯 2-bit 差在哪？纯 2-bit 是"一刀切"，敏感张量被压得太狠会直接崩坏（重复循环、算不对简单乘法）；oQ2 把约 19.5% 的关键张量保留 8 bit，多花 0.7 bpw 换来"能用且稳定"，代价只是多几十 GB 磁盘。

Q：为什么需要 128 GB 内存？权重 92 GB + KV cache + 运行开销，实测峰值 99 GB。KV cache 随上下文长度增长，128 GB 是最小舒适线。

Q：想自己量化 Hy3 行不行？可以，但注意第四节的大坑：直接对 556 GB 原模型做 oQ 会撑爆内存和 Metal 看门狗，需要先做一个能装进内存的中间量化版当敏感度代理。

九、写在最后

Hy3-oQ2 展示了 2026 年本地大模型的一条清晰路线：MoE 大参数 + 校准量化 + Apple Silicon 统一内存，让 295B 级模型在消费级顶配 Mac 上以 33 tok/s 的速度可用。理解 "oQ 校准"（测敏感度 → 按张量分配位宽）和 "2.7 bits/weight"（混合精度的加权平均、约 1/6 压缩比）这两个概念，你就能读懂大部分低比特量化模型卡了。