背景概述

在基于 PyTorch 的分布式训练场景中，合理配置 torchrun 的启动参数是保障训练任务稳定运行的关键。尤其在从旧型硬件平台迁移至新型号设备时，硬件资源（如 NPU 卡数量）的差异容易引发配置不匹配问题。本文记录一次因 --nproc_per_node 参数未同步更新导致的分布式训练失败案例，重点分析问题现象、根因定位及解决方案，为类似场景提供参考。

问题现象

在执行多机分布式训练任务时，作业在启动阶段即失败。主节点日志首报错为 EE8888 memcpy exception，伴随关键错误信息 there is a sdma error，表明底层数据传输模块出现异常。

进一步查看各节点日志，发现所有节点中 device 0 对应的进程均出现相同异常，且错误集中在训练启动初期。

原因分析

1、日志层面分析

从 plog 日志中确认，每个节点的 device 0 进程均上报 EE8888 memcpy exception，表明该设备在数据拷贝阶段发生异常，与 SDMA（System Direct Memory Access）子系统相关。

2、资源使用情况异常

检查运行目录下的进程编号分布，发现每个节点仅启动了 8 个连续进程，说明实际分配的设备数为 8。然而，目标硬件平台单节点支持 16 个设备（NPU 卡），存在明显的资源未充分利用。

3、设备冲突与抢占分析

单节点日志显示，进程 ID 为 51302 和 60120 均尝试使用 device 0。在 60120 进程启动前，51302 已因 SDMA ERROR 退出。该现象表明设备分配存在冲突，任务下发逻辑异常，导致资源争用。

4、迁移过程配置遗漏

经与用户确认，该任务由旧平台迁移至新硬件平台，原代码逻辑设计为每节点使用全部 16 个设备。但拉起脚本中 torchrun 的 --nproc_per_node 参数未同步更新，仍保持为 8，导致实际启动进程数与预期不符，引发设备资源分配错乱。修改参数为 --nproc_per_node 16 后，任务成功启动并正常运行。

问题根因

在平台迁移过程中，未同步更新 torchrun 的 --nproc_per_node 参数，导致实际启动的进程数少于硬件支持的最大数量，进而引发设备资源争用与 SDMA 传输异常。

解决措施

根据实际硬件资源与训练逻辑，将 torchrun 启动命令中的 --nproc_per_node 参数设置为与设备总数一致，确保每个节点的训练进程能正确分配并独占对应设备。

示例命令：

torchrun \
  --nproc_per_node 16 \
  --master_port 29500 \
  --nnodes 8 \
  --node_rank 0 \
  --master_addr "192.168.1.1" \
  train.py

✅ 建议：在平台迁移或硬件升级后，务必核对并更新 --nproc_per_node 参数，使其与目标设备数量匹配。

建议与总结

1. torchrun 参数说明--nproc_per_node 用于指定每个节点启动的进程数，应与实际可用设备数保持一致。若设置过小，可能导致设备资源未充分利用；若设置过大，可能引发资源竞争或分配失败。参考文档：torchrun (弹性启动) — PyTorch 2.9 文档
2. 最佳实践建议在硬件平台变更或任务迁移时，优先检查并更新分布式启动参数。使用脚本自动化校验 nproc_per_node 与设备数量的一致性。在训练前通过 npu-smi info 等工具确认设备状态与数量，避免因配置错误引发底层异常。
3. 异常排查提示当出现 sdma error、memcpy exception 等底层传输错误时，应优先排查：--nproc_per_node 是否与设备数匹配；是否存在多个进程争用同一设备；是否存在设备未正确初始化或驱动异常。

本文档旨在分享一次典型分布式训练配置问题的排查与解决经验，帮助开发者在类似场景中快速定位并规避潜在风险。