分布式训练这件事一旦从单机八卡跨到多机问题就从模型写没写对变成了调度、网络、存储、容错四件事同时压过来。Kubernetes 上跑 PyTorch 分布式本质上就是把这四件事交给集群去管谁先起、谁是 0 号节点、显卡怎么分、数据从哪读、断了之后从哪个 checkpoint 续。这篇内容会从选型、镜像、YAML 逐字段拆解、通信调优到排错把一条能真正跑起来的多机多卡链路讲透适合已经会用torchrun单机跑、但一上集群就卡在Waiting for rank 0或者 NCCL 超时的开发者也适合负责给算法团队搭训练平台的同学。1. 先确认这套训练到底该不该搬进集群1.1 单机多卡与多机多卡的分水岭很多人是被显存逼上集群的这个动机本身没问题但判断标准得换一下。我的经验是看两条线一是单机 8 卡在你能接受的 batch size 下一轮训练时间是否已经长到影响迭代节奏二是数据量增长后单机 8 卡是否已经装不下完整的数据并行切分。如果单机 8 卡跑一个 epoch 只要几十分钟那多机带来的通信开销很可能把收益吃光。多机并行的效率不是线性叠加的8 卡到 16 卡实际吞吐能到 1.7 倍就算不错到 32 卡可能只剩 1.5 倍甚至更低具体取决于模型大小、梯度同步量和网络带宽。换个角度说模型参数量在 1 亿以下、单卡放得下完整模型、只是数据量大优先考虑的是把数据加载流水线做扎实而不是加机器。真正该上多机的典型场景是单个模型用 8 卡 梯度累积仍然要吃几天或者单卡显存放不下哪怕一个 micro-batch。这时候多机的价值才立得住因为你是拿通信换时间而不是拿通信换一个本来就够用的结果。还有一类隐性成本容易被忽略集群上的 GPU 是共享资源你的任务随时可能被别人挤占也可能因为节点维护被驱逐。所以上集群之前就要想好 checkpoint 策略否则一次抢占丢掉三天训练量比单机慢一点更让人崩溃。1.2 容器化训练真正解决的三个麻烦把训练塞进容器收益不在跑起来这一步而在反复跑起来。第一是环境一致性CUDA 驱动由宿主机负责但 CUDA runtime、cuDNN、NCCL、PyTorch 版本、Python 依赖全部封在镜像里换一台机器不用再担心libnccl.so找不到或者版本不匹配。第二是资源隔离与配额GPU 用nvidia.com/gpu这种扩展资源来申请由设备插件统一分配谁占了几张卡一目了然不用再靠人工约定这台机器归你。第三是失败恢复Pod 挂了由控制器重建配合持久化存储上的 checkpoint任务能从断点续上而不是从零开始。但容器化也带来两个新麻烦必须提前知道。一是共享内存容器默认/dev/shm只有 64MBDataLoader 的 worker 进程一多就会报Bus error这个坑几乎人人踩过。二是网络命名空间容器内的网卡名、IP 和宿主机不一样NCCL 自动选网卡经常选错导致本来该走高速互联的流量走了普通网络性能直接腰斩。提示如果你现在的训练脚本在裸机上跑得好好的先别急着改代码。80% 的上集群失败都是环境和编排配置问题跟模型代码无关。2. 编排方案选型原生命令加 Job还是专用 Operator2.1 两种路线的能力边界对照Kubernetes 上跑 PyTorch 分布式主流就两条路。一条是用原生Job或StatefulSet承载 Pod容器启动命令里直接调torchrun靠环境变量注入 rank 信息。另一条是引入专门的训练 Operator用自定义资源描述训练任务Operator 负责创建 Pod、注入MASTER_ADDR、WORLD_SIZE、RANK这些变量还支持弹性伸缩。维度原生 Job torchrun训练 Operator上手成本低会写 YAML 就行中要先装 CRD 和控制器rank 信息注入自己拼环境变量或 DNS自动注入弹性扩缩容需要自己做 rendezvous原生支持与调度器联动需自行配置 gang 调度多数已内置排错可见性Pod 日志直接看多一层资源状态需熟悉适合团队任务形态固定、规模小任务多、需要平台化这个表不是让你二选一搞对立而是帮你判断当前阶段该付多少学习成本。团队只有三五个算法同学、每周跑两三次训练用 Operator 属于拿大炮打蚊子反过来如果有几十个任务天天排队手工维护 Job 的 YAML 会把人耗死。2.2 我倾向先用原生 Job 跑通的原因我自己的做法是先用原生 Job 把整条链路跑通再决定要不要上 Operator。理由很实际原生方案把每个环节都摊在明面上MASTER_ADDR是谁、WORLD_SIZE是几、Pod 之间能不能解析域名全部你得自己确认一遍。这个过程很痛但痛完之后你对分布式训练的运行机理会有完全不同的理解。等链路稳了再迁到 Operator你就知道它帮你省掉的是哪部分工作出问题时也能一眼看出是哪一层的事。具体到 rank 信息的注入最稳的办法是给 Pod 挂一个 headless Service让每个 Pod 拥有稳定的 DNS 名比如job 名-0.service 名。这样 0 号 Pod 的地址不依赖它先启动、也不依赖它的 IP其他 Pod 只要拼出这个域名就能找到它。这里有个非常关键的字段publishNotReadyAddresses: true。不加这个Pod 没进入 Ready 状态时 DNS 里查不到它而 0 号 Pod 恰恰要等所有 worker 起来才开始建组于是所有 Pod 互相等待形成死锁日志停在Waiting for rank 0一动不动。这个坑我在第一次部署时耗了整整一个下午。3. 镜像构建那些让你反复重建镜像的细节3.1 CUDA、NCCL、PyTorch 三者的版本对齐镜像的基础层建议直接用官方的 PyTorch 镜像选带 CUDA runtime 的版本别自己从nvidia/cuda手动装。原因是官方镜像里 CUDA、cuDNN、NCCL、PyTorch 的版本组合是验证过的你自己拼很容易出现 PyTorch 编译时链接的 NCCL 版本和运行时加载的不是同一个症状是多机训练能启动但集合通信报错排查起来非常折磨。宿主机驱动版本要单独确认。容器里的 CUDA runtime 版本不能高于驱动支持的上限这个约束由驱动本身决定。部署前在目标节点上跑一次nvidia-smi看右上角的 CUDA Version那个数字就是这台机器能支持的最高 runtime 版本。镜像里写的 CUDA 版本只要不超过它就没问题。还有一个坑是多机场景下 NCCL 的版本必须完全一致。只要有一个节点的镜像里 NCCL 版本不同集合通信初始化阶段就可能挂掉报的错还特别含糊。所以镜像 tag 要固定到具体版本号绝对不能用latest滚动更新一次就可能出现新旧镜像混跑。3.2 共享内存、文件句柄与 ulimit 的隐形配置这三个东西平时在裸机上都不用管进了容器全是坑。共享内存的问题最典型DataLoader 设了num_workers8容器里/dev/shm只有 64MBworker 往共享内存写 batch 数据时直接崩报Bus error或者DataLoader worker exited unexpectedly。解决办法是在 Pod 里挂一个内存介质的emptyDir覆盖/dev/shm大小按单 batch 大小 × worker 数 × 预取数估一般给到宿主机内存的一半比较稳妥比如 64GB 内存的机器给 32GB。文件句柄上限也容易出事。多机训练时要建大量 TCP 连接如果nofile太小会出现Too many open files表现为训练跑着跑着某个 rank 突然失联。在容器的securityContext里把ulimit的nofile调到 65536 以上同时确认宿主机内核参数fs.file-max够大。还有一个不常被提到的是net.core.somaxconn和 TCP 拥塞控制参数。如果集群规模较大、节点间连接数多建议在宿主机层面把net.ipv4.tcp_rmem、tcp_wmem调高一些。这些不是容器内能改的需要节点初始化时统一处理。3.3 数据集要不要打进镜像结论是不要。镜像只放代码和依赖数据走挂载。把几百 GB 的数据集打进镜像会让镜像分层变得巨大每次拉取都慢节点磁盘也扛不住。正确做法是数据放在共享存储上通过 PVC 挂载进容器或者用对象存储加缓存层。如果数据在共享存储上读得慢可以在每个节点上先做一次本地缓存把当前 epoch 需要的数据预取到节点本地盘训练时读本地。这个方案在数据量可控时效果很明显代价是要写一点缓存管理逻辑。另外一个常被忽略的点是如果多个 worker 同时从同一个网络存储读同一个文件会形成热点读取速度可能比单机还慢。分段读、每个 rank 读不同 shard是更稳的做法。4. 作业清单落地一份能跑的多机 YAML 拆解4.1 让所有 Worker 自动拿到 0 号节点地址先看 Service 的定义这是整条链路的地基apiVersion: v1 kind: Service metadata: name: train-headless spec: clusterIP: None publishNotReadyAddresses: true selector: app: train-job ports: - name: rdzv port: 29500clusterIP: None表示这是 headless Service不做负载均衡DNS 查询会直接返回 Pod 的 IP 列表。publishNotReadyAddresses: true是前面提到的关键保证 Pod 还没 Ready 时也能被解析到。端口 29500 是 PyTorch 默认的 rendezvous 端口可以改成别的但改的话启动参数里要同步改。有了这个 ServicePod 的 DNS 名就是pod 名.service 名.namespace.svc.cluster.local。用 StatefulSet 或索引式 Job 保证 Pod 名带序号0 号 Pod 的地址就可以直接拼出来不需要任何服务发现逻辑。启动命令里这样写torchrun \ --nnodes4 \ --nproc_per_node8 \ --node_rank${RANK} \ --master_addrtrain-job-0.train-headless \ --master_port29500 \ train.py --config /workspace/config.yaml其中RANK通过 downward API 从 Pod 的序号注入。如果你用的是索引式 Job可以通过metadata.annotations[batch.kubernetes.io/job-completion-index]拿到索引号用 StatefulSet 的话hostname的最后一段就是序号启动脚本里cut一下即可。注意--nnodes写的是节点数不是进程数--nproc-per-node才是每台机器的进程数通常等于 GPU 数。这两个参数写反了是最常见的低级错误。4.2 GPU 资源申请的写法与限制GPU 的申请方式和 CPU 完全不同它必须是整数而且requests和limits必须写成同一个值否则调度器会拒绝创建 Pod。原因在于 GPU 是不可压缩资源不支持超卖。resources: limits: nvidia.com/gpu: 8 memory: 200Gi cpu: 60 requests: nvidia.com/gpu: 8 memory: 200Gi cpu: 60CPU 请求值建议按GPU 数 × 8 到 12来给因为数据加载和预处理都在 CPU 上给少了 GPU 会周期性空转。但也不能给太满把整台机器的 CPU 全占了会影响系统进程反而拖慢。这里还要提一句设备插件。集群里必须有 NVIDIA 设备插件在跑否则nvidia.com/gpu这个资源根本不存在Pod 会一直 Pending 并报资源不足。检查方法很简单kubectl describe node 节点名看 Allocatable 里有没有nvidia.com/gpu没有就是插件没装好或者驱动有问题。4.3 重启策略与超时设置的取舍训练任务的重启策略比较讲究。用 Job 的话restartPolicy一般设成Never让 Pod 失败后保留现场方便查日志设成OnFailure会在同一个 Pod 里重启容器好处是省掉重新调度的开销坏处是失败现场的日志会被覆盖。backoffLimit也别设太大尤其是多机任务。一个 worker 挂了其他 worker 会一直等在集合通信里最后全组超时。这时候如果控制器疯狂重启失败的 Pod会让整个任务反复卡住。我的做法是把backoffLimit设成 0 到 2配合外层的监控告警挂了就人工看一眼再决定是否重跑。超时控制要写在训练代码里。给init_process_group传一个合理的 timeout比如 30 分钟import datetime import torch.distributed as dist dist.init_process_group( backendnccl, timeoutdatetime.timedelta(minutes30), )不设的话默认是 30 分钟其实也还行但如果是每轮迭代很快的模型这个默认值太长一个节点挂了要等半小时才报错白白浪费资源。反过来如果模型每轮要跑很久超时设太短会误杀正常任务得按单轮耗时往上留余量。5. 通信链路与拓扑NCCL 跑不快多半卡在这里5.1 HostNetwork 与容器网络的选择容器网络默认走的是 overlay 网络多一层封装就多一层开销。对于集合通信这种对延迟敏感的场景封装带来的额外延迟和可能的 MTU 问题会明显影响性能。所以多机训练我一般优先考虑hostNetwork: true让容器直接用宿主机的网络栈。代价有两个。一是端口冲突多个 Pod 在同一节点上都想用 29500 就会打架所以要保证一个节点只跑一个训练 Pod或者给每个 Pod 分配不同的端口段。二是 DNS 解析要调整用了 hostNetwork 后 Pod 的 DNS 策略要设成ClusterFirstWithHostNet否则解析不到集群内的服务名。如果集群网络本身支持高性能模式比如有专门的 RDMA 网络方案那也可以不用 hostNetwork让容器网络直接跑在高速网络上。这种情况需要网络方案本身支持设备透传配置复杂度高一些但隔离性更好。5.2 NCCL 环境变量的实际调参清单NCCL 的行为高度依赖环境变量默认值在容器里经常是错的。下面这几个是我每次部署都会显式设置的env: - name: NCCL_DEBUG value: INFO - name: NCCL_SOCKET_IFNAME value: eth0 - name: NCCL_IB_DISABLE value: 1 - name: NCCL_NET_GDR_LEVEL value: 2 - name: NCCL_P2P_LEVEL value: NVL - name: NCCL_NSOCKS_PERTHREAD value: 4 - name: NCCL_SOCKET_NTHREADS value: 4逐条说理由。NCCL_DEBUGINFO是排查必备启动时会打印它选了哪张网卡、用了什么协议、拓扑结构是什么样几乎所有 NCCL 问题都能从这个日志里看出端倪。NCCL_SOCKET_IFNAME必须显式指定因为容器里可能有一堆虚拟网卡NCCL 自动选经常选到lo或者某个虚拟网桥上然后性能惨不忍睹。NCCL_IB_DISABLE1是在没有高速互联的情况下必须设的否则 NCCL 会尝试初始化 IB 设备超时后才回退白白浪费几分钟启动时间。NCCL_P2P_LEVELNVL表示允许通过 NVLink 做点对点通信。如果是同一台机器上的多卡这个能让通信走 NVLink 而不是绕 PCIe。NCCL_NSOCKS_PERTHREAD和NCCL_SOCKET_NTHREADS是调整 socket 并发数的默认值偏保守在多机场景适当调大能提升带宽利用率但也别调太高会引起 CPU 争抢。还有一个NCCL_ALGO和NCCL_PROTO这两个一般不用动让 NCCL 自己选。只有在特定模型上发现通信成为瓶颈时才需要手动指定 ring 或 tree 算法做对比测试。5.3 多网卡环境下的设备选择高性能机器上经常有多张网卡一张管理网、一张或几张数据网。这时候光设NCCL_SOCKET_IFNAME不够还得确认流量走的是带宽最大的那张。做法是在 NCCL_DEBUG 日志里找NET/IB或NET/Socket那几行看它选中的设备名和 IP 是不是你期望的那个。如果机器上有 RDMA 设备需要把设备暴露进容器resources: limits: rdma/hca: 1同时容器需要相应能力并且宿主机上要装好对应的驱动和用户态库。这块配置比较重如果集群没有现成方案建议先用普通网络把流程跑通再逐步优化。别一上来就追求极致带宽先把正确性拿到手。另外GPU 的拓扑位置也影响通信效率。同一台机器上GPU 到网卡的 PCIe 路径不同跨 NUMA 节点的通信会明显慢。理想情况下让 NCCL 选中的网卡和 GPU 在同一个 NUMA 节点下。这个在NCCL_DEBUG日志的拓扑信息里能看到如果发现跨了 NUMA可以考虑用 CPU 管理器的静态绑核策略把 Pod 的 CPU 和 GPU 绑定到同一个 NUMA 域。6. 数据与检查点训练中断之后能不能不从头再来6.1 共享存储的读写特性对 DataLoader 的影响共享文件系统的元数据操作通常比本地盘慢一个数量级。DataLoader 如果用num_workers 0并且每个样本都要open()一次文件元数据请求会瞬间打满存储端表现为训练启动阶段极慢或者干脆卡住。几个缓解手段按性价比排序一是把小样本数据集预处理成大文件格式比如打包成若干个几百 MB 的分片每个 worker 顺序读分片而不是随机开文件二是用persistent_workersTrue避免每个 epoch 重启 worker 进程三是把prefetch_factor调大一点让读取和计算重叠更充分。这几项加起来启动时间往往能从十几分钟降到一两分钟。还有一个容易忽略的点多个 worker 同时读同一个大文件时如果存储不支持并发读优化会互相拖慢。所以分片数量要够至少是总 worker 数的几倍让每个 worker 读不同的分片。6.2 Checkpoint 落盘与断点恢复的组织方式多机训练的 checkpoint 绝对不能每个 rank 都存一份完整的那会把存储写爆。标准做法是只在 rank 0 上保存其他 rank 通过集合通信把状态汇总过去。if dist.get_rank() 0: torch.save({ model: model.state_dict(), optimizer: optimizer.state_dict(), scheduler: scheduler.state_dict(), epoch: epoch, step: global_step, }, f/ckpt/run-{run_id}/epoch-{epoch}.pt) dist.barrier()dist.barrier()很重要保证所有 rank 都等到保存完成再继续否则可能出现 rank 0 还在写文件、其他 rank 已经开始下一轮训练训练进程把存储压满影响写入。恢复的时候要区分两种情况。完整恢复是把模型、优化器、调度器状态全读回来适合计划内的重启。部分恢复是只读模型权重适合微调或者换优化器配置。代码里用一个resume_from参数控制就好。checkpoint 的保留策略也要设计。存太多把 PVC 撑爆存太少回退太远。我的做法是保留最近 3 个加一个每 N 轮的最佳模型同时给 PVC 设配额上限超了触发告警。这样既保证能回退又不会无限增长。提示写到网络存储之前先写本地临时文件再mv过去避免写入过程中任务被驱逐留下半截文件。恢复时先校验文件大小或加载一次别直接信任。7. 排错实录几个卡了我很久的现场7.1 全部 Pod 都在等 rank 0 的完整排查链路这个现象的表现是所有 Pod 都 Running日志里清一色Waiting for rank 0没有任何报错。排查顺序我总结成四步。第一步进任意一个 worker Podnslookup train-job-0.train-headless。如果解析不到问题在 Service 层。常见原因有三个Service 的 selector 和 Pod 的 label 对不上忘了加publishNotReadyAddresses: truePod 还没被 Endpoint 收录。逐个核对。第二步如果能解析nc -zv train-job-0.train-headless 29500。连不上说明 0 号 Pod 的进程没监听可能是它的启动命令里--node_rank传错了或者它在等数据加载卡住了。第三步看 0 号 Pod 的日志。如果它自己也在等别人那说明--nnodes和实际的 Pod 数对不上比如声明 4 个节点但只起了 3 个 Podrank 0 会一直等第 4 个。第四步如果上面都正常检查 DNS 策略。用了 hostNetwork 但没设ClusterFirstWithHostNet的话Pod 用的是宿主机 DNS根本解析不到集群内服务名这个坑特别隐蔽因为nslookup会返回外部 DNS 的失败结果而不是明显报错。7.2 Pod Pending 与 GPU 资源碎片Pending 的原因要看kubectl describe pod的 Events。如果写的是Insufficient nvidia.com/gpu说明集群里虽然有空闲 GPU但凑不出一个节点上的 8 张连续可用卡。这种情况在共享集群里很常见节点 A 剩 3 张、节点 B 剩 5 张看着总量够实际没法满足单 Pod 要 8 张的需求。解决办法有两个方向。调度层面用支持 gang 调度的调度器保证整组 Pod 要么全部调度成功要么全部等待避免部分 Pod 占着卡干等。资源层面把大任务和小任务分池大任务专用几个节点不混跑避免碎片化。还有一种 Pending 是资源名写错了比如写成nvidia.com/gpu.count或者漏了命名空间前缀这种情况 Events 里会明确提示资源不存在比较容易发现。7.3 显存不足与真实泄漏的区分方法报CUDA out of memory之后第一步不是改 batch size而是判断是一开始就不够还是跑着跑着才不够。前者是配置问题降 batch 或者上梯度累积就能解决后者大概率是代码里有东西在累积。判断方法很简单在每个 epoch 结束打印torch.cuda.memory_allocated()和torch.cuda.max_memory_allocated()。如果 allocated 逐轮上升就是有引用没释放常见于把 tensor 存进了 list 或者 dict 做统计或者 loss 的反向图没释放。如果 allocated 稳定但 max 不断上涨那是碎片问题可以试试PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True。还有一个多机特有的现象某个 rank 报 OOM其他 rank 都正常。这通常意味着数据分布不均那个 rank 拿到的样本特别长。检查 DataLoader 的采样器有没有做长度分桶或者 padding 策略是否合理。分布式场景下最长样本会决定整体显存峰值这个是单机时不明显的问题。8. 部署跑稳之后才慢慢体会到的几件事我自己的体会是把训练搬上集群这件事前 20% 的工作量在写 YAML后 80% 在调环境和排错。所以第一次部署别追求最优性能先让任务能从头跑到尾哪怕慢一点。跑通之后再逐项优化先看启动时间把镜像大小、数据读取、NCCL 初始化逐段计时再看单轮耗时对比单机多卡的基线算出多机扩展效率最后才去动拓扑绑定、NUMA 亲和这些深水区。另一个很值的习惯是给训练脚本加一层轻量的状态上报每隔 N 步往一个共享位置写一次当前 step 和 loss。任务挂了之后从这些记录里能立刻判断是卡在数据加载、前向计算还是同步阶段比翻几百兆的日志快得多。最后提醒一句NCCL_DEBUGINFO别长期开着日志量很大正式跑的时候关掉只在排错时打开。而且这个变量在多机场景下会让每个 rank 都输出一份记得配合日志聚合一