MindSpeed-LLM mcore LoRA 微调实战:从权重转换、数据预处理到 CCLoRA 加速与推理验证

原创2026-10-13 15:19:281,826 阅读
文章标签:人工智能大模型分布式训练预训练微调强化学习LoRA深度学习AscendCANN

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 微调与模型校验。

LoRA 权重更新结构:冻结原权重 W,新增可训练低秩矩阵 A 与 B

LoRA 微调整体流程:权重准备、权重转换、数据预处理、LoRA 训练、推理验证

1. LoRA 微调核心原理与适用场景

LoRA 是一种广泛用于预训练深度学习模型的高效微调方法。传统全量微调直接更新模型全部权重,而 LoRA 的核心思想是把模型参数更新分解为低秩形式:在每一层的权重矩阵上引入两个低秩矩阵 AA 和 BB,作为更新项:

W′=W+A⋅BW' = W + A \cdot B

其中 W′W' 是更新后的权重,WW 是原始(冻结)权重,AA、BB 是训练时需要学习的低秩矩阵。由于 AA、BB 的秩很低,需要训练和存储的参数数量相比全量权重大幅减少,从而显著降低显存(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 个阶段:

  1. 环境安装:按 MindSpeed LLM 安装指南 完成环境部署,并加载昇腾 NPU Toolkit 相关环境变量;
  2. 权重与数据准备:下载 HF 格式模型权重和指令微调数据集;
  3. 权重转换:将 HF 权重转换为 Megatron 权重(convert_ckpt_v2.py);
  4. 数据预处理:将指令数据集转换为 Megatron 二进制索引格式(preprocess_data.py);
  5. LoRA 训练:配置并运行微调脚本(posttrain_gpt.py),可单机/多机执行;
  6. 推理验证:在基础推理脚本上叠加 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 特性文档):

  1. 双流水线:将原权重分支与低秩更新分支的串行前向/反向重构为通信-计算重叠的双流水线;
  2. 数学等价变换合并通信:例如在 SP + RowParallel 场景下,grada=all_gather(grady⋅B)=all_gather(grady)⋅B\mathrm{grad}_a = \mathrm{all\_gather}(\mathrm{grad}_y \cdot B) = \mathrm{all\_gather}(\mathrm{grad}_y) \cdot B,可直接复用 MC2 计算中已产生的 all_gather(grad_y),省掉一次独立通信;
  3. 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:适配 peft LoraLayer.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 高效微调。

登录后查看全文
MindSpeed-LLM