使用 PaddleNLP 在昇腾 NPU 上训练与推理 llama2-13B：从环境搭建到 SFT/LoRA/Pretrain 全流程实战

PaddleNLP 对昇腾 NPU（Ascend 910 芯片）上的 llama2-13B 模型进行了深度适配与优化，实现了 NPU 与 GPU 训推入口的基本统一，让同一套训练推理代码可以在不同硬件上"无缝切换"。本文基于 llm/devices/npu/llama/README.md 及仓库中配套的启动脚本，完整梳理在 8 卡昇腾 910 机器上从环境准备、数据准备、SFT 微调、静态图导出到推理的端到端流程，并深入解析训练策略适配、通信掩盖、自定义算子抽象与 Layer 级算子融合等底层特性。读完本文，你将能够在一台昇腾 NPU 机器上独立完成 llama2-13B 的微调训练与推理部署。

一、方案总览：NPU 与 GPU 训推入口的统一

PaddleNLP 在昇腾 NPU 上对 llama2-13B 模型进行了深度适配和优化，该套件实现了昇腾 NPU 和 GPU 的训推入口基本统一，达到了"无缝切换"的效果——用户在 GPU 上习惯使用的 run_finetune.py、run_pretrain.py 等入口脚本，只需将 --device 参数指定为 npu 即可在昇腾芯片上运行。

该方案在技术上的核心能力包括：

• 训练策略完全适配：支持 4D 混合并行（数据并行 DP、张量并行 TP、流水线并行 PP、分片并行 Sharding），可灵活适应多种训练策略；
• 训练性能极致优化：通过通信掩盖技术，绝大部分通信开销被隐藏在计算中，软硬结合提供极致性能；
• 低门槛性能调优：分布式策略自动寻优能力打通多硬件，屏蔽硬件复杂性的同时，使用户可以轻松挖掘算力极限；
• 推理成本极致压缩：推理支持 Layer 级算子融合，且融合算子已支持动态插入功能，无需手工改写模型结构即可享受融合带来的加速。

说明：仓库中除 NPU 外，还为 XPU（llm/devices/xpu/README.md）、DCU（llm/devices/dcu/README.md）、SDAA 等硬件提供了类似的自定义设备支持，本文聚焦 NPU 场景。

二、环境准备：昇腾 NPU 机器与开发容器搭建

2.1 硬件与系统要求

在开始之前，你需要一台昇腾 NPU 机器。本示例基于 8 卡机器，通过"微调训练 + 推理"的流程演示运行方法。机器的系统要求如下：

芯片类型	驱动版本	CANN 版本
昇腾 910	23.0.3	CANN 8.0.RC1

如果要验证机器是否为昇腾 910B 芯片，只需在系统环境下输入命令查看是否有输出：

lspci | grep d802

例如输出如下内容，即表明检测到了昇腾 910B 加速卡：

28:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
29:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
38:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
39:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
48:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
49:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
59:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
5a:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
98:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
99:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
b8:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
b9:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
c8:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
c9:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
d9:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)
da:00.0 Processing accelerators: Huawei Technologies Co., Ltd. Device d802 (rev 20)

2.2 拉取开发镜像并启动容器（约 5～15 分钟）

PaddleNLP 提供了包含 CANN 开发环境的 Docker 镜像。注意此镜像仅为开发环境，镜像中不包含预编译的飞桨安装包，因此需要在容器内另行安装 PaddlePaddle 与自定义设备插件。

docker pull registry.baidubce.com/device/paddle-npu:cann80RC1-ubuntu20-x86_64-gcc84-py39

参考如下命令启动容器。通过 -v 参数挂载宿主机上的昇腾驱动、npu-smi 与 dcmi 目录，并通过 ASCEND_RT_VISIBLE_DEVICES 指定容器可见的昇腾卡号：

