一条torchrun命令跑通8卡DDP训练:its-stable-llm快速开始完全指南

原创2026-09-21 19:58:021,837 阅读
文章标签:人工智能大模型微调深度学习分布式训练示例工程AscendCANN

一条torchrun命令跑通8卡DDP训练:its-stable-llm快速开始完全指南

its-stable-llm 是 CANN 社区的大模型训练稳定性分析仓库,面向昇腾 NPU,提供基于 openPangu-Embedded-1B 的 Alpaca 全参数微调脚本和多卡 DDP 对照实验。本文将带你用一条 torchrun 命令在单机 8 卡环境下跑通 DDP 分布式训练,并看懂各 Rank 的 Loss 与梯度范数诊断日志。🚀

快速了解:这个仓库能帮你做什么

能力 说明
🎯 多卡 DDP 对照实验 S1-1 / S1-2 / S1-3(随机种子策略对照)、S2-1 / S2-2(FP32 / BF16 精度对照)
📊 Rank 级诊断日志 通过 HookedTrainer + DDP Communication Hook,在 All-Reduce 前采集各 Rank 本地 Loss 与梯度范数,写入 JSONL
📦 本地训练数据 仓库随附 Alpaca 数据:data/train-00000-of-00001-a09b74b3ef9c3b56.parquet

在 DDP 全参数微调中,参数经 All-Reduce 后全局一致,但聚合前各 Worker 的优化动态可能出现差异。训练脚本会记录 4 个关键字段:

  • loss_local / loss_reduced:各 Rank 本地 Loss,以及 Rank0 聚合后的 Loss
  • grad_norm_pre_ar / grad_norm_reduced:All-Reduce 前梯度范数,以及聚合后的梯度范数

这正是识别训练"局部分化"等失稳前兆的核心数据源。

一键环境准备:版本配套与依赖安装

环境是新手最容易踩坑的环节。本仓库推荐以 CANN 8.5.0 为主版本,请先按官方配套关系选型,避免混用不同代际的 CANN / 驱动 / torch_npu:

组件 推荐版本
昇腾驱动(Ascend HDK) 25.0.X / 25.2.X / 25.3.X / 25.5.X
CANN 8.5.0(Toolkit + ops)
Python 3.10.x
PyTorch 2.6.0
torch_npu(Ascend Extension for PyTorch) 2.6.0.post5
目标硬件 昇腾 NPU(示例按单机 8 卡)

⚠️ 注意:不要将 CANN 8.5.0 与面向其他大版本的 torch_npu 插件混用;同一环境中只保留一套 Ascend Toolkit。

完成驱动与 CANN 安装后,确认设备可正常查询:

npu-smi info

然后克隆仓库并配置环境:

git clone https://gitcode.com/cann/its-stable-llm.git
cd its-stable-llm

配置 CANN 环境变量

仓库提供了环境变量示例 code/fix.sh,其中含本机示例绝对路径,请改为本机实际安装目录后执行:

cd code
source fix.sh
# 或使用 CANN 自带脚本,例如:
# source /usr/local/Ascend/ascend-toolkit/set_env.sh

创建虚拟环境并安装依赖

python3.10 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

# 先安装配套 PyTorch,再按官方说明安装对应 torch_npu wheel
pip install torch==2.6.0
pip install transformers datasets

修改脚本中的本地路径

训练脚本使用硬编码绝对路径,运行前请将各脚本中的 model_path / data_path / output_path 改为本机路径(参考 code/experiments/S1-1.py)。基座模型 openPangu-Embedded-1B 需自行准备;训练数据仓库已随附,直接使用 data/train-00000-of-00001-a09b74b3ef9c3b56.parquet 即可。

可选的语法自检:

python -m py_compile code/*.py code/experiments/*.py

核心一步:一条 torchrun 命令启动 8 卡 DDP 训练

一切就绪后,打开终端,进入 code 目录执行下面这条命令,即可拉起 8 卡 DDP 训练:

cd code
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export PYTHONNOUSERSITE=1
source fix.sh
torchrun --nproc_per_node=8 --master_addr=localhost --master_port=12355 experiments/S1-1.py

💡 启动命令与 code/run.ipynb 中的 Notebook 示例完全一致,可对照参考。

逐参数解读:这条命令做了什么

参数 / 环境变量 含义
--nproc_per_node=8 本机启动 8 个进程,对应 8 张 NPU(1 卡 1 进程)
--master_addr=localhost 单机模式,Rank 间通过本机回环地址通信,不对外暴露端口
--master_port=12355 torchrun 各进程建联用的本机端口,被占用时换一个即可
experiments/S1-1.py 训练入口脚本,torchrun 会为其自动注入 RANK / LOCAL_RANK 等环境变量
PYTORCH_NPU_ALLOC_CONF=expandable_segments:True 开启 NPU 显存动态分段分配,缓解碎片导致的 OOM

为什么推荐 master_addr=localhost?安全声明 SECURITY.md 指出:单机多卡场景下 localhost + 指定 master_port 仅用于本机进程间通信,不开放对外网络端口,是最安全的默认配置;除非明确需要跨机且已完成安全评审,否则不要改为其他地址。

训练跑起来之后:看日志、看卡

训练启动后,你可以通过两种方式确认一切正常:

1️⃣ 实时观察 NPU 占用(另开一个终端):

watch -n 1 npu-smi info

正常情况下应看到 8 张 NPU 的利用率与显存占用同步上升。

2️⃣ 查看诊断日志。实验脚本会把诊断数据写入 output_path/logs 目录下的 JSONL 文件:

  • 每个 Rank 一份:loss_grad_<时间戳>_rankN.jsonl,记录 step、rank、loss_local、grad_norm_pre_ar
  • Rank0 聚合一份:loss_grad_reduced_<时间戳>_rank0.jsonl,记录 loss_reduced、grad_norm_reduced

训练结束时,微调后的模型会保存到 output_path/final_model(见 code/experiments/S1-1.py)。仓库还附带了 8 卡训练日志样例 code/run.log,可对照预期输出排查问题。

换一行命令,跑通 5 组稳定性对照实验

torchrun 命令的启动方式完全相同,只需替换入口脚本,即可在 code/experiments/ 目录中切换不同的稳定性对照实验:

脚本 实验设置 预期观察
S1-1.py 全 Rank seed=42(严格一致性) 各 Rank Loss / 梯度范数离散度较低
S1-2.py Rank0 seed=42+999,其余 seed=42(轻度失配) Worker 级离散度略升,全局平均 Loss 仍较平滑
S1-3.py seed=42+rank*10(显著失配) Loss / 梯度范数离散度更大,全局 Loss 看起来可能仍正常
S2-1.py FP32(bf16=False) 精度对照基线
S2-2.py BF16(bf16=True) 低精度下的动态对照

例如跑轻度失配实验,只需把入口脚本换成 S1-2.py:

torchrun --nproc_per_node=8 --master_addr=localhost --master_port=12355 experiments/S1-2.py

这正是仓库的核心价值所在:全局平均 Loss 曲线正常,不代表各 Rank 的训练动态一致。通过对比 per-rank 与聚合日志的离散程度,就能量化种子策略、训练精度对失稳风险的影响。

新手常见问题排查清单

症状 排查建议
启动报端口被占用 更换 --master_port(如 12356);确认 12355 未被其他训练进程占用
报错找不到模型 / 数据 检查脚本中 model_path / data_path 是否已改为本机实际路径
npu-smi info 查不到卡 确认昇腾驱动与 CANN 已正确安装,source fix.sh 后路径指向真实 Toolkit 目录
版本冲突 / 算子报错 核对 CANN 8.5.0 与 torch_npu 版本配套关系,勿混装多套 Toolkit
显存 OOM 保留 export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True;可降低 per_device_train_batch_size

默认超参(供调试时参考):1 epoch、学习率 5e-5、per_device_train_batch_size=2、gradient_accumulation_steps=4、max_length=1024,详见 README.md 的"默认超参"章节。

总结

你现在已经掌握了 its-stable-llm 的完整快速开始路径:

  1. 装环境:CANN 8.5.0 + torch_npu 2.6.0.post5 配套安装,source fix.sh 配置变量
  2. 改路径:把脚本中硬编码的 model_path / data_path / output_path 改成本机路径
  3. 跑训练:一条 torchrun --nproc_per_node=8 --master_addr=localhost --master_port=12355 experiments/S1-1.py 拉起 8 卡 DDP
  4. 看诊断:对比 per-rank JSONL 与 Rank0 聚合日志,观察各 Rank 的 Loss 与梯度范数离散度

从"能跑通"到"看得懂",这些 Rank 级诊断日志就是通往大模型训练稳定性分析的下一步。🎉

登录后查看全文
its-stable-llm