源码深扒:its-stable-llm如何用DDP Communication Hook在All-Reduce前采集各卡梯度范数
源码深扒:its-stable-llm如何用DDP Communication Hook在All-Reduce前采集各卡梯度范数
its-stable-llm 是 CANN 社区旗下的大模型训练稳定性分析仓库,本文带你深扒它的核心实现:如何利用 DDP Communication Hook,在多卡数据并行的 All-Reduce 之前捕获每张卡(Rank)的本地 Loss 与梯度范数,并写入 JSONL 诊断日志,让全局平均曲线看不见的“静默不一致”无所遁形。
为什么要在 All-Reduce 前采集?🎯
在同步数据并行(DDP)训练中,各 Worker 反向传播后会对梯度桶做 All-Reduce,聚合完成后全局参数完全一致——这既是 DDP 的强项,也是监控的盲区:
- 框架日志里的
grad_norm通常是聚合后的值,单卡异常会被平均掉; - 某张卡数据分布偏斜、精度异常时,全局 Loss 曲线依然平滑,但各 Rank 的优化动态早已分化。
所以监控点必须选在 All-Reduce 之前的"原始梯度"。而 DDP 恰好留了口子:DistributedDataParallel.register_comm_hook() 允许你在每个梯度桶执行规约前插入自定义通信逻辑。这就是 its-stable-llm 的核心抓手。
三个关键角色:一条完整的采集链路
整个方案由三部分协作完成,代码集中在 code/run.py 和 code/experiments/run.py:
| 角色 | 位置 | 职责 |
|---|---|---|
PreAllReduceGradNorm |
code/run.py#L32-L41 | 累加器:缓存各梯度桶平方和、最新范数 |
make_comm_hook |
code/run.py#L44-L76 | 注册进 DDP 的通信钩子,边采集边做规约 |
HookedTrainer |
code/run.py#L128-L211 | 继承 transformers 的 Trainer,负责注册 Hook、落盘日志 |
深扒一:make_comm_hook——采集与同步一次完成 ⚡
通信钩子的签名是 hook(state, bucket),DDP 在每个梯度桶 All-Reduce 之前调用它,并期望它返回规约后的张量。make_comm_hook 闭包捕获 PreAllReduceGradNorm 实例,在每个桶到来时做三件事(code/run.py#L45-L74):
- 取桶张量:兼容
buffer()/get_buffer()/get_tensor()三种 GradBucket API,屏蔽 PyTorch 版本差异(code/run.py#L47-L56); - 本地采集:把桶内梯度平方和累加进
sum_sq,实时更新latest_norm;并在桶序号为 0 时reset(),把窗口对齐到"一次 backward 同步"(code/run.py#L59-L65); - 异步规约:调用
dist.all_reduce(t, SUM, async_op=True),用 future 的then()回调完成除以 world_size 的均值,保持 DDP 原有的"求和再平均"语义(code/run.py#L66-L74)。
核心逻辑非常精炼:
gn.sum_sq += float(t.float().pow(2).sum().item())
gn.latest_norm = math.sqrt(gn.sum_sq)
fut = dist.all_reduce(t, op=dist.ReduceOp.SUM, async_op=True).get_future()
return fut.then(_post) # 规约结果 / world_size
💡 一个细节:因为钩子"接管"了规约,DDP 桶内走的是你写的 all_reduce。这里刻意用异步方式发起,避免阻塞采集路径。
深扒二:HookedTrainer——把数据闭环走完
HookedTrainer 重写了 training_step(code/experiments/run.py#L137-L212),每个训练步的时序是:
- 一次性注册 Hook:检测到模型是 DDP 实例后调用
model.register_comm_hook(...),用_hook_registered标志位防止重复注册(code/run.py#L136-L152); - 先摘本地 Loss:在 loss 被任何规约动作污染前,
detach()存下loss_local; - backward 触发钩子:只有到达梯度同步点的 micro-step 才会触发通信钩子,因此梯度累积(
gradient_accumulation_steps=4)期间no_sync的 micro-step 里grad_norm_pre_ar为None,这是设计内的行为; - 分两路落盘:
LossGradLogger:每个 Rank 各自写loss_grad_{时间戳}_rank{N}.jsonl,字段为step / rank / loss_local / grad_norm_pre_ar(code/run.py#L82-L101);Rank0ReducedLogger:仅 Rank 0 把规约后的loss_reduced/grad_norm_reduced写入聚合日志(code/run.py#L103-L123)。
关于聚合梯度范数,代码里有个容易踩错的数学细节(code/run.py#L194-L201):先 All-Reduce 各 Rank 的平方和 sum(g²),再开方,得到的是真正的全局 L2 范数;如果直接平均各卡范数会系统性低估。
对照实验:用"故意失配"验证诊断能力 🔬
仓库在 code/experiments/ 下内置了一组对照实验,专门检验上述日志能否暴露 Rank 级分化(各脚本默认 seed=42,差异仅在进程级随机种子):
| 实验 | 种子策略 | 预期现象 |
|---|---|---|
| S1-1.py | 全 Rank seed=42 |
严格一致,Loss / 范数离散度最低 |
| S1-2.py | Rank0 seed=42+999,其余 42 |
轻度失配,Worker 级离散度略升 |
| S1-3.py | seed=42+rank*10 |
显著失配,各 Rank 分化明显 |
| S2-1.py / S2-2.py | FP32 / BF16 精度对照 | 考察精度对梯度范数的影响 |
配合 8 卡 torchrun 启动(示例见 code/run.ipynb 与 README.md 的"学习教程"一节),即可得到完整的 per-rank 诊断序列。
日志字段速查表 📊
拿到 JSONL 后,常用诊断视角如下:
| 字段 | 来源 | 用途 |
|---|---|---|
loss_local |
各 Rank 本地 | 计算 Rank 间 Loss 极差,识别局部分化 |
grad_norm_pre_ar |
各 Rank All-Reduce 前 | 检测单卡梯度尖峰、尾部扩张 |
loss_reduced |
Rank0 聚合 | 全局平滑基线 |
grad_norm_reduced |
Rank0 聚合 | 与 local 值对比看"平均掩盖了多少差异" |
当 max(|loss_local_i - loss_reduced|) 持续走高而全局曲线平滑时,就是典型的失稳前兆信号。
小结
its-stable-llm 的巧思在于:不修改任何训练逻辑,仅用 DDP 官方预留的 Communication Hook 一个挂载点,就把"各卡梯度范数"这个原本被 All-Reduce 抹平的维度留了下来。整套实现不到两百行,对做昇腾 NPU 大模型训练监控的读者来说,是一份可以直接照抄的轻量模板。想继续了解实验设计与版本记录,可参考 CHANGELOG.md 与测试报告 its-stable-llm_Test_Report.md。