docker run -it --name paddle-npu-dev -v $(pwd):/work \
    --privileged --network=host --shm-size=128G -w=/work \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -e ASCEND_RT_VISIBLE_DEVICES="0,1,2,3,4,5,6,7" \
    registry.baidubce.com/device/paddle-npu:cann80RC1-ubuntu20-x86_64-gcc84-py39 /bin/bash

参数说明：

• --privileged：容器内需要访问昇腾设备节点，需以特权模式运行；
• --shm-size=128G：大模型分布式训练时各进程间需要通过共享内存通信，需要足够大的共享内存；
• --network=host：使用宿主机网络，便于多机或本机分布式通信；
• ASCEND_RT_VISIBLE_DEVICES：控制容器内可见的物理昇腾卡号，与 GPU 场景的 CUDA_VISIBLE_DEVICES 语义一致。

2.3 安装 PaddlePaddle 与 PaddleCustomDevice

容器启动后，依次安装以下软件：

（1）PaddlePaddle 飞桨框架：提供运算基础能力：

python -m pip install paddlepaddle==3.0.0b0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

（2）paddle-custom-npu：这是飞桨框架的自定义硬件接入实现，提供 NPU 上的算子实现：

python -m pip install paddle-custom-npu==3.0.0b0 -i https://www.paddlepaddle.org.cn/packages/stable/npu/

如需源码编译安装，可参考 PaddleCustomDevice 仓库中 backends/npu 目录的安装文档。

2.4 克隆 PaddleNLP 仓库并安装依赖

PaddleNLP 是基于飞桨的自然语言处理和大语言模型（LLM）开发库，存放了基于飞桨框架实现的各种大模型，llama2-13B 模型也包含其中：

git clone https://github.com/PaddlePaddle/PaddleNLP.git
cd PaddleNLP
python -m pip install -r requirements.txt
python -m pip install -e .

2.5 编译安装 paddlenlp_ops（NPU 专用融合算子）

PaddleNLP 仓库内置了部分昇腾专用的融合算子（fused_rope、rms_norm_npu、flash_attention_npu 等），以便用户享受到极致压缩的推理成本。编译安装步骤如下：

cd csrc/npu
python setup.py build bdist_wheel
pip install dist/paddlenlp_ops-0.0.0-cp39-cp39-linux_x86_64.whl
cd -

从 csrc/npu/setup.py 可以看到，该工程打包的包名为 paddlenlp_ops，描述为 "PaddleNLP NPU CustomOps"，其 Python 包位于 csrc/npu/python/paddlenlp_ops，编译产物为二进制的 .so 扩展。编译安装完成后，这些自定义算子会通过 CUSTOM_DEVICE_ROOT 环境变量被加载到飞桨运行时中（见 paddlenlp/transformers/llama/fusion_ops.py 中通过 load_op_meta_info_and_register_op 动态注册 .so 算子库的逻辑）。

三、数据准备：广告生成 SFT 数据集（约 2～5 分钟）

精调（SFT）阶段，仓库提供了广告生成数据集 demo 便于调试使用。进入 NPU llama 目录后下载并解压：

cd llm/devices/npu/llama
wget https://bj.bcebos.com/paddlenlp/datasets/examples/AdvertiseGen.tar.gz
tar -zxvf AdvertiseGen.tar.gz

PaddleNLP 支持的精调数据格式是每行包含一个字典的 JSON 文件，每个字典包含以下字段：

• src：str, List(str)，指模型的输入指令（instruction）、提示（prompt），即模型应该执行的任务；
• tgt：str, List(str)，指模型的输出。

样例数据：

{"src": "类型#裙*颜色#蓝色*风格#清新*图案#蝴蝶结", "tgt": "裙身处采用立体蝴蝶结装饰辅以蓝色条带点缀，令衣身造型饱满富有层次的同时为其注入一丝甜美气息。将女孩清新娇俏的一面衬托而出。"}

你可以根据此格式自行制作精调数据。脚本中的 --dataset_name_or_path "data/" 即指向解压后的 AdvertiseGen 数据目录。

四、模型训练：SFT / LoRA / Pretrain 三套入口脚本

