MindSpeed-LLM mcore LoRA 微调实战:从权重转换、数据预处理到 CCLoRA 加速与推理验证
MindSpeed-LLM mcore LoRA 微调实战:从权重转换、数据预处理到 CCLoRA 加速与推理验证
本文基于 MindSpeed-LLM(昇腾 LLM 分布式训练框架)官方文档,完整讲解 mcore 路径下 LLM 的 LoRA(Low-Rank Adaptation)高效微调方案:以 Qwen3-8B 在 1×8(单台 Atlas 900 A2 PoD)集群为例,覆盖环境配置、HF 权重转 Megatron 权重、指令数据预处理、LoRA 训练脚本参数(lora-r、lora-alpha、lora-fusion、lora-target-modules 等)、单机/多机启动方式,以及基于 --lora-load 的 LoRA 推理验证流程;并结合仓库源码说明 LoraFeature 参数注册与 CCLoRA 通信-计算融合的实现原理,读完即可独立完成一整套 LoRA 微调与模型校验。
1. LoRA 微调核心原理与适用场景
LoRA 是一种广泛用于预训练深度学习模型的高效微调方法。传统全量微调直接更新模型全部权重,而 LoRA 的核心思想是把模型参数更新分解为低秩形式:在每一层的权重矩阵上引入两个低秩矩阵 和 ,作为更新项:
其中 是更新后的权重, 是原始(冻结)权重,、 是训练时需要学习的低秩矩阵。由于 、 的秩很低,需要训练和存储的参数数量相比全量权重大幅减少,从而显著降低显存(HBM)占用与计算开销,使中等规模集群也能对数十亿参数级别的模型做指令微调。
在 MindSpeed-LLM 的 mcore 训练路径中,LoRA 微调以 feature 插件的形式接入 Megatron 训练主流程。可以从 LoraFeature 的源码中看到,它负责注册以下训练参数,并在训练启动时通过 patch 机制接管 Megatron 的模型包装、checkpoint 保存/加载等入口:
| 参数 | 默认值 | 说明 |
|---|---|---|
--lora-target-modules |
[](空列表) |
添加 LoRA 的模块名列表 |
--lora-load |
None |
LoRA 权重 checkpoint 目录,用于断点续训或推理加载 |
--lora-r |
16 |
LoRA 秩,即低秩矩阵的维度 |
--lora-alpha |
32 |
LoRA 缩放系数,控制低秩分支对原权重的影响强度 |
--lora-modules-to-save |
None |
需要额外保存的模块(可整模块训练) |
--lora-register-forward-hook |
['word_embeddings', 'input_layernorm'] |
注册 forward hook 的模块 |
--lora-fusion |
关闭 | 启用 CCLoRA 融合加速(见第 5 节) |
--lora-ckpt-filter |
关闭 | 仅保存 LoRA 权重,不保存基座权重 |
源码中还对 LoRA 与 MoE 的组合做了约束校验(validate_args):MoE 模型使用 LoRA 时 token dispatcher 只支持 alltoall_seq,且 LoRA 与 --moe-tp-extend-ep 互斥。对于 Dense 模型(如本文的 Qwen3-8B)不受这些限制。
2. 整体流程
LoRA 微调 LLM 在 MindSpeed-LLM 中分为 6 个阶段:
- 环境安装:按 MindSpeed LLM 安装指南 完成环境部署,并加载昇腾 NPU Toolkit 相关环境变量;
- 权重与数据准备:下载 HF 格式模型权重和指令微调数据集;
- 权重转换:将 HF 权重转换为 Megatron 权重(
convert_ckpt_v2.py); - 数据预处理:将指令数据集转换为 Megatron 二进制索引格式(
preprocess_data.py); - LoRA 训练:配置并运行微调脚本(
posttrain_gpt.py),可单机/多机执行; - 推理验证:在基础推理脚本上叠加 LoRA 参数,检查模型输出是否符合预期。
3. 环境准备与模型/数据准备
3.1 环境配置
安装环境后,训练前需配置昇腾 NPU Toolkit 相关环境变量(路径按实际安装位置替换):
source /usr/local/Ascend/cann/set_env.sh # 替换为实际 Toolkit 安装路径
source /usr/local/Ascend/nnal/atb/set_env.sh # 替换为实际 nnal 包安装路径
3.2 模型权重
模型权重可从 PyTorch 框架支持模型 文档中对应模型的下载入口获取。以 Qwen3-8B 为例,完整的模型目录应包含以下文件:
.
├── README.md # 模型文档
├── config.json # 模型架构配置文件
├── generation_config.json # 文本生成配置
├── merges.txt # Tokenizer 合并规则
├── model-00001-of-00005.safetensors # 权重分片 1/5
├── model-00002-of-00005.safetensors # 权重分片 2/5
├── model-00003-of-00005.safetensors # 权重分片 3/5
├── model-00004-of-00005.safetensors # 权重分片 4/5
├── model-00005-of-00005.safetensors # 权重分片 5/5
├── model.safetensors.index.json # 权重分片索引
├── tokenizer.json # Hugging Face 格式 tokenizer
├── tokenizer_config.json # tokenizer 配置
└── vocab.json # 词表文件
3.3 微调数据集
本例使用 Alpaca 单样本指令数据集(train-00000-of-00001-a09b74b3ef9c3b56.parquet)。LoRA 微调脚本使用单样本格式数据。
4. 权重转换:HF 转 Megatron
LoRA 微调脚本使用标准 Megatron 格式基座权重,因此需要先把 HF 权重转换为 Megatron 权重。详细配置见 Qwen3 权重转换脚本,需要修改相关路径参数和模型切分设置:
source /usr/local/Ascend/cann/set_env.sh # 替换为实际 Toolkit 安装路径
......
--target-tensor-parallel-size 1 # TP 切分数
--target-pipeline-parallel-size 2 # PP 切分数
--load-dir ./model_from_hf/qwen3_hf/ # Hugging Face 权重路径
--save-dir ./model_weights/qwen3_mcore/ # Megatron 权重保存路径
仓库中该脚本的默认配置为 --target-tensor-parallel-size 1 --target-pipeline-parallel-size 8,实际使用时请将其改为与后续训练脚本一致的切分(本文训练脚本为 TP=1、PP=2)。确认路径正确后执行:
bash examples/mcore/qwen3/ckpt_convert_qwen3_hf2mcore.sh
关键约束:训练参数中的并行配置(TP、PP)必须与权重转换时的切分配置一致,否则加载会失败。
5. 数据预处理
数据预处理将原始指令数据 tokenize 并打包为 Megatron 二进制数据集,详细配置见 Qwen3 指令数据预处理脚本。需要修改脚本中的如下路径:
source /usr/local/Ascend/cann/set_env.sh # 替换为实际 Toolkit 安装路径
......
--input ./dataset/train-00000-of-00001-a09b74b3ef9c3b56.parquet # 原始数据集路径
--tokenizer-name-or-path ./model_from_hf/qwen3_hf # HF tokenizer 路径
--output-prefix ./finetune_dataset/alpaca # 保存路径
......
数据预处理关键参数说明:
| 参数 | 说明 |
|---|---|
handler-name |
数据集 handler 类,常见取值 AlpacaStyleInstructionHandler、SharegptStyleInstructionHandler、AlpacaStylePairwiseHandler |
tokenizer-type |
处理数据使用的 tokenizer 类型,常见取值 PretrainedFromHF |
workers |
并行处理数据集的工作进程数 |
log-interval |
每隔多少条打印一次进度日志 |
enable-thinking |
开关“快思考/慢思考”模板。取值为 [true, false, none],默认 none。启用后,数据集模型回复中会加入 think//think 标记并计入 loss(所有数据按慢思考数据处理);禁用后会在用户输入中插入空的 CoT 标记且不计算 loss(所有数据按快思考数据处理);设为 none 适合原始数据本身混合了快/慢思考的情况。注意该选项目前仅支持 Qwen3 系列模型 |
prompt-type |
指定模型对话模板,帮助基座模型微调后获得更强对话能力,可用取值见 templates.json(含 qwen3、glm4、chatml、llama3 等 30+ 模板) |
参数配置完成后执行:
bash examples/mcore/qwen3/data_convert_qwen3_instruction.sh
预处理完成后会生成带后缀的文件,例如 ./finetune_dataset/alpaca/alpaca_packed_input_ids_document.bin。
6. 配置 LoRA 微调训练脚本
完整参数见 Qwen3-8B LoRA 微调脚本;脚本中各环境变量的说明见 模型脚本环境变量文档。再次强调:训练参数的 TP/PP 必须与权重转换时的配置一致。
6.1 单机配置
# 单机配置
NPUS_PER_NODE=8
MASTER_ADDR=localhost
MASTER_PORT=6000
NNODES=1
NODE_RANK=0
WORLD_SIZE=$(($NPUS_PER_NODE * $NNODES))
确认环境变量正确后,修改路径参数和模型切分设置:
CKPT_LOAD_DIR="your model ckpt path" # 权重加载路径,填权重转换时的保存路径
CKPT_SAVE_DIR="your model save ckpt path" # LoRA 微调结束后的权重保存路径
DATA_PATH="your data path" # 数据集路径,填数据预处理保存路径(只需前缀,不含后缀)
TOKENIZER_PATH="your tokenizer path" # 词表路径,填下载开源权重中的词表路径
TP=1 # 权重转换时 target-tensor-parallel-size 的取值
PP=2 # 权重转换时 target-pipeline-parallel-size 的取值
脚本内的关键训练参数(与仓库示例脚本 tune_qwen3_8b_4K_lora_ptd.sh 一致):
DATA_PATH:数据预处理生成的实际文件会附加_input_ids_document等后缀,因此该参数只需填数据集前缀。例如实际文件相对路径为./finetune_dataset/alpaca/alpaca_packed_input_ids_document.bin,则填./finetune_dataset/alpaca/alpaca;is-instruction-dataset:声明使用的是指令微调数据,保证按指令形式进行微调;prompt-type:指定模型模板(示例中为qwen3),帮助基座模型微调后具备更强对话能力;no-pad-to-seq-lengths:支持动态序列长度微调。默认按 8 的倍数做 padding,可通过--pad-to-multiple-of修改 padding 倍数;lora-r:LoRA 秩,即低秩矩阵维度。秩越小,训练中更新的参数越少,计算与显存消耗越低;但秩过小会限制模型表达能力。示例取16;lora-alpha:控制 LoRA 权重对原权重的影响强度,值越大影响越强。一般保持α/r = 2,示例取32;lora-fusion:是否启用 CCLoRA 算法,通过通信与计算重叠提升性能。当前 GLM-4.5 模型不支持该参数;lora-target-modules:选择添加 LoRA 的模块,当前可用模块为linear_qkv、linear_proj、linear_fc1、linear_fc2。
示例脚本中还包含典型优化参数(--use-flash-attn、--use-fused-swiglu、--use-fused-rmsnorm、--use-distributed-optimizer 等)与训练超参(micro-batch-size 4、global-batch-size 16、lr 1.25e-5、bf16、seq-length 4096、train-iters 2000),以及 Qwen3-8B 的模型结构参数(36 层、hidden 4096、GQA 8 组等),可通过脚本文件直接复用。
6.2 启动训练
单机执行时,仅在一台机器上启动:
bash examples/mcore/qwen3/tune_qwen3_8b_4K_lora_ptd.sh
多机执行时,在单机脚本基础上修改以下参数:
# 多机配置
# 按实际集群配置分布式参数
NPUS_PER_NODE=8 # 每个节点上的 NPU 数量
MASTER_ADDR="your master node IP address" # 主节点 IP,勿使用 localhost
MASTER_PORT=6000
NNODES=2 # 集群节点数,按实际填写
NODE_RANK="current node ID" # 当前节点 RANK,节点间必须唯一;主节点为 0,其余节点依次为 1、2……
WORLD_SIZE=$(($NPUS_PER_NODE * $NNODES))
确认每台机器上的模型路径与数据集路径正确后,在多台机器的多个终端同时启动脚本即可开始训练。
7. 源码纵深:CCLoRA 融合加速与 LoRA 权重处理
启用 --lora-fusion 后,MindSpeed-LLM 通过 cc_lora_forward.py 中的自定义 autograd Function(如 _FusedColumnSeqParallelLoRAFunction)实现 CCLoRA 加速,其要点(可对照 CCLoRA 特性文档):
- 双流水线:将原权重分支与低秩更新分支的串行前向/反向重构为通信-计算重叠的双流水线;
- 数学等价变换合并通信:例如在 SP + RowParallel 场景下,,可直接复用 MC2 计算中已产生的
all_gather(grad_y),省掉一次独立通信; - scaling 逻辑优化:按
BS < H/BS ≥ H两种情况分别选择Y = Wx + B(λAx)或Y = (W + BλA)x的计算路径,把weight + b @ a_scale合并为一次矩阵乘。
从 lora/utils.py 的源码还可以看到两类工程细节:
filter_lora_keys:保存 checkpoint 时过滤出 key 中含lora的参数(对应--lora-ckpt-filter,只保存 LoRA 权重,显著减小落盘体积),并兼容虚拟流水线并行(VPP)下的model{i}多个子字典;dispatch_megatron_wrapper:适配 peftLoraLayer.dispatch_megatron的调用签名,保证在 Megatron 分布式层上正确挂载 LoRA。
需要说明的是,CCLoRA 与 --overlap-param-gather 特性存在冲突,二者不要同时使用;对 RC2 及以后版本,LoRA 微调场景兼容 PP、VPP、分布式优化器等配置。
8. 模型验证:LoRA 推理
LoRA 微调完成后,需验证模型输出是否符合预期。仓库提供了基础推理脚本 Qwen3-8B 推理脚本。LoRA 推理需要在该脚本基础上叠加 LoRA 相关参数——可将脚本另存为 generate_qwen3_8b_lora_ptd.sh(以 Qwen3-8B 为例)。修改路径参数并加入 LoRA 参数:
TOKENIZER_PATH="your tokenizer directory path" # 词表路径,填下载开源权重中的词表路径
CHECKPOINT="your model directory path" # 权重加载路径,填权重转换时的保存路径
CHECKPOINT_LORA="your lora model directory path" # LoRA 微调结束后的权重保存路径
......
--lora-load ${CHECKPOINT_LORA} \
--lora-r 16 \
--lora-alpha 32 \
--lora-fusion \
--lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \
--prompt-type qwen3 \
......
| tee logs/generate_qwen3_8b_lora_ptd.log # 对应日志文件名
参数说明:
lora-load:加载 LoRA 权重,用于从 checkpoint 恢复训练或推理。推理时需配合--load(指向CKPT_LOAD_DIR的基座权重)使用,从CKPT_SAVE_DIR路径加载 LoRA 权重;lora-r、lora-alpha、lora-fusion、lora-target-modules:取值需与训练时一致,保证权重形状匹配。
参数配置完成后运行:
bash examples/mcore/qwen3/generate_qwen3_8b_lora_ptd.sh
预期结果:模型能正确回答数据集中的问题,输出无乱码、无重复,即表明 LoRA 微调流程验证通过。
9. 小结
本文以官方文档 docs/en/pytorch/training/finetune/mcore/lora_finetune.md 为主线,梳理了 MindSpeed-LLM mcore 路径 LoRA 微调的完整落地链路:set_env.sh 环境 → HF/Megatron 权重转换(TP/PP 对齐)→ 指令数据预处理(handler、enable-thinking、prompt-type)→ LoRA 训练(lora-r/lora-alpha/lora-target-modules/lora-fusion)→ 单机/多机启动 → --lora-load 推理验证;并结合 LoraFeature、cc_lora_forward.py 等源码补充了参数注册、MoE 约束校验、CCLoRA 通信融合与 checkpoint 过滤的实现依据。按此流程执行,即可在昇腾集群上完成一套可复现、可验证的 LLM LoRA 高效微调。

