58个分片里到底装了什么?MiniMax-M3.1-Flash-Text-4bit权重文件与index.json完全解读
58个分片里到底装了什么?MiniMax-M3.1-Flash-Text-4bit权重文件与index.json完全解读
下载 MiniMax-M3.1-Flash-Text-4bit 模型后,你会看到 58 个 model-XXXX-of-00058.safetensors 权重分片和一份 model.safetensors.index.json 索引文件。这篇文章用大白话带你彻底看懂:248GB 的权重文件里到底装了什么?index.json 是如何把 2070 个张量一一对应到 58 个分片的?NVFP4 与 MXFP8 混合量化又是什么门道?读完 10 分钟,你就能完全解读这个仓库。
30 秒速览:仓库里的文件各管什么
| 文件 | 作用 |
|---|---|
model-00001-of-00058.safetensors ~ model-00058-of-00058.safetensors |
58 个模型权重分片,合计约 248GB |
| model.safetensors.index.json | “张量地图”:每个张量存放在哪个分片 |
| config.json | 模型结构参数与量化配置 |
| generation_config.json | 生成参数(temperature 1.0、top_p 0.95) |
| tokenizer.json、chat_template.jinja | 分词器与对话模板 |
| processing_minimax.py、image_processor.py、video_processor.py | 图像/视频预处理代码(本仓库是纯文本版,不含视觉权重) |
| configuration_minimax_m3_vl.py | 模型 Config 类定义 |
| LICENSE | minimax-community 许可协议 |
为什么权重要拆成 58 个分片?
单个大文件在分发、下载和加载时都很容易“爆掉”,所以业界惯例是把权重按固定体积切片。index.json 中的 metadata 字段给出了总量:
- total_size:248,369,178,624 字节,即约 231.6 GiB(248 GB)
- 58 个分片平均每个约 4.28 GB(例如第 1 个分片实际约 4.98 GB)
另外注意:当前仓库里的 .safetensors 文件只有 135 字节,那是 Git LFS 指针文件,真正的权重数据需要走 LFS 拉取,下载完成后每个分片才会变成几 GB 的真实文件。
💡 分片还有一个好处:safetensors 支持内存映射(mmap)加载,推理框架可以只按需读取用到的分片,而不必一次性把 248GB 全部读进内存。
读懂 index.json:一张 2070 张量的“藏宝图”
model.safetensors.index.json 是整个权重体系的目录页,结构非常简单,就两部分:
1. metadata —— 两个总数
{
"metadata": {
"total_size": 248369178624,
"total_parameters": 426186362880
}
}
- 参数量高达 426,186,362,880(约 426B),但磁盘只占 248GB,平均每个参数约 0.58 字节,也就是 4.7 bit/参——这正是混合量化压缩出来的效果。
2. weight_map —— 张量名到分片文件的映射
weight_map 共收录 2070 个张量,每一条都是“张量全名 → 所在分片”:
"language_model.lm_head.weight": "model-00058-of-00058.safetensors",
"language_model.model.embed_tokens.weight": "model-00001-of-00058.safetensors",
"language_model.model.layers.0.self_attn.q_proj.weight": "model-00001-of-00058.safetensors"
加载模型时,mlx-lm 等框架会先读这个索引:想知道某个权重在哪,直接查表,无需逐个打开分片试探。
58 个分片到底是怎么划分的?
我们逐一比对了 index.json 中 2070 条映射,分片规律非常整齐:
| 分片范围 | 存放内容 |
|---|---|
| 第 1 片 | 词嵌入 embed_tokens + 第 0~3 层(其中 0~2 层为稠密层,第 3 层被拆分) |
| 第 2 ~ 57 片 | 每片约 2 个 MoE Transformer 层 |
| 第 58 片 | 第 59 层(末层)+ 全局归一化 norm + 输出投影 lm_head |
模型共有 60 层(编号 0~59,见 config.json 中 num_hidden_layers: 60)。前 3 层用的是普通稠密 MLP,从第 4 层起全部换成 MoE(混合专家)结构。因为 MoE 层体量大(128 个路由专家),每两个 MoE 层恰好占满一个分片,于是就有了 56 个“标准层”分片 + 首尾两个特殊分片 = 58 片。
每一层 Transformer 里都装了什么?
以第 40 层(典型 MoE 层)为例,它在 index.json 中对应约 30 个张量,可以归为四大块:
- 注意力部分:
q/k/v/o_proj四个投影矩阵(各带一份量化标度scales),以及稀疏注意力特有的index_q_proj/index_k_proj索引投影和归一化层 - 归一化部分:
input_layernorm、post_attention_layernorm - MoE 路由部分:
gate.weight(路由器权重)和e_score_correction_bias(专家打分偏置) - 专家部分:
switch_mlp:128 个路由专家的三组投影(gate/up/down),每个专家各自带global_scaleshared_experts:1 个共享专家,每个 token 都会经过它
对应的关键架构数字(来自 config.json 的 text_config):
- 隐藏维度
hidden_size:6144 - 注意力头:64 个 query 头 + 4 个 KV 头(GQA 分组查询注意力)
- 词表大小:200,064
- 专家配置:
num_local_experts: 128,每 token 只激活num_experts_per_tok: 4个
“4bit”的真相:四种数据格式混装
这个模型名字里的 4bit 并不表示所有权重都是 4 位,实际是分部位、分精度的混合量化方案:
| 模型部位 | 精度格式 | 说明 |
|---|---|---|
路由专家 switch_mlp |
NVFP4(4bit,group_size 16) | 占存储大头,每个专家附带一个 global_scale 标度 |
| 注意力、稠密 MLP、共享专家 | MXFP8(8bit,group_size 32) | 全局默认量化方式 |
路由器 gate |
float32 | 保持全精度,保证专家路由准确 |
这些量化参数逐层写在 config.json 的 quantization 字段里(从第 3 层到第 59 层,每层的 switch_mlp.gate_proj / up_proj / down_proj 均标注 bits: 4, mode: nvfp4)。官方说明该转换保留了原始量化,贪心解码输出与原检查点逐 token 一致,测试峰值内存约 249GB。
用 mlx-lm 跑起来
README.md 给出了最简用法,安装依赖后按张量索引自动从 58 个分片中拼装模型:
pip install -U mlx-lm
from mlx_lm import load, generate
model, tokenizer = load("mlx-community/MiniMax-M3.1-Flash-Text-4bit")
prompt = "hello"
messages = [{"role": "user", "content": prompt}]
prompt = tokenizer.apply_chat_template(
messages, add_generation_prompt=True, return_dict=False,
)
response = generate(model, tokenizer, prompt=prompt, verbose=True)
官方在 mlx-lm 0.32.2 下完成验证;由于是 MoE 大模型,建议为推理预留充足的内存带宽。
常见问题 FAQ
Q1:下载后 .safetensors 只有 135 字节,是损坏了吗? 没有。那是 Git LFS 指针文件,完成 LFS 数据拉取后会变成真正的 GB 级权重文件。
Q2:总共需要多大磁盘空间? 58 个分片 + 索引合计约 248GB(231.6 GiB),请预留至少 300GB 可用空间。
Q3:能只下载部分分片吗? index.json 让你能精确定位任意张量所在的分片,方便做调试或局部检查;但完整推理需要全部 58 个分片齐全,缺一片都装不完整模型。
Q4:为什么有 image_processor.py,却没有视觉权重? 这是纯文本转换版(text-only conversion),视觉塔权重并未包含在内,相关处理脚本仅为兼容原始多模态结构而保留。
小结
MiniMax-M3.1-Flash-Text-4bit 的 58 个分片本质上是:首片装词嵌入与稠密层 → 中间 56 片每片 2 个 MoE 层 → 尾片装末层、归一化与 lm_head,再由 model.safetensors.index.json 这张 2070 张量的索引表把它们串成完整的 426B 参数模型。理解了这个“分片 + 索引”的协作机制,你就能看懂绝大多数大模型仓库的权重组织了。