llm/devices/npu/llama/ 目录下提供了对应 Pretrain / SFT / LoRA 的三个入口脚本，并已按照 8 张 910 芯片的训练资源优化了并行策略等配置供参考：

脚本	策略	默认 max_steps	数据来源
llama_npu_sft_N1C8.sh	SFT 微调	100	data/（AdvertiseGen）
llama_npu_lora_N1C8.sh	LoRA 微调	100	data/（AdvertiseGen）
llama_npu_ppt_N1C8.sh	继续预训练	2000	pre-data/

三个脚本均通过 python -m paddle.distributed.launch 启动，并设置了一组共用的 NPU 环境变量与混合并行参数，以下逐一解析。

4.1 启动 SFT 微调训练（约 4 小时）

运行 SFT 策略：

bash llama_npu_sft_N1C8.sh

脚本也支持传入自定义训练步数：bash llama_npu_sft_N1C8.sh 1000，默认值为 100 步，便于快速验证流程。

4.2 NPU 关键环境变量解读

三个脚本头部设置了一组对昇腾 NPU 训练性能至关重要的环境变量，它们的含义如下：

环境变量	值	作用
FLAGS_npu_storage_format=1	1	启用 NPU 存储格式优化（如 5D 格式转换的优化处理）
FLAGS_use_stride_kernel=0	0	关闭 stride kernel，规避部分算子在不连续内存布局下的性能损耗
HCCL_OP_BASE_FFTS_MODE_ENABLE=TRUE	TRUE	开启 HCCL（昇腾集合通信库）的 Fast Fourier 传输调度优化
MULTI_STREAM_MEMORY_REUSE=1	1	多流内存复用，提升多 stream 并发场景下的显存利用效率
HCCL_INTRA_PCIE_ENABLE=0	0	节点内通信不使用 PCIe 通道
HCCL_INTRA_ROCE_ENABLE=1	1	节点内通信启用 RoCE 高速通道
FLAGS_allocator_strategy=naive_best_fit	naive_best_fit	采用 best-fit 内存分配策略
ASCEND_RT_VISIBLE_DEVICES	0-7	指定可见的 8 张昇腾卡
FLAGS_NPU_MC2=1	1	开启通信计算融合（MC2）pass，将张量并行通信开销掩藏在计算中
MC2_Recompute=1	1	MC2 融合与重计算策略配合，进一步降低显存压力

脚本还会执行 source /usr/local/Ascend/ascend-toolkit/set_env.sh 加载 CANN 工具链环境，并设置 PYTHONPATH=../../../../ 使 llm/ 目录下的 run_finetune.py 与 run_pretrain.py 能够被正确导入。

4.3 SFT 脚本核心训练参数解析

llama_npu_sft_N1C8.sh 的核心训练参数如下：

参数	值	说明
--device "npu"	npu	指定运行设备，与 GPU 场景入口统一，实现"无缝切换"
--model_name_or_path	meta-llama/Llama-2-13b	预训练模型名或路径
--dataset_name_or_path	data/	精调数据集路径
--per_device_train_batch_size	2	单卡 batch size
--gradient_accumulation_steps	64	梯度累积步数，等效全局 batch = 2 × 8 × 64
--max_steps	100（可传参）	最大训练步数
--learning_rate	3e-06	学习率，SFT 场景通常保持较小
--warmup_steps	20	学习率预热步数
--src_length	1024	输入序列长度
--max_length	4096	最大序列长度
--bf16 true	true	使用 BF16 混合精度
--fp16_opt_level "O2"	O2	混合精度优化等级，O2 为框架自动插入 AMP 操作
--amp_master_grad true	true	使用 FP32 master gradient，提升训练稳定性
--tensor_parallel_degree 8	8	张量并行度 8，将 13B 模型切分到 8 卡
--pipeline_parallel_degree 1	1	流水线并行度 1
--sharding_parallel_degree 1	1	分片并行度 1
--sharding "stage1"	stage1	使用 ZeRO Stage-1 优化器状态分片
--sharding_parallel_config	enable_stage1_tensor_fusion enable_stage1_overlap	开启 Stage-1 张量融合与通信重叠
--sequence_parallel 1	1	开启序列并行
--use_flash_attention 1	1	使用 FlashAttention
--use_fused_rope 1	1	使用融合版 RoPE 位置编码
--use_fused_rms_norm 1	1	使用融合版 RMSNorm
--fuse_attention_qkv true	true	融合 Attention 的 QKV 线性层
--fuse_attention_ffn true	true	融合 FFN 线性层
--pad_to_multiple_of 4096	4096	序列长度对齐到 4096 的倍数
--tensor_parallel_output true	true	TP 输出张量并行切分
--zero_padding 0	0	关闭 zero padding

