从零复现 MiniCPM-V-4.7-35B-A3B-5bit:mlx_vlm.convert 量化转换全流程与权重校验详解
从零复现 MiniCPM-V-4.7-35B-A3B-5bit:mlx_vlm.convert 量化转换全流程与权重校验详解
MiniCPM-V-4.7-35B-A3B-5bit 是基于 MLX 框架对开源视觉语言 MoE 模型 MiniCPM-V 4.7(总参数 35B / 激活 3B)做 5bit 量化转换的版本。本文带你用 mlx_vlm.convert 一步步走完量化转换全流程,并详解 SHA-256 哈希与冒烟测试两级权重校验,即使你是新手,也能看懂一个量化模型是如何「生」出来的。
🎯 模型速览:MiniCPM-V-4.7-35B-A3B-5bit 是什么
| 项目 | 说明 |
|---|---|
| 基础模型 | openbmb/MiniCPM-V-4.7-35B-A3B(apache-2.0 许可) |
| MoE 结构 | 每层 256 个专家,每个 token 激活 8 个(A3B = Active 3B) |
| 层数与注意力 | 40 层,每 4 层 1 次 full_attention,其余为 linear_attention |
| 上下文长度 | 最长 256K token |
| 视觉编码器 | 27 层 ViT,patch_size 14,视觉特征注入语言模型第 6 层 |
| 量化方案 | 5bit affine(group_size=64);专家路由 8bit;视觉/嵌入层保持 BF16 |
| 权重大小 | 6 个 safetensors 分片,合计约 25.7 GiB |
有一个关键点要理解:5bit 不等于全模型每个参数都是 5bit。这次转换采用的是「混合精度」策略:
- 5bit affine:MoE 主体中 280 个核心线性层(专家权重、shared_expert 等)
- 8bit affine:80 个专家路由模块(各层
mlp.gate与mlp.shared_expert_gate)——路由负责决定激活哪些专家,对量化误差最敏感,因此单独提高到 8bit - 保持 BF16:视觉编码器、visual merger、token 嵌入、输出头(lm_head)、线性注意力投影等,这些模块体量大而准,保持全精度几乎不增加体积,却显著稳定图像理解效果
- A_log 张量:线性注意力的 30 个循环状态张量保留源精度(bfloat16),不做量化
上述分布可以直接在 config.json 的 quantization 字段里逐条核对——40 层中每一层的 mlp.gate、mlp.shared_expert_gate 都被单独写成了 "bits": 8。
📦 第一步:环境准备与源模型版本锁定
转换前必须确定两件事,这是「可复现」的核心:
- 安装 MLX-VLM:安装支持 MiniCPM-V 4.7 的版本。若要精确复现本仓库的权重,建议锁定官方转换所用的提交
e928101a144a3f11a27c7ef8d71b6d889b2d250c(版本 0.7.8),转换器版本不同,产出的量化权重也可能不同。 - 锁定源模型 revision:源模型
openbmb/MiniCPM-V-4.7-35B-A3B固定在 revision17e651151c161dce119cd0ac57570f60da8a0b40。即使源模型日后更新,你拿到的也是完全相同的输入权重。
这两条信息都记录在仓库根目录的 conversion.json 里,随时可查。
🛠️ 第二步:mlx_vlm.convert 量化转换命令拆解
完整的复现命令只有一行:
mlx_vlm.convert --hf-path openbmb/MiniCPM-V-4.7-35B-A3B --revision 17e651151c161dce119cd0ac57570f60da8a0b40 --mlx-path MiniCPM-V-4.7-35B-A3B-5bit --dtype bfloat16 -q --q-bits 5 --q-group-size 64 --q-mode affine
参数逐个理解:
| 参数 | 本文示例取值 | 作用 |
|---|---|---|
--hf-path |
openbmb/MiniCPM-V-4.7-35B-A3B | 待转换的源模型 |
--revision |
17e6511… | 锁定源模型版本,保证可复现 |
--mlx-path |
MiniCPM-V-4.7-35B-A3B-5bit | 转换结果的输出目录 |
--dtype |
bfloat16 | 非量化部分的精度基准 |
-q |
— | 开启量化开关 |
--q-bits |
5 | 量化位宽 |
--q-group-size |
64 | 每 64 个权重为一组,共享一组 scale/zero-point |
--q-mode |
affine | 采用 affine(线性仿射)量化方式 |
一句话概括:下载源模型 → 按模型架构自动套用混合精度规则 → 5bit 分组仿射量化 → 输出为 MLX 格式的 safetensors 分片。8bit 路由与 BF16 豁免规则由转换器按架构自动应用,无需手动配置。
🗂️ 第三步:核对转换产物
转换完成后,输出目录的结构应与本仓库一致:
- model-00001-of-00006.safetensors ~ model-00006-of-00006.safetensors:6 个权重分片
- model.safetensors.index.json:权重索引,把全部 1912 个张量映射到对应分片,
total_size为 27,604,452,448 字节(约 25.7 GiB) - config.json:模型结构 + 混合精度的
quantization/quantization_config配置 - conversion.json:转换参数、源模型 revision、各分片 SHA-256 的完整记录
- generation_config.json、processor_config.json、preprocessor_config.json、chat_template.jinja、tokenizer.json:推理与分词相关配置
🔍 一个有用的自查技巧:量化后的线性层会生成 .weight(整型权重)、.biases、.scales 三组张量。本仓库索引中恰好有 360 个 .scales 条目,与 280(5bit)+ 80(8bit)= 360 个量化模块一一对应——你复现转换后可以用同样的方法交叉验证。
✅ 第四步:权重校验详解
SHA-256 完整性校验
conversion.json 的 weight_files 字段记录了 6 个分片的大小与 sha256 哈希。下载权重后,本地执行 sha256sum 逐一比对:
| 分片 | 字节数 | SHA-256(前 8 位) |
|---|---|---|
| model-00001-of-00006 | 5,359,547,904 | e7e00c26 |
| model-00002-of-00006 | 5,332,445,072 | aada4a44 |
| model-00003-of-00006 | 5,283,753,400 | d7bc749a |
| model-00004-of-00006 | 5,262,274,932 | 65478d19 |
| model-00005-of-00006 | 5,079,895,813 | 9c806a3b |
| model-00006-of-00006 | 1,286,787,801 | 92003f3d |
哈希一致即说明文件传输未损坏、未被篡改——这是权重校验的第一道关卡。
运行时冒烟测试
仓库的 validation.json 记录了官方校验结果,"status": "passed",共 4 项:
- strict checkpoint reload:严格重载检查点,确保没有缺失或多余的权重
- quantization configuration check:核对落盘的 5bit / 8bit / BF16 混合精度与配置一致
- 贪心文本生成:提问 “What is 2 + 2?”,模型只输出
4 - 图像理解:在
16x与4x两种视觉下采样模式下描述一张双猫图片,输出如 “Two tabby cats are sleeping on a bright pink couch…”
校验环境为 JarvisLabs RTX PRO 6000 Blackwell(cuda)+ MLX 0.32.3。注意:仓库明确说明这些是 smoke checks(冒烟测试),只用于确认模型「可加载、可运行」,并非质量基准测试。
🚀 转换之后:快速跑通推理
mlx_vlm.generate --model mlx-community/MiniCPM-V-4.7-35B-A3B-5bit --image path/to/image.jpg --prompt "Describe this image." --max-tokens 200 --temperature 0
内置的 NumPy/Pillow 处理器不依赖 PyTorch 和远程代码,支持文本、单图、多图与视频输入。默认视觉下采样为 16x(更快);需要更精细的细节时,追加参数即可:
--processor-kwargs '{"downsample_mode": "4x"}'
❓ 常见问题
为什么 A_log 保留 bfloat16?
A_log 是线性注意力的循环状态张量,长序列推理中会反复参与状态递推,量化误差容易累积。转换器特意不对它量化,validation.json 的 A_log_dtypes 确认全部 30 个 A_log 张量均为 mlx.core.bfloat16。
为什么路由层用 8bit 而不是 5bit? 专家路由的输出是「选哪个专家」的离散决策,对数值误差极其敏感。5bit 的舍入噪声可能导致选错专家、放大理解错误,8bit 能在几乎不增加体积的情况下保住路由精度。
16x 与 4x 下采样怎么选?
16x 压缩率高,推理更快、显存占用更低;4x 保留更多图像细节,适合需要识别小字、细碎结构的场景。
📎 参考资料
| 文件 | 用途 |
|---|---|
| README.md | 模型卡:使用方式与复现命令 |
| conversion.json | 转换参数、源模型 revision、各分片 SHA-256 |
| validation.json | 校验项、测试输出与环境信息 |
| config.json | 模型结构与混合精度量化配置 |
| model.safetensors.index.json | 张量 → 分片的映射索引 |