hyperpod-nccl

HyperPod NCCL 调试器

操作策略。 自行运行只读诊断。切勿运行会更改集群、节点或工作负载状态的命令——请将每条命令放在 建议的命令（请自行运行） 代码块中，并等待客户操作。破坏性操作顺序：调查 → 重启 → 更换（更换会销毁根卷和次级卷；不支持 Slurm 控制器节点）。切勿因猜测而丢弃训练状态。

诊断 SageMaker HyperPod（EKS 和 Slurm）上的 NCCL 故障。scripts/nccl-diagnose.sh 通过 AWS API、kubectl 和 SSM 读取状态，然后将每个问题打印为 [FAIL] ... → references/<file>.md § <section>。只读。

信号来源：list-cluster-events 仅包含基础设施级状态（生命周期、引导、EFA 健康检查、容量、更换、重启、AMI 回滚）。它不包含 NCCL 超时、GPU XID/ECC 或按 pod 划分的训练信号——这些信号来自 pod 日志、CloudWatch 训练流、节点上的 SSM 探测和 NCCL 环境审计。训练期间发生 NCCL 问题时，“无事件”是预期情况，并不代表状态良好。

---

工作流

1. 收集集群名称、区域、命名空间/作业（EKS）和确切的 NCCL 错误字符串。
2. 运行诊断（始终执行——后续所有步骤都依据其输出）。
3. 对于每条 [FAIL]，Read 相应的参考章节。
4. 提出问题发现、根本原因，以及填入脚本输出中具体值（实例 ID、SG ID、命名空间）的建议命令代码块。等待客户批准。
5. 重新运行诊断以确认。

如果某项发现没有对应章节，请将其报告为 bug——不要编造修复方法。

第 1 步：验证 kubectl 身份（EKS）

EKS_ARN=$(aws sagemaker describe-cluster --cluster-name <HYPERPOD-NAME> --region <REGION> \
  --query 'Orchestrator.Eks.ClusterArn' --output text)
EKS_NAME=$(echo "$EKS_ARN" | awk -F'/' '{print $NF}')
aws eks update-kubeconfig --name "$EKS_NAME" --region <REGION>
kubectl get nodes

第 2 步：运行诊断

# Basic:
bash scripts/nccl-diagnose.sh --cluster <HYPERPOD-NAME> --region <REGION>

# Scope to an EKS job/namespace:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --namespace <NS> --job <JOB>

# Force orchestrator:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --orchestrator slurm

# Larger hardware sample (default 3):
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --sample-nodes 10

# Specific node only:
bash scripts/nccl-diagnose.sh --cluster <NAME> --region <REGION> --node i-0abc123def456

标签：[PASS] · [FAIL]（计入 Issues Found，带参考指针）· [WARN] · [INFO]。优先级：P0 阻断训练 · P1 性能下降 · P2 仅供参考。

---

修复索引

脚本中的每一行 [FAIL] 都已直接指向相应章节。此表可用于手动排查。

问题	章节
SG 缺少入站/出站自引用规则	operations.md § 8
NetworkPolicy 阻断 / 缺少允许所有流量的规则	operations.md § 8
Slurm 节点 DOWN / DRAINING / RemoveIPC	operations.md § 7
GPU XID / SYSTEM_ERROR / 硬件故障	hyperpod-node-debugger § F / § G
GPU 行重映射 / DCGM Fail / 静默 NaN	hyperpod-node-debugger § G.1.a/b
NCCL 超时 / rendezvous / 慢节点	debugging-guide.md § 1
EFA 配置 / 未使用	debugging-guide.md § 6
EFA TCP 回退（NET/OFI Using TCP）	debugging-guide.md § 13
Pod 之间 NCCL 版本不匹配	debugging-guide.md § 10
容器 OOM（Pod 被终止，退出码 137）	debugging-guide.md § 4
GPU OOM（CUDA out of memory）	debugging-guide.md § 11
RDMA memlock / /dev/shm 过小	debugging-guide.md § 17
MASTER_ADDR DNS / headless Service	debugging-guide.md § 12
NVLS / PXN / 拓扑调优	debugging-guide.md § 19
任何 NCCL / EFA / rendezvous 日志模式	error-patterns-quick-ref.md
性能 / nccl-tests / 带宽	performance-testing.md

---

先决条件

• aws CLI v2.13+ 已完成身份验证（aws sts get-caller-identity）
• jq、python3、bash 4.2+
• unbuffer（来自 expect 软件包：yum install expect / apt install expect）
• kubectl 已通过 EKS 集群身份验证（如果不存在，则跳过 K8s 检查）
• 用于节点硬件检查的 session-manager-plugin

默认值

• 区域 — 必填：传入 --region 或设置 $AWS_DEFAULT_REGION。
• 编排器 — 自动检测；可通过 --orchestrator eks|slurm 覆盖。
• 命名空间 / 作业（EKS） — 所有命名空间；使用 --namespace <NS> --job <JOB> 指定范围。
• 硬件采样 — 通过 SSM 检查 3 个节点（上限为 50 个）。使用 --node <ID> 指定节点。节点探测按串行方式运行（每个节点 180 秒）：--sample-nodes 10 可能需要约 30 分钟。
• CloudWatch 时间窗口 — 最近 2 小时。
• 颜色 — 在非 TTY 环境或 TERM=dumb 时自动禁用。

错误处理

