本文档介绍如何在华为昇腾 NPU 上进行 LlamaFactory 模型训练。
支持设备
LlamaFactory 当前已适配以下昇腾 NPU 设备:
支持功能
快速开始
为了快速上手,建议直接使用 LlamaFactory 提供的 Docker 镜像。以下示例使用 A2 Ubuntu 镜像 latest-910b-ubuntu;其他硬件和容器操作系统组合请参考 NPU 安装及配置。
latest-910b-ubuntu
1. 启动容器 (请根据实际情况修改 device 映射):
device
docker run -itd \ --net=host \ --device=/dev/davinci0 \ --device=/dev/davinci1 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ --shm-size=1200g \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /data:/data \ --name llamafactory-npu \ hiyouga/llamafactory:latest-910b-ubuntu \ /bin/bash
2.进入容器并配置环境变量:
docker exec -it llamafactory-npu /bin/bash
进入容器后,务必 先加载 Ascend 环境配置,否则无法识别 NPU 设备:
source /usr/local/Ascend/ascend-toolkit/set_env.sh
3.开始训练:
备注
下载模型时,如果无法顺利访问 Hugging Face 社区资源下载,推荐前往 ModelScope 下载,或按需配置以下参数:
设置 USE_MODELSCOPE_HUB 环境变量,优先使用 ModelScope 下载模型/数据集或使用缓存路径中的模型/数据集:export USE_MODELSCOPE_HUB=1
USE_MODELSCOPE_HUB
ms_hub_token
更多参数说明请参考 参数介绍。下载前需关注待下载文件的正确性与安全性。
llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
常用调参建议
如果希望在显存占用和训练吞吐之间做简单取舍,建议优先关注以下参数:
per_device_train_batch_size
gradient_accumulation_steps
cutoff_len
gradient_checkpointing
下面给出一个更偏向“先跑通、少占显存”的示例配置:
per_device_train_batch_size: 1 gradient_accumulation_steps: 8 cutoff_len: 4096 gradient_checkpointing: true
分布式训练
NPU 的分布式训练配置与 分布式训练 文档描述的基本一致。本节主要介绍 NPU 环境下的特定配置,包括设备指定和多机通信设置。
关键环境变量
在启动训练前,请注意以下环境变量的设置:
1.ASCEND_RT_VISIBLE_DEVICES (单机/多机均需关注)
用于指定参与训练的 NPU 设备。
export ASCEND_RT_VISIBLE_DEVICES=0,1
2.HCCL_SOCKET_IFNAME (仅多机训练必需)
指定 HCCL 集合通信使用的网卡接口名称。
ifconfig
eth0
enp1s0
export HCCL_SOCKET_IFNAME=eth0
单机训练
单机训练(单卡或多卡)的启动方式与标准流程一致。
单机多卡示例:
ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
多机训练
在 NPU 环境下,推荐使用 accelerate launch 配合 FSDP 1/2 进行多机训练,这种方式在 NPU 上通信和计算效率更优。
accelerate launch
其他启动方式(如 torchrun/deepspeed)及更多详细配置请参考 分布式训练 文档。
torchrun/deepspeed
1. 准备 Accelerate 配置文件
创建或修改 examples/accelerate/fsdp_config.yaml,关键参数如下(请根据实际节点数和 IP 修改):
examples/accelerate/fsdp_config.yaml
compute_environment: LOCAL_MACHINE debug: false distributed_type: FSDP downcast_bf16: 'no' fsdp_config: fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP fsdp_backward_prefetch: BACKWARD_PRE fsdp_forward_prefetch: false fsdp_cpu_ram_efficient_loading: true fsdp_offload_params: false fsdp_sharding_strategy: FULL_SHARD fsdp_state_dict_type: FULL_STATE_DICT fsdp_sync_module_states: true fsdp_use_orig_params: true machine_rank: 0 main_training_function: main mixed_precision: bf16 main_process_ip: 192.168.0.1 main_process_port: 29500 num_machines: 2 num_processes: 16 rdzv_backend: static same_network: true use_cpu: false
关键多机参数说明:
2. 启动训练
在所有节点上执行相同的启动命令(确保 machine_rank 在 yaml 中已正确配置):
machine_rank
export HCCL_SOCKET_IFNAME=eth0 accelerate launch --config_file examples/accelerate/fsdp_config_multiple_nodes.yaml \ src/train.py examples/train_lora/qwen3_lora_sft.yaml
训练方式
以下是常见训练场景的启动命令参考,具体参数配置文件请根据实际需求调整。
预训练 (PT)
llamafactory-cli train examples/train_lora/qwen3_lora_pretrain.yaml
监督微调 (SFT)
奖励模型 (RM)
llamafactory-cli train examples/train_lora/qwen3_lora_reward.yaml
DPO 训练
llamafactory-cli train examples/train_lora/qwen3_lora_dpo.yaml
全参数微调 (Full)
llamafactory-cli train examples/train_full/qwen3_full_sft.yaml
性能优化
融合算子
LlamaFactory 支持 FA、NpuFusedRMSNorm、NpuFusedSwiGlu、NpuFusedRoPE 和 NpuFusedMoE 融合算子。
可在训练脚本中配置如下参数,模型加载后替换对应模型结构,使能NpuFusedRMSNorm、NpuFusedSwiGlu、NpuFusedRoPE和NpuFusedMoE融合算子,提升训练效率。该接口使能后,代码内部自动识别是否满足模型结构替换的要求,满足的情况对应模型结构会被替换为融合算子形式。
use_v1_kernels: true
同时 LlamaFactory 支持昇腾 NPU 的 FA 融合算子。启用后,Transformers 会为支持的模型选择 FA Attention 后端;对于混合注意力架构,FA 仅作用于其中的 Full Attention 层。在训练配置文件中设置如下参数即可使能:
flash_attn: fa2
当前融合算子对模型的支持程度受限,该功能正在持续迭代开发中,以提升泛化性和适用性。当前各融合算子支持的模型系列如下:
算子下发优化
通过设置 TASK_QUEUE_ENABLE 环境变量优化算子下发性能(推荐 Level 2):
TASK_QUEUE_ENABLE
export TASK_QUEUE_ENABLE=2
模型保存、断点续训以及 LoRA 适配器后续合并导出,请参考 模型保存、LoRA 合并与量化。