为什么模型日志通常找不到真正根因
分布式训练或张量并行启动卡住时，模型框架只会显示通信初始化失败、超时或某个rank退出。根因可能是单卡硬件、PCIe ACS、共享内存、容器权限、网卡选择、RDMA或不同节点软件版本。有效方法是先脱离模型，用最小通信测试逐层缩小范围。
第一层：每张GPU单独健康
nvidia-smi -L
nvidia-smi --query-gpu=index,uuid,name,pci.bus_id,memory.total,temperature.gpu,power.draw --format=csv
dmesg -T | grep -Ei 'NVRM|Xid|AER|pcie' | tail -n 100逐卡执行CUDA张量计算。任何一张卡单独失败都不应继续做NCCL测试。记录GPU UUID而不是只记序号，因为重启或容器映射后序号可能变化。
第二层：读取真实拓扑
nvidia-smi topo -m
nvidia-smi nvlink --status
lspci -tv
lscpu | grep -E 'NUMA|Socket'拓扑表中的NV表示NVLink路径，PIX/PXB表示经过PCIe交换，PHB跨主桥，SYS通常还跨CPU互联。两张卡型号相同不代表通信路径相同。张量并行优先放在互联更近的GPU组；网卡也应靠近对应NUMA节点。
第三层：容器共享内存与设备
df -h /dev/shm
ulimit -l
docker inspect YOUR_CONTAINER --format '{{.HostConfig.IpcMode}} {{.HostConfig.ShmSize}}'多进程框架会使用 `/dev/shm`。Docker默认共享内存常常过小，测试容器可使用 `--ipc=host` 或明确的 `--shm-size`。这两种方式安全边界不同，生产多租户环境不能盲目共享宿主机IPC。
编译和运行nccl-tests
在与业务相同的容器或软件环境中构建：
```bash git clone https://github.com/NVIDIA/nccl-tests.git cd nccl-tests make -j MPI=0 CUDA_HOME=/usr/local/cuda
NCCL_DEBUG=INFO NCCL_DEBUG_SUBSYS=INIT,GRAPH,NET \ ./build/all_reduce_perf -b 8M -e 4G -f 2 -g 2 ```
先测两卡，再增加到本机全部GPU。输出中的algBW是算法带宽，busBW按集合通信的数据移动量换算，更适合跨卡配置比较。小消息受启动延迟影响，大消息更能体现链路带宽；不要只截取一个最好数字。
如何保存可比较的基线
固定消息范围、GPU组合、测试次数、NCCL和驱动版本。每组运行至少三遍，记录平均值和离群点。同时保存 `nvidia-smi topo -m`，否则换插槽或换服务器后数据没有解释力。
NCCL_DEBUG=INFO NCCL_DEBUG_FILE=/tmp/nccl-%h-%p.log \
./build/all_reduce_perf -b 1M -e 8G -f 2 -g 8 | tee /tmp/allreduce-8gpu.txt多进程时每个rank要写不同日志文件，避免内容互相覆盖。
多机测试的最短排查路径
先确认主机名解析、时间同步、SSH/MPI或调度器启动正常，再确认业务网卡互通。服务器有管理网、存储网和RoCE/IB网时，NCCL可能选错接口。临时使用 `NCCL_SOCKET_IFNAME` 做对照可以帮助定位，但确认正确配置后应在部署系统中明确网络，而不是长期靠人工环境变量。
RDMA环境还要检查HCA、GID、MTU、PFC/ECN和交换机无损配置。两个节点能ping通不能证明RDMA集合通信可用。
典型现象与根因
- 初始化永久等待：rank数量或地址不一致、端口被阻断、某进程提前退出。
- 两卡快、八卡骤降：跨NUMA/PCIe主桥、部分NVLink异常或拓扑分组不合理。
- 宿主机正常、容器失败：共享内存、设备映射、memlock或网络命名空间。
- 运行一段时间后报错：Xid、链路抖动、温度降频或网络丢包。
- 更换NCCL版本后下降：算法或协议选择变化，需要保留旧环境复测。
回到模型之前的验收条件
只有当目标GPU组合的nccl-tests稳定、无Xid、无超时且带宽符合该拓扑历史基线，才回到vLLM、PyTorch或Megatron。随后用相同模型比较单卡与多卡扩展效率。这样模型层出现问题时，已知底层通信是可信的。
