MindSpeed-LLM/docs/features/checkpoint.md-代码预览-MindSpeed-LLM:基于昇腾生态的大语言模型分布式训练套件

Ii-robot!2703 up date merge lora of readme of ckpt in 2.0.0

fcfcb6d5创建于 2025年5月26日历史提交

权重转换特性清单

MindSpeed-LLM 支持 Huggingface、Megatron-Legacy 以及 Megatron-Core 之间的权重格式互转，具体功能列表如下:

源格式	目标格式	支持特性	特性入参
HuggingFace	Megatron-Legacy	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		流水并行动态划分	--num-layer-list
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
	Megatron-Core	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		流水并行动态划分	--num-layer-list
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
		专家并行	--target-expert-model-parallel-size
		自定义空操作层	--noop-layers
Megatron-Legacy	Huggingface	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		LoRA训练模块	--lora-target-modules
		LoRA权重	--lora-load
		LoRA r	--lora-r
		LoRA alpha	--lora-alpha
	Megatron-Core	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		流水并行动态划分	--num-layer-list
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
	Megatron-Legacy	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		LoRA训练模块	--lora-target-modules
		LoRA权重	--lora-load
		LoRA r	--lora-r
		LoRA alpha	--lora-alpha
Megatron-Core	Huggingface	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		LoRA训练模块	--lora-target-modules
		LoRA权重	--lora-load
		LoRA r	--lora-r
		LoRA alpha	--lora-alpha
	Megatron-Legacy	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		流水并行动态划分	--num-layer-list
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
	Megatron-Core	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		专家并行	--target-expert-model-parallel-size
		流水并行动态划分	--num-layer-list
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
		LoRA训练模块	--lora-target-modules
		LoRA权重	--lora-load
		LoRA r	--lora-r
		LoRA alpha	--lora-alpha
		自定义空操作层	--noop-layers
	distributed-optimizer	张量并行	--target-tensor-parallel-size
		流水并行	--target-pipeline-parallel-size
		专家并行	--target-expert-model-parallel-size
		虚拟流水并行	--num-layers-per-virtual-pipeline-stage
		流水并行动态划分	--target-expert-model-parallel-size
		自定义空操作层	--noop-layers

权重转换使用

1. 权重下载

从Huggingface等网站下载开源模型权重

预训练权重链接在稠密模型和MoE模型章节列表的参数列链接中可以获取；更多社区资源可以在模型列链接中获取，如Chat/Instruct权重等。

权重可以基于网页直接下载，也可以基于命令行下载，保存到MindSpeed-LLM/model_from_hf目录，比如：

#!/bin/bash
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 ../../

2. 权重转换

2.1 Huggingface权重转换到Megatron-LM格式

python convert_ckpt.py \
    --model-type GPT \
    --load-model-type hf \
    --save-model-type mg \
    --target-tensor-parallel-size 2 \
    --target-pipeline-parallel-size 4 \
    --num-layer-list 8,8,8,8 \
    --model-type-hf llama2 \
    --use-mcore-models \
    --load-dir ./model_from_hf/llama-2-7b-hf/ \
    --save-dir ./model_weights/llama-2-7b-mcore/ \
    --tokenizer-model ./model_from_hf/llama-2-7b-hf/tokenizer.model

参数	说明	可选/必选
--target-tensor-parallel-size	TP 切分数量，默认为 1	必选
--target-pipeline-parallel-size	PP 切分数量，默认为 1	必选
--num-layer-list	动态PP划分，通过列表指定每个PP Stage的层数，默认为None	可选
--num-layers-per-virtual-pipeline-stage	VPP划分，指定VPP的每个Stage层数，默认为None	可选
--target-expert-model-parallel-size	专家并行，指定专家并行卡数，默认为1	可选
--noop-layers	自定义空层操作，指定在模型某层增加空层，转换后层数为原huggingface模型层数+空层数，默认为None	可选
--use-mcore-models	转换为Megatron-Mcore权重，若不指定，则默认转换为Megatron-Legacy权重	可选
--model-type-hf	huggingface模型类别，默认为llama2	可选
--tokenizer-model	需要指明到具体的分词器模型文件，如 tokenizer.model、tokenizer.json、qwen.tiktoken、None等，具体取决于huggingface中词表文件的格式形式	必选
--params-dtype	指定权重转换后的权重精度模式，默认为fp16，如果源格式文件为bf16，则需要对应设置为bf16，影响推理或评估结果	必选

