一条torchrun命令跑通8卡DDP训练:its-stable-llm快速开始完全指南
一条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 聚合后的 Lossgrad_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 的完整快速开始路径:
- 装环境:CANN 8.5.0 + torch_npu 2.6.0.post5 配套安装,
source fix.sh配置变量 - 改路径:把脚本中硬编码的
model_path/data_path/output_path改成本机路径 - 跑训练:一条
torchrun --nproc_per_node=8 --master_addr=localhost --master_port=12355 experiments/S1-1.py拉起 8 卡 DDP - 看诊断:对比 per-rank JSONL 与 Rank0 聚合日志,观察各 Rank 的 Loss 与梯度范数离散度
从"能跑通"到"看得懂",这些 Rank 级诊断日志就是通往大模型训练稳定性分析的下一步。🎉