企业官网建设流程全解析

Hy3-oQ2是 Hy3（Hunyuan 3.0，295B-A21B MoE）面向 Apple Silicon 的 MLX 校准 2-bit 量化版：磁盘占用 92 GB、推理峰值内存 99 GB。这篇文章讲清楚 Hy3-oQ2 的内存调优完整策略——如何把一个 BF16 下高达 556 GB 的 MoE 大模型压进 128 GB 统一内存，并稳稳落在 Metal 默认工作集上限之内。

1️⃣ 调优背景：556GB 模型 vs 128GB 的 Metal 工作集上限

在动手之前，先理解两个硬约束：

• 模型太大：Hy3 在 BF16 精度下是 556 GB，单台 128 GB 的 Mac 根本装不下原始权重，必须做 2-bit 级别的激进量化。
• Metal 工作集上限：Apple Silicon 的 GPU 显存（wired memory）默认有上限，128 GB 机器上约为107.5 GB。一旦 GPU 占用超限，会触发 Metal command-buffer watchdog，直接报GPU Timeout。

💡 所以 Hy3-oQ2 的调优目标非常明确：让峰值内存 < 107.5 GB 的默认上限，不依赖任何系统参数修改，同时给 KV cache 留出长上下文空间。

2️⃣ 关键数字：99GB 峰值 vs 107.5GB 上限

作者实际测试中，量化路径上的两个版本对比如下（数据来自 README.md 的 Memory 一节）：

结论一目了然：oQ2 用更少的比特（2.7 vs 3.15 bpw）拿到了更低 17 GB 的峰值内存，还额外更抗难样本。这就是"从 99GB 峰值到 Metal 工作集上限"这一策略的核心成果。

3️⃣ oQ2 校准量化是如何炼成的：两步走策略

直接对 556 GB 的 BF16 模型做校准量化会失败，原因有两个：

1. oQ 需要整模型驻留内存来测量各层敏感度——128 GB 机器装不下 556 GB；
2. omlx 的自动 4-bit 敏感度代理需要约 150 GB GPU 内存，直接冲爆 Metal 默认工作集上限，触发 watchdog 超时。

作者走通了"两步走"路线（详见 README.md 的 How it was quantized 一节）：

• 第一步：造中间版mixed_2_6。用mlx_lm.convert做均匀启发式混合量化（2-bit 打底 + 固定结构层集合用 6-bit）。它体积 108 GB、峰值 116 GB，需要调高 Metal 上限才能跑，且在难样本上表现不均衡——但它能装进内存。
• 第二步：以它为"敏感度模型"做 oQ2 校准。把mixed_2_6作为sensitivity_model_path传给 oQ：oQ 跳过会失败的自动代理，在中间版上测量敏感度（按推理方式运行，不触发 watchdog），然后逐张量流式产出最终量化权重。

最终产物 oQ2 是"数据驱动的混合精度"：每个张量分多少 bit，由实测敏感度图决定，而不是死规则。

4️⃣ 数据驱动混合精度：2-bit 打底 + 8-bit 敏感层

量化方案完整记录在 config.json 的quantization段中：

• 基准配置：bits: 2、group_size: 64、mode: affine；
• 数十个敏感张量被单独标为 8-bit，集中在：注意力的q_proj/k_proj/v_proj/o_proj（如 config.json 的 14~17 层o_proj）、各层shared_mlp的gate/up/down_proj，以及lm_head。

这种分配方式的实际收益，作者用一道算术推理做了"冒烟测试"：

模型结构方面，可参考 config.json：80 层、192 个专家、每 token 激活 8 个（即 A21B），张量分布全景见 model.safetensors.index.json。

5️⃣ 长上下文 KV Cache 预算：为什么强烈推荐 TurboQuant KV

Hy3 支持max_position_embeddings达 262144（262K）。KV cache 按 config.json 的 GQA 配置（8 个 KV 头 × 128 维 × 80 层）估算，每个 token 约 320 KiB（BF16）：

99 GB 模型峰值贴着 107.5 GB 上限，长上下文的 KV 空间非常紧张。README 给出的官方建议是：尽量开启 TurboQuant KV（作者实测 3-bit 下性能良好），这是长文本场景下最划算的一档内存调优手段。

6️⃣ Hy3-oQ2 内存调优实战清单 📋

1. 优先选 oQ2 而非均匀 2-bit：校准版 2.7 bpw 更省内存、更难"崩"（见上文对比表）。
2. 默认不用改 Metal 上限：99 GB < 107.5 GB，开箱即用；只有自行制作中间量化版（如 108 GB 的 mixed_2_6，峰值 116 GB）时，才需要临时调高sysctl iogpu.wired_limit_mb。
3. 长上下文必开 TurboQuant KV（建议 3-bit），把 KV 预算压下来。
4. 加载后做冒烟测试：跑一道算术推理题，检查逐步推理是否完整、有无重复循环。
5. 运行环境注意：hy_v3架构尚未进入 mlx-lm 正式发行版，需按 README.md 的 Requirements 一节安装 PR 分支的 dev 版 mlx-lm，否则模型无法加载。

最小运行命令（详见 README 的 Usage 一节）：

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

采样参数默认值参考 generation_config.json（temperature: 0.9、top_p: 1）。

7️⃣ 性能与质量数据

性能（MacBook Pro M5 Max 128GB 40 GPU，短 prompt）：

• 生成速度33.6 tok/s，prompt 处理5.05 tok/s，峰值99 GB

质量（oMLX 智能套件，300 条种子样本，与 oQ2e 系列同题对比）：

⚠️ 注意：README 强调这是种子样本抽样、并非完整 benchmark，分数差值应视为噪声——选型前建议用自己的工作负载实测。

一句话总结：Hy3-oQ2 的内存调优本质是"校准量化省基线 + 默认 Metal 上限不越界 + TurboQuant KV 管长尾"三板斧，让 295B 参数 MoE 在单台 128 GB Apple Silicon 上既跑得动、又跑得快。