可以看到，该脚本采用了 TP=8 + Sequence Parallel + ZeRO Stage-1 + FlashAttention + 算子融合 的组合，这是针对 13B 参数规模在 8 张昇腾 910 上的典型优化配置。

4.4 LoRA 微调脚本

llama_npu_lora_N1C8.sh 与 SFT 脚本结构基本一致，主要差异在于：

• 模型使用 meta-llama/Llama-2-13b-chat；
• 增加了 --lora true 与 --lora_rank 32，即以秩为 32 的 LoRA 适配器进行参数高效微调；
• 训练与推理输出目录为 ./output/lora_bf16_llama_N1C8。

LoRA 只训练低秩适配矩阵，可显著降低显存占用与训练成本，适合在资源受限时快速定制模型。

4.5 继续预训练脚本

llama_npu_ppt_N1C8.sh 面向 Pretrain 场景，参数上存在以下差异：

• 通过 --input_dir "./pre-data" 指定预训练语料，--split 949,50,1 划分训练/验证/测试集；
• 默认 --max_steps 2000，学习率 1e-5，--min_learning_rate 1e-6；
• 张量并行度为 4，分片并行度 2（--sharding "stage1" --sharding_parallel_degree 2）；
• 开启 --unified_checkpoint 统一检查点机制，配合 --load_sharded_model true --save_sharded_model true 加载与保存分片模型；
• 使用 --tensor_parallel_config "enable_mp_async_allreduce enable_mp_skip_c_identity" 优化张量并行通信；
• 开启 --virtual_pp_degree 1 虚拟流水线，以及 --recompute_use_reentrant true 重计算。

五、静态图导出与推理部署（约 10～15 分钟）

为了保障极致压缩的推理成本，NPU 推理使用了静态图实现，因此需要先从训练产出的动态图模型中导出静态图模型。

5.1 修改推理配置文件

推理前需要准备推理用的配置文件。在 merge 好参数的路径下（本教程路径为 ./output/sft_bf16_llama_N1C8），将 config.json 更改为以下内容：

{
  "architectures": [
    "LlamaForCausalLM"
  ],
  "bos_token_id": 1,
  "eos_token_id": 2,
  "hidden_act": "silu",
  "hidden_size": 5120,
  "initializer_range": 0.02,
  "intermediate_size": 13824,
  "max_position_embeddings": 4096,
  "model_type": "llama",
  "num_attention_heads": 40,
  "num_hidden_layers": 40,
  "num_key_value_heads": 40,
  "pad_token_id": 0,
  "pretraining_tp": 1,
  "rms_norm_eps": 1e-05,
  "rope_scaling": null,
  "tie_word_embeddings": false,
  "torch_dtype": "float16",
  "transformers_version": "4.31.0",
  "use_cache": false,
  "vocab_size": 32000
}

这些字段与 Llama-2-13B 的模型结构一一对应：hidden_size=5120、intermediate_size=13824、num_attention_heads=40、num_hidden_layers=40、num_key_value_heads=40（非 GQA 结构）、vocab_size=32000、max_position_embeddings=4096。

5.2 导出静态图模型

执行导出脚本，将动态图模型转换为静态图推理模型：