故障	脚本	告知客户
aws sts get-caller-identity 失败	以 AWS 错误信息退出，返回代码 1	“修复 AWS 凭证后重新运行。”
describe-cluster AccessDenied	发出警告，添加 Missing IAM for sagemaker:DescribeCluster	“授予 sagemaker:DescribeCluster 权限（见 operations.md § 2）。”
未找到集群	列出区域中的集群后退出，返回代码 1	“确认 HyperPod 集群名称和区域。”
缺少 kubectl / 未通过身份验证	发出警告，跳过 K8s 检查	“运行 aws eks update-kubeconfig --name <EKS> --region <R>。”
缺少 SSM 插件	发出警告，跳过节点硬件检查	“安装 session-manager-plugin。”
SSM 超时（180 秒）	输出部分结果，将节点标记为无法访问	“使用 --node <ID> --sample-nodes 1 重新运行；检查节点上的 SSM Agent。”
未找到 CloudWatch 日志组	跳过 CloudWatch 扫描	“在集群上启用 CloudWatch（见 operations.md § 4）。”
集群事件 API 被限流	发出警告，继续处理部分数据	“稍后重新运行——脚本具有幂等性。”

退出代码：0 诊断完成 · 1 缺少必要的先决条件或集群无法访问。

IAM 权限

完整策略和 RBAC 配置见 operations.md § 2。HyperPod 上的 SSM 使用 start-session，目标为 sagemaker-cluster:<cluster-id>_<group>-<iid>——请授予 ssm:StartSession / ssm:TerminateSession，而非 ssm:SendCommand。

扩展策略

范围	方法	覆盖范围
所有节点	sagemaker:ListClusterNodes（分页）	100% 节点
所有 K8s 对象	kubectl	100% Pod/节点/策略
硬件	SSM --sample-nodes N（默认值为 3）	抽样
节点日志	CloudWatch	100% 节点

大型集群： PyTorch NCCL 后端默认将集合操作超时设为 10 分钟（依据 PyTorch 分布式文档）。大型集群首次 rendezvous 通常会超过此时限；可通过 torch.distributed.init_process_group(timeout=timedelta(seconds=<N>)) 延长超时时间。HyperPod 支持团队还观察到，在 memlock 为 unlimited 的 256 个及以上节点集群中，NCCL 拓扑图搜索会卡住；在 Pod 的 securityContext 或 /etc/security/limits.conf 中使用较大的固定 memlock 值（例如 8388608）已在实际案例中解决此问题。这种 memlock 模式是现场观察结果，并非 AWS 或 NCCL 文档所述行为。

有关 FSDP、DeepSpeed 或 Megatron-LM 调优，请参阅：debugging-guide.md § 18。

技能委派

需求	使用
集群创建／部署失败	hyperpod-cluster-debugger（§ A / B / C / H + --validate）
部署后集群范围的管理	hyperpod-cluster-debugger
单节点问题（磁盘、生命周期、硬件）	hyperpod-node-debugger
Trainium/Inferentia 集合通信（AWS Neuron Collectives，不是 NCCL）	hyperpod-node-debugger § G.2
在节点上运行 Shell	hyperpod-ssm
跨节点版本比较	hyperpod-version-checker
提交给 AWS Support 的诊断包	hyperpod-issue-report
MFU／性能下降	hyperpod-mfu-debugger

升级至 AWS Support

在以下情况下升级：

1. 所有 SG 规则均正确，已在节点上验证 EFA，但 NCCL 仍然超时。
2. 所有节点的硬件检查均通过，但 AllReduce 仍然挂起。
3. Issues Found: 0，但训练仍然失败。
4. 更换节点后，GPU XID 错误仍然持续。
5. 已触发集合操作超时并应用 memlock 解决方法，但大型集群的会合过程仍然挂起。

创建案例前

# 1. Cluster identity + status
aws sagemaker describe-cluster --cluster-name <C> --region <R>

# 2. Full NCCL diagnostic (sample more nodes for escalation)
bash scripts/nccl-diagnose.sh --cluster <C> --region <R> --sample-nodes 10 > nccl-diag.txt

# 3. Per-node log/config bundle to S3 (delegates to hyperpod-issue-report)
#    See skills/hyperpod-issue-report/SKILL.md for the exact invocation.

在案例中提供

• 集群名称 + ARN 和 AWS 区域
• 编排器（EKS 或 Slurm）以及 EKS 集群名称／Slurm 控制器节点
• 故障发生的时间范围（UTC 开始／结束时间）
• 完整的 NCCL／libfabric 错误字符串（从 Pod 日志或 journalctl 中原样复制）
• 受影响的实例 ID／节点名称／Pod 名称／命名空间／作业名称
• 上述步骤 2 中的 nccl-diag.txt
• 步骤 3 中 hyperpod-issue-report 诊断包的 S3 URI
• 生效中的 NCCL 环境变量（在一个 Pod 中运行 printenv | grep -E '^NCCL|^FI_|^TORCH_'）

参考资料

• error-patterns-quick-ref.md — 日志模式 → 代码 → 修复方法表
• debugging-guide.md — 各场景的操作流程（共 21 个章节，包括 NVLS/PXN/拓扑）
• performance-testing.md — nccl-tests、带宽阈值、慢节点检测
• operations.md — IAM、SSM 格式、CloudWatch、环境变量参考、节点标签、Slurm 操作、修复措施