MiniCPM-V-4.7-35B-A3B-mxfp4配置文件详解:config.json与量化配置关键参数完全参考
MiniCPM-V-4.7-35B-A3B-mxfp4配置文件详解:config.json与量化配置关键参数完全参考
MiniCPM-V-4.7-35B-A3B-mxfp4 是开源多模态大模型 MiniCPM-V 4.7 的 MXFP4 量化 MLX 版本。本文逐条拆解 config.json 与 conversion.json 中的关键参数,帮助新手快速看懂 MoE 架构、MXFP4 量化配置、8-bit 例外模块和生成参数,让你一次性读懂量化配置并快速跑通模型 🚀
一、30秒认识MiniCPM-V-4.7-35B-A3B-mxfp4
📦 该仓库是由 mlx-community 基于 openbmb/MiniCPM-V-4.7-35B-A3B 转换而来的 MLX 格式量化模型,核心信息一览:
| 项目 | 说明 |
|---|---|
| 总参数量 | 35B(MoE 混合专家) |
| 每 token 激活参数 | 约 3B(从 256 个专家中路由选 8 个) |
| 量化格式 | MXFP4,4-bit,group_size = 32 |
| 例外模块 | 40 层的 MoE 路由共 80 个模块保留 8-bit |
| 上下文长度 | 262144(256K) |
| 权重体积 | 约 20.95 GiB(5 个 safetensors 分片) |
| 许可证 | apache-2.0 |
"35B-A3B" 的含义:总参数 35B,但每个 token 只激活约 3B 参数,兼顾能力与速度。模型采用 线性注意力 + 全注意力(3:1) 的混合结构,视觉编码器为 27 层 ViT,支持文本、图片与视频输入。更多介绍见 README.md。
二、config.json核心参数速查
config.json 是模型的"主配置",分为四块:顶层模型属性、text_config(语言模型)、vision_config(视觉编码器)和 quantization(量化配置)。
2.1 顶层模型属性
| 参数 | 取值 | 含义 |
|---|---|---|
architectures |
MiniCPMV4_7ForConditionalGeneration | 模型架构类名 |
model_type |
minicpmv4_7 | 模型族标识 |
version |
4.7 | MiniCPM-V 版本号 |
dtype |
bfloat16 | 基础计算精度 |
downsample_mode |
16x | 视觉默认下采样倍率(4x 更精细) |
mrope_mode |
canvas | 多模态 RoPE 位置编码模式 |
use_cache |
true | 启用 KV Cache 加速生成 |
eos_token_id |
[248044, 248046] | 两个停止 token |
视觉相关的特殊 token 编号(多模态理解的关键):
| 参数 | 取值 | 作用 |
|---|---|---|
image_token_id |
248056 | 单个图像 patch 占位符 |
video_token_id |
248057 | 单个视频帧占位符 |
image_start_id / image_end_id |
248078 / 248079 | 图像起止标记 |
slice_start_id / slice_end_id |
248088 / 248089 | 高分辨率图像切片标记 |
insert_layer_id |
6 | 视觉特征注入语言模型的第 6 层 |
2.2 text_config:语言模型(qwen3_5_moe_text)
| 参数 | 取值 | 含义 |
|---|---|---|
num_hidden_layers |
40 | Transformer 层数 |
num_experts / num_experts_per_tok |
256 / 8 | 每层 256 个专家,每次只激活 8 个,"3B 激活"的关键 |
moe_intermediate_size |
512 | 专家 FFN 中间维度 |
shared_expert_intermediate_size |
512 | 共享专家中间维度 |
hidden_size |
2048 | 隐藏层维度 |
num_attention_heads / num_key_value_heads |
16 / 2 | GQA 分组注意力,省显存 |
head_dim |
256 | 注意力头维度 |
full_attention_interval |
4 | 每 4 层插入 1 层全注意力,其余为线性注意力 |
layer_types |
linear_attention ×3 + full_attention | 线性:全注意力 = 3:1,长文本成本大降 |
max_position_embeddings |
262144 | 256K 超长上下文 |
vocab_size |
248144 | 词表大小 |
mtp_num_hidden_layers |
1 | 多 token 预测层 |
rope_parameters |
mrope_interleaved=true,mrope_section=[11,11,10] | 多模态 RoPE,文本/图像/视频位置统一编码 |
mamba_ssm_dtype |
float32 | 线性注意力的 SSM 状态用 float32 保精度 |
📌 新手记住两点即可:MoE top-8 路由 + 线性注意力是这个 35B 模型低显存、高速度的原因;256K 上下文可轻松处理超长文档与长视频。
2.3 vision_config:视觉编码器(minicpmv4_7_vision)
| 参数 | 取值 | 含义 |
|---|---|---|
num_hidden_layers |
27 | ViT 层数 |
hidden_size |
1152 | 隐藏层维度 |
num_attention_heads |
16 | 注意力头数 |
patch_size |
14 | 图像切成 14×14 的 patch |
image_size |
980 | 视觉编码器内部分辨率 |
hidden_act |
gelu_pytorch_tanh | 激活函数 |
⚠️ 注意:视觉编码器不参与量化,始终保持 BF16,详见下一节。
三、MXFP4量化配置详解:4-bit分组量化+8-bit例外
quantization(与 quantization_config 内容一致)是整个配置的核心,决定权重如何压缩存储。
3.1 全局量化参数
"quantization": {
"group_size": 32,
"bits": 4,
"mode": "mxfp4",
"language_model.model.layers.0.mlp.gate": {
"group_size": 64,
"bits": 8
}
}
| 参数 | 取值 | 含义 |
|---|---|---|
mode |
mxfp4 | Microscaling FP4 格式,按组共享浮点缩放因子 |
bits |
4 | 默认权重精度 4-bit |
group_size |
32 | 每 32 个权重共享一个缩放因子 |
🔍 MXFP4 是"微缩放"浮点量化:相比传统的仿射整数量化,它的动态范围更大、精度更接近 BF16,是新一代低比特格式。
3.2 8-bit例外模块:路由为什么要保留高精度
config.json 中包含 80 个模块级覆盖配置,全部位于 40 层的 MoE 路由组件:
language_model.model.layers.0.mlp.gate → { "group_size": 64, "bits": 8 }
language_model.model.layers.0.mlp.shared_expert_gate → { "group_size": 64, "bits": 8 }
...(第 1–39 层完全相同)
| 项目 | 数值 |
|---|---|
| 例外模块数 | 40 层 × 2(gate + shared_expert_gate)= 80 |
| 覆盖精度 | 8-bit 仿射量化,group_size = 64 |
为什么这么设计? gate 是 MoE 的"路由器",决定每个 token 走哪 8 个专家。路由稍有误差,输出质量就会明显退化,所以保留 8-bit 高精度;而其余 280 个计算密集型模块(注意力投影、专家 FFN 等)则放心压到 4-bit。验证报告 validation.json 也确认了这个分布:"affine:8:g64": 80, "mxfp4:4:g32": 280。
3.3 哪些部分完全不量化
根据 README,以下模块保持 BF16 原精度:
- 视觉编码器(vision)与视觉融合层(merger)
- 嵌入层(embeddings)与输出头(lm_head)
- 线性注意力权重
- 循环状态
A_log张量(保留源精度 bfloat16,共 30 个)
这就是混合精度量化的关键设计:算力敏感的大矩阵压到 4-bit 省显存,精度敏感的模块保留高精度保质量。
四、conversion.json:追溯量化来源与校验权重
conversion.json 是转换时自动记录的"出生证明",用于溯源与完整性校验:
| 字段 | 取值 | 含义 |
|---|---|---|
source_model |
openbmb/MiniCPM-V-4.7-35B-A3B | 源模型 |
source_revision |
17e6511…0b40 | 源模型精确 commit |
mlx_vlm_version |
0.7.8 | 转换工具版本 |
dtype / format |
bfloat16 / mxfp4 | 转换前精度与量化格式 |
conversion_options |
quantize=true, q_bits=4, q_group_size=32 | 转换命令行参数 |
它还记录了 5 个权重文件的大小与 SHA-256 校验和,下载后可直接核对:
| 权重文件 | 大小 |
|---|---|
| model-00001-of-00005.safetensors | 5.30 GB |
| model-00002-of-00005.safetensors | 5.37 GB |
| model-00003-of-00005.safetensors | 5.31 GB |
| model-00004-of-00005.safetensors | 5.25 GB |
| model-00005-of-00005.safetensors | 1.29 GB |
weight_map 索引文件 则记录每个参数张量存放在哪个分片中。整个检查点已通过严格重载、量化配置检查、文本生成及 16x/4x 两种下采样的图像生成验证(status: "passed")。
五、generation_config.json与其他配置文件
5.1 generation_config.json:默认生成参数
| 参数 | 取值 | 使用建议 |
|---|---|---|
temperature |
1.0 | 默认中性;客观问答建议设 0(贪心) |
top_k |
20 | 采样候选数 |
top_p |
0.95 | 累计概率截断阈值 |
do_sample |
true | 是否启用采样 |
官方示例对图像描述使用 --temperature 0,结果更稳定可复现。
5.2 其他配置文件一览
| 文件 | 关键参数 |
|---|---|
| processor_config.json | downsample_mode=16x,scale_resolution=448,max_slice_nums=9,视频 max_num_frames=128 |
| preprocessor_config.json | image_mean/std=0.5,mrope_mode=canvas |
| tokenizer_config.json | Qwen2Tokenizer,model_max_length=262144,视觉特殊 token |
| chat_template.jinja | 对话模板 |
💡 downsample_mode 决定视觉 token 数量与细节的平衡:默认 16x token 更少、速度更快;需要识别小字细节时传 --processor-kwargs '{"downsample_mode": "4x"}' 即可。
六、快速上手:用mlx-vlm加载量化模型
pip install -U mlx-vlm # 需 ≥ 0.7.8 版本(含 MiniCPM-V 4.7 支持)
mlx_vlm.generate --model mlx-community/MiniCPM-V-4.7-35B-A3B-mxfp4 \
--image path/to/image.jpg \
--prompt "Describe this image." \
--max-tokens 200 --temperature 0
原生处理器仅依赖 NumPy/Pillow,无需 PyTorch,支持文本、单图、多图和视频输入。
七、常见问题FAQ
Q1:模型名字很长,"35B-A3B" 到底什么意思? 35B 是总参数(含每层 256 个专家),A3B 表示每 token 只激活约 3B 参数(top-8 路由),所以推理速度和显存占用接近一个小模型。
Q2:MXFP4 和 GPTQ/AWQ 是一回事吗? 不是。MXFP4 是按组共享缩放因子的微缩放浮点量化;本模型还额外混入 8-bit 仿射量化(路由模块)与 BF16(视觉/嵌入/线性注意力),属于混合精度方案。
Q3:量化后看图能力会下降吗? 视觉编码器保持 BF16 未量化,图像理解主要依赖原始模型精度;官方验证也在 16x 与 4x 两种下采样模式下通过了图像生成测试。
Q4:如何验证下载的文件没损坏?
用 conversion.json 中 weight_files 字段的 SHA-256 对每个 safetensors 分片做哈希比对即可。