bash export_npu.sh ./output/sft_bf16_llama_N1C8/ ./inference

查看 export_npu.sh 可以看到其核心是调用 llm/predict/export_model.py：

python predict/export_model.py --model_name_or_path ${src_path} \
    --inference_model --output_path ${dst_path} \
    --dtype float16 --device npu --block_attn

其中 --block_attn 表示导出支持 BlockAttention（分块 KV Cache）的推理模型，--inference_model 表示导出推理专用模型。导出前脚本会 source CANN 工具链与 Ascend 的 ATB（Ascend Transformer Boost）加速库环境。

此外，目录下的 export_utils.py 展示了 NPU 推理所需的权重变换细节：导出后处理会把 qkv_weight、out_proj_weight、ffn1_weight、ffn2_weight、llama_lm_head_0.w_0 等 Linear 层权重转置并设置 matmul_v2 的 trans_y=True，同时将量化相关的 *_out_scale 反量化尺度转换为 NPU 推理算子所需的紧凑格式。这一步是 NPU 静态图推理能够直接高效执行的关键。

5.3 静态图推理

通过静态图模型执行推理：

bash predict_npu.sh ./inference

predict_npu.sh 的核心调用如下：

python predict/predictor.py --model_name_or_path ${model_path} \
    --inference_model --dtype "float16" --mode "static" --block_attn --device npu

其中 --mode "static" 指定使用静态图模式执行，--block_attn 使用分块注意力推理。

成功运行后，可以查看到推理结果的生成，样例如下：

***********Source**********
解释一下"温故而知新"
***********Target**********

***********Output**********
"温故而知新" (wēn gù er zhī xīn) is a Chinese idiom that means "to know the old and appreciate the new." It is often used to describe the idea of learning from the past and being open to new experiences and ideas.

The word "温" (wēn) in this idiom means "old" or "past," and "故" (gù) means "origin" or "beginning." The word "知" (zhī) means "to know" or "to understand," and "新" (xīn) means "new."

So, the idiom "温故而知新" can be translated as "to know the old and appreciate the new," or "to learn from the past and embrace the new." It suggests that by understanding the past, we can gain a deeper appreciation for the present and be more open to new ideas and experiences.

This idiom is often used in Chinese culture to encourage people to learn from their heritage and traditions, while also being open to new ideas and perspectives. It is a reminder that knowledge and understanding are not limited to the present, but can also be gained from the past, and that by combining the old and the new, we can gain a more complete and nuanced understanding of the world.

六、特性深度解析：NPU 上的性能优化原理

6.1 通信掩盖技术（MC2）

当模型训练开启张量并行后，计算过程中会出现很多"通信（AllReduce / ReduceScatter / AllGather）+ 矩阵乘（Matmul）"的算子组合。昇腾 910 芯片提供了一种高效的并行机制来掩盖通信开销。

通过设置 FLAGS_NPU_MC2=1 开启通信计算融合 pass，将绝大部分的张量并行通信开销掩藏在计算中，有效提升训练性能。这一机制对应文档中所提到的"95% 的通信被掩盖在计算中"的优化目标。在 SFT 与 LoRA 脚本中，FLAGS_NPU_MC2=1 与 MC2_Recompute=1 同时开启，即融合后的通信-计算图还配合了重计算策略，在保持通信掩盖效果的同时控制显存占用。

6.2 自定义算子的统一抽象

在实践中，fusion 算子对于大模型训练的性能影响往往很大。为了全面支持昇腾以及其他各种硬件的高性能算子，同时保持组网代码的简洁性，PaddleNLP 提供了统一的自定义算子接口实现，位于 paddlenlp/transformers/llama/fusion_ops.py。目前覆盖了 llama 中常见的 fusion_rope、fusion_rms_norm、fusion_flash_attention 在 NPU、GPU、XPU、GCU 等设备上的实现。

