mcpField
D
dynamo-interconnect-check

dynamo-interconnect-check

github.com/nvidia云与 DevOps3.8k1.9k 次安装今天更新
代码仓库

关于 dynamo-interconnect-check

这项只读诊断技能用于检查 Dynamo 分离式部署依赖的网络传输。它检查配方环境变量、节点网络能力和 NIXL 测试准备情况，辅助部署验证和基准测试。

主要功能

  1. 01检查 NIXL、UCX 和 NCCL 环境变量
  2. 02探测 InfiniBand 与 GPUDirect RDMA 能力
  3. 03检查 GDRCopy 和 NVLink 是否可用
  4. 04检查 NIXL 传输测试准备情况
  5. 05汇总分离式传输就绪状态

适用场景

  1. 01部署分离式配方后验证传输配置
  2. 02报告基准结果前检查网络状态
  3. 03排查分离式服务速度慢或输出异常

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nvidia/skills --skill dynamo-interconnect-check

安装后在 Claude Code 中输入/dynamo-interconnect-check确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

BENCHMARK.md
skill-card.md
skill.oms.sig
evals/
evals.json
references/
interconnect-env-vars.md
scripts/
check_interconnect.py

详细介绍

Dynamo 互连检查

目的

确认解耦服务所依赖的传输实际上可用。部署可能通过端点冒烟测试，但解耦配置可能存在隐蔽问题：如果 NIXL/UCX 无法通过 RDMA 或 NVLink 连接对端工作节点，KV 传输就会回退到缓慢或不可用的路径。在信任解耦部署或其基准测试数据之前，通过只读检查发现这些问题。

此技能为只读。它不会修改集群，也不会打印机密信息。

前提条件

  • 操作员机器上安装了 Python 3.10+。
  • 可以通过 kubectl exec 访问目标 Dynamo 部署中的工作节点 Pod。
  • 具有配方目录（recipes/<model>/<framework>/<mode>）的读取权限。
  • 对于节点能力检查：工作节点 Pod 镜像中提供 ibstat、nvidia-smi、lsmod 等工具（缺少工具会报告为 skipped，而非失败）。

适用场景

  • dynamo-recipe-runner 部署了解耦或多节点配方之后。
  • 报告解耦吞吐量/延迟之前，确保数据反映真实传输情况。
  • 聚合模式可用，但解耦模式速度慢、挂起或返回错误输出，并且怀疑问题出在网络而非模型时。

对于诊断已经崩溃或无法调度的 Pod，请先使用 dynamo-troubleshoot。

操作说明

1. 检查配方中的传输环境变量
python3 scripts/check_interconnect.py env recipes/<model>/<framework>/<mode>

报告已设置的 NIXL/UCX/NCCL 传输变量，并标出缺失的解耦关键变量（例如 UCX_TLS、UCX_NET_DEVICES、NCCL_IB_HCA）。 这里缺少变量仅为警告——它们可能已内置于镜像中——因此请通过节点和 NIXL 检查进行确认。各变量的作用请参阅 references/interconnect-env-vars.md。

2. 检查节点能力

在 GPU 节点上本地检查，或在运行中的工作节点 Pod 内检查：

python3 scripts/check_interconnect.py node \
  --namespace "${NAMESPACE}" --pod <worker-pod>

以只读方式探测 InfiniBand 设备及活动链路、GPUDirect RDMA （nvidia_peermem）、GDRCopy，以及 GPU 拓扑中的 NVLink。缺少工具会报告为 skipped，而非失败。

3. 验证 NIXL 可达性
python3 scripts/check_interconnect.py nixl \
  --namespace "${NAMESPACE}" --pod <worker-pod>

查找 Pod 中的 NIXL 测试工具，并提供运行成对预填充↔解码传输测试的确切后续步骤。完整的跨 Pod 传输测试需要在网络上调度两个 GPU Pod。

可用脚本

脚本用途参数
scripts/check_interconnect.py env检查配方中的 NIXL/UCX/NCCL 环境变量配方路径位置参数
scripts/check_interconnect.py node探测节点或 Pod 上的 InfiniBand、GPUDirect RDMA、GDRCopy、NVLink--namespace、--pod
scripts/check_interconnect.py nixl检查 Pod 是否已准备好进行 NIXL 传输测试--namespace、--pod

通过 agentskills.io run_script() 协议调用：

run_script("scripts/check_interconnect.py", args=["env", "recipes/qwen3-coder-480b/sglang/disagg"])
run_script("scripts/check_interconnect.py", args=["node", "--namespace", "dynamo-demo", "--pod", "qwen-worker-0"])

示例

部署前，确认解耦配方中的传输环境变量配置：

python3 scripts/check_interconnect.py env recipes/qwen3-coder-480b/sglang/disagg

部署后，验证工作节点 Pod 的网络：

python3 scripts/check_interconnect.py node \
  --namespace dynamo-demo --pod qwen-worker-0
python3 scripts/check_interconnect.py nixl \
  --namespace dynamo-demo --pod qwen-worker-0

通过 Agent 协议执行的等效操作：

run_script("scripts/check_interconnect.py", args=["nixl", "--namespace", "dynamo-demo", "--pod", "qwen-worker-0"])

输出约定

每项检查会返回 ok / warn / fail / skipped 之一，并附带一行详情，以及汇总后的解耦传输就绪状态。报告：

  • 已设置的传输环境变量，以及缺失的解耦关键变量
  • RDMA / GPUDirect / NVLink 能力状态
  • NIXL 可达性是否已验证；如果未验证，提供下一条命令
  • 明确说明是否可以信任解耦配置，或应先修复哪些问题

限制

  • 只读网络探测；不会运行完整的成对 NIXL 传输（这需要两个已调度的 GPU Pod 和 Pod 内的 NIXL 测试工具）。
  • 缺少工具（ibstat、nvidia-smi、lsmod）时返回的 skipped 结果无法定论，不代表通过。
  • 环境变量检查只检查配方文本；无法检测通过 initContainers 注入的运行时变量或由操作器应用的环境变量。
  • 单节点聚合部署不会使用该传输——此技能用于解耦/多节点验证。

故障排查

症状可能原因下一步
env 报告所有关键变量均缺失变量已写入镜像，或由运维人员注入在工作节点 Pod 内运行 node 检查，以验证实际环境变量
node 报告没有 Active IB 链路Fabric 故障，或 HCA 未配置到节点联系集群管理员；验证 kubectl describe node 是否显示 nvidia.com/gpu 和 IB 标签
缺少 nvidia_peermemGPUDirect RDMA 模块未加载请集群管理员加载 nvidia-peermem；如果未加载，NIXL 将回退到分阶段复制
nixl 未找到测试工具工作节点镜像缺少 NIXL 测试框架使用启用了 NIXL 的镜像，或在调试 Pod 中运行独立传输测试

基准测试

有关 NVCARPS-EVAL 性能报告，请参阅 BENCHMARK.md（由 NVSkills CI 流水线自动生成）。要刷新报告，请在涉及此技能的上游 PR 上重新运行 /nvskills-ci。

参考资料

  • references/interconnect-env-vars.md — NIXL/UCX/NCCL 环境变量目录和 IB 能力检查清单。
  • 对所有只读检查，请使用 scripts/check_interconnect.py。

评论

支持 Markdown