⚡

Dynamo互连检查Skill dynamo-interconnect-check

验证Dynamo部署中NIXL/UCX/NCCL互连是否就绪，确保分离式服务基于RDMA/NVLink的KV传输正确。通过检查传输环境变量、节点能力和NIXL可达性，发现并避免网络回退问题。关键词：Dynamo、NIXL、UCX、NCCL、RDMA、NVLink、分离式服务、KV传输、GPUDirect、InfiniBand、互连验证。

大模型推理部署 0 次安装 2 次浏览 更新于 9/7/2026
名称 dynamo-interconnect-check
描述 验证Dynamo部署的NIXL/UCX/NCCL互连是否已为基于RDMA/NVLink的分离式服务就绪。在recipe-runner启动部署后（尤其是disagg/多节点），使用此技能确认KV传输正确；对于已失败的Pod，请使用troubleshoot进行诊断。
开源协议 Apache-2.0 metadata:
作者 Dan Gil dagil@nvidia.com tags: - dynamo - nixl - rdma - disagg - validation

Dynamo 互连检查

<!– SPDX-FileCopyrightText: Copyright © 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: CC-BY-4.0 –>

目的

确认分离式服务所依赖的传输实际上是否可用。一个部署可能通过端点冒烟测试，但分离式服务却静默出错：如果NIXL/UCX无法通过RDMA或NVLink到达对端worker，KV传输将回退到缓慢或损坏的路径。在信任分离式部署或其基准测试数字之前，通过只读检查来捕获这些问题。

此技能是只读的。它从不修改集群，也从不打印机密。

先决条件

  • 操作机器上安装Python 3.10+。
  • 能够对目标Dynamo部署中的worker pod执行kubectl exec。
  • 对recipe目录（recipes/<model>/<framework>/<mode>）有读取权限。
  • 对于节点能力检查：worker pod镜像中具有类似ibstat、nvidia-smi、lsmod的工具（缺少工具时报告为skipped，而不是失败）。

使用时机

  • 在dynamo-recipe-runner部署disagg或多节点recipe之后。
  • 在报告disagg吞吐量/延迟之前，以便数字反映真实传输。
  • 当agg正常但disagg缓慢、挂起或返回错误输出，并且你怀疑是网络结构而非模型问题。

对于已经崩溃或不可调度的pod进行诊断，请先使用dynamo-troubleshoot。

操作说明

1. 检查Recipe上的传输环境变量

python3 scripts/check_interconnect.py env recipes/<model>/<framework>/<mode>

报告设置了哪些NIXL/UCX/NCCL传输变量，并标记缺失的disagg关键变量（例如UCX_TLS、UCX_NET_DEVICES、NCCL_IB_HCA）。这里缺失只是警告——它们可能已内置到镜像中——因此请通过节点和NIXL检查确认。请参阅references/interconnect-env-vars.md了解每个变量的作用。

2. 检查节点能力

在GPU节点本地，或在正在运行的worker 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测试工具，并显示进行prefill↔decode成对传输测试的下一个确切步骤。完整的跨pod传输测试需要两个已调度的GPU pod位于同一网络上。

可用脚本

脚本 目的 参数
scripts/check_interconnect.py env 检查recipe上的NIXL/UCX/NCCL环境变量 位置参数：recipe路径
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'])

示例

部署前验证disagg recipe的传输环境形状：

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

部署后，验证worker 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，附带一行详细信息，并给出disagg传输就绪性的总体结论。报告：

  • 存在的传输环境变量与缺失的disagg关键变量
  • RDMA/GPUDirect/NVLink能力状态
  • NIXL可达性是否已验证，如果未验证，给出下一步命令
  • 明确说明disagg是否可被信任，或应首先修复什么

局限性

  • 只读网络结构探测；不运行完整的成对NIXL传输（需要两个已调度的GPU pod和pod内的NIXL测试工具）。
  • 工具缺失（ibstat、nvidia-smi、lsmod）导致的skipped结果是不确定的，而非通过。
  • 环境变量检查检查recipe文本；运行时通过initContainers或operator注入的值不会被检测到。
  • 单节点agg部署不经过传输层——本技能专用于disagg/多节点验证。

故障排查

症状 可能原因 下一步
env报告所有关键变量缺失 变量已内置到镜像或由operator注入 在worker pod内运行node检查以验证实际环境
node报告没有Active IB链路 网络结构宕机或HCA未配置到节点 联系集群管理员；验证kubectl describe node显示nvidia.com/gpu和IB标签
nvidia_peermem缺失 GPUDirect RDMA模块未加载 请集群管理员加载nvidia-peermem；否则NIXL将回退到分段拷贝
nixl找不到测试工具 worker镜像缺少NIXL测试工具 使用启用了NIXL的镜像，或从调试pod运行独立传输测试

基准测试

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

参考资料

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