128GB Mac内存够不够：Hy3-oQ2部署前的硬件要求与准备工作清单

Hy3-oQ2 是腾讯 Hunyuan 3.0（295B-A21B MoE 大模型）的 2-bit MLX 校准量化版本，专为 Apple Silicon 打造。本文给出部署 Hy3-oQ2 前的硬件要求与准备工作清单，帮你快速判断 128GB Mac 内存够不够，并避开加载失败、GPU Timeout 等常见坑。

一、先说结论：128GB 够，但属于"紧凑够用"

✅结论：128GB 统一内存的 Mac 可以运行 Hy3-oQ2，无需手动调系统参数。

关键数据（来自 README.md）：

💡 官方实测机型为MacBook Pro M5 Max 128GB（40 GPU core）：生成速度 33.6 tok/s，提示词处理 5.05 tok/s，峰值 99 GB。

需要特别注意的一点：KV cache 余量偏紧。如果计划跑长上下文，强烈建议开启TurboQuant KV（3-bit），作者在该项目中验证了开启后性能良好。

二、硬件要求清单：逐项核对再动手

⚠️为什么是 128GB 而不是更少？Hy3 原版 BF16 权重高达 556 GB，远超 128GB 内存，所以必须使用量化版本；而 oQ2 的 99 GB 峰值恰好压在 128GB 机型的默认 Metal 上限之下，这是它能"免调参"跑起来的根本原因。

对比参考：早期中间版本mixed_2_6峰值高达 116 GB，必须用sysctl iogpu.wired_limit_mb抬高上限才能运行——oQ2 版本则不需要任何 sysctl 调整。

三、软件环境准备：3 步搞定

1. 安装 Python 与 uv

推荐使用uv管理 Python 环境（若未安装可先装 uv，再用它创建虚拟环境并激活）。

2. 安装支持 hy_v3 架构的 mlx-lm（关键步骤！）

这是新手最容易卡住的一步：官方已发布的 mlx-lm 尚不支持hy_v3架构，直接用最新版加载会失败。

模型架构定义见 config.json（architectures: HYV3ForCausalLM、model_type: hy_v3）。当前必须从支持 Hy3 的 PR 分支安装 mlx-lm，具体安装命令以 README.md 的 Requirements 一节为准（该 PR 合并进正式版后可改用标准安装）。

3. 下载模型文件

模型权重为 19 个分片（model-00001-of-00019.safetensors ~ model-00019-of-00019.safetensors），权重索引与分片映射见 model.safetensors.index.json。

下载完成后，本地目录应包含以下核心文件：

• 配置文件：config.json、generation_config.json
• 分词器：tokenizer.json、tokenizer_config.json
• 对话模板：chat_template.jinja
• 19 个权重分片 + model.safetensors.index.json

四、首次运行验证：一条命令测通

环境就绪后，执行冒烟测试命令（与 README 一致）：

python -m mlx_lm generate --model <模型路径> --prompt "Explain Bayes' theorem in two sentences." --max-tokens 300

✅合格的标准（来自官方 smoke test）：

• 输出连贯、无复读循环
• 能完成17 * 24 = 408这类分步推理题

作者对比测试发现：普通 2-bit 和 2-bit+8-bit-router 均匀量化在这道推理题上会"崩坏"，而校准版 oQ2 输出稳定——这也是"数据驱动混合精度"（按张量敏感度分配比特数）的价值所在。

五、能力速览：这个模型能干什么

• 架构规模：80 层、192 个专家、每 token 激活 8 个（MoE），词表 120,832，详见 config.json
• 上下文长度：max_position_embeddings为 262,144（256K），但如前所述，长上下文场景建议开启 TurboQuant KV
• 对话与工具调用：chat_template.jinja 内置思考模式（<think>）、工具调用（<tool_calls>）等占位符，支持 function calling 工作流
• 基准表现（300 样本，参考 README.md）：mathqa 0.63 / mmlu_pro 0.65 / winogrande 0.74

六、常见问题排查

七、出发前最终清单

• 确认机型为 Apple Silicon + 128GB 统一内存
• 磁盘预留 ≥ 100 GB
• 已用uv建好 Python 环境
• 已安装支持 hy_v3 的 PR 分支版mlx-lm
• 19 个权重分片 + 配置文件完整落地
• 冒烟测试通过（输出连贯、推理题正确）
• 长上下文场景已规划开启 TurboQuant KV

🎯 按这份清单逐项打钩，你的 128GB Mac 就能稳定跑起 Hy3-oQ2 这枚 295B 量级的 MoE 大模型了。