以 fusion_rope 为例，在 NPU 设备上它通过 core.eager._run_custom_op("fused_rope", ...) 调用自定义算子完成旋转位置编码的融合计算；fusion_rms_norm 在 NPU 上对应 rms_norm_npu 自定义算子；fusion_flash_attention 在 NPU 上则调用 flash_attention_npu 自定义算子，支持因果掩码（causal）等参数。这些自定义算子最终由 paddlenlp_ops 编译产物提供，通过 CUSTOM_DEVICE_ROOT 环境变量下的 .so 库动态注册进飞桨运行时。这意味着上层模型代码无需感知硬件差异，统一调用 fusion_* 接口即可自动路由到各硬件的最优实现。

6.3 Layer 级算子融合与动态插入

Layer 级算子融合显著提升计算效率，同时融合算子支持动态插入功能——无需修改模型源码，推理时框架会通过 IR（中间表示）pass 自动在计算图中插入融合算子。执行推理的过程中可以看到如下日志：

--- Running IR pass [remove_residual_in_fused_bias_residual_layernorm]
--- Running IR pass [remove_residual_in_rms_norm]
--- Running IR pass [remove_blha_get_max_len]
--- Running IR pass [llama_fuse_attention_layer_begin]
--- Running IR pass [llama_fuse_attention_layer_end]
--- Running IR pass [llama_fuse_attention_layer]
--- Running IR pass [llama_fuse_lm_head_with_slice]
--- Running IR pass [llama_fuse_lm_head]
--- Running IR pass [llama_fuse_get_padding_offset]

从这些 pass 名称可以推断，推理阶段会对残差连接、RMSNorm、注意力层（llama_fuse_attention_layer）、LM Head（llama_fuse_lm_head）以及 padding offset 计算等环节进行逐层融合。正是这种"动态插入"机制，让同一份模型代码在不开融合时保持可读性，在开启融合时自动获得 Layer 级算子融合带来的推理成本压缩。

七、常见问题与排错建议

• 确认芯片型号：如果 lspci | grep d802 无输出，说明机器不是昇腾 910B 芯片，需要确认驱动是否正确加载，或芯片型号是否与本方案匹配。
• 容器内找不到昇腾设备：检查 docker run 是否添加了 --privileged 以及昇腾 driver / npu-smi / dcmi 目录的挂载，容器内需能正常执行 npu-smi info。
• 自定义算子未生效：确认 paddlenlp_ops 已通过 csrc/npu 中的构建流程编译安装成功，且容器内 CUSTOM_DEVICE_ROOT 环境变量指向的目录下存在编译产物 .so 文件。
• 分布式通信异常：确认 HCCL_INTRA_ROCE_ENABLE 与 HCCL_INTRA_PCIE_ENABLE 的组合是否匹配实际网络拓扑，并确认 ASCEND_RT_VISIBLE_DEVICES 指定的卡号与 --devices 参数一致。
• 推理前遗漏权重变换：务必确认导出后的模型已经过 export_utils.py 中的权重转置与反量化尺度转换处理，否则静态图推理可能出现结果错误或算子不支持。

八、总结

本文完整演示了 PaddleNLP 在昇腾 NPU 上运行 llama2-13B 的端到端流程：从昇腾 910 机器的环境检查、开发镜像启动、PaddlePaddle 与自定义设备插件安装，到 paddlenlp_ops 融合算子编译，再到 SFT / LoRA / Pretrain 三套并行训练脚本的运行，最后经过 config.json 修改、静态图导出与 predictor.py 推理，输出生成结果。

其背后的技术支撑包括：4D 混合并行训练策略适配、FLAGS_NPU_MC2 通信掩盖、fusion_rope / fusion_rms_norm / fusion_flash_attention 的统一自定义算子抽象，以及推理阶段的 Layer 级算子融合与动态插入。这些设计共同实现了昇腾 NPU 与 GPU 训推入口的基本统一，让开发者可以以近乎相同的代码在多种硬件上完成大模型的训练与部署。相关脚本与源码均可在 llm/devices/npu/llama/ 目录及 csrc/npu 中进一步查阅。