一个 8 节点 64 卡的训练任务在裸机上跑通了，all_reduce_perf 的大消息 busbw 接近网卡的标称值。同一个镜像、同一套 NCCL 环境变量搬到 Kubernetes 上，Pod 全部 Running，任务也在正常推进，只是 step time 慢了两倍多。再跑一次 all_reduce_perf，busbw 只剩裸机的三分之一。日志里没有报错，nvidia-smi 显示八张卡都在，ibstat 在宿主机上也一切正常。

这种”没有错误、只是慢”的故障在平台层非常典型，因为它不是某个组件坏了，而是引擎想走的那条路平台没有铺。NCCL 需要直接打开 /dev/infiniband/uverbs*、在网卡上注册显存、通过 RDMA 网卡的 IP 完成握手；而 Kubernetes 默认给每个 Pod 的只有一张 veth 网卡和一个 overlay 地址。NCCL 发现没有 RDMA 设备，就安静地退回 TCP socket，用那张 veth 把几十 GB 的梯度搬来搬去——它做了它该做的事，慢是唯一的症状。

存储侧的故障形态是同一类：训练任务每半小时写一次 checkpoint，在单机 NVMe 上几十秒写完；上了集群改写共享文件系统，一次 checkpoint 十几分钟，训练在这十几分钟里停着。没有报错，只是慢。而推理服务扩容一个副本要拉 140 GB 权重，从对象存储拉要八分钟，”扩容”这个动作的大部分时间花在了 I/O 上。

本篇讲这两条”喂饱 GPU”的管道在 Kubernetes 上怎么铺：网络这一半是让 RDMA 设备和 GPUDirect RDMA 在容器里可用、可验证；存储这一半是按三类负载（数据集、checkpoint、权重）选方案，并把 checkpoint I/O 的带宽需求算清楚。本篇要回答总纲提出的核心问题：

一个 8 节点 64 卡的训练任务，nccl-tests 在容器里测出的 all_reduce 带宽只有裸机的三分之一。从 Pod 的网络配置、device plugin 的资源分配、NCCL 的环境变量三个层面，各自可能出了什么问题？¹

依照系列惯例，本篇不解释 NCCL 为什么选某条路径、不讲 RDMA verbs 与 IB/RoCE 的协议差别，只讨论如何让 NCCL 在容器里能选到 RDMA 这条路、如何从日志确认它选了。源码与 CRD 以 Multus CNI v4.3.0、k8s-rdma-shared-dev-plugin v1.5.4、NVIDIA Network Operator v26.7.0、NVIDIA GPU Operator v26.7.0 为准；NCCL 2.28.9 与 nccl-tests 2.18.3 只用到环境变量名、日志行与命令行；PyTorch v2.13.0 只用到 torch.distributed.checkpoint 的公开 API。存储产品（Lustre、Storage Scale、WEKA、BeeGFS、JuiceFS、Alluxio、Fluid、GPUDirect Storage）按公开文档描述定位，本篇不给任何实测数字。

一、总览

1. 引擎的需求

训练框架与推理引擎在网络和存储这一层的需求，可以从 NCCL 的初始化和 PyTorch 的 checkpoint 路径倒推出来：

前五条是网络，后三条是存储。它们有一个共同点：引擎自己检测能力、自己降级。NCCL 找不到 IB 设备就用 socket，找不到 peermem 就走 host 内存；PyTorch 的 dcp.save 写不完就等。降级不报错，所以平台层必须主动验证”引擎走的是不是铺的那条路”。

2. K8s 的空缺

原生 Kubernetes 在这一层留下四个洞：