注意：

1、VPP和动态PP划分只能二选一

2、目前支持的模型见 model_cfg.json

【启动脚本】

MindSpeed-LLM Huggingface到Megatron-Legacy权重转换脚本命名风格及启动方法为：

# 命名及启动：
# bash examples/legacy/model_name/ckpt_convert_xxx_hf2legacy.sh
# 需要配置并行参数以及权重词表加载保存等路径

bash examples/legacy/llama2/ckpt_convert_llama2_hf2legacy.sh

MindSpeed-LLM Huggingface到Megatron-Mcore权重转换脚本命名风格及启动方法为：

# 命名及启动：
# bash examples/mcore/model_name/ckpt_convert_xxx_hf2mcore.sh
# 需要配置并行参数以及权重词表加载保存等路径

bash examples/mcore/llama2/ckpt_convert_llama2_hf2mcore.sh

2.2 Megatron-LM权重转换到Huggingface格式

python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type hf \
    --model-type-hf llama2 \
    --use-mcore-models \
    --load-dir ./model_weights/llama-2-7b-mcore/ \
    --target-tensor-parallel-size 1 \
    --target-pipeline-parallel-size 1 \
    --save-dir ./model_from_hf/llama-2-7b-hf/  # <-- 需要填入原始HF模型路径，新权重会存于./model_from_hf/llama-2-7b-hf/mg2hf/

参数意义参考2.1

【启动脚本】

MindSpeed-LLM Megatron-Legacy到Huggingface的权重转换脚本命名风格及启动方法为：

# 命名及启动：
# bash examples/legacy/model_name/ckpt_convert_xxx_legacy2hf.sh
# 需要配置并行参数以及权重词表加载保存等路径

bash examples/legacy/llama2/ckpt_convert_llama2_legacy2hf.sh

MindSpeed-LLM Megatron-Mcore到Huggingface的权重转换脚本命名风格及启动方法为：

# 命名及启动：
# bash examples/mcore/model_name/ckpt_convert_xxx_mcore2hf.sh
# 需要配置并行参数以及权重词表加载保存等路径

bash examples/mcore/llama2/ckpt_convert_llama2_mcore2hf.sh

2.3 Megatron-LM格式权重互转

# legacy转legacy
python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type mg \
    --target-tensor-parallel-size 2 \
    --target-pipeline-parallel-size 2 \
    --load-dir ./model_weights/llama-2-7b-legacy/ \
    --save-dir ./model_weights/llama-2-7b-legacy_tp2pp2/

# legacy转mcore
python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type mg \
    --use-mcore-models \
    --load-from-legacy \
    --target-tensor-parallel-size 2 \
    --target-pipeline-parallel-size 2 \
    --load-dir ./model_weights/llama-2-7b-legacy/ \
    --save-dir ./model_weights/llama-2-7b-mcore_tp2pp2/

# mcore转mocre
python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type mg \
    --use-mcore-models \
    --target-tensor-parallel-size 2 \
    --target-pipeline-parallel-size 2 \
    --load-dir ./model_weights/llama-2-7b-mcore/ \
    --save-dir ./model_weights/llama-2-7b-mcore_tp2pp2/

# mcore转legacy
python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type mg \
    --use-mcore-models \
    --save-to-legacy \
    --target-tensor-parallel-size 2 \
    --target-pipeline-parallel-size 2 \
    --load-dir ./model_weights/llama-2-7b-mcore/ \
    --save-dir ./model_weights/llama-2-7b-legacy_tp2pp2/

