[Installation]: Bug / Enhancement][Blackwell HGX B300] Pre-flight check for nvcc/ninja before multi-TB shard load & graceful fallback for NV

快速结论：该问题通常发生在 Blackwell 平台（如 8× HGX B300）上部署 Kimi 等超大 MoE 模型时：加载完 1.56 TB 分片权重后，FlashInfer 触发 SM100/SM103 内核 JIT 编译，而主机缺少 nvcc/ninja 导致启动失败；或在 NVLS 多播绑定阶段抛出 CUDA error 401 直接崩溃。优先排查主机是否安装完整 CUDA ToolKit 与 ninja，以及 NVSwitch 多播表状态是否正常。

适用环境：Ubuntu 24.04 LTS；CUDA 13.1；8× NVIDIA HGX B300（288 GB HBM3e/GPU，SM100/SM103，NVLink 5）；NVIDIA Container Toolkit；vLLM 0.34.0+ verilmiş；模型 Kimi K3.1 Pro（Full MXFP4，96 shards，约 1.56 TB，TP=8，max_model_len=1048576）。

最快修复方案：Issue 评论中明确验证过的两个 workaround：1）安装 cuda-toolkit-13-1 与 ninja-build，补全 FlashInfer 的 JIT 编译依赖；2）执行 sudo nvidia-smi -r 并重启 nvidia-fabricmanager，重置 HGX B300 的 NVSwitch 多播表，消除 CUDA error 401。

注意事项：这两个 workaround 只在裸金属（bare-metal）8× HGX B300 上确认有效，不保证虚拟化 B300 环境同样适用；nvidia-smi -r 会重置 GPU，应在无任务运行时执行。Issue 中提出的“加载前预检 nvcc/ninja”和“多播不可用时的优雅回退”属于上游改进建议，尚未合入，不能当作已发布的配置项或开关使用。

问题场景

用户在裸金属 8× NVIDIA HGX B300 节点上，通过 pip 安装 vLLM 0.34.0+，以 TP=8 部署 Kimi K3.1 Pro（Full MXFP4 权重，96 个分片，约 1.56 TB，max_model_len=1048576）。在耗时约 15 分钟把 1.56 TB 权重加载完成后，出现两类失败：一是主机只装了匹配的 GPU 驱动和 nvidia-fabricmanager、没有完整 CUDA Toolkit，FlashInfer 尝试为 Blackwell 的 NVLS all-reduce / MXFP4 MoE 内核做 JIT 编译时因缺少 nvcc 或 ninja 硬崩溃；二是在 NVLS 多播绑定阶段，cuMulticastBindMem 抛出 CUDA error 401，latent_moe_tail 路径（torch.distributed._symmetric_memory）直接中止启动，没有回退路径。

报错原文

[Installation]: Bug / Enhancement][Blackwell HGX B300] Pre-flight check for nvcc/ninja before multi-TB shard load & graceful fallback for NVLS multicast bind failure (CUDA error 401)

CUDA error 401
cuMulticastBindMem
latent_moe_tail

原因分析

问题一：HGX 生产节点常只预装驱动和 nvidia-fabricmanager，不带完整 CUDA Toolkit。当 FlashInfer 检测到当前 SM 架构（sm_100a / sm_103a）没有预编译 cubin 时，会在权重加载之后触发 JIT 编译，此时若 PATH/CUDA_HOME 中找不到 nvcc 或 ninja 就会直接崩溃，前面的加载时间全部浪费。

问题二：在 HGX B300 基板上，热重启后 NVSwitch 多播表可能处于未初始化状态，即使 nvidia-fabricmanager 报告 Completed / Success 也是如此。Blackwell 的 latent_moe_tail 融合会经 torch.distributed._symmetric_memory 自动启用，且不遵循 NCCL_NVLS_ENABLE=0，于是 cuMulticastBindMem 抛出 CUDA error 401，vLLM 没有软件回退。Issue 提出在分布式组初始化阶段探测多播能力并回退到非融合 MoE 集合通信，但这只是改进建议，并非现有行为。

环境排查

确认主机是否安装完整 CUDA Toolkit：检查 /usr/local/cuda-13.1/bin 下是否存在 nvcc，以及 CUDA_HOME 是否正确指向。
确认 ninja 是否在 PATH 中可执行。
确认 vLLM 版本为 0.34.0 或更新版本（含 Kimi-K3.1 支持）。
确认 TORCH_CUDA_ARCH_LIST 已按安装步骤设置为 10.0a;10.3a。
确认 GPU 型号与计算架构为 SM100/SM103（8× HGX B300）。
确认 nvidia-fabricmanager 状态；必要时检查 NVSwitch 多播表是否已初始化。
确认主机为裸金属还是虚拟化环境，因为 Issue 仅在裸金属上验证了修复。

解决步骤

按 Issue 安装步骤设置环境变量：export CUDA_HOME=/usr/local/cuda-13.1，并把 $CUDA_HOME/bin 加入 PATH；设置 TORCH_CUDA_ARCH_LIST=”10.0a;10.3a”。
安装与驱动匹配的 CUDA 13.1 工具包：安装 cuda-toolkit-13-1；同时安装 ninja-build，使 FlashInfer 在权重加载后能完成 SM100/SM103 NVLS JIT 编译。
若出现 CUDA error 401（cuMulticastBindMem）：停止正在运行的 GPU 任务，执行 sudo nvidia-smi -r 重置 GPU，并重启 nvidia-fabricmanager，以重新初始化 HGX B300 的 NVSwitch 多播表。
重新启动 vLLM 服务，按原配置以 TP=8 加载 Kimi K3.1 Pro（max_model_len=1048576）。
上游改进（可优先尝试、尚未合入）：在加载多 TB 分片前预检 nvcc/ninja 是否可用并快速失败；在分布式组初始化时探测 cuMulticastBindMem 能力，绑定失败时记录警告并回退到非融合 MoE 集合通信；或在发布 wheel 中打包 SM100/SM103 NVLS all-reduce cubin，免除运行时 nvcc 依赖。

验证方法

Issue 评论确认，在裸金属 Ubuntu 24.04 的 8× HGX B300 上应用两个 workaround 后：服务能完成权重加载与 FlashInfer JIT 编译，不再出现缺 nvcc/ninja 的崩溃；CUDA error 401（cuMulticastBindMem）崩溃消失；8 个 rank 稳定运行在约 208 GB/GPU 的权重占用下，且无 Xid 错误。完成修复后可对照这些现象确认问题是否解决。