• 一个 Pod 一张网卡。CNI 规范本身允许多网卡，但 kubelet 只调用一个 CNI 插件、只关心一个 Pod IP；Service、NetworkPolicy、DNS 都围绕这一个 IP。RDMA 网卡要作为”第二张网卡”进入 Pod，需要一个元插件在 kubelet 之下把多个 CNI 调用串起来——这是 Multus 的位置。
• 设备文件不进容器。容器运行时默认不挂 /dev/infiniband/*；Kubernetes 没有”RDMA 设备”这种资源类型，只有 device plugin 这个通用扩展点。谁来发现 HCA、谁决定哪个 Pod 能用、挂哪些设备文件——这是 RDMA device plugin 的位置。
• 内核模块不归 K8s 管。OFED/DOCA 驱动、nvidia_peermem、rdma_cm 这些模块要在每个节点上装好并且版本匹配；K8s 没有”节点级驱动”的对象。GPU Operator 用驱动容器解决了 GPU 驱动，Network Operator 用同样的方式解决网卡驱动，两者还要协调顺序。
• 存储只有 PV/PVC 的接口。CSI 把”挂一个卷”标准化了，但 K8s 不知道这个卷是 Lustre 还是 NFS、带宽多少、能不能被 64 个 Pod 同时写。选型、带宽规划、缓存策略都在 CSI 之上，由平台决定。

3. 平台的机制（全局图）

4. 本文的章节安排

二、为什么 CNI overlay 不够

1. 默认路径：veth + overlay

默认 CNI（Calico、Cilium、Flannel 等）给每个 Pod 创建一对 veth，一端在 Pod 的网络命名空间里叫 eth0，另一端接在宿主机的网桥或路由表上；跨节点流量再经 VXLAN/IPIP 封装或 BGP 路由。这条路径的每个环节都是内核 TCP/IP 协议栈：

对 NCCL 的 socket transport 来说，这条路径的带宽上限由 CPU 拷贝和协议栈决定，通常远低于网卡线速；延迟在几十微秒量级。一张 400 Gb/s 的网卡走这条路，能用到的带宽可能只有几分之一，而且要消耗大量 CPU 核。这就是开头那个”三分之一”的来源之一。

2. NCCL 想走的路：/dev/infiniband + GPUDirect RDMA

NCCL 的 IB transport 需要的是另一条路：

内核协议栈完全不参与数据搬运，CPU 只负责下发工作请求。要走这条路，容器里必须有三样东西：

1. 设备文件：/dev/infiniband/uverbsN（对应某个 HCA 端口）、/dev/infiniband/rdma_cm，以及 umadN/issmN 这类管理设备。NCCL 2.28.9 的 src/transport/net_ib.cc 在 ncclIbInit 里调 ibv_get_device_list 枚举设备；容器里没有这些文件，就是 NET/IB : No device found.，然后按 src/plugin/net.cc 里内部插件的顺序（IB 之后是 Socket）回落到 NET/Socket。
2. GPUDirect RDMA 的内核支持：ibGdrSupportInitOnce（同文件）检查 /sys/module/nvidia_peermem/version 或旧的 nv_mem 路径；ncclIbDmaBufSupport 试探 ibv_reg_dmabuf_mr 是否可用。两者都没有，网卡就只能读写 host 内存，数据要在 GPU 与 host 之间多拷一次。
3. 一个 RDMA 侧的 IP：NCCL 的 IB transport 用一个 IP 接口做带外（OOB）握手（ncclFindInterfaces，受 NCCL_SOCKET_IFNAME 影响）；RoCE 还要用网卡的 IP 决定 GID（ncclIbGetGidIndex）。这个 IP 通常来自 IPoIB 子接口或 RoCE 网卡本身，而不是 overlay。

3. 两条路径的对照图

第三章到第五章就是把右边那一列一项项铺出来。

三、第二张网卡：Multus 与 NetworkAttachmentDefinition

1. Multus 的位置：thin 与 thick

Multus CNI 是一个”元插件”：kubelet 只认它一个 CNI，它再把 ADD/DEL 调用分发给默认网络插件和若干附加网络插件（delegate）。v4.3.0 有两种部署形态（docs/thick-plugin.md）：

• thin：/opt/cni/bin/multus 是一个完整的二进制，每次 CNI 调用都由它直接读 kubeconfig、查 API、调 delegate；部署文件 deployments/multus-daemonset.yml。
• thick：节点上的 multus-shim 只负责把 CNI 参数通过 unix socket 转给常驻的 multus-daemon，后者取 NetworkAttachmentDefinition、算 RuntimeConfig、调 delegate；部署文件 deployments/multus-daemonset-thick.yml，daemon 配置默认在 /etc/cni/net.d/multus.d/daemon-config.json。

thick 的好处是有了一个常驻进程可以做缓存、指标和更复杂的逻辑，代价是多一个 DaemonSet 和一次本地 RPC。Network Operator 部署的是它自己打包的 Multus 镜像（secondaryNetwork.multus），形态以 Operator 版本为准。

Multus 的配置选项（docs/configuration.md）里和本篇相关的有：clusterNetwork 或 delegates 指定默认网络；namespaceIsolation 限制 Pod 只能引用本 namespace 的 NAD；readinessindicatorfile 让 Multus 等默认网络就绪再工作——GPU 训练 Pod 起不来时，先看这个文件是否存在。

2. NetworkAttachmentDefinition 与三个注解

附加网络用 CRD NetworkAttachmentDefinition（API 组 k8s.cni.cncf.io/v1，Network Plumbing WG 的事实标准）描述，spec.config 就是一段 CNI 配置 JSON。Pod 用注解引用它。Multus v4.3.0 pkg/k8sclient/k8sclient.go 里定义了三个关键注解：

• k8s.v1.cni.cncf.io/networks：Pod 上：要挂哪些附加网络。逗号分隔的名字，或 JSON 数组（可带 interface、ips、mac、gateway）
• k8s.v1.cni.cncf.io/resourceName：NAD 上：这个网络要消耗哪个 device plugin 资源；Multus 据此把 kubelet 分配的设备信息传给 delegate
• k8s.v1.cni.cncf.io/network-status：Pod 上（Multus 写回）：每个接口的名字、IP、MAC、是否默认路由

networks 注解跨 namespace 引用写成 <namespace>/<name>；resourceName 把 NAD 与第四章的 device plugin 关联起来——Pod 请求了 nvidia.com/hostdev: 1，kubelet 分配了某个 PCI 设备，Multus 从 kubelet 的设备分配记录（checkpoint 文件或 PodResources API）读到结果，再以 deviceID 传给 host-device 或 sriov CNI，让 CNI 知道要把哪张网卡搬进 Pod。

3. 四种接入方式

RDMA 网卡进 Pod 的第二张网卡有四种常见接法。它们决定的是IP 接口怎么进 Pod；RDMA 设备文件由第四章的 device plugin 负责，两者是正交的。下图把这两条链放在一起看：kubelet 创建 Pod 时分别走 CNI 和 device plugin 两个扩展点，前者给 Pod 两个 IP 接口（eth0 走内核协议栈；net1 也是内核接口，但 NCCL 只用它做握手），后者把 /dev/infiniband/* 挂进容器；NCCL 的数据面最终只经 verbs 直达 HCA，两条链在此汇合。唯一的交叉点是 NAD 上的 resourceName 注解——host-device/sriov 接法需要 CNI 知道 device plugin 分到了哪张网卡。

%% 图：RDMA 网卡进 Pod 的两条链：CNI 扩展点给 Pod eth0 与 net1 两个 IP 接口，device plugin 把 /dev/infiniband/* 挂进去
flowchart TB
    PodSpec["Pod spec<br/>annotations: k8s.v1.cni.cncf.io/networks: rdma-net<br/>resources.limits: rdma/rdma_shared_device_a: 1"]
    subgraph ipchain["IP 接口这条链（第三章，CNI 扩展点）"]
        Kubelet1["kubelet 调 CNI ADD"]
        NAD["NAD rdma-net<br/>spec.config = CNI JSON<br/>注解 resourceName（host-device/sriov 才需要）"]
        Multus["Multus 元插件<br/>读 networks 注解，取 NAD，逐个调 delegate"]
        DefCNI["默认 CNI<br/>Calico / Cilium / Flannel"]
        Delegate["delegate CNI<br/>ipoib / macvlan / host-device / sriov"]
        Eth0["eth0：veth + overlay IP<br/>Service / NetworkPolicy / DNS 只认它<br/>数据走内核协议栈"]
        Net1["net1：RDMA 侧 IP<br/>IPoIB 子接口 / macvlan / VF<br/>内核接口，只承担 OOB 握手与 RoCE GID"]
    end
    subgraph devchain["设备文件这条链（第四章，device plugin 扩展点）"]
        Kubelet2["kubelet 调 device plugin Allocate"]
        DP["rdma-shared-dev-plugin（一组 PF × rdmaHcaMax）<br/>或 SR-IOV device plugin（一 VF 一 Pod）"]
        DevFiles["/dev/infiniband/uverbsN umadN issmN rdma_cm<br/>以 rwm 挂进容器；需 IPC_LOCK"]
    end
    Verbs["NCCL IB transport<br/>用户态 verbs 经 uverbsN 下发工作请求<br/>数据 GPU 显存 ⇄ HCA（GPUDirect RDMA），绕过内核协议栈"]

    PodSpec --> Kubelet1
    PodSpec --> Kubelet2
    Kubelet1 --> Multus
    NAD --> Multus
    Multus --> DefCNI --> Eth0
    Multus --> Delegate --> Net1
    Kubelet2 --> DP --> DevFiles
    DP -. "分配结果（PCI deviceID）经 resourceName 注解传给 delegate" .-> Delegate
    Net1 -- "握手" --> Verbs
    DevFiles -- "数据面" --> Verbs

    classDef kernel fill:#fde2e2,stroke:#c0392b;
    classDef bypass fill:#e3f4e1,stroke:#2e7d32;
    classDef oob fill:#fff4d6,stroke:#b7791f;
    class Eth0 kernel;
    class Net1 oob;
    class Verbs,DevFiles bypass;

红色是走内核协议栈的数据路径（NCCL 回落到 socket 时用的就是它），黄色是只做控制面的接口，绿色是 RDMA 数据面。四种接法的差别只在 Delegate → Net1 这一格：

Network Operator 用三个 CRD 把前三种包装成”填几个字段就生成 NAD”（sriov 的 NAD 通常由 SR-IOV Network Operator 的 SriovNetwork 生成，不在本篇检出范围）：

• HostDeviceNetwork（api/v1alpha1/hostdevicenetwork_types.go）：spec.networkNamespace、spec.resourceName、spec.ipam；生成的 NAD 模板在 manifests/state-hostdevice-network/0010-hostdevice-net-cr.yml，type: host-device，并带 k8s.v1.cni.cncf.io/resourceName 注解指向 sriovDevicePlugin 上报的资源；
• MacvlanNetwork（macvlannetwork_types.go）：spec.master、spec.mode、spec.mtu、spec.ipam；
• IPoIBNetwork（ipoibnetwork_types.go）：spec.master、spec.ipam；NAD 模板 manifests/state-ipoib-network/0010-ipoib-net-cr.yaml，type: ipoib。

ipam 字段是一段 JSON，Network Operator 的例子用它自己的 nv-ipam（{"type":"nv-ipam","poolName":"my-pool"}，由 NicClusterPolicy.spec.nvIpam 部署），也可以用 whereabouts 或 static。

直接写 NAD 也完全可以，这是 mini-platform 的做法（第十一章 net/nad-ipoib.yaml，IB 集群 + shared device plugin 的组合）：

apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: rdma-net
  namespace: default
spec:
  config: '{
    "cniVersion": "0.3.1",
    "name": "rdma-net",
    "type": "ipoib",
    "master": "ibs3f1",
    "ipam": {
      "type": "whereabouts",
      "range": "192.168.100.0/24"
    }
  }'

master 是宿主机上的 IPoIB 接口名，各节点要一致（或按节点分别建 NAD）。RoCE 集群把 type 换成 macvlan、master 换成以太网接口、加 "mode": "bridge"。host-device 变体（net/nad-hostdevice.yaml）不写 master，而是加注解 k8s.v1.cni.cncf.io/resourceName: nvidia.com/hostdev，由 CNI 从 device plugin 的分配结果里得知要搬哪张网卡——它要求 NicClusterPolicy 里配了 sriovDevicePlugin（资源名 nvidia.com/hostdev，第四章第 2 节），Pod 也要请求这个资源。Pod 侧（片段）：

metadata:
  annotations:
    k8s.v1.cni.cncf.io/networks: rdma-net

多张网卡（每 GPU 一张的 8 卡节点）写成 rdma-net-0,rdma-net-1,... 或 JSON 数组并指定 interface 名，Pod 里就会出现 net1…net8。

四、把 RDMA 设备给容器

1. RDMA shared device plugin：一个 HCA 给很多 Pod

k8s-rdma-shared-dev-plugin v1.5.4 的模型很简单：把宿主机上的每个 RDMA 网卡（按 selector 过滤后）当作一个”共享设备”，对外上报 rdmaHcaMax 个同名资源副本；任何 Pod 请求一个副本，就把这组网卡的全部 RDMA 字符设备挂进容器。配置文件（默认 /k8s-rdma-shared-dev-plugin/config.json，由 ConfigMap 挂入）的结构在 pkg/types/types.go：

UserConfigList
  periodicUpdateInterval   秒；0 关闭；不设默认 60（README）
  configList[]             每项一个资源
    resourceName           资源名后缀，如 rdma_shared_device_a
    resourcePrefix         默认 "rdma"（resources_manager.go 的 rdmaHcaResourcePrefix）→ 资源名 rdma/rdma_shared_device_a
    rdmaHcaMax             上报多少个副本；每个 Pod 请求 1 就是"最多 rdmaHcaMax 个 Pod 共用"
    devices[]              按接口名选网卡（等价于 selectors.ifNames）
    selectors              vendors / deviceIDs / drivers / ifNames / linkTypes；同一 selector 内 OR，selector 之间 AND

Network Operator 的例子（example/crs/mellanox.com_v1alpha1_nicclusterpolicy_cr.yaml）是 resourceName: rdma_shared_device_a，rdmaHcaMax: 63，selectors.vendors: ["15b3"]、deviceIDs: ["101b"]——15b3 是 Mellanox 的 PCI vendor ID，101b 是 ConnectX-6 的 device ID。这就是总纲里提到的 rdma/rdma_shared_device_a 的出处。

分配时发生什么（pkg/resources/server.go）：Allocate 对每个容器返回同一份 deviceSpec——非 CDI 模式下是 ContainerAllocateResponse.Devices，CDI 模式下（useCdi）是以 nvidia.com 为前缀的 CDI 注解。deviceSpec 由 getDevicesSpec 汇总所有匹配网卡的 GetRdmaSpec()，而 pkg/resources/rdma_device_spec.go 的 Get 用 utils.GetRdmaDevices(pciAddress) 从 PCI 地址找到 RDMA 设备再列出其字符设备，每个以 HostPath == ContainerPath、权限 rwm 挂入。VerifyRdmaSpec 要求 rdma_cm、umad、uverbs 三类设备都在（requiredRdmaDevices）。也就是说，Pod 请求 rdma/rdma_shared_device_a: 1 之后，容器里会出现该资源下所有网卡的 /dev/infiniband/uverbsN、umadN、issmN 与共享的 /dev/infiniband/rdma_cm。

两点常被忽略：

• 它没有做 GPU 亲和。一个 8 卡 8 网卡的节点配成一个资源，Pod 拿到的是 8 张网卡的设备文件，由 NCCL 自己按 PCIe 距离选卡；想让 Pod 只看到某几张，要拆成多个 configList 项（用 ifNames 分组）并请求对应的资源名。
• 它要求 RDMA 子系统处于 shared netns 模式：resources_manager.go 的 ValidateRdmaSystemMode 调 netlink.RdmaSystemGetNetnsMode，返回 exclusive 就报错退出（见本章第 4 节）。

2. SR-IOV device plugin：一个 VF 给一个 Pod

另一条路是把物理网卡切成 SR-IOV 虚拟功能（VF），每个 VF 有独立的 PCI 地址、独立的 RDMA 设备，由 SR-IOV network device plugin 作为独立资源上报，一个 Pod 拿一个。Network Operator 通过 NicClusterPolicy.spec.sriovDevicePlugin 部署它，配置格式是那个插件自己的 resourceList（example/crs/mellanox.com_v1alpha1_nicclusterpolicy_cr-full.yaml）：

{
  "resourceList": [
    {
      "resourcePrefix": "nvidia.com",
      "resourceName": "hostdev",
      "selectors": { "vendors": ["15b3"], "isRdma": true }
    }
  ]
}

isRdma: true 让插件在分配 VF 时一并挂入该 VF 的 RDMA 字符设备。VF 的创建本身不在这个插件里——由 SR-IOV Network Operator 的 SriovNetworkNodePolicy（numVfs、nicSelector、isRdma，example/sriov-network/）或节点脚本完成；SR-IOV network device plugin 与 SR-IOV Network Operator 不在本篇的检出范围内，字段以 Network Operator v26.7.0 的示例为准。

3. 两种插件的对照

训练集群的主流做法是 shared plugin：训练任务通常独占节点，隔离是多余的，而 NCCL 看到全部网卡反而更好选。SR-IOV 的价值在多租户和网络策略执行，代价是 VF 配置、固件依赖与更多的运维面。

4. RDMA 子系统的 netns 模式：shared 与 exclusive

Linux RDMA 子系统有一个全局开关，决定 RDMA 设备与网络命名空间的关系（iproute2 的 rdma 工具，属通用知识）：

rdma system show                 # netns shared | exclusive
rdma system set netns shared     # 所有 netns 都能看到所有 RDMA 设备
rdma system set netns exclusive  # RDMA 设备只属于一个 netns，需显式 rdma dev set <dev> netns <ns>

• shared（默认）：容器只要有设备文件就能用任何 HCA；RDMA 流量与 netns 无关，所以 NetworkPolicy 管不到它。shared-dev-plugin 只在这个模式下工作。
• exclusive：每个 RDMA 设备归属一个 netns；配合 SR-IOV，rdma-cni 在 Pod 创建时把 VF 对应的 RDMA 设备 move 进 Pod 的 netns，其他 Pod 即使有设备文件也看不到它。切换到 exclusive 要求当前没有 RDMA 设备被 netns 之外的用户占用，实践中在节点初始化、加载驱动之后立即设置；Network Operator 的 OFED 驱动容器挂了 /etc/modprobe.d/ib_core.conf（manifests/state-ofed-driver/0050_ofed-driver-ds.yaml），ib_core 的模块参数也可以固定这个模式（参数名以内核/OFED 文档为准）。

5. 容器还需要什么：IPC_LOCK 与 memlock

RDMA 注册内存需要把页锁定，容器默认的 RLIMIT_MEMLOCK 通常很小。所有官方示例（rdma-shared-dev-plugin example/test-hca-pod.yaml、Network Operator example/rdma-gpu-test-pod1.yml）都给容器加了 securityContext.capabilities.add: ["IPC_LOCK"]。少了它，ibv_reg_mr 会在注册大块内存时失败，NCCL 的表现是初始化时报 Call to ibv_reg_mr failed with error …（src/misc/ibvwrap.cc 的 IBV_PTR_CHECK_ERRNO）或直接回落。这是第六章排查清单里最容易漏的一项。

五、Network Operator 与 GPU Operator 的配合

1. NicClusterPolicy：一个 CR 部署整条网络栈

NVIDIA Network Operator v26.7.0 的核心 CRD 是 NicClusterPolicy（API 组 mellanox.com/v1alpha1，api/v1alpha1/nicclusterpolicy_types.go）。它是集群级（scope=Cluster）单例，控制器只处理名为 nic-cluster-policy 的那一个实例（pkg/consts/consts.go 的 NicClusterPolicyResourceName，controllers/nicclusterpolicy_controller.go 据此忽略其他名字）。NicClusterPolicySpec 的字段与本篇相关的部分：

spec.ofedDriver                  OFEDDriverSpec：DOCA-OFED 驱动容器（image/repository/version，upgradePolicy、探针、env、
                                 certConfig/repoConfig、forcePrecompiled、terminationGracePeriodSeconds）
spec.rdmaSharedDevicePlugin      DevicePluginSpec：镜像 + config（第四章的 JSON 原样放进去）+ useCdi
spec.sriovDevicePlugin           DevicePluginSpec：镜像 + config（resourceList JSON）+ useCdi
spec.secondaryNetwork            SecondaryNetworkSpec：multus（MultusSpec，可带 config）· cniPlugins（containernetworking 插件集）· ipoib（IPoIB CNI）
spec.nvIpam                      NVIPAMSpec：nv-ipam 控制器与 CNI，enableWebhook
spec.ibKubernetes                IBKubernetesSpec：IB 分区（PKey/GUID）管理，pKeyGUIDPoolRangeStart/End、ufmSecret
spec.nicFeatureDiscovery         NICFeatureDiscoverySpec：配合 NFD 打网卡标签
spec.nicConfigurationOperator    NicConfigurationOperatorSpec：网卡固件参数
spec.docaTelemetryService        DOCATelemetryServiceSpec
spec.nodeAffinity / tolerations  DaemonSet 的调度约束

注意 v26.7.0 没有 docaDriver 字段：DOCA-OFED 驱动容器仍由 ofedDriver 配置（类型注释写的是 “DOCA-OFED Driver Container”），示例镜像是 nvcr.io/nvidia/mellanox/doca-driver:doca3.5.0-26.07-0.7.7.0-0。ofedDriver 的 Env 可以传 docs/mofed-container-env-vars.md 列出的变量，例如 UNLOAD_THIRD_PARTY_RDMA_MODULES。OFEDDriverSpec 里的 upgradePolicy（autoUpgrade、maxParallelUpgrades、drain、safeLoad、waitForCompletion）决定驱动升级时怎么排空节点——驱动升级要重载 mlx5_core，所有用着网卡的 Pod 都会断，这是训练集群最需要谨慎的运维动作之一（docs/host-ofed.md 与 docs/automatic-ofed-upgrade.md）。

一份最小的 NicClusterPolicy（mini-platform 的 net/nicclusterpolicy.yaml）：

apiVersion: mellanox.com/v1alpha1
kind: NicClusterPolicy
metadata:
  name: nic-cluster-policy
spec:
  ofedDriver:
    image: doca-driver
    repository: nvcr.io/nvidia/mellanox
    version: doca3.5.0-26.07-0.7.7.0-0
    forcePrecompiled: false
    upgradePolicy:
      autoUpgrade: true
      maxParallelUpgrades: 1
      drain:
        enable: true
        force: true
        deleteEmptyDir: true
        timeoutSeconds: 300
  rdmaSharedDevicePlugin:
    image: k8s-rdma-shared-dev-plugin
    repository: nvcr.io/nvidia/mellanox
    version: network-operator-v26.7.0
    config: |
      {
        "configList": [
          {
            "resourceName": "rdma_shared_device_a",
            "rdmaHcaMax": 63,
            "selectors": {
              "vendors": ["15b3"],
              "linkTypes": ["infiniband"]
            }
          }
        ]
      }
  secondaryNetwork:
    multus:
      image: multus-cni
      repository: nvcr.io/nvidia/mellanox
      version: network-operator-v26.7.0
    cniPlugins:
      image: plugins
      repository: nvcr.io/nvidia/mellanox
      version: network-operator-v26.7.0
    ipoib:
      image: ipoib-cni
      repository: nvcr.io/nvidia/mellanox
      version: network-operator-v26.7.0
  nvIpam:
    image: nvidia-k8s-ipam
    repository: nvcr.io/nvidia/mellanox
    version: network-operator-v26.7.0
    enableWebhook: false

镜像 tag 来自仓库示例，实际以随 Operator 发布的 values 为准。rdmaSharedDevicePlugin.config 与 sriovDevicePlugin.config 都是”原样透传”的字符串，Operator 只负责生成 ConfigMap 和 DaemonSet（manifests/state-rdma-shared-device-plugin/），不校验里面的 JSON——写错了要去 device plugin 的日志里找。

2. GPU Operator 的一半：driver.rdma

GPUDirect RDMA 需要 GPU 驱动侧的 nvidia_peermem 模块（把显存作为 RDMA 可注册的 peer memory 暴露给 ib_core），它属于 GPU 驱动包而不是网卡驱动。GPU Operator v26.7.0 的 ClusterPolicy（api/nvidia/v1/clusterpolicy_types.go）在 DriverSpec 里有：

• spec.driver.rdma.enabled：GPUDirectRDMASpec.Enabled，在驱动 DaemonSet 里保留 nvidia-peermem-ctr sidecar，并给驱动容器设 GPU_DIRECT_RDMA_ENABLED=true（controllers/object_controls.go）；
• spec.driver.rdma.useHostMofed：GPUDirectRDMASpec.UseHostMOFED，OFED 装在宿主机而不是 Network Operator 容器里时，把 /usr/src 从宿主机挂进来编 peermem，并设 USE_HOST_MOFED=true；
• spec.gds.enabled：GPUDirectStorageSpec，nvidia-fs 驱动容器（实验性），device plugin 加 GDS_ENABLED 与 MOFED_ENABLED 以注入 /dev/nvidia-fs 与 /dev/infiniband；
• spec.gdrcopy.enabled：GDRCopySpec，gdrdrv 驱动。

驱动 DaemonSet 模板 assets/state-driver/0500_daemonset.yaml 里可以看到这套机制的形状：nvidia-peermem-ctr 容器运行 nvidia-driver reload_nvidia_peermem，探针是 nvidia-driver probe_nvidia_peermem；它挂了 /run/mellanox/drivers（mountPropagation: HostToContainer）——这正是 Network Operator 的 OFED 容器把驱动树发布到宿主机的路径（manifests/state-ofed-driver/0050_ofed-driver-ds.yaml 同样挂 /run/mellanox/drivers）。transformPeerMemoryContainer 在 rdma.enabled 为假时把这个 sidecar 从 DaemonSet 里删掉。validator（cmd/nvidia-validator/main.go）用 lsmod | grep nvidia_peermem 确认模块加载并写 nvidia-peermem-ready 状态文件。

3. 两个 Operator 的顺序

两者的依赖关系是：nvidia_peermem 要针对当前的 OFED 内核模块编译并在其后加载。所以推荐顺序是 Network Operator 的 OFED 驱动先就位，GPU Operator 的驱动容器再启动；OFED 升级重载后，nvidia-peermem-ctr 的 reload_nvidia_peermem 负责重新加载。Network Operator 用节点标签 network.nvidia.com/operator.mofed.wait 表达”OFED 尚未就绪”（controllers/mofed_wait_labels.go 设置；pkg/nodeinfo/attributes.go 的 NodeLabelWaitOFED），GPU Operator 在 internal/nodeinfo/attributes.go 里定义了同名常量；这个标签也出现在 Network Operator Helm values 的 configDaemonNodeSelector 里。两个 Operator 各自的 Helm 参数与安装顺序以 NVIDIA 文档为准，本篇只说明机制。把这条依赖链画出来，两个 Operator 之间靠的是一个宿主机路径和一个节点标签：

%% 图：两个 Operator 的顺序：Network Operator 的 OFED 驱动先就位并移除 wait 标签，GPU Operator 的驱动容器再启动并加载 nvidia_peermem
flowchart TB
    NCP["NicClusterPolicy.spec.ofedDriver<br/>（Network Operator）"]
    OFED["OFED / DOCA 驱动容器 DaemonSet<br/>加载 mlx5_core · ib_core · ib_uverbs · rdma_cm"]
    Publish["驱动树发布到宿主机<br/>/run/mellanox/drivers"]
    WaitLabel["节点标签 network.nvidia.com/operator.mofed.wait<br/>OFED 就绪前存在，就绪后移除"]
    CP["ClusterPolicy.spec.driver.rdma.enabled = true<br/>（GPU Operator）"]
    GPUDrv["GPU 驱动容器 DaemonSet<br/>nvidia / nvidia_uvm / nvidia_modeset"]
    Peermem["nvidia-peermem-ctr sidecar<br/>挂 /run/mellanox/drivers（HostToContainer）<br/>reload_nvidia_peermem：针对当前 ib_core 编译并加载"]
    Validator["validator：lsmod 有 nvidia_peermem<br/>→ 写 nvidia-peermem-ready 状态文件"]
    Ready["Pod 里 NCCL 日志出现 via NET/IB/N/GDRDMA"]
    Upgrade["OFED 升级（upgradePolicy）<br/>drain 节点 → 重载 mlx5_core<br/>所有用着网卡的 Pod 断开"]

    NCP --> OFED --> Publish
    OFED --> WaitLabel
    CP --> GPUDrv --> Peermem
    WaitLabel -- "GPU Operator 用同名常量判断 OFED 是否就绪" --> GPUDrv
    Publish -- "peermem 必须针对这套 ib_core 编译、在其后加载" --> Peermem
    Peermem --> Validator --> Ready
    Upgrade --> OFED
    Upgrade -. "重载后 probe_nvidia_peermem 失败，sidecar 重新 reload" .-> Peermem

    classDef netop fill:#e3f0fb,stroke:#1f5f99;
    classDef gpuop fill:#e3f4e1,stroke:#2e7d32;
    classDef warn fill:#fde2e2,stroke:#c0392b;
    class NCP,OFED,Publish,WaitLabel netop;
    class CP,GPUDrv,Peermem,Validator gpuop;
    class Upgrade warn;

蓝色属于 Network Operator，绿色属于 GPU Operator；两条实线跨色边就是全部耦合点。红色的 OFED 升级会把整条链从头重跑一遍，这也是为什么 maxParallelUpgrades: 1 与 drain 在训练集群上几乎是必配的。

4. nvidia_peermem 与 DMA-BUF

GPUDirect RDMA 有两条内核路径，NCCL 2.28.9 两条都探测：

对平台来说两者是可替换的：只要 NCCL 日志里出现 via NET/IB/N/GDRDMA 就说明 GPUDirect RDMA 生效了；paths.cc 的 GPU Direct RDMA Disabled for GPU … (distance N > M) 则说明模块在但拓扑距离超过了 NCCL_NET_GDR_LEVEL。

六、容器内验证与排障

1. 验证清单

在一个请求了 RDMA 资源的 Pod 里，按这个顺序验证，每一步不通就不用看下一步：

第 1～5 步在没有 GPU 的节点上也能做，是平台层的责任；第 6 步验证 RDMA 网络本身；第 7 步才轮到 NCCL。

2. 容器里跑 nccl-tests

nccl-tests 2.18.3 的多机模式靠 MPI（src/common.cu 用 MPI_Comm_rank/size 定 rank、MPI_Bcast 分发 ncclUniqueId），mini-platform 的 net/nccl-tests-job.yaml 用一个 Indexed Job 起两个 Pod：index 1 跑 sshd，index 0 等对端就绪后 mpirun。生产上这一步由 MPI Operator 或 Kubeflow Trainer 的 MPI runtime 自动化，这里手写是为了看清每一层。关键片段：

apiVersion: v1
kind: Service
metadata:
  name: nccl-tests
spec:
  clusterIP: None                   # headless：Pod 得到 nccl-tests-<index>.nccl-tests 的稳定 DNS
  selector:
    job-name: nccl-tests
---
apiVersion: batch/v1
kind: Job
metadata:
  name: nccl-tests
spec:
  completionMode: Indexed
  completions: 2
  parallelism: 2
  template:
    metadata:
      annotations:
        k8s.v1.cni.cncf.io/networks: rdma-net     # 第三章的 NAD；Pod 里出现 net1
    spec:
      subdomain: nccl-tests
      restartPolicy: Never
      containers:
      - name: nccl
        image: registry.example.com/nccl-tests:2.18.3-mpi   # 自建：nccl-tests make MPI=1 + openssh
        securityContext:
          capabilities:
            add: ["IPC_LOCK"]
        resources:
          limits:
            nvidia.com/gpu: 8
            rdma/rdma_shared_device_a: 1
        env:
        - name: NCCL_DEBUG
          value: INFO
        - name: NCCL_DEBUG_SUBSYS
          value: INIT,NET
        - name: NCCL_SOCKET_IFNAME
          value: net1                 # Multus 挂进来的 RDMA 侧接口，不是 eth0
        # - name: NCCL_IB_HCA
        #   value: mlx5_0,mlx5_1,mlx5_2,mlx5_3,mlx5_4,mlx5_5,mlx5_6,mlx5_7
      # ... 省略：ssh 密钥 Secret 的挂载、按 JOB_COMPLETION_INDEX 分支的 command（1 起 sshd，0 跑 mpirun）、
      #     podAntiAffinity 让两 Pod 落在不同节点

index 0 最终执行的命令与裸机一致：

mpirun -np 16 -N 8 -H nccl-tests-0.nccl-tests:8,nccl-tests-1.nccl-tests:8 \
  -x NCCL_DEBUG -x NCCL_DEBUG_SUBSYS -x NCCL_SOCKET_IFNAME -x NCCL_IB_HCA -x LD_LIBRARY_PATH \
  ./build/all_reduce_perf -b 8 -e 8G -f 2 -g 1 -n 20 -w 5 -c 0 -T 600

-T 600 让网络不通时得到一个错误而不是一个永远不退出的 Job。

没有 RDMA 网卡的集群（总纲允许的”host network 模拟”）：同一份 Job 去掉 rdma/... 请求与 networks 注解，改成 hostNetwork: true 与 hostIPC: true，NCCL_SOCKET_IFNAME 指向宿主机的物理网卡名。这样测出的是 socket 路径的数字，意义在于走通”两 Pod 的 NCCL 能互相发现并完成 all_reduce”这一整条流程，并把 NET/Socket 的日志形态看一遍——之后在真 RDMA 集群上看到 NET/Socket 就知道是回落了。如果宿主机有 RDMA 网卡但没装 device plugin，再加一个 hostPath: /dev/infiniband 的挂载与 privileged: true，就是”不经 device plugin 的直通”，只适合验证，不适合生产。

3. 读 NCCL_DEBUG=INFO：只看”走了哪条路”

本篇只需要 INFO 日志里的这几行（NCCL_DEBUG_SUBSYS=INIT,NET 足够）：

只要第一行列出了正确数量的 HCA、Using network IB、每个 channel 都有 GDRDMA，网络这一层就是通的；再慢就不是平台的问题，而是第三章之外的调优范围。按固定顺序读这几行，就是一棵四层决策树，每一层的”否”分支都对应一个明确的修法：

%% 图：读 NCCL_DEBUG=INFO 的四层决策树：Using network 是 IB 还是 Socket，HCA 数够不够，OOB 接口是否 net1，每个 channel 有没有 GDRDMA
flowchart TB
    Start["NCCL_DEBUG=INFO<br/>NCCL_DEBUG_SUBSYS=INIT,NET"]
    Q1{"Using network<br/>IB 还是 Socket？"}
    Sock["Using network Socket：回落了<br/>前面必有 NET/IB : No device found.<br/>容器里没有 uverbs：没请求 rdma/… 资源、<br/>selector 没匹配到网卡、节点 Allocatable 为 0"]
    Q2{"NET/IB : Using<br/>HCA 数够？"}
    FewHCA["NET/IB : Using 列出的 HCA 少于期望<br/>NCCL_IB_HCA 名字写成 netdev 名、^ 排除反了，<br/>或 shared plugin 的 selector 只选了部分网卡"]
    Q3{"OOB 接口<br/>是 net1？"}
    OOB["OOB eth0:10.244…：握手走了 overlay<br/>握手慢、偶发 timeout<br/>设 NCCL_SOCKET_IFNAME=net1"]
    Q4{"每个 channel<br/>都有 /GDRDMA？"}
    NoGDR["via NET/IB/N 后没有 /GDRDMA：数据经 host 内存中转，带宽约一半<br/>宿主机 lsmod 无 nvidia_peermem → 开 driver.rdma.enabled<br/>GPU Direct RDMA Disabled (distance N > M) → 拓扑 / NCCL_NET_GDR_LEVEL"]
    OK["网络这一层是通的<br/>再慢看大消息 busbw：NCCL 调优或硬件问题，不在平台层"]

    Start --> Q1
    Q1 -- "Socket" --> Sock
    Q1 -- "IB" --> Q2
    Q2 -- "否" --> FewHCA
    Q2 -- "是" --> Q3
    Q3 -- "否" --> OOB
    Q3 -- "是" --> Q4
    Q4 -- "否" --> NoGDR
    Q4 -- "是" --> OK

    classDef bad fill:#fde2e2,stroke:#c0392b;
    classDef good fill:#e3f4e1,stroke:#2e7d32;
    class Sock,FewHCA,OOB,NoGDR bad;
    class OK good;

4. 常见的坑

5. 回答核心问题：三层排查表

回到开头：8 节点 64 卡，容器里 all_reduce 带宽只有裸机的三分之一。按总纲的三个层面：

“三分之一”这个数字本身也有信息量：如果是 socket 回落，通常比三分之一还差得多（而且 CPU 打满）；如果是三分之一到一半，更像是 IB 通了但没有 GDRDMA（数据多经一次 host 内存），或者 8 张网卡只用上了 2～3 张（selector 只选了部分、或 NCCL_IB_HCA 写漏了）。先看 Using network 那一行，再数 NET/IB : Using 列出的设备，两个信息就能把范围缩到一层。

七、存储：三类需求与方案定位

1. 三类负载，三种 I/O 画像

训练与推理对存储提出三类完全不同的要求，混在一个”共享存储”上是大多数存储问题的根源：

2. 方案定位

把三类负载映射到方案：

• 数据集：源放对象存储，前面放缓存层（JuiceFS/Alluxio/Fluid），缓存落节点本地 NVMe。数据只读且反复读，缓存命中率高；小文件用 JuiceFS 这类有独立元数据引擎的方案比直接 S3 好几个量级（定性判断，以各产品文档为准）。
• checkpoint：并行文件系统直写，或先落本地 NVMe 再异步上传对象存储（第八章）。关键是聚合写吞吐，元数据不重要。
• 权重：源在对象存储，分发靠缓存层或节点本地缓存 + 预热（第九章）。

3. K8s 里的挂载：CSI

所有这些在 Pod 里的样子都一样：一个 PVC。差别在 StorageClass 的 provisioner 和参数。JuiceFS CSI Driver 的 provisioner 是 csi.juicefs.com，StorageClass 参数通过 Secret 指向元数据引擎与对象存储（字段名以 JuiceFS CSI Driver 文档为准）；mini-platform 的 storage/juicefs-pvc.yaml：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: juicefs-ckpt
provisioner: csi.juicefs.com
reclaimPolicy: Retain
parameters:
  csi.storage.k8s.io/provisioner-secret-name: juicefs-secret
  csi.storage.k8s.io/provisioner-secret-namespace: kube-system
  csi.storage.k8s.io/node-publish-secret-name: juicefs-secret
  csi.storage.k8s.io/node-publish-secret-namespace: kube-system
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ckpt
  namespace: default
spec:
  accessModes: ["ReadWriteMany"]
  storageClassName: juicefs-ckpt
  resources:
    requests:
      storage: 10Ti

ReadWriteMany 是训练 checkpoint 的硬要求——64 个 Pod 同时写同一个目录。并行文件系统（Lustre、Storage Scale、WEKA、BeeGFS）各有自己的 CSI 驱动，也有很多集群直接在节点上挂好文件系统再以 hostPath 进 Pod——后者绕过了 CSI 的生命周期管理，但对静态、全集群共享的并行文件系统是常见做法。

缓存层这一类方案（JuiceFS/Alluxio/Fluid）在 Pod 里也只是一个 PVC，但一次 read() 在节点上要经过的组件比并行文件系统多得多——元数据和数据分两条路，数据又按缓存命中与否分两条：

%% 图：缓存层文件系统里一次 read() 的路径：FUSE 客户端分元数据与数据两条路，数据再按本地缓存命中与否分两条
flowchart TB
    subgraph podside["训练 Pod"]
        DL["dataloader worker<br/>open / stat / read"]
        Mount["PVC 挂载点（FUSE 文件系统）"]
    end
    subgraph nodeside["同一节点上的 CSI node 侧"]
        FUSE["FUSE 客户端进程<br/>DaemonSet 或 per-PVC mount Pod<br/>占节点 CPU / 内存；重启时使用者 I/O 中断"]
        Hit{"数据块在<br/>本地缓存？"}
        Cache["本地 NVMe 缓存目录 → 数据沿原路返回 Pod<br/>hostPath / local PV<br/>容量与驱逐策略决定命中率"]
    end
    Meta["元数据引擎<br/>JuiceFS：Redis / TiKV 等；Alluxio：master<br/>open / stat 全走这里：小文件性能的来源，也是新的单点"]
    Obj["对象存储（S3 / MinIO）<br/>数据集与权重的源"]

    DL --> Mount --> FUSE
    FUSE -- "元数据请求" --> Meta
    FUSE -- "数据请求" --> Hit
    Hit -- "命中：本地 NVMe 带宽" --> Cache
    Hit -- "未命中：首次读受对象存储吞吐限制" --> Obj
    Obj -- "回填缓存，再从缓存返回" --> Cache

    classDef hot fill:#e3f4e1,stroke:#2e7d32;
    classDef cold fill:#fde2e2,stroke:#c0392b;
    classDef spof fill:#fff4d6,stroke:#b7791f;
    class Cache hot;
    class Obj cold;
    class Meta,FUSE spof;

绿色是命中后的热路径（数据集第二个 epoch 起、权重第二个副本起走的路），红色是冷路径，黄色是平台要额外运维的两个进程——图里的每个黄框都对应下面的一条注意点。

两个平台层的注意点：

• FUSE 客户端跑在哪。JuiceFS/Alluxio 的 CSI 通常在节点上以 DaemonSet 或 per-PVC 的 mount Pod 运行 FUSE 进程；它的 CPU/内存是平台开销，而且升级 CSI 或 mount Pod 重启期间，用着这个卷的训练 Pod 的 I/O 可能中断（各产品的平滑升级能力以其文档为准）。
• 缓存盘的容量与驱逐。节点本地 NVMe 做缓存时，一个节点上跑几个任务、每个任务的数据集多大、缓存驱逐策略是什么，决定命中率；缓存目录用 hostPath 还是 local PV 也影响 Pod 的可迁移性。

八、checkpoint I/O 的算术

1. 一个 70B 模型的训练状态有多大

混合精度 + Adam 的训练状态，每个参数：

70B 参数 × 14 字节 ≈ 980 GB，取整就是 1 TB 量级（不含 dataloader 状态、RNG 状态和可选的梯度）。这个数字与并行策略无关：无论 TP/PP/DP 怎么切，整个任务的状态总量就是这么多，只是分布在不同 rank 上。ZeRO（Zero Redundancy Optimizer，DeepSpeed 的分片优化器）/FSDP（Fully Sharded Data Parallel，把参数、梯度、优化器状态切到各卡的数据并行） 把优化器状态分片后，每个 rank 持有的是 1/DP 份，合起来仍是 1 TB。

2. 聚合带宽

总纲的设定：每 30 分钟一次，要求 1 分钟内写完。

分摊到 8 个节点，每节点 ≈ 2.1 GB/s 的持续写；分摊到 64 个 rank，每 rank ≈ 260 MB/s。这三个数字分别对应存储系统的聚合吞吐、每节点网卡/客户端吞吐、每个进程的写吞吐。

为什么是 1 分钟而不是随便多久：同步 checkpoint 期间训练是停的。每 30 分钟训练停 1 分钟，约 3% 的时间开销；如果写要 10 分钟，每 40 分钟里只有 30 分钟在训练，有效吞吐掉四分之一。这就是开头那个”一次 checkpoint 十几分钟”的成本——它直接从任务级的 MFU 里扣。反过来，为什么是 30 分钟：间隔决定故障时丢多少进度，64 卡 30 分钟 = 32 卡·小时的重算。checkpoint 频率是”写开销”与”重算损失”之间的权衡，两者都和存储带宽挂钩。

3. 分片 checkpoint：让每个 rank 写自己的那份

早期的做法是 rank 0 all_gather 全部状态再 torch.save——1 TB 先汇聚到一个节点再由一个进程写，单节点网卡与单进程写吞吐成为瓶颈，而且需要 1 TB 的 host 内存。PyTorch 的 Distributed Checkpoint（DCP）改成每个 rank 只写自己持有的分片：

• torch.distributed.checkpoint.save(state_dict, checkpoint_id=path)（torch/distributed/checkpoint/state_dict_saver.py）：各 rank 调用 planner 生成写计划，ShardedTensor/DTensor 只保存本地分片，由 coordinator rank 去重后各自写文件；
• FileSystemWriter(path, single_file_per_rank=True, sync_files=True, thread_count=1, per_thread_copy_ahead=10_000_000)（filesystem.py）：默认每 rank 一个文件加一个全局 .metadata；thread_count 决定每个 rank 的 I/O 并发，sync_files 决定是否 fsync；
• torch.distributed.checkpoint.state_dict.get_state_dict(model, optimizers, options=StateDictOptions(...)) 把 FSDP/DDP 模型与优化器的状态取成 DCP 能处理的形式。

分片 checkpoint 不改变总量（还是 1 TB），但把写压力从一个进程摊到 64 个进程、从一个节点摊到 8 个节点，让”每 rank 260 MB/s”成为一个每个进程都能轻松做到的数字，瓶颈回到存储系统的聚合吞吐上。它还带来一个平台层的后果：恢复时 rank 数可以变——DCP 按元数据重新分片（resharding.py），16 节点存的 checkpoint 可以用 8 节点恢复。这对第三篇讲的弹性与抢占很重要。

4. 异步 checkpoint：把 1 分钟变成 1 秒

同步写的 1 分钟里 GPU 是空转的。异步 checkpoint 把”写”拆成两步：先把状态从显存拷到 host 内存（stage），训练立刻继续；再由后台线程/进程把 host 内存里的副本写到存储（upload）。

• torch.distributed.checkpoint.async_save(state_dict, checkpoint_id=..., storage_writer=..., async_checkpointer_type=AsyncCheckpointerType.THREAD, async_stager=None)（state_dict_saver.py）：AsyncCheckpointerType 有 THREAD 与 PROCESS 两种；返回一个 Future，或者在提供了支持异步 stage 的 stager 时返回 AsyncSaveResponse（staging_completion 与 upload_completion 两个 future）。
• FileSystemWriter 本身实现了 BlockingAsyncStager（staging.py）：stage 是同步的 D2H 拷贝（可用 pinned memory 加速），upload 在后台。
• DefaultStager(StagingOptions(use_pinned_memory=True, use_shared_memory=True, use_async_staging=True, use_non_blocking_copy=True))：把 stage 也做成异步，训练几乎不停。

两种模式在一个 checkpoint 间隔内的时间线（横轴不按比例）——关键差别是训练在哪个时刻可以继续、存储写占据的是哪一段：

同步模式下存储在 1 分钟里被压满、其余 29 分钟空闲，带宽需求由”停顿能忍多久”决定；异步模式下训练只在 stage 期间停，存储写被摊到整个间隔上，带宽需求由”下一次 checkpoint 之前写得完”决定，但 host 内存里的副本要一直驻留到 upload 结束。于是算术变成：

异步 checkpoint 把存储带宽需求降了一个量级以上，代价是每节点上百 GB 的 host 内存和”最新一份可能还没落盘”的语义。平台要做的是：给训练 Pod 留够 host 内存（resources.requests.memory 要算上这一份）、存储网与 RDMA 网分开（否则后台写会和 all_reduce 抢带宽）、并监控 upload 的完成时间是否一直小于 checkpoint 间隔——一旦超过就会积压。

把同一套算术（14 字节/参数、30 分钟一次、同步要求 1 分钟写完）推到别的规模上，能看出哪一项随什么变化。下面全是推算，不是实测：

三个规律：聚合写带宽只跟状态总量挂钩，与卡数无关——同一个 70B 从 64 卡扩到 1024 卡，存储侧的 16.7 GB/s 一分不少，只是摊到每节点、每 rank 的份额变小了；千卡训练更大的模型时，同步写要的聚合带宽（这里 95 GB/s）对大多数集群配套的并行文件系统都是很高的要求（能否达到以具体部署为准），异步才把它拉回到几 GB/s 的量级——这是”千卡任务默认异步 checkpoint”的算术依据；异步的 host 内存代价随节点数摊薄，反而是小集群跑大模型（第一行）最吃紧：8 卡节点要拿出近 100 GB host 内存放副本。

5. dcp-bench.py：测这两个数字

mini-platform 的 storage/dcp-bench.py 是一个 torchrun 脚本，在指定路径（挂进 Pod 的 PVC）上对同一份人造状态字典分别跑 dcp.save 与 dcp.async_save，报告每次的墙钟时间与聚合吞吐。它是工具，不附带任何结果：

#!/usr/bin/env python3
"""mini-platform/storage/dcp-bench.py — 对比 dcp.save 与 dcp.async_save 的写入耗时。

用法（每个 rank 写 GB_PER_RANK GB 的人造状态，键带 rank 后缀以模拟分片）：
  torchrun --nnodes=$NNODES --nproc_per_node=8 --rdzv_backend=c10d --rdzv_endpoint=$MASTER:29500 \
      dcp-bench.py --path /ckpt/bench --gb-per-rank 4 --threads 4 --rounds 2
输出：每轮 save / async_save 的 stage 时间、总时间、聚合 GB/s（以 rank 0 统计，各 rank 用 barrier 对齐）。
"""
import argparse
import os
import shutil
import time

import torch
import torch.distributed as dist
import torch.distributed.checkpoint as dcp
from torch.distributed.checkpoint import FileSystemWriter


def make_state(gb: float, rank: int, device: torch.device) -> dict:
    # 每个 rank 的键唯一，DCP 不会跨 rank 去重，因此每个 rank 写自己的全部数据（模拟 FSDP/ZeRO 分片）
    n = int(gb * (1 << 30) // 2)  # bf16
    chunks = 8
    per = n // chunks
    return {f"shard_r{rank}_{i}": torch.randn(per, dtype=torch.bfloat16, device=device) for i in range(chunks)}


def barrier_time() -> float:
    dist.barrier()
    return time.perf_counter()


def run_sync(state, path, threads):
    writer = FileSystemWriter(path, thread_count=threads, sync_files=True)
    t0 = barrier_time()
    dcp.save(state, storage_writer=writer)
    t1 = barrier_time()
    return t1 - t0


def run_async(state, path, threads):
    writer = FileSystemWriter(path, thread_count=threads, sync_files=True)
    t0 = barrier_time()
    fut = dcp.async_save(state, storage_writer=writer)
    t_stage = time.perf_counter() - t0  # 训练线程被阻塞的时间（stage）
    # v2.13.0：返回 Future 或 AsyncSaveResponse（有 upload_completion）
    upload = getattr(fut, "upload_completion", fut)
    upload.result()
    t1 = barrier_time()
    return t_stage, t1 - t0


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--path", required=True)
    ap.add_argument("--gb-per-rank", type=float, default=2.0)
    ap.add_argument("--threads", type=int, default=4)
    ap.add_argument("--rounds", type=int, default=2)
    args = ap.parse_args()

    backend = "nccl" if torch.cuda.is_available() else "gloo"
    dist.init_process_group(backend)
    rank, world = dist.get_rank(), dist.get_world_size()
    device = torch.device("cuda", rank % torch.cuda.device_count()) if torch.cuda.is_available() else torch.device("cpu")
    if device.type == "cuda":
        torch.cuda.set_device(device)

    state = make_state(args.gb_per_rank, rank, device)
    total_gb = args.gb_per_rank * world

    def log(msg):
        if rank == 0:
            print(msg, flush=True)

    log(f"world={world} backend={backend} total={total_gb:.1f} GB threads={args.threads} path={args.path}")
    for r in range(args.rounds):
        for mode in ("sync", "async"):
            sub = os.path.join(args.path, f"{mode}-{r}")
            if rank == 0:
                shutil.rmtree(sub, ignore_errors=True)
                os.makedirs(sub, exist_ok=True)
            dist.barrier()
            if mode == "sync":
                t = run_sync(state, sub, args.threads)
                log(f"round {r} sync     total={t:7.2f}s  agg={total_gb / t:6.2f} GB/s")
            else:
                t_stage, t = run_async(state, sub, args.threads)
                log(f"round {r} async    stage={t_stage:6.2f}s  total={t:7.2f}s  agg={total_gb / t:6.2f} GB/s")
    dist.destroy_process_group()


if __name__ == "__main__":
    main()

用它能回答三个问题：这个 PVC 的聚合写吞吐是多少（同步模式的 agg）；异步模式下训练实际被阻塞多久（stage）；线程数（--threads，即 FileSystemWriter.thread_count）和每 rank 数据量怎样影响这两个数字。把 --gb-per-rank 设成真实任务每 rank 的状态大小、--nnodes 设成真实节点数，得到的就是这个集群上这个任务的 checkpoint 时间下界。

九、推理侧的权重分发

1. 问题：扩容时间被 I/O 主导

一个 70B BF16 模型的权重约 140 GB。推理副本扩容时，从对象存储拉到本地、加载进显存，这一步的时间由”读 140 GB 的吞吐”决定：1 GB/s 要两分多钟，200 MB/s 要十几分钟。而扩容往往是并发的——高峰来了要同时起 4 个副本，4 个副本同时读同一份文件，对象存储或文件系统的热点就出现了。第六篇讲扩缩容时会把这一段计入”扩容时间分解”；本篇讨论平台能做什么。

2. 三种方案与 GPUDirect Storage

选择顺序通常是：先用缓存层 + 本地 NVMe（覆盖大多数场景），并发扩容规模大了加 P2P，只有模型固定且节点多才考虑权重进镜像。GDS 解决的是另一个瓶颈——当 NVMe 已经很快而 host 内存拷贝与 CPU 成为限制时，它把存储读直接送进显存；对”从对象存储拉权重”这类受网络限制的场景没有帮助。GDS 是否值得用，看 nvidia-smi 和 top：如果加载权重时 CPU 打满而 NVMe 还有余量，才是它的场景。

十、代价与边界

每个机制都在填一个洞，也都挖了新的：

两条更宏观的边界：

• RDMA 流量绕过 K8s 的网络模型。NetworkPolicy、Service mesh、eBPF 数据面对 verbs 流量一无所知。安全与审计要在 IB 分区（pkey，Network Operator 的 ibKubernetes）、RoCE 的 VLAN、或 SR-IOV + exclusive netns 这一层做，不能指望 K8s 原生对象。
• 存储选型不是 K8s 的问题。CSI 只是接口；带宽、并发、元数据这些属性全在存储系统本身。平台能做的是把三类负载分开、把需求算清楚（第八章）、把缓存放对地方，而不是靠一个 StorageClass 解决所有问题。

十一、本文小结

1. 要点回顾

• 为什么不够
  • 默认 CNI 给 Pod 一张 veth 走 overlay，数据经 host 内存与内核协议栈
  • NCCL 需要三样：/dev/infiniband 设备文件、peermem/DMA-BUF 注册显存、一个 RDMA 侧 IP 做握手
  • 缺任何一项都不报错，只是回落："NET/IB : No device found." → "Using network Socket"
• 第二张网卡
  • Multus（thin 或 thick）当元插件；NetworkAttachmentDefinition（k8s.cni.cncf.io/v1）装 CNI 配置
  • Pod 注解 k8s.v1.cni.cncf.io/networks 引用 NAD；NAD 注解 k8s.v1.cni.cncf.io/resourceName 关联 device plugin；Multus 写回 network-status
  • 四种接入：
    • host-device：整卡/VF 独占
    • macvlan：RoCE 共享
    • ipoib：IB 共享
    • sriov：VF 独占，带 VLAN/MAC
  • Network Operator 的 HostDeviceNetwork / MacvlanNetwork / IPoIBNetwork 生成前三种的 NAD
• 设备进容器
  • rdma-shared-dev-plugin：configList[].resourceName/rdmaHcaMax/selectors → rdma/<name> 资源，Allocate 挂该组网卡全部 uverbs/umad/issm + rdma_cm；要求 netns shared，无隔离、无 GPU 亲和
  • SR-IOV device plugin：一 VF 一 Pod，isRdma 挂 VF 的 RDMA 设备，通常配 exclusive netns
  • 容器要 IPC_LOCK
  • rdma system set netns shared|exclusive 是节点级全局开关
• 两个 Operator
  • NicClusterPolicy（mellanox.com/v1alpha1）：
    • ofedDriver：DOCA-OFED 容器，没有 docaDriver 字段
    • rdmaSharedDevicePlugin / sriovDevicePlugin：config 原样透传
    • secondaryNetwork.{multus,cniPlugins,ipoib}、nvIpam
  • ClusterPolicy 的 spec.driver.rdma.{enabled,useHostMofed} 管 nvidia-peermem sidecar
  • 顺序：OFED 先、GPU 驱动后
  • nvidia_peermem 与 DMA-BUF 二选一即可，NCCL 都能探测
• 验证
  • 顺序：ls /dev/infiniband → ibv_devinfo → rdma link → ip addr → ulimit -l → ib_write_bw → nccl-tests
  • INFO 日志看这几行：
    • NET/IB : Using：数 HCA、看 OOB 接口
    • Using network IB/Socket
    • via NET/IB/N/GDRDMA
    • GPU Direct RDMA Disabled：拓扑问题
• 核心问题
  • Pod 网络：注解、NAD、IPAM、OOB 接口
  • device plugin：未请求、selector、部分网卡、IPC_LOCK、netns 模式
  • NCCL 环境：IB_HCA 名字与 ^= 语义、SOCKET_IFNAME 容器内名字、NET_GDR_LEVEL、RoCE 的 GID_INDEX
• 存储
  • 三类负载：
    • 数据集：小文件随机读，要缓存
    • checkpoint：大块顺序写，要聚合吞吐
    • 权重：一写多读，要并发
  • 并行文件系统给 checkpoint，对象存储 + 缓存层给数据集与权重，本地 NVMe 做缓存与暂存
  • CSI 只是接口
• 算术
  • 70B × 14 B/参数 ≈ 1 TB
  • 30 分钟一次、1 分钟写完 → 16.7 GB/s 聚合、2.1 GB/s 每节点、260 MB/s 每 rank
  • 分片（dcp.save + FileSystemWriter）把压力摊到每个 rank
  • 异步（dcp.async_save）把停顿变成 D2H 拷贝，带宽需求降到 1 TB / 30 min ≈ 0.56 GB/s，代价是每节点 ~125 GB host 内存
• 权重分发
  • 本地 NVMe 缓存（默认）→ P2P（大规模并发扩容）→ 权重进镜像（模型固定）
  • GDS 只在 CPU 成为瓶颈时值得

2. 引擎需求 → K8s 空缺 → 平台机制 → 代价

3. 本篇涉及的源码与 CRD 位置

4. mini-platform 本篇增量：net/ 与 storage/

mini-platform/
├── net/
│   ├── nad-ipoib.yaml               NetworkAttachmentDefinition（k8s.cni.cncf.io/v1）：type ipoib + master + whereabouts IPAM
│   ├── nad-hostdevice.yaml          变体：type host-device + resourceName 注解（需 sriovDevicePlugin）；注释里给出 macvlan 变体
│   ├── rdma-plugin-configmap.yaml   rdma-shared-dev-plugin 的 config.json（configList：resourceName/rdmaHcaMax/selectors）
│   ├── nicclusterpolicy.yaml        第五章的最小 NicClusterPolicy（mellanox.com/v1alpha1）
│   └── nccl-tests-job.yaml          Indexed Job × 2 + headless Service：RDMA 资源请求、networks 注解、IPC_LOCK、NCCL_DEBUG；
│                                    注释给出 hostNetwork/hostIPC 变体（无 RDMA 集群）与 hostPath /dev/infiniband 变体
└── storage/
    ├── juicefs-pvc.yaml             StorageClass（csi.juicefs.com）+ RWX PVC；可替换为任何 RWX CSI
    └── dcp-bench.py                 第八章的 torchrun 脚本：dcp.save vs dcp.async_save 的 stage/总时间/聚合 GB/s

rdma-plugin-configmap.yaml 只在不用 Network Operator、直接部署 device plugin 的 DaemonSet 时需要（deployment/k8s/base/）；用了 NicClusterPolicy 就由 Operator 生成。三步验证的剧本：

1. kubectl apply -f net/nicclusterpolicy.yaml；等 rdma-shared-dp-ds 与 mofed 的 Pod Ready；kubectl describe node <n> | grep rdma/ 看到 Allocatable
2. kubectl apply -f net/nad-ipoib.yaml（RoCE 换 macvlan 变体；SR-IOV 换 nad-hostdevice.yaml）；kubectl apply -f net/nccl-tests-job.yaml；kubectl logs job/nccl-tests -c nccl（index 0）；先找 "NET/IB : Using" 数设备，再找 "Using network"，再找 "GDRDMA"；最后看大消息的 busbw
3. kubectl apply -f storage/juicefs-pvc.yaml；把 PVC 挂到一个 torchrun Job 的 /ckpt；torchrun … dcp-bench.py --path /ckpt/bench --gb-per-rank <真实每 rank 状态 GB>；同步的 agg 与第八章的 16.7 GB/s 比，异步的 stage 与训练 step time 比

到这里，资源层的四篇讲完了：GPU 怎么进容器、任务怎么被调度、卡怎么切、网络和存储怎么喂。下一篇进入交付层：一个 vLLM 进程加一个 Service 只是最简单的推理服务，多节点副本、扩缩容、PD 分离、灰度都要 Serving 平台来补。

一个 TP=4 的 70B 模型服务，晚高峰要从 2 副本扩到 6 副本，每个副本从调度到能接流量要 8 分钟。扩缩容指标选什么、阈值定多少、提前多久触发，才能在高峰到来前就绪而不在平时浪费 16 张卡？

十二、自测

1. NCCL 日志出现 NET/IB : No device found. 然后 Using network Socket，容器里 ls /dev/infiniband 是空的——问题在哪一层？

   答案

   device plugin 层：RDMA 设备没被分配进容器——Pod 没申请 rdma/<name> 资源、或 rdma-shared-dev-plugin 的 selectors 没匹配到网卡、或 rdma system 的 netns 模式与 plugin 要求不符（shared plugin 要 shared）。

2. Multus 的 NAD 上 k8s.v1.cni.cncf.io/resourceName 注解做什么？漏了会怎样？

   答案

   把这个网络附着与 device plugin 的资源名（如 rdma/hca_shared 或 SR-IOV 的 VF 资源）关联，让 Multus 知道给 Pod 的第二张网卡对应哪个已分配的设备；漏了则网卡与 RDMA 设备可能不是同一张，或 VF 分配与网络附着对不上。

3. host-device、macvlan、ipoib、sriov 四种接入各适合什么？各自的代价？

   答案

   host-device：整张网卡或一个 VF 独占进 Pod，性能最好、隔离最好，但一节点能起的 Pod 数受网卡 / VF 数限制；macvlan：多个 Pod 共享一张 RoCE 网卡（各有 MAC），性能好、无隔离；ipoib：IB 网卡上的 IP over IB 共享，最灵活、bootstrap 方便，但只是控制面，数据面仍靠 verbs；sriov：分配一个 VF，CNI 再给它配 VLAN/MAC，一个 VF 一个 Pod，隔离最强、可配 exclusive netns，代价是 VF 配置、固件依赖和 SR-IOV Network Operator 那一套运维面。

4. 容器里 ib_write_bw --use_cuda 报注册显存失败，最可能缺什么？

   答案

   Pod 没有 IPC_LOCK capability（pin 内存被拒）、宿主机没装 nvidia-peermem 或内核不支持 DMA-BUF、或 ulimit -l 太小；这一步不过，GDR 一定关着，NCCL 走主机 staging。

5. GPU 与网卡在容器里被分到了不同 PCIe root complex 下，NCCL 会怎样？日志里怎么看出来？怎么修？

   答案

   NCCL_NET_GDR_LEVEL 默认 PXB，路径超过它 GDR 被关，数据经主机内存中转，带宽打折；日志 GPU Direct RDMA Disabled for HCA ... (distance N > 3)、连接行没有 /GDRDMA。修：让 device plugin 的 GPU 与 RDMA 分配带拓扑亲和（SR-IOV plugin + 节点拓扑、或每 GPU 一个 rdma 资源组），而不是直接放宽 GDR_LEVEL。

• 上一篇
  AI 平台工程（04）：GPU 共享与切分——MIG、时间片、MPS 与 HAMi
• 下一篇
  AI 平台工程（06）：Serving 平台——从 InferenceService 到 llm-d