参数	说明	可选/必选
--load-from-legacy	legacy转mcore时设置此参数以指定导入权重格式为legacy	可选
--save-to-legacy	mcore转legacy时设置此参数以指定保存权重格式为legacy	可选
--noop-layers	自定义空层操作，权重转换当前只支持mcore-mcore、hf-mcore、优化器权重转换，在mcore-mcore时，空层参数不能更改，只能更改并行方式，同时需要设置参数--load-checkpoint-loosely	可选
--load-checkpoint-loosely	允许松弛加载，在带有空层的mcore-mcore权重转换时，需要设置此参数	可选

其余参数意义参考2.1

注：上述权重legacy和mcore互转为高阶功能，MindSpeed-LLM基于llama2提供基础能力，并进行版本迭代看护.对于其他模型的支持，用户需根据实际需求自行进行修改与适配。

2.4 lora权重与base权重合并

2.4.1 Megatron-Legacy格式权重合并

在上述权重转换命令中，加入如下参数可以将训练的lora权重与base进行融合。

--lora-load ./ckpt/llama-2-7b-lora  \
--lora-r 16 \
--lora-alpha 32 \
--lora-target-modules query_key_value dense dense_h_to_4h dense_4h_to_h \

参数	说明	可选/必选
--lora-load	加载 lora 微调后生成的权重	可选
--lora-r	LoRA中的秩（rank），它决定了低秩矩阵的大小	可选
--lora-alpha	定义了LoRA适应的学习率缩放因子。这个参数影响了低秩矩阵的更新速度	可选
--lora-target-modules	定义了Lora目标模块，字符串列表，由空格隔开，无默认值。每一个字符串是需要进行LoRA微调的层的名称。	可选

【合并后转换为Megatron-Legacy权重】

python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type mg \
    --load-dir ./model_weights/llama-2-7b-legacy/ \
    --lora-load ./ckpt/llama-2-7b-lora \
    --lora-r 16 \
    --lora-alpha 32 \
    --lora-target-modules query_key_value dense dense_h_to_4h dense_4h_to_h \
    --target-tensor-parallel-size 1 \
    --target-pipeline-parallel-size 1 \
    --save-dir ./model_weights/llama-2-7b-lora2legacy

转换脚本命名风格及启动方法为：

# 命令启动方式以 legacy 下的模型 llama2 为例
bash examples/legacy/llama2/ckpt_convert_llama2_legacy2legacy_lora.sh

【合并后转换为Huggingface权重】

python convert_ckpt.py \
    --model-type GPT \
    --load-model-type mg \
    --save-model-type hf \
    --load-dir ./model_weights/llama-2-7b-legacy/ \
    --lora-load ./ckpt/llama-2-7b-lora \
    --lora-r 16 \
    --lora-alpha 32 \
    --lora-target-modules query_key_value dense dense_h_to_4h dense_4h_to_h \
    --target-tensor-parallel-size 1 \
    --target-pipeline-parallel-size 1 \
    --save-dir ./model_from_hf/llama-2-7b-hf/    # <-- 需要填入原始HF模型路径，新权重会存于./model_from_hf/llama-2-7b-hf/mg2hg/

转换脚本命名风格及启动方法为：

#命令启动方式以 legacy 下的模型 llama2 为例
bash examples/legacy/llama2/ckpt_convert_llama2_legacy2hf_lora.sh

2.4.2 Megatron-Mcore格式权重合并

在上述权重转换命令中，加入如下参数可以将训练的lora权重与权重转换出的base权重进行融合。

--lora-load ./ckpt/llama-2-7b-lora  \
--lora-r 16 \
--lora-alpha 32 \
--lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \

参数含义同2.4.1

【合并后转换为Megatron-Mcore权重】

python convert_ckpt.py \
    --model-type GPT \
    --use-mcore-models \
    --load-model-type mg \
    --save-model-type mg \
    --load-dir ./model_weights/llama-2-7b-mcore/ \
    --lora-load ./ckpt/llama-2-7b-lora \
    --lora-r 16 \
    --lora-alpha 32 \
    --lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \
    --target-tensor-parallel-size 1 \
    --target-pipeline-parallel-size 1 \
    --save-dir ./model_weights/llama-2-7b-lora2mcore

