MindSpeed-LLM 大参数权重转换实战:HuggingFace 与 Megatron-MCore 格式互转完整指南
MindSpeed-LLM 大参数权重转换实战:HuggingFace 与 Megatron-MCore 格式互转完整指南
本文以 MindSpeed-LLM 官方工具文档为主体,结合仓库源码,系统讲解大参数(TB 级)模型在 HuggingFace 与 Megatron-MCore 两种格式之间互转的完整流程:从权重下载、转换前的训练配置核对、核心命令行参数语义,到 hf2mg / mg2hf 双向转换示例与减层调试功能。读完本文,你将能够独立完成 Qwen3-MoE、DeepSeek 等大规模模型在任意并行切分策略下的权重转换,并掌握转换失败时的排查思路。
权重转换背景:TB 级参数模型的迁移难题
随着模型规模从亿级向万亿级跃迁,TB 级别的参数模型在实际部署与迁移过程中对系统资源提出了极高的要求,单一设备已经无法容纳完整模型参数。如果在转换阶段一次性把所有权重加载进内存,超大模型极易因内存溢出(OOM)而崩溃。
MindSpeed-LLM 为此采用了一套支持按需加载、内存高效的权重转换方案:转换过程不再要求一次性持有全部参数,而是按 PP/VPP 分层、按需读取对应权重文件进行处理,从而解决了大参数规模模型在转换阶段易崩溃的问题,为超大模型的高效训练与应用提供基础技术支持。这一点在源码中有直接体现:convert_hf2mg.py 的 load_matched_hf_weight() 方法只读取当前 PP/VPP rank 对应层的 safetensors 文件(通过 layer_files_map_dict[layer] 定位每个 layer 所在的权重文件),而不是一次性加载整个模型。
此外,源码中还有一个自动保护机制:在 convert_hf2mg.py 中定义 LAYER_BY_LAYER_SAVING_THRESHOLD = 256,当 tensor_model_parallel_size * expert_model_parallel_size >= 256 时自动开启逐层保存(save_layer_by_layer),进一步避免高 TP×EP 组合下的内存峰值。这一阈值可通过命令行参数 --save-layer-by-layer 显式控制。
权重转换能力总览
权重转换旨在解决不同深度学习框架和训练策略下模型权重的兼容性问题,支持在多个模型和训练配置之间进行高效的权重互转。核心功能包括:
- 权重格式互转:能够在 HuggingFace、Megatron-LM 两大主流框架之间实现任意并行切分策略下的权重格式互转。
- 训练并行策略权重转换:支持多种训练并行策略之间的权重转换,包括张量并行(TP)、流水并行(PP)、专家并行(EP)、专家张量并行(ETP)和虚拟流水并行(VPP)。无论是针对不同并行策略的训练,还是需要在不同策略之间切换的场景,都能实现灵活的权重转换,以适应各种训练和推理需求。
转换入口统一为仓库根目录下的 convert_ckpt_v2.py。该入口按 --model-type-hf 与 --load-model-type/--save-model-type 组合分发到不同的转换器(Hf2MgConvert、Mg2HfConvert,以及 Mamba2、LongCat、DeepSeek4 等专用转换器),其支持的 HuggingFace 模型类别包括 qwen3、qwen3-moe、deepseek2/3/4、glm45、llama2、qwen25、seed-oss、mamba2、longcat、glm5、minimax_m2 等。
第一步:权重下载
从 HuggingFace 等网站下载开源模型权重,训练权重的下载链接可在 模型支持列表(或中文版 模型支持列表)的下载链接列中获取。
方法一:网页直接下载
通过浏览器访问链接,手动下载所有权重文件。
方法二:命令行下载
将下载的权重保存至 MindSpeed-LLM/model_from_hf 目录,例如:
mkdir ./model_from_hf/llama-2-7b-hf/
cd ./model_from_hf/llama-2-7b-hf/
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/config.json
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/generation_config.json
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/pytorch_model-00001-of-00002.bin
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/pytorch_model-00002-of-00002.bin
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/pytorch_model.bin.index.json
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/special_tokens_map.json
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/tokenizer.json
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/tokenizer.model
wget https://huggingface.co/daryl149/llama-2-7b-hf/resolve/main/tokenizer_config.json
cd ../../
常见问题
如果下载过程中遇到问题,请参考:
- HuggingFace 官方文档:https://huggingface.co/docs/hub/models-downloading
- ModelScope 下载指南:https://modelscope.cn/docs/models/download
[!NOTE]
如果出现下载速度太慢或者无法访问下载的情况,请配置可用的代理或国内镜像源重试。
注意事项
- 确保有足够的磁盘空间存放模型权重。
- 检查文件完整性,下载后验证文件大小和 MD5 值。
- 部分模型可能需要登录或申请相应权限才能下载。
HuggingFace 权重转换至 Megatron-MCore 格式
权重转换实现了 HuggingFace 权重到 Megatron-MCore 格式的转换,支持多种并行策略(如张量并行、流水并行等),确保转换后可以在 MindSpeed-LLM 框架下继续训练和推理。
[!NOTE]
在做权重转换前,请先确认训练时的参数配置,根据训练配置修改仓上的权重转换脚本——因为这些配置会改变权重的结构,如果与训练的参数不一致,会导致训练无法加载权重。需要确认的训练配置见下表。
转换前必须核对:训练配置参考
| 参数 | 说明 | 默认值 | 需要和训练配置一致 |
|---|---|---|---|
--load-model-type |
源模型类型,可选项为 hf 或 mg |
hf |
❌ |
--save-model-type |
转换后模型类型,可选项为 hf 或 mg |
mg |
❌ |
--load-dir |
源模型路径 | None | ❌ |
--save-dir |
转换后模型权重的储存路径 | None | ❌ |
--hf-cfg-dir |
源 HuggingFace 权重配置文件目录,可选参数。在 mg2hf 转换过程中,将必要配置文件拷贝至权重保存目录,生成开箱即用的 hf 格式权重 | None | ❌ |
--model-type-hf |
HuggingFace 模型类别。对于已经支持的模型,脚本内已经配置好,使用者无需更改 | qwen3 |
❌ |
--target-tensor-parallel-size |
TP,指定张量并行数量 | 1 | ✅ |
--target-pipeline-parallel-size |
PP,指定流水线数量 | 1 | ✅ |
--target-expert-parallel-size |
EP,指定专家并行数量 | 1 | ✅ |
--expert-tensor-parallel-size |
ETP,指定专家张量并行,当前仅支持开启后 ETP=1 | None,在实际转换过程中等于 TP 的大小 | ✅ |
--num-layers-per-virtual-pipeline-stage |
VPP 划分,指定 VPP 的每个 Stage 层数 | None | ✅ |
--num-layer-list |
动态 PP 划分,通过列表指定每个 PP Stage 的层数。使用时,列表以英文逗号隔开,列表的总和为模型总层数,并且列表的长度等于 PP。例如,总层数为 14 层,指定 --num-layer-list 3,4,4,3、--target-pipeline-parallel-size 4 |
None | ✅ |
--noop-layers |
自定义空层操作,指定在模型某层增加空层,转换后层数为原 HuggingFace 模型层数加上空层数 | None | ✅ |
--moe-grouped-gemm |
MoE 分组矩阵乘法优化 | None | ✅ |
--moe-tp-extend-ep |
TP 拓展 EP,开启后,专家层 TP 组切分专家参数 | None | ✅ |
--mla-mm-split |
开启后对压缩后的 q_compressed 和 kv_compressed 进行升维 |
None | ✅ |
--mtp-num-layers |
MTP 层的层数 | 0 | ✅ |
--schedules-method |
DualPipeV 流水排布,可选项为 dualpipev |
None | ✅ |
其中,"✅" 表示该参数直接决定权重结构(并行切分方式、层分布等),必须与训练脚本中的对应配置保持一致;"❌" 表示仅决定转换行为本身,无需与训练配置对齐。
上述参数在 convert_ckpt_v2.py 中均有对应的 argparse 定义,值得注意的源码细节:
--expert-tensor-parallel-size在未指定时默认等于--target-tensor-parallel-size,且只允许取1或等于 TP 的值,否则 convert_hf2mg.py 的check_etp_conflict()会直接报错;若 ETP=1,还要求 TP 与 EP 之间满足整除关系,且不能与--moe-tp-extend-ep同时使用。--num-layers-per-virtual-pipeline-stage(VPP)与--num-layer-list(动态 PP)在 argparse 中属于互斥参数组,同时配置会直接报错。--moe-grouped-gemm、--moe-tp-extend-ep、--mla-mm-split、--schedules-method等特性开关会改变 MCore 侧权重的组织方式(如专家权重合并为weight1/weight2、MLA 升维切分、DualPipeV 层排布),因此同样必须与训练配置一致。
使用约束
- 模型的层数必须能被 PP 切分数量整除,否则需要增加空层
--noop-layers或者使用动态 PP--num-layer-list。 - VPP
--num-layers-per-virtual-pipeline-stage和动态 PP 划分--num-layer-list只能二选一。
这一约束在 convert_hf2mg.py 的 _valid_parameter() 中有完整校验:未配置 num_layer_list 时要求 num_layers % pipeline_model_parallel_size == 0;配置了 VPP 时要求每层 PP 的层数能被 VPP stage 整除;配置 num_layer_list 时要求列表长度等于 PP、列表元素之和等于总层数,且与 noop_layers 互斥。
使用示例:Qwen3-235b
以下是 Qwen3-235b 模型的 hf2mg 权重转换脚本(参考 ckpt_convert_qwen3_moe_235b_hf2mcore.sh),仅供参考:
source /usr/local/Ascend/ascend-toolkit/set_env.sh
python convert_ckpt_v2.py \
--load-model-type hf \
--save-model-type mg \
--target-tensor-parallel-size 1 \
--target-pipeline-parallel-size 4 \
--target-expert-parallel-size 32 \
--num-layers-per-virtual-pipeline-stage 8 \
--noop-layers 94,95 \
--load-dir ./model_from_hf/qwen3_moe_hf/ \
--save-dir ./model_weights/qwen3_moe_mcore/ \
--moe-grouped-gemm \
--model-type-hf qwen3-moe
该示例体现了几个典型用法:
- noop 空层:Qwen3-235b 的 MoE 层数为偶数,通过
--noop-layers 94,95插入空层,使总层数可以被 PP=4 与 VPP stage=8 整除(每个 PP 段 24 层、每 VPP stage 8 层)。 - EP=32:专家并行度设置为 32,转换后每个专家分片由对应 EP rank 持有。
--moe-grouped-gemm:开启 MoE 分组 GEMM 后,专家权重在 MCore 侧以mlp.experts.weight1/weight2形式存储(见 model_builder.py 中的layers_mlp_experts_weight1映射),该开关必须与训练配置一致。
启动脚本
MindSpeed-LLM 提供预置的模型权重转换脚本,以下列出 HuggingFace 至 Megatron-MCore 权重转换脚本的命名风格及启动方法,可按模型类别进行查找:
# 脚本命名
# bash examples/mcore/model_name/ckpt_convert_xxx_hf2mcore.sh
# 启动方法
bash examples/mcore/qwen3_moe/ckpt_convert_qwen3_moe_235b_hf2mcore.sh
[!NOTE]
需在权重转换脚本中配置并行参数、权重词表路径、权重加载路径(包括词表等配置文件)以及权重保存的路径。
仓库中已预置的同类脚本还包括 deepseek3(61 层 + MTP、--num-layers 64、VPP stage=2、noop 47/62/63)、deepseek32、glm5、longcat、seed_oss 等,均位于 examples/mcore/<模型名>/ 目录下,可按需修改并行参数后直接使用。
源码级原理:hf2mg 转换如何工作
从源码看,hf2mg 的转换流程大致如下:
- convert_ckpt_v2.py 解析参数并创建
Hf2MgConvert实例; - convert_hf2mg.py 的
__init__中计算 PP/VPP 各 rank 对应的 HuggingFace 层序号映射(get_pprank_hf_layeridxs/get_vpprank_hf_layeridxs),这是"按需加载"的基础; - 转换时
load_matched_hf_weight()只读取当前 rank 负责的层所在的权重文件(model.layers.[layer_id]前缀对应的文件),并通过set_model_preprocess(embedding)、set_model_layer_norm/set_model_layer_attn/set_model_layer_mlp(逐层处理)、set_model_postprocess(final norm 与 LM Head)逐段转换; - 权重写出时按
mp_rank_{tp:02}_{pp:03}_{ep:03}命名规则生成目录结构(见 convert.py 的generate_mg_weights_dir),并自动创建iter_0000001目录与latest_checkpointed_iteration.txt文件(mg_path_process),使产出目录符合 Megatron 检查点格式,可直接被训练加载。
HuggingFace 侧的权重解析依赖 model_builder.py 中 HuggingFaceModel 的 load_hf_args():它会读取权重目录下的 config.json,并结合 model_cfg.json 中的 config_hf_key_mapping 与 config_set_value 完成字段映射与默认值注入;权重文件格式则通过 infer_weight_format() 自动识别为 .safetensors 或 pytorch_model*.bin。
Megatron-MCore 权重转换至 HuggingFace 格式
权重转换实现了 Megatron-MCore 权重至 HuggingFace 格式的转换,支持多种并行策略(如张量并行、流水并行等)。转换过程中,模型权重会被适配为 HuggingFace 的标准格式,确保可以在 HuggingFace 权重格式下继续进行训练和推理。
使用约束
- 由于 HuggingFace 权重不涉及并行切分,转至 HuggingFace 权重时无需设置
--target-tensor-parallel-size、--target-pipeline-parallel-size、--target-expert-parallel-size、--num-layers-per-virtual-pipeline-stage。转换器会从 MCore 检查点的args中自动读取源切分信息(见 convert_mg2hf.py 的load_mg_args())。 - 转换成功后的权重保存目录下仅包含模型权重文件,不会生成
config.json模型配置文件和tokenizer.model、vocab.json等词表文件。可以使用--hf-cfg-dir参数指向原始 HuggingFace 模型的配置文件路径,自动将配置文件拷贝至 mg2hf 转出的权重保存目录,生成"开箱即用"的 HuggingFace 权重目录。 - 如果 Megatron-MCore 权重配置了空层
--noop-layers,在将 Megatron-MCore 权重转换至 HuggingFace 格式时,需要在命令行中添加相同的空层配置。 - 若原始 Megatron-MCore 权重的专家张量并行度(ETP)为 1,则在执行 mcore2hf 转换脚本时,必须添加
--expert-tensor-parallel-size 1参数。
说明:
--hf-cfg-dir的拷贝行为由 convert_mg2hf.py 的copy_hf_cfg()实现,其通过正则匹配自动拷贝*.json、*.model、merges.txt、tokenization_*.py、modeling_*.py等配置文件到保存目录。
使用示例:Qwen3-235b
以下是 Qwen3-235b 模型的 mg2hf 权重转换脚本(参考 ckpt_convert_qwen3_moe_235b_mcore2hf.sh),仅供参考:
source /usr/local/Ascend/ascend-toolkit/set_env.sh
python convert_ckpt_v2.py \
--load-model-type mg \
--save-model-type hf \
--noop-layers 94,95 \
--load-dir ./model_weights/qwen3_moe_mcore/ \
--save-dir ./model_from_hf/qwen3_moe_hf/ \
--moe-grouped-gemm \
--model-type-hf qwen3-moe
注意:示例中保留了 --noop-layers 94,95 与 --moe-grouped-gemm,这是为了与 hf2mg 时的权重结构保持一致(noop 层与 grouped-gemm 布局必须对应),符合上述约束要求。
启动脚本
# 脚本命名
# bash examples/mcore/model_name/ckpt_convert_xxx_mcore2hf.sh
# 启动方法
bash examples/mcore/qwen3_moe/ckpt_convert_qwen3_moe_235b_mcore2hf.sh
[!NOTE]
需在权重转换脚本中配置并行参数、权重词表路径、权重加载路径(包括词表等配置文件)以及权重保存的路径。
仓库中同类脚本包括 ckpt_convert_deepseek3_mcore2hf.sh、ckpt_convert_qwen3_mcore2hf.sh、ckpt_convert_qwen3_moe_mcore2hf.sh、ckpt_convert_glm5_mcore2hf.sh 等。此外,LoRA 场景还提供专用的 ckpt_convert_deepseek3_merge_lora2hf.sh(对应 --lora-load、--lora-r、--lora-alpha 等 LoRA 参数)。
源码级原理:mg2hf 转换如何工作
mg2hf 是 hf2mg 的逆过程,核心差异在于:
- 读取方向相反:
Mg2HfConvert通过get_iter_path()读取latest_checkpointed_iteration.txt确定迭代目录,再按mp_rank_{tp:02}_{pp:03}_{ep:03}规则定位各 TP/PP/EP rank 的model_optim_rng.pt分片文件(见 convert_mg2hf.py 的get_pt_path_by_tpppep_rank()); - 反向映射:
calc_pprank_layeridxs()/calc_vpprank_layeridxs()/calc_layeridx_pprank()等将 MCore 的分片层映射回 HuggingFace 的全局层序号,例如{hf layer: (pp_rank, vpp_rank, local_idx)}; - 张量拼接:对 QKV、专家权重等,需要把多个 TP 分片
torch.cat拼接回完整矩阵(例如unpack类型的 q/k/v 拼接、pack_mla类型的 MLA 权重还原),再还原为q_proj、k_proj、v_proj等 HuggingFace 标准键名; - 模型结构还原:
MegatronModel的load_mg_args()会读取检查点中保存的训练 args(src_model['args'].__dict__),并用 model_cfg.json 中的model_hf_key_mapping完成键名双向映射,从而支持各种并行结构与特性开关的还原。
调试功能:HuggingFace 权重减层转换至 Megatron-MCore 格式
本框架支持在 HuggingFace 权重转换到 Megatron-MCore 格式时进行减层调试,并且无需更改模型的配置文件,通过以下命令行参数进行减层配置。这一功能对快速验证模型正确性、小规模跑通训练流水线非常实用。
--num-layers
指定减层模型的层数,不能大于原始模型层数,并且该层数不包含 MTP 层。默认值为 None,非减层情况下通过配置文件传入,无需指定该参数。
- 如配置空操作层,
num-layers的值应为真实层数,不包含 MTP 层,也不包括--noop-layers层数。 - 如果需要配合训练脚本进行减层调试,请注意此参数需要和训练脚本保持一致。具体来说:当未使用
--noop-layers配置时,此参数必须与训练脚本一致;当使用了--noop-layers配置时,权重转换的--num-layers参数是真实层数(不含空层),而训练脚本中的--num-layers参数是总层数(含空层层数)。
从源码看,这一逻辑在 convert_hf2mg.py 中有明确实现:num_layers 若大于原始模型层数会直接抛出 ValueError;当配置了 noop_layers 时,转换器内部将 num_layers 修正为 num_layers + noop 层数(即最终写入 MCore 检查点的总层数),从而与训练脚本的"总层数"语义对齐。
--first-k-dense-replace
指定减层模型中 MoE 层前的 dense 层数,不能大于原始模型的 dense 层数,默认值为 None,非减层情况下通过配置文件传入,无需指定该参数。
- 如果需要配合训练脚本进行减层调试,请注意此参数需要和训练脚本保持一致。
源码中,convert_hf2mg.py 的 get_pprank_hf_layeridxs() / get_vpprank_hf_layeridxs() 会根据 first_k_dense_replace 重新组织层序号映射(先排前 k 个 dense 层,再排后续 MoE 层),并校验其不超过开源模型实际的 dense 层数。DeepSeek3 等模型的 MoE 结构中,前若干个 dense 层(如 3 个)与后续 MoE 层在权重键名上不同,减层调试时必须保证 dense 层分布与训练一致。
--mtp-num-layers
MTP(Multi-Token Prediction)层的层数,默认值为 0,支持减层时配置 MTP 层,但不能大于原始模型的 MTP 层数。
- 如需要配置 MTP 层,可通过命令行设置,例如
--mtp-num-layers 1。 - 如果需要配合训练脚本进行减层调试,请注意此参数需要和训练脚本保持一致。
源码层面,MTP 权重使用独立的键名前缀 mtp.layers[...] 与 mtp.final_layernorms[...](见 model_builder.py 的 mtp_layers_* 映射),转换时通过 set_mtp_preprocess / set_mtp_postprocess 处理,MTP 层权重默认存放于最后一个 PP stage(DualPipeV 场景存放于 pp0 的 vpp1)。同时注意,convert_hf2mg.py 中 transformer_impl == 'transformer_engine' 与 mtp_num_layers > 0 不可同时配置。
减层调试与训练脚本的配合要点
- 减层模式下,
--num-layers、--first-k-dense-replace、--mtp-num-layers三个参数都必须与训练脚本保持一致(noop 场景下--num-layers的语义除外,见上文)。 - 减层转换产出的 MCore 权重可以直接用于小规模训练脚本,从而在完整模型训练前快速验证数据管线、并行配置与模型结构是否正确。
常见问题排查与最佳实践
结合文档与源码,整理以下常见问题及处理建议:
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 训练加载权重失败 | 转换时的并行/特性参数与训练配置不一致(表 1 中 ✅ 项) | 逐项核对 TP、PP、EP、ETP、VPP、noop、grouped-gemm、MTP 等参数 |
number of layers should be divisible by the pipeline parallel size 报错 |
总层数无法被 PP 整除 | 使用 --noop-layers 补空层,或改用 --num-layer-list 动态 PP |
ETP 相关 ValueError |
--expert-tensor-parallel-size 取值非法,或与 --moe-tp-extend-ep 冲突 |
只取 1 或不设置(默认等于 TP);ETP=1 时 TP/EP 需满足整除关系 |
--num-layer-list 与 VPP 同时配置报错 |
两参数互斥 | 只保留其中一种层分布方式 |
| mg2hf 后目录缺少 config.json / tokenizer | mg2hf 默认只输出权重文件 | 指定 --hf-cfg-dir 指向原始 HuggingFace 配置目录 |
| mg2hf 时权重结构错乱 | 原 MCore 权重含 noop 层或 ETP=1,但转换命令未对应设置 | 补加相同的 --noop-layers;ETP=1 时加 --expert-tensor-parallel-size 1 |
| 超大模型转换时 OOM | 一次加载全部权重导致内存溢出 | 利用按需加载机制(自动按层读取),必要时开启 --save-layer-by-layer |
核心原则:权重转换的产出结构由训练并行配置决定,转换命令与训练脚本之间任何一项并行/特性参数不一致,都可能导致训练无法加载权重。建议在转换前以训练脚本为准,逐项核对 表 1 中标注 "✅" 的全部参数。
如需进一步了解各模型的支持范围(含下载链接与训练脚本路径),可查阅 模型支持列表;若需将 MCore 检查点转回 HuggingFace 并配合 LoRA 微调使用,可参考 DeepSeek3 转换说明 中的 LoRA 合并与分离加载示例。