单卡训练一切正常，loss听话地往下掉，显存也够用。你为了赶进度把模型塞到两张甚至四张卡上，启动命令从python train.py改成torchrun ...，然后噩梦就开始了：进程直接卡死、NCCL报错、loss曲线像心跳图一样震荡、GPU利用率只有30%...这套组合拳打下来，再佛系的人也会怀疑人生。
这篇文章我想把分布式多卡训练（DDP）这条路上的坑系统性地捋一遍。不是贴官方文档，而是把我自己从第一次接触DDP到后来能稳定跑几十张卡的过程中，踩过、看过、帮人排查过的那些问题整理成一份排查手册。内容会更贴近实际使用场景，不管是刚入门的初学者，还是被线上任务折磨的资深工程师，应该都能找到自己需要的那块拼图。
1. 单卡跑得好好的，一上DDP就崩：先搞懂DDP到底改了什么
很多人的第一反应是"DDP把我的代码改坏了"，其实DDP压根没改你的代码，它改的是"代码运行的方式"。理解这一点，后面排查问题会顺畅很多。
1.1 DDP和DataParallel的差异：不只是名字不同
PyTorch里有两套多卡方案，torch.nn.DataParallel（DP）和torch.nn.parallel.DistributedDataParallel（DDP）。DP是老方案，写法简单，一行代码就能把模型包起来，但它有j几个硬伤：多进程虽然都叫多卡，DP其实是单进程多线程，一个进程的GIL会限制吞吐；通信走的是GPU 0这块卡做梯度聚合，很容易把GPU 0的显存和通信带宽打满，形成单点瓶颈；而且DP的负载均衡很差，卡多了以后加速比基本是线性衰减的。所以当你用DP跑8卡的时候，实际效果可能和4卡差不多，甚至更慢。
DDP的实现思路完全不同，它是真正意义上的多进程：每张卡对应一个独立进程，每个进程持有完整的模型副本和优化器状态，前向和反向都在本地计算，然后通过ring-allreduce算法在进程之间同步梯度。环形通信让每张卡只和相邻卡通信，通信量均衡分布在所有卡上，不存在单点瓶颈。这也是为什么DDP能支撑起几百张卡规模的训练任务。
理解这个差异非常关键，因为很多从DP迁移到DDP的人会保留DP时代的惯性思维：模型包一层就完事了，反正都是"多卡"嘛。实际上DDP对代码结构、数据加载、进程管理都有明确要求，任何一环没跟上，训练就跑不起来。
1.2 分布式训练的根本：进程、rank、world_size
DDP的整套逻辑建立在一组基础概念上，我把它们用最直白的方式解释一下：
- process（进程）：每张GPU卡对应一个Python进程，这个进程只操作自己那块卡。
- rank（进程编号）：每个进程有一个全局唯一的编号，从0到
world_size-1。它决定了这个进程使用哪块GPU、处理哪一部分数据。 - local_rank（本地进程编号）：在一台机器内部，每个进程的编号，通常从0到
num_gpus_per_node-1。单机多卡时local_rank和rank是同一个值，多机多卡时local_rank就是本机内编号。 - world_size（全局进程数）：所有参与训练的进程总数，等于机器数乘以每台机器的卡数。
- master_addr / master_port：rank 0进程的IP地址和端口，其他进程通过它来建立初始通信。
每次新开一个项目，我都会习惯性地花两分钟把这张表写进笔记里。因为后续所有启动参数的设置、所有报错信息的解读，都离不开这几个概念。很多人看到world_size报错就懵了，其实它就是在告诉你"我期望4个进程，但只找到了2个"。
还有一层容易被忽视的基础知识：init_method。DDP要求所有进程在训练开始前先完成一组网络握手，PyTorch默认用环境变量方式env://来初始化进程组，也就是从MASTER_ADDR、MASTER_PORT、WORLD_SIZE、RANK这几个环境变量里读取分布式配置。torchrun这样的启动工具会自动帮我们设置好这些变量，但如果你绕开torchrun手动启动进程，就必须手动把它们设置正确，一个不对就是起不来或者进程组初始化失败。
2. 启动阶段连环坑：环境变量、进程调度与初始化顺序
如果说单卡训练是从代码开始的，那么DDP训练是从"启动"开始的。这一阶段的问题往往最让人抓狂，因为代码逻辑完全没跑到，报错却在最开始就出现了。
2.1 GPU设备分配：CUDA_VISIBLE_DEVICES的潜规则
这是DDP入门的第一个经典大坑。很多人想用0号卡和1号卡训练，启动脚本里写了CUDA_VISIBLE_DEVICES=0,2，然后在代码里用torch.cuda.set_device(local_rank)来分配设备。看似合理对吧？但实际跑起来你大概率会遇到两种问题：一是第0个进程被分到了物理GPU 2上，二是进程组初始化时NCCL找不到设备。
为什么？因为CUDA_VISIBLE_DEVICES=0,2会把物理GPU 2重映射成逻辑GPU 1，所以NCCL看到的设备编号是0和1，而不是物理编号0和2。你的代码里如果用了set_device(local_rank)，local_rank=1时设置的是逻辑设备1，也就是物理GPU 2，这倒是能对上；但如果你的代码里写死了torch.device('cuda:' + str(args.local_rank))，且没有先设置CUDA_VISIBLE_DEVICES，那就会把local_rank=1的进程硬塞到物理GPU 1上，完全不理会你原本的分配计划。
正确的做法是：如果你用torchrun启动，它会自动设置好环境变量，你要做的就是在代码最前面（设置模型和tensor之前）执行：
import torch import torch.distributed as dist local_rank = int(os.environ['LOCAL_RANK']) torch.cuda.set_device(local_rank)torchrun已经把CUDA_VISIBLE_DEVICES设置成了只暴露本机卡，所以local_rank和CUDA逻辑设备号是对应的。这块我一直严格遵守一个原则：进程启动后第一件事就是设置设备，绝不在初始化分布式环境之前创建任何CUDA tensor。因为一旦某个进程的CUDA上下文先创建了，它可能被绑定到错误设备上，后续set_device也无力回天，表现就是显存分配到了某张不想要的卡上、NCCL初始化失败。
2.2 启动方式：torchrun、python -m、手动多进程的区别
不同启动方式对新手来说是个隐形陷阱。官网现在推荐的是torchrun，但是网上大量老教程还在用python -m torch.distributed.launch。这两个方式在参数上有细微差别，torchrun用--nproc_per_node，而torch.distributed.launch也支持这个参数，但老代码经常写--ngpus_per_node，格式完全不同。
我自己统一使用torchrun，写法如下：
torchrun --nproc_per_node=4 \ --master_port=29500 \ train.py --args...这里有一个非常容易忽略的细节：--master_port。如果多个人在同一台机器上同时起训练任务，或者你自己起了任务没关掉就再起一个，默认的29500端口很容易被占用，然后报Address already in use。这个报错信息模棱两可，经常被误认为网络问题，调半天防火墙才发现是端口被前面的任务占了。
排查这个问题的快捷命令：
netstat -tlnp | grep 29500看到进程ID后，用kill结束旧任务，或者换一个不常用的端口比如29501、32000+。我在团队里已经形成了习惯：需要长时间跑的任务固定端口段，其他临时任务用随机高位端口，从源头上避开冲突。
torchrun和不用torchrun的另一个核心区别是RANK和LOCAL_RANK这两个环境变量。用torchrun时，它帮你设置好一切；不用时，你需要手动为每个进程设置环境变量，一旦漏了RANK，初始化进程组会直接报Environment variable RANK is not set，这是最常见的启动失败原因之一。
2.3 初始化顺序：dist.init_process_group放哪个位置很关键
进程组初始化的位置不是随便放的，它必须在所有使用GPU的操作之前。一个原本能跑的单卡代码，如果加了DDP却在init_process_group之前创建了模型并放到CUDA上，会直接报初始化失败或者进程卡住。
完整的顺序应该是：
import os import torch import torch.distributed as dist # 步骤1：读取环境变量并设置设备 local_rank = int(os.environ['LOCAL_RANK']) torch.cuda.set_device(local_rank) # 步骤2：初始化进程组 dist.init_process_group(backend='nccl') # 步骤3：创建模型并放到设备 model = MyModel().cuda() model = torch.nn.parallel.DistributedDataParallel(model, device_ids=[local_rank]) # 步骤4：构建数据加载器 # 步骤5：开始训练循环注意一个细节：init_process_group里如果没指定init_method，它会默认读环境变量。用torchrun启动时这些变量是齐的，但如果你是手动起进程，就必须自己设好。backend='nccl'是GPU训练的首选后端，CPU训练才用gloo。如果版本比较老，还需要在init_process_group里指定一个唯一的rank，但现在环境变量有了以后一般不传也不会错。
还有一种坑是初始化方式不一致。比如有同事喜欢在代码里写init_method='tcp://...'去指定通信地址，有时候IP写错了或者端口被占用也会卡住。初期调试如果遇到hang住不出日志，最优先检查的就是init_process_group是否能顺利通过。
2.4 随机种子：少一个种子的罪与罚
DDP要求每个进程独立、可复现地运行，但进程之间又是相互依赖的生产者/消费者关系。如果不设置随机种子，每个进程初始化模型参数的随机权重就不一样，训练从第一步就开始发散，梯度同步没有任何意义，loss曲线出现各种奇怪形态。这是很多人训练正常但结果总不对劲的隐性原因之一。
每个进程里都应该在进程组初始化之后、模型初始化之前设置好所有随机源：
import random import numpy as np import torch def set_seed(seed=42): local_rank = int(os.environ['LOCAL_RANK']) seed = seed + local_rank # 每个进程不同的种子 random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed(seed) torch.cuda.manual_seed_all(seed)使用seed + local_rank而不是完完全全相同的种子，是因为有些操作（比如BatchNorm的统计值）期望不同进程看到不同的随机序列，后续结果才不至于所有卡生成一模一样的数据。但这里有个反直觉的细节：模型初始化的权重必须所有进程一致，数据加载的偏移和增强的随机性必须各进程不同。所以种子策略是"模型前固定，数据后分开"。我在实际项目里的做法是：初始化前先torch.manual_seed(seed)让所有进程模型一致，然后在构造DataLoader时加上worker_init_fn配合seed + rank做差异化。
3. 训练运行中的隐蔽坑：数据采样、日志、状态同步与恢复
前面的坑还算明显，启动阶段过了，训练开始后又是一堆暗雷。这些坑不会让你一眼崩溃，但会让结果离谱、时间白白浪费。
3.1 DistributedSampler的乱序问题
DDP训练里，每个进程负责处理一部分数据，靠的是torch.utils.data.distributed.DistributedSampler。很多人踩的第一个坑是：用了DataLoader(shuffle=True)，同时结合DistributedSampler，结果每个epoch喂给模型的数据顺序是错误的，或者某些数据永远没有被采到。
DistributedSampler内部自带shuffle逻辑，你需要在每个epoch开始时手动调用sampler.set_epoch(epoch)，否则每个epoch的shuffle顺序会完全一样。更重要的是，如果DataLoader里同时开了shuffle=True，那就和sampler的shuffle冲突了。我自己固定写法是：
sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank, shuffle=True) dataloader = DataLoader(dataset, batch_size=batch_size, sampler=sampler, num_workers=4, pin_memory=True) for epoch in range(epochs): sampler.set_epoch(epoch) for batch in dataloader: ...另外一个很容易被忽视的点是batch_size的含义。在DDP模式下，如果你在DataLoader里设置batch_size=32，那么每个进程都会取32个样本，一个step的实际batch size是32 × world_size。这直接影响学习率设置、梯度累积的步数计算和显存预估。不少人一开始没概念，直接用单卡batch size跑8卡，结果显存爆炸，或者学习率没有同步放大导致收敛极慢。合理做法是让每个进程的batch size和单卡时保持一致，然后按照world_size倍数放大全局学习率（或者在优化器里做线性缩放），具体要结合任务调节，没有通解，但至少要知道"全局batch size = 单进程batch size × 卡数"这件事。
3.2 日志和 checkpoint 的进程重复问题
DDP下所有进程都执行同样的代码，如果打印一行日志，你会看到8行完全相同的输出。如果保存模型文件，你会看到8个一样的checkpoint。这看起来无伤大雅，但日志把你刷到找不到有效信息、checkpoint占满磁盘的时候，就很痛苦了。
比较规范的做法是：只让rank 0进程负责日志打印、指标记录、模型保存这些"全局职责"：
if dist.get_rank() == 0: print(f"Epoch: {epoch}, Loss: {loss.item():.4f}")checkpoint保存也只在rank 0上执行。这一条看起来简单，但很多人是在整个任务跑完，发现最后一轮模型是坏的、或者压根没有checkpoint时才想起来。更隐蔽的问题是：rank 0负责保存模型，但模型每个进程都有副本，保存前要确保当前epoch所有进程的模型状态一致。正常情况下梯度同步保证了参数一致，但如果你自己改了某些参数、手动调用了no_sync，就可能出现某个进程的模型和其他进程不同步的情况。所以我保存模型时，除了常规的model.module.state_dict()之外，还会把优化器状态、随机数状态、epoch、scaler（用AMP时）一起存下来，方便断点续训。
3.3 从checkpoint恢复时的状态同步
断点续训是DDP里的重灾区。很多人保存checkpoint的时候没想太多，恢复的时候，每个进程都用同样的文件恢复模型，模型是一致的，但每个进程的随机数状态、DataLoader的采样起始位置并不一致，导致恢复后第一个epoch的数据分布和训练曲线出现跳变。
通用的恢复流程应该是：
checkpoint = torch.load(path, map_location='cpu') model.module.load_state_dict(checkpoint['model_state']) optimizer.load_state_dict(checkpoint['optimizer_state']) sampler.set_epoch(checkpoint['epoch']) for state in torch.random.get_rng_state_all(): ...更为关键的是：如果只在一个进程（比如rank 0）上恢复了优化器状态，其他进程没有恢复，那么后续梯度更新时各进程的优化器状态就乱了，模型参数开始发散。解决方案是让所有进程都加载同一份checkpoint，因为checkpoint是从rank 0保存下来的，所有进程都能访问到，直接都加载即可。一行dist.barrier()再配合所有进程加载，就避免了"有的进程读完、有的进程还没读"的竞态问题。
3.4 数据集划分与缓存：坑在数据预处理阶段
DDP很容易让人忽略数据预处理部分的并行语义。比如你有预处理逻辑（图像解码、数据增强）写在Dataset.__getitem__里，这个逻辑会在每个进程复制执行。数据量大的时候，8个进程一起做重复的预处理，CPU直接被打满，GPU却在空转等数据。
排查这个问题时，用nvidia-smi看GPU利用率会发现利用率忽高忽低，最常被误判为"NCCL通信慢"或者"训练代码有bug"。实际原因是num_workers过低、数据预处理过重、或者数据读取路径里有不可并行的共享锁。我一般会先把num_workers调到4-8，然后在Dataset里对核心耗时操作做缓存，比如离线把resize做完存成内存中的list，训练时只做随机裁剪等轻量增强。
还有一类缓存坑：某些第三方库会在各进程的临时目录（/tmp）里缓存特征，比如huggingface的datasets库。多个进程同时写同一个缓存目录可能互锁或写坏文件。问题是它报的错五花八门——权限错误、文件不存在、HDF5错误——排查半天都是一头雾水。解决办法是给每个进程设置独立的缓存目录：TMPDIR=/tmp/rank_${LOCAL_RANK}，或者把这些缓存目录指向不同的地方。在NFS或者SSHFS这种网络文件系统上训练时更要当心，缓存目录和checkpoint目录的网络IO往往是隐形性能瓶颈。
4. 性能问题：显存占满但GPU利用率上不去，通信成了瓶颈
训练能跑通，loss也能收敛，但训练速度就是上不去，8卡加速比只有3倍，这就到了性能调优阶段。性能问题最隐蔽，因为报错很少，只有数据说话。我一般按照下面几条路径排查。
4.1 先看GPU利用率和CPU瓶颈
拿到一个DDP训练任务，第一件事是开一个终端监控工具：
watch -n 1 nvidia-smi重点看两个指标：GPU-Util和Memory-Usage。如果GPU-Util在0%-100%之间剧烈跳动，说明GPU在频繁地等数据。这时候大概率数据加载环节出问题了。如果GPU-Util一直很低（个位数到30%），而CPU的使用率很高（top看每个core都打满），说明数据预处理或者数据读取代销超过了GPU计算。
经典的排查手段是：先把num_workers调大，再看pin_memory=True是否设置。pin_memory本质上是让数据loader分配"锁页内存"，从CPU到GPU的拷贝更快，你不用太关心原理，照做就行。还有一个常见误区的细节：num_workers开大了并不一定代表快，比如你在Windows上跑，num_workers>0反而可能更慢，因为进程启动的额外开销比并行收益还大；在Linux服务器上就比较靠谱。
接下来是NCCL通信时间。DDP做梯度同步时所有进程都要等待最慢的那个，如果数据加载不均衡，某个进程单步时间比其他进程慢，整个训练就被拖慢。这种情况下，可以适当增大DataLoader的prefetch_factor（默认2），让数据加载提前多缓冲几批。
4.2 DDP参数调优：find_unused_parameters、static_graph、gradient_as_bucket_view
这三个参数是DDP性能的隐藏开关，很多人一辈子都用默认值，遇到性能问题只能干瞪眼。
find_unused_parameters：默认
False。如果你的网络中存在一些没有参与loss计算、没有梯度的参数（比如BERT在某次forward中没有使用的某些层、或多任务训练中某些分支没被激活），DDP在后向传播时会因为找不到所有参数的梯度而报错。把find_unused_parameters=True能让它通过，但代价是每次迭代都要额外遍历一次参数，性能有明显损耗。所以我建议：网络结构稳定、没有unused参数时保持False；如果确实要使用，优先检查是否能通过结构调整消除unused参数，而不是长期依赖这个开关。static_graph：DDP假设每次迭代的计算图结构可能变化，所以它会做一些动态检查。如果你的模型每轮forward的结构完全一样（绝大多数训练任务都是如此），设置
static_graph=True可以让DDP跳过这些检查，减少一部分开销。这个参数比较隐蔽，但对某些小模型或者计算很快的模型非常有效。gradient_as_bucket_view：默认
False。这个参数让DDP把所有参数的梯度打包到同一个连续存储块（bucket）中，通信时直接对这块内存做allreduce，而不是逐个tensor通信。显存占用会更友好，通信效率更高。我的做法是设置True，这个参数在PyTorch 1.7+开始支持，几乎没有副作用。
还有一个常常被忽略的优化点：broadcast_buffers。DDP默认会在每次forward前广播buffer（比如BatchNorm的running_mean/running_var），如果你的模型里BatchNorm很多，广播开销不小。当显存和通信都吃紧时，分析一下你的模型是否真的需要跨卡同步BN统计值，如果场景允许（比如小batch足够你不需要同步BN），可以设置broadcast_buffers=False，能省下一些通信量。注意这两个是互斥的：你想省通信选False，你想用同步BN选True，没有既省又同步的办法。
4.3 梯度累积与no_sync的正确姿势
梯度累积（gradient accumulation）是模拟大batch的经典技巧，配合DDP时有个大坑。默认情况下，每次loss.backward()都会触发一次跨进程的梯度allreduce通信。如果你一次迭代做4步梯度累积，就会通信4次，而其中3次完全没有必要。正确做法是在前3步加model.no_sync()上下文管理器，在第4步才执行真正的累积同步：
with model.no_sync(): loss = compute_loss(model, batch) loss.backward() # 只会本地累积，不触发跨卡同步 # 第4步，正常backward触发同步 loss = compute_loss(model, batch) loss.backward() optimizer.step() optimizer.zero_grad()这个优化对加速效果非常明显。尤其你的模型单次forward时间很短、通信时间占比高的时候，不做这个优化就是白白浪费3/4的通信开销。注意no_sync必须配合优化器的梯度累积逻辑使用，即你不能在no_sync块内调用optimizer.step()，否则梯度的更新状态就乱了。
另一个相关的问题是：你开启梯度累积后，如果学习率调整策略是按step调整的，那你实际上的"逻辑步"是4次迭代才更新一次，学习率调度器的step也要相应每4次迭代才调一次，否则你实际上会比预期学习率衰减快很多，导致收敛变慢。这个细节不容易看错，但改动后收敛行为异常时优先检查。
4.4 多机多卡时NCCL通信稳定性问题
从单机多卡扩展到多机多卡，NCCL通信的坑会指数级增多。最常见的是NCCL timeout，报错信息形如：
RuntimeError: NCCL error in: ProcessGroupNCCL::broadcast: NCCL communicator aborted这类问题出现时，先检查以下几点：
- 网络连通性：
ping测试机器之间是否通，NCCL走的是RDMA或TCP，拥塞或丢包都会导致超时。 - master_addr设置：
MASTER_ADDR必须指向rank 0所在机器的IP，端口要能在所有机器上访问。当然也不能是防火墙屏蔽的端口。 - NCCL环境变量：设置
NCCL_DEBUG=INFO可以看到更详细的通信日志，定位是哪一步卡住。NCCL_SOCKET_IFNAME需要和实际网卡名对应，比如NCCL_SOCKET_IFNAME=eth0。集群环境里IP地址有多个网卡时，这个变量尤其重要。 - 带宽和拓扑：多机通信最好走高速网络（如InfiniBand），如果走千兆以太网，传输大量梯度时性能大幅下降。至少要知道你的环境是哪种网络，做一次简单的带宽测试再决定模型大小和卡数是否匹配。
很多人觉得NCCL报错就是代码问题，其实很多时候是网络环境问题。我会在项目早期就做一个最小化的NCCL通信测试：
# test_nccl.py import torch import torch.distributed as dist dist.init_process_group(backend='nccl') rank = dist.get_rank() tensor = torch.ones(1024, 1024).cuda(rank) dist.all_reduce(tensor) print(f'Rank {rank}: NCCL communication test passed')用torchrun --nproc_per_node=... --nnodes=... train.py类似的方式起这个测试脚本，能快速判断分布式通信环境是否正常。不要等到训练跑到一半才去排查网络问题。
5. 从踩坑到稳定：我沉淀下来的一套DDP工程规范
经历了这么多之后，我开始把DDP训练当作一个有固定流程的工程来做，而不是每次踩坑再修。这里有几个我一直在用的规范，对新人尤其重要。
5.1 最小可复现的启动模板
我每次开始新项目时，都从下面这个模板起步，它包含了所有DDP必须的要素，已经跑通过无数次，能排除90%的启动错误：
# train.py import os import random import argparse import numpy as np import torch import torch.distributed as dist import torch.nn as nn from torch.utils.data import DataLoader, Dataset from torch.utils.data.distributed import DistributedSampler def setup(): local_rank = int(os.environ['LOCAL_RANK']) world_size = int(os.environ['WORLD_SIZE']) rank = int(os.environ['RANK']) torch.cuda.set_device(local_rank) dist.init_process_group(backend='nccl', init_method='env://') return local_rank, world_size, rank def cleanup(): dist.destroy_process_group() def set_seed(seed, local_rank): random.seed(seed + local_rank) np.random.seed(seed + local_rank) torch.manual_seed(seed + local_rank) torch.cuda.manual_seed(seed + local_rank) torch.cuda.manual_seed_all(seed + local_rank) class DummyDataset(Dataset): def __init__(self, size=1000): self.data = torch.randn(size, 64) self.label = torch.randint(0, 2, (size,)) def __len__(self): return len(self.data) def __getitem__(self, idx): return self.data[idx], self.label[idx] def main(): local_rank, world_size, rank = setup() set_seed(42, local_rank) dataset = DummyDataset() sampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank, shuffle=True) dataloader = DataLoader(dataset, batch_size=32, sampler=sampler, pin_memory=True) model = nn.Sequential(nn.Linear(64, 128), nn.ReLU(), nn.Linear(128, 2)).cuda() model = nn.parallel.DistributedDataParallel(model, device_ids=[local_rank], output_device=local_rank) criterion = nn.CrossEntropyLoss() optimizer = torch.optim.SGD(model.parameters(), lr=0.01) for epoch in range(5): sampler.set_epoch(epoch) for data, label in dataloader: data, label = data.cuda(), label.cuda() logits = model(data) loss = criterion(logits, label) optimizer.zero_grad() loss.backward() optimizer.step() if rank == 0: print(f'Epoch {epoch}, Loss: {loss.item():.4f}') cleanup() if __name__ == '__main__': main()启动命令：
torchrun --nproc_per_node=2 train.py这个模板虽然简单，但它正确处理了设备分配、进程组初始化、数据采样、模型封装、日志隔离、进程组销毁这些核心环节。当你的训练出问题时，先把任务代码套回这个模板跑一遍，能跑通再逐步替换成真实的数据和模型。这种二分排查法能快速缩小问题范围。
5.2 每个训练脚本都要有的环境探针
深入DDP之后，我养成了一个习惯：在每个训练脚本的初始化阶段加一段环境打印，把关键信息输出到日志里，方便后续排查问题。这个"环境探针"长这样：
if rank == 0: print(f'[Env] PyTorch: {torch.__version__}') print(f'[Env] CUDA: {torch.version.cuda}') print(f'[Env] NGPU: {world_size}, Rank: {rank}') print(f'[Env] NCCL: {torch.cuda.nccl.version()}') print(f'[Env] GPUs: {torch.cuda.get_device_name(local_rank)}')这段信息在排查"为什么这个版本能跑，那个版本不能跑"、"为什么换了机器就报NCCL错误"这类问题时极其有用。多机训练时尤其要保证所有机器的PyTorch、CUDA、NCCL版本一致，版本不匹配可能导致NCCL初始化行为异常。我遇到过的最离谱的一次，就是两台机器上的CUDA小版本不一致，导致通信协议协商失败，报错非常诡秘。
5.3 排查DDP问题的固定排查链路
踩了这么多坑，我最终沉淀出一套自己的排查链路。每当DDP训练出问题，我会按下面的顺序一个环节一个环节地检查，效率远高于随机搜索：
- 启动环境：
torchrun能不能成功执行，是否报端口/文件/权限错误。 - 进程组：所有进程是否成功调用了
init_process_group，是否设置了正确的backend。 - 设备设置：每个进程的
torch.cuda.set_device是否在CUDA操作之前执行，设备编号是否和LOCAL_RANK一致。 - 数据加载：
DistributedSampler是否正确传给DataLoader，是否存在shuffle=True冲突。 - 模型封装：
DistributedDataParallel的device_ids和output_device是否正确，是否在模型调cuda()之后封装。 - 通信与同步：报错是否出现在
backward或step阶段，如果是，要怀疑梯度同步问题，检查是否有unused parameters、是否某个进程的forward分支不同导致死锁。 - 性能监控：nvidia-smi看GPU利用率和显存是否均衡，
top看CPU状态，NCCL_DEBUG=INFO看通信日志。
这套链路被我写成了团队内部的文档，后来很多新同事照着排查，大部分问题都能自己解决，找我的次数大大减少。
写在最后的一些零碎经验
最后分享几个不太好归类、但实际中总会遇到的零碎经验。
多进程的错误处理比单卡诡异得多。在单卡上，某个进程exception直接抛出来，程序退出。但DDP下，如果rank 0那个进程抛错退出，其他进程还在等待通信，就会hang住。所以DDP训练日志里看到某个进程报错时，整个任务通常表现为"卡死"而非"退出"，这个现象本身就是一个信号：先去查崩溃日志，而不是盯着通信配置发愁。我一般建议在每个训练脚本里加上进程崩溃时的处理逻辑：如果任意进程非零退出，用torch.distributed.destroy_process_group()加os.kill让所有进程尽快结束，避免僵尸进程占着GPU显存不放。
关于显存不均衡问题。如果每张卡的batch size一样，理论显存应该基本一致。但实际中经常看到某张卡显存明显高于其他卡，数据和batch size看起来也都对。排查方向有两个：一是某些进程的dataloader采样了不同长度的序列（NLP任务），存在padding不均问题；二是某个进程显存没有释放干净（比如多余的tensor没释放）。对第一个问题，DistributedSampler配合drop_last=True可以缓解长度不匹配带来的步数错乱。对第二个问题，就要靠显存监控工具（比如nvidia-smi dmon）查看是谁占着显存。
还有一个容易被忽略的经验：不要在训练过程中用torch.cuda.empty_cache()。这个函数会清理缓存块，看起来像是释放了显存，但实际上下一个forward会触发更耗时的重新分配，反而让训练变慢。它更适合做显存调试，比如临时观察最大可用显存，而不是作为常规训练的一部分。
如果你正准备把项目从单卡改成DDP，我的建议是先跑通最小模板，然后用一个简单的模型完整训练几个epoch，确认收敛没有问题，再把真实模型搬进去。不要一步到位，否则出错时单卡模型、DDP环境、数据并行、模型结构这几个变量纠缠在一起，排查难度剧增。分布式训练本质上没有多神秘，只要理解了进程模型、数据划分和通信同步这三件事，剩下的坑基本都可以通过日志和监控一步步定位。
