CANN 昇腾 NPU 上基于 MindSpeed-LLM 的 Qwen3-1.7B 全参数 SFT 微调实战指南

CANN 昇腾 NPU 上基于 MindSpeed-LLM 的 Qwen3-1.7B 全参数 SFT 微调实战指南【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train本篇指南围绕 cann-recipes-train 仓库中的 llm_sft/qwen3/README_EN.md 及其配套脚本完整讲解在单张 Atlas A3 昇腾 NPU 上以 MindSpeed-LLM 为训练框架跑通 Qwen3-1.7B 全参数监督微调SFT的一站式链路。读完本文你将掌握「数据转换 → HuggingFace 权重转 Mcore 格式 → 启动 SFT 训练 → 权重转回 HuggingFace」四大步骤的完整实操命令、每个脚本的关键参数含义以及 Docker 与一站式平台两种环境构建方式可直接复制脚本在自有环境或 CANNLab 一站式开发平台上复现本样例。一、样例概览与整体链路本样例是 cann-recipes-train 中「监督微调SFT」入口的代表样例见仓库根目录 README.md 的样例列表面向单卡快速验证模型、数据与训练流程。它以Qwen3-1.7B 稠密模型 Alpaca 指令数据集为载体展示 MindSpeed-LLM 在昇腾 NPU 上的完整微调路径。整个 SFT 链路共分四步前两步是训练前的数据与权重准备后两步是训练本身及产物复原数据转换把 Alpaca 原始 parquet 数据转成训练可读的 mmap 格式并套用 Qwen3 模板模型转换HF → Mcore把 HuggingFace 格式权重按目标并行配置切分为 Megatron-CoreMcore训练格式SFT 训练使用posttrain_gpt.py加载转换后的权重与数据执行全参微调模型转换Mcore → HF把训练产出的 Mcore 检查点还原为 HuggingFace 格式便于后续推理与部署。对应脚本均位于仓库 llm_sft/qwen3/qwen3_dense/ 目录下四个脚本分别是data_convert_qwen3_instruction.sh、ckpt_convert_qwen3_hf2mcore.sh、tune_qwen3_4K_full_A3_ptd.sh、ckpt_convert_qwen3_mcore2hf.sh。二、硬件与环境要求按文档声明本样例的硬件要求为卡数1 张 Atlas A3示例脚本默认NPUS_PER_NODE1。环境方面有两种入口按部署方式选择其一方式环境前置条件Docker 构建基于 Dockerfile.cann.mindspeed.qwen3 自建镜像已有可运行的昇腾驱动与容器运行时一站式平台CANNLab 一站式开发平台镜像选CANN-8.5.0-A3或CANN-8.5.0-A2平台浏览器环境即可无需自建镜像一站式平台为「快速跑通第一个训练样例」推荐路径仓库根 README 亦将本样例列为 A2/A3 单卡 SFT 的快速启动入口。三、环境构建详解3.1 方式一基于 Dockerfile 构建镜像先在llm_sft/qwen3/目录下基于 Dockerfile.cann.mindspeed.qwen3 构建镜像并进入容器# 构建镜像传入镜像名称例如 qwen3_sft docker build -t qwen3_sft -f Dockerfile.cann.mindspeed.qwen3 . # 创建并进入容器container_nameqwen3_sft, image_nameqwen3_sft:latest bash build_docker.sh打开 Dockerfile.cann.mindspeed.qwen3 可以看到镜像内部已固化好整套训练依赖这是本样例可复现的关键基础镜像quay.io/ascend/cann:8.5.0-a3-openeuler24.03-py3.11即 CANN 8.5.0 OpenEuler 24.03 Python 3.11硬件规格SOC_VERSIONascend910_9391对应 Atlas A3 的 910C 芯片型号PyTorch 栈torch2.8.0与torch-npu2.8.0.post2以及torchvision0.23.0训练框架MindSpeedmaster 分支以pip install -e .方式安装、MindSpeed-LLM固定 commit6fe0df7f...、Megatron-LM固定 tagcore_v0.12.1其megatron目录被复制进 MindSpeed-LLM 内数据与模型生态transformers5.1.0、datasets2.16.0环境变量TASK_QUEUE_ENABLE1、OMP_NUM_THREADS1一并写入镜像。关于 build_docker.sh 需要注意默认的docker run按单机 16 卡配置挂载了/dev/davinci0/dev/davinci15及 davinci_manager、devmm_svm、hisi_hdc 等设备。文档明确提示本样例只需 1 张卡请按实际环境把--device/dev/davinciX裁剪为所需卡数同时保持--nethost、/usr/local/dcmi、npu-smi、驱动目录、/dev/shm等挂载项不变。容器创建后通过docker exec -it -u root qwen3_sft bash进入。进入容器后准备源码# 下载本样例所在代码仓以 master 分支为例 git clone https://gitcode.com/cann/cann-recipes-train.git # 在样例目录下添加镜像中已准备好的依赖并把样例脚本复制进 MindSpeed-LLM 的 examples/mcore cd ./cann-recipes-train/llm_sft/qwen3/ cp -r /workspace/MindSpeed-LLM MindSpeed-LLM cp -r qwen3_dense MindSpeed-LLM/examples/mcore cd MindSpeed-LLM注意/workspace/MindSpeed-LLM是镜像内已构建好的框架源码即 3.1 节 Dockerfile 中 clone 的工程将其复制到当前目录后样例脚本才能以examples/mcore/qwen3_dense/xxx.sh的相对路径运行。3.2 方式二一站式平台快速启动在仓库的llm_sft/qwen3/目录下直接执行bash build_project_platform.sh # 进入对应目录 cd MindSpeed-LLMbuild_project_platform.sh 面向已具备 CANN 8.5.0 的一站式平台环境做了全自动装配其内部动作包括pip install torch2.8.0 torch-npu2.8.0.post2clone MindSpeedmaster并以可编辑模式安装clone MindSpeed-LLM固定 commit与 Megatron-LMcore_v0.12.1把 Megatron-LM 的megatron目录并入 MindSpeed-LLM安装torchvision0.23.0、transformers5.1.0、datasets2.16.0、setuptools79.0.1并卸载scikit-learn避免与 CANN 环境依赖冲突cp -r qwen3_dense MindSpeed-LLM/examples/mcore完成样例脚本装配source /home/developer/Ascend/cann-8.5.0/set_env.sh激活 CANN 环境。对比可见两种方式最终都落在「MindSpeed-LLM Megatron core_v0.12.1 qwen3_dense 脚本」同一套运行环境上后续训练步骤完全一致。四、数据与模型权重准备4.1 Alpaca 数据集准备# 在样例目录下创建数据集目录 mkdir -p ./dataset cd dataset/ # 安装 modelscope 并从魔塔社区下载 Alpaca 的 parquet 文件 pip install modelscope modelscope download --dataset OmniData/alpaca --local_dir ./alpaca cd ../下载完成后./dataset/alpaca/下即为后续数据转换脚本的输入目录。4.2 Qwen3-1.7B 权重准备# 从魔塔社区下载基础模型文件到 ./Qwen3-1.7B mkdir ./Qwen3-1.7B modelscope download --model Qwen/Qwen3-1.7B --local_dir ./Qwen3-1.7B该目录既作为 HF → Mcore 转换的输入也作为数据转换脚本的 tokenizer 路径以及训练脚本的TOKENIZER_PATH。五、SFT 训练四步实操以下命令均在MindSpeed-LLM/目录下执行样例脚本位于examples/mcore/qwen3_dense/。5.1 第一步数据转换bash examples/mcore/qwen3_dense/data_convert_qwen3_instruction.sh该脚本调用框架内的preprocess_data.py具体执行内容见 data_convert_qwen3_instruction.shmkdir ./finetune_dataset python ./preprocess_data.py \ --input ./dataset/alpaca/data/train-00000-of-00001-a09b74b3ef9c3b56.parquet \ --tokenizer-name-or-path ./Qwen3-1.7B \ --output-prefix ./finetune_dataset/alpaca \ --handler-name AlpacaStyleInstructionHandler \ --tokenizer-type PretrainedFromHF \ --workers 4 \ --log-interval 1000 \ --enable-thinking true \ --prompt-type qwen3参数含义对照参数作用--input输入数据文件路径可为目录处理目录内全部文件或单个文件支持.parquet/.csv/.json/.jsonl/.txt/.arrow格式同一目录下文件格式必须一致--tokenizer-name-or-pathtokenizer 文件路径此处指向下载好的./Qwen3-1.7B--output-prefix输出数据文件前缀生成./finetune_dataset/alpaca开头的 mmap 数据集--handler-name数据处理 HandlerAlpaca 风格数据集须指定AlpacaStyleInstructionHandler配合--map-keys提取对应列--tokenizer-type使用PretrainedFromHF从 HuggingFace 配置加载 tokenizer--enable-thinking是否添加推理标签如think /think本样例置为true--prompt-type指定模型 prompt 模板默认qwen3--workers/--log-interval并行处理进程数4与日志打印间隔1000Alpaca 风格数据示例字段说明[ { instruction: Human instruction (required), input: Human input (optional), output: Model response (required), system: System prompt (optional), history: [ [First round instruction (optional), First round response (optional)], [Second round instruction (optional), Second round response (optional)] ] } ]其中instruction人类指令与output模型回答为必填input、system、history多轮对话可选。5.2 第二步模型转换HF → Mcorebash examples/mcore/qwen3_dense/ckpt_convert_qwen3_hf2mcore.sh脚本调用框架内的convert_ckpt_v2.py见 ckpt_convert_qwen3_hf2mcore.shpython convert_ckpt_v2.py \ --load-model-type hf \ --save-model-type mg \ --target-tensor-parallel-size 1 \ --target-pipeline-parallel-size 1 \ --load-dir ./Qwen3-1.7B/ \ --save-dir ./Qwen3-1.7B-tp1pp1/ \ --model-type-hf qwen3参数说明参数说明--load-model-type hf/--save-model-type mg从 HuggingFace 格式转换为 MegatronMcore格式--target-tensor-parallel-size张量并行大小本样例为 1--target-pipeline-parallel-size流水线并行大小本样例为 1--load-dir/--save-dir输入模型路径 / 输出模型路径输出为./Qwen3-1.7B-tp1pp1/--model-type-hfHuggingFace 模型类型指定qwen3--moe-grouped-gemm是否启用 MoE grouped GEMM 优化Qwen3-1.7B 为稠密模型本脚本未开启--expert-tensor-parallel-size专家张量并行大小若涉及 MoE 需显式指定为 1关键约束此处的--target-tensor-parallel-size/--target-pipeline-parallel-size必须与后续训练脚本中的TP/PP保持一致否则权重分片与训练并行配置不匹配会导致加载失败或语义错误。5.3 第三步启动 SFT 训练bash examples/mcore/qwen3_dense/tune_qwen3_4K_full_A3_ptd.sh这是整个链路的训练核心。打开 tune_qwen3_4K_full_A3_ptd.sh脚本先声明分布式环境与路径配置NPUS_PER_NODE1 # 单节点 1 卡 MASTER_ADDRlocalhost MASTER_PORT6001 NNODES1 NODE_RANK0 WORLD_SIZE$(($NPUS_PER_NODE*$NNODES)) CKPT_LOAD_DIR./Qwen3-1.7B-tp1pp1/ # 加载转换后的预训练权重 CKPT_SAVE_DIR./saved_models/Qwen3-1.7B-alpaca-mcore/ # 保存微调模型 DATA_PATH./finetune_dataset/alpaca # 训练数据集 TOKENIZER_PATH./Qwen3-1.7B/ # tokenizer TP1 PP1 SEQ_LENGTH4096 MBS1 GBS32 TRAIN_ITERS2000随后通过torchrun启动posttrain_gpt.py参数分四组① 模型结构参数GPT_ARGS 关键项—— 对应 Qwen3-1.7B 稠密架构参数值含义--tensor-model-parallel-size / --pipeline-model-parallel-size${TP} / ${PP}张量 / 流水线并行与模型转换保持一致--num-layers28Transformer 层数--hidden-size2048隐藏层维度--ffn-hidden-size6144FFN 中间维度配合--swiglu--num-attention-heads16注意力头数--num-query-groups8GQA 查询组数配合--group-query-attention--kv-channels128KV 通道数--padded-vocab-size151936对齐后的词表大小--rotary-base1000000RoPE 基数Qwen3 系列设定--qk-layernorm、--norm-epsilon 1e-6、--position-embedding-type rope、--normalization RMSNorm—Qwen3 的 QK LayerNorm、RMSNorm 与 RoPE 位置编码--use-flash-attn、--attention-softmax-in-fp32、--sequence-parallel、--bf16—FlashAttention、FP32 softmax、序列并行与 BF16 混合精度--max-position-embeddings / --seq-length4096最大位置 / 序列长度② 训练配置参数参数值说明SEQ_LENGTH/TRAIN_ITERS4096 / 2000序列长度、训练迭代次数--micro-batch-size/--global-batch-size1 / 32单卡 batch size / 全局 batch size--lr/--min-lr1.25e-6 / 1.25e-7初始 / 最小学习率--weight-decay1e-1权重衰减--lr-warmup-fraction0.01预热比例--clip-grad1.0梯度裁剪阈值--adam-beta1 / --adam-beta20.9 / 0.95Adam 超参--seed42随机种子--split 100,0,0—数据 100% 用于训练--log-interval 1、--save-interval ${TRAIN_ITERS}、--eval-iters 0、--log-throughput—日志、保存与吞吐统计策略本样例 save-interval 等于总迭代数即训练结束统一落盘--no-load-optim/--no-load-rng—不加载优化器与 RNG 状态从预训练权重续训时保持干净状态③ 微调专用参数TUNE_ARGS参数说明--finetune启用微调模式--stage sft训练阶段为监督微调SFT--is-instruction-dataset使用指令数据集--prompt-type qwen3使用 Qwen3 风格 prompt--no-pad-to-seq-lengths不强制 pad 到统一序列长度④ 输出与加载--load ${CKPT_LOAD_DIR}加载第一步转换出的权重--save ${CKPT_SAVE_DIR}指定保存位置训练日志通过tee写入logs/tune_qwen3_1.7b_full.log便于排查。5.4 第四步模型转换回 HFMcore → HFbash examples/mcore/qwen3_dense/ckpt_convert_qwen3_mcore2hf.sh脚本调用convert_ckpt_v2.py反向转换见 ckpt_convert_qwen3_mcore2hf.shpython convert_ckpt_v2.py \ --load-model-type mg \ --save-model-type hf \ --load-dir ./saved_models/Qwen3-1.7B-alpaca-mcore/ \ --save-dir ./saved_models/Qwen3-1.7B-alpaca-hf/ \ --hf-cfg-dir ./Qwen3-1.7B/ \ --model-type-hf qwen3参数说明参数说明--load-model-type mg/--save-model-type hf从 Mcore 训练格式转回 HuggingFace 格式--load-dir输入模型路径即训练脚本CKPT_SAVE_DIR保存的./saved_models/Qwen3-1.7B-alpaca-mcore/--save-dir输出 HuggingFace 模型路径--hf-cfg-dir原始 HuggingFace 配置目录用于补齐 config 信息指向./Qwen3-1.7B/--model-type-hfHuggingFace 模型类型qwen3转换完成后./saved_models/Qwen3-1.7B-alpaca-hf/即为可直接用于 vLLM 推理或继续微调的 HuggingFace 格式模型。六、ascend-toolkit 路径注意事项文档与全部脚本均强调需按实际环境修改 ascend-toolkit 路径。默认配置为source /usr/local/Ascend/ascend-toolkit/set_env.sh一站式平台需改为以 CANN 8.5.0 为例source /home/developer/Ascend/cann-8.5.0/set_env.sh仓库内 4 个脚本data_convert_qwen3_instruction.sh、ckpt_convert_qwen3_hf2mcore.sh、tune_qwen3_4K_full_A3_ptd.sh、ckpt_convert_qwen3_mcore2hf.sh以及 build_project_platform.sh 中均已内置这两条路径并做了注释区分实际运行时请按部署环境选择其一避免因 Toolkit 环境变量缺失导致算子或工具链加载失败。七、附录参数速查总表为便于直接引用以下汇总原文档附录中的全部参数说明。7.1 数据准备参数参数说明--input输入数据文件路径可为目录处理全部文件或单个文件支持.parquet/.csv/.json/.jsonl/.txt/.arrow同目录下格式须一致--tokenizer-name-or-pathtokenizer 文件路径--output-prefix输出数据文件前缀--handler-name微调数据预处理 Alpaca 风格数据集时指定为AlpacaStyleInstructionHandler配合--map-keys提取对应列--enable-thinking是否添加推理标签如think /think--seq-length序列长度默认 4096--prompt-type指定模型模板默认qwen37.2 模型转换 HF → Mcore 参数参数说明--target-tensor-parallel-size张量并行大小--target-pipeline-parallel-size流水线并行大小--load-dir输入模型路径--save-dir输出模型路径--moe-grouped-gemm启用 MoE grouped GEMM 优化--model-type-hfHuggingFace 模型类型--expert-tensor-parallel-size专家张量并行大小需显式指定为 17.3 SFT 训练参数路径配置参数说明CKPT_LOAD_DIR加载预训练权重路径CKPT_SAVE_DIR保存微调模型路径DATA_PATH训练数据集路径TOKENIZER_PATHtokenizer 文件路径并行配置须与模型转换参数保持一致参数说明TP张量并行大小PP流水线并行大小CP上下文并行大小CP_TYPE上下文并行算法训练配置参数说明SEQ_LENGTH序列长度TRAIN_ITERS训练迭代次数--micro-batch-size单卡 batch size--global-batch-size全局 batch size--lr学习率--lr-decay-style学习率衰减方式--min-lr最小学习率--weight-decay权重衰减--lr-warmup-fraction预热比例--clip-grad梯度裁剪微调参数参数说明--finetune启用微调模式--stage训练阶段sft表示监督微调--is-instruction-dataset使用指令数据集--prompt-type使用 Qwen3 格式的 prompt7.4 模型转换 Mcore → HF 参数参数说明--load-dir输入模型路径训练保存的 Mcore 检查点--save-dir输出 HuggingFace 模型路径--model-type-hfHuggingFace 模型类型八、实操要点与注意事项小结并行配置一致性模型转换HF → Mcore时的TP/PP必须与训练脚本中的TP/PP完全一致CP、CP_TYPE同理改动并行配置需重新执行权重转换路径三处对齐数据转换的--output-prefix输出目录 训练脚本的DATA_PATH训练脚本的CKPT_SAVE_DIR 反向转换的--load-dirtokenizer 统一指向./Qwen3-1.7Bascend-toolkit 路径Docker 环境用/usr/local/Ascend/ascend-toolkit/set_env.sh一站式平台用/home/developer/Ascend/cann-8.5.0/set_env.sh容器卡数裁剪build_docker.sh 默认挂载 16 卡单卡场景请按需删除多余的--device/dev/davinciX数据格式一致性--input指向目录时同目录下所有文件必须为同一格式训练产物本样例--save-interval设为总迭代数训练结束统一在./saved_models/Qwen3-1.7B-alpaca-mcore/落盘训练日志位于logs/tune_qwen3_1.7b_full.log可配合--log-throughput观察吞吐后续延伸如需更大规模的 SFT 或多卡并行可参考本仓 llm_sft/qwen3_30b_a3b/README.md医学领域多卡全参微调与 llm_sft/qwen36_ascendc/Ascend C 算子生成领域全参 / LoRA 微调等样例。【免费下载链接】cann-recipes-train本项目针对LLM与多模态模型训练业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-train创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考