转换脚本命名风格及启动方法为：

#命令启动方式以 mcore 下的模型 llama2 为例
bash examples/mcore/llama2/ckpt_convert_llama2_mg2mg_lora.sh

【合并后转换为Huggingface权重】

python convert_ckpt.py \
    --model-type GPT \
    --use-mcore-models \
    --load-model-type mg \
    --save-model-type hf \
    --load-dir ./model_weights/llama-2-7b-mcore/ \
    --lora-load ./ckpt/llama-2-7b-lora \
    --lora-r 16 \
    --lora-alpha 32 \
    --lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \
    --target-tensor-parallel-size 1 \
    --target-pipeline-parallel-size 1 \
    --save-dir ./model_from_hf/llama-2-7b-hf/    # <-- 需要填入原始HF模型路径，新权重会存于./model_from_hf/llama-2-7b-hf/mg2hg/

转换脚本命名风格及启动方法为：

#命令启动方式以 mcore 下的模型 llama2 为例
bash examples/mcore/llama2/ckpt_convert_llama2_mcore2hf_lora.sh

注意：

lora参数值需与lora微调时的参数保持一致,且lora权重的切分方式需与base权重的切分方式保持一致。

由于调用peft库合并lora权重后，权重数据类型为float16，但是部分模型如qwen系列模型，默认数据类型为bfloat16，合并后的权重转回hf格式会有精度损失问题。可以将原始HF模型的config.json中的数据类型改为float16暂时规避。

2.5 优化器权重转换

在权重转换脚本中指定--load-model-type参数为optim , 则为优化器权重转换

使用方法：

1.准备预训练权重

转换前权重为预训练存储权重，并且需要在预训练脚本中加入参数--use-distributed-optimizer ,并且删除参数--no-save-optim 使训练生成的每个权重文件夹都包括model_optim_rng.pt和distrib_optim.pt两个权重文件。

2.mg-mg权重转换

优化器权重需要先做一次mg-mg的权重转换，并指定所需的切分方式，脚本参考2.3中mcore-mcore脚本：

    python convert_ckpt.py \
        --model-type GPT \
        --load-model-type mg \
        --save-model-type mg \
        --target-tensor-parallel-size 4 \
        --target-pipeline-parallel-size 2 \
        --load-dir ./ckpt/llama2-7b-tp2pp4 \
        --save-dir ./ckpt/llama2-7b-tp4pp2-optim \
        --use-mcore-models

在此步骤完成后，--save-dir 中应该会生成 model_optim_rng.pt 格式的权重文件。

3.权重转换优化器:

完成上述步骤后，可以执行优化器权重转换。此时，指定 --load-model-type optim 参数来加载优化器权重，并进行转换。

注意：并行配置如：TP、PP、EP、VPP、num-layer-list、noop-layers等参数需要与mcore-mcore权重转换脚本相同。

python convert_ckpt.py
--model-type GPT
--load-model-type optim
--load-dir ./ckpt/llama2-7b-tp2pp4
--target-tensor-parallel-size 4
--target-pipeline-parallel-size 2
--save-dir ./ckpt/llama2-7b-tp4pp2-optim
--use-mcore-models
--model-type-hf llama2

参数	说明	可选/必选
--save-dir	权重保存路径，需要与`mg-mg`转换时的保存路径一致	必选
--load-model-type	指定加载模型的方式。对于优化器权重转换，必须设置参数值为`optim`	必选
--moe-grouped-gemm	对于moe模型，如果在预训练脚本和mcore-mcore权重转换脚本中加入此参数`--moe-grouped-gemm` ，则在优化器权重转换脚本中，也需要加入该参数。	可选

转换脚本命名风格及启动方法为：

# 命令启动方式以 mcore 下的模型llama2为例子
bash examples/mcore/llama2/ckpt_convert_llama2_optim.sh

注意：

优化器权重转换当前只验证过模型：

llama2-7b支持TP、PP、EP、VPP、DPP、noop-layers；

deepseek-lite支持PP、EP、DPP、noop-layers。