NCCL4Py 框架互操作指南:用 CuPy 与 PyTorch 零拷贝接入 NCCL 托管内存
NCCL4Py 框架互操作指南:用 CuPy 与 PyTorch 零拷贝接入 NCCL 托管内存
NCCL4Py 是 NCCL(NVIDIA Collective Communications Library)的 Python 绑定,其 nccl.core.interop 子模块为 CuPy 数组与 PyTorch 张量提供了与 NCCL 内存管理无缝对接的能力:通过 empty 分配由 NCCL 内存分配器(而非框架自身分配器)托管的设备内存,再通过 resolve_array / resolve_tensor 把框架对象翻译成 NCCL 期望的 (ptr, count, dtype, device_id) 缓冲描述符。本文以官方文档 docs/userguide/source/nccl4py/interop.rst 为骨架,结合源码实现讲解 API 用法、dtype 映射规则、底层零拷贝原理与典型集成场景。读完本文,你将能够直接用熟悉的 PyTorch / CuPy 对象编写 NCCL 分布式通信代码,并理解其与 mem_alloc、缓冲注册(register_buffer / register_window)的关系。
一、互操作模块的定位与懒加载机制
互操作模块解决的核心问题是:NCCL 的 C 接口只认识裸设备指针、元素个数、数据类型与设备号,而 Python 开发者习惯使用 CuPy 数组或 PyTorch 张量。interop 子模块在两者之间架起桥梁:
- 分配侧:
empty创建由 NCCL 内存分配器托管的数组/张量,内存由 NCCL 优化管理(例如配合零拷贝注册获得更低延迟、更高带宽),而非由 CuPy/PyTorch 的默认分配器管理; - 解析侧:
resolve_array/resolve_tensor把框架对象解析为 NCCL 操作所需的元组,供Communicator的各类集合通信调用使用。
模块设计上刻意保持“按需加载”。根据 docs/userguide/source/nccl4py/interop.rst 的说明,两个子模块通过 nccl.core.cupy 与 nccl.core.torch 在首次属性访问时才被导入。实现位于 bindings/nccl4py/nccl/core/init.py 的 __getattr__:
def __getattr__(name):
"""Lazy-loads interop submodules on first access to avoid importing cupy/torch unless needed."""
if name == "cupy":
import nccl.core.interop.cupy
return nccl.core.interop.cupy
elif name == "torch":
import nccl.core.interop.torch
return nccl.core.interop.torch
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
nccl.core 的 __all__ 中声明了 "cupy"、"torch" 两个公开符号(bindings/nccl4py/nccl/core/init.py),并注释说明它们属于“lazy-loaded”互操作模块。这意味着:只要你的环境里没有安装 CuPy 或 PyTorch,NCCL4Py 的其余 API 依然可以正常使用,只有真正访问 nccl.core.cupy / nccl.core.torch 时才触发对应依赖导入。这一点在模块内部也有双重保险:cupy.py 与 torch.py 都用 try: import ... except ImportError 记录 _cupy_enabled / _torch_enabled 标志,未安装对应框架时调用其 API 会抛出 ModuleNotFoundError,而不是在 import 阶段崩溃。
二、CuPy 互操作:empty 与 resolve_array
CuPy 互操作模块位于 bindings/nccl4py/nccl/core/interop/cupy.py,公开两个函数:empty 与 resolve_array。
2.1 nccl.core.cupy.empty:分配 NCCL 托管的 CuPy 数组
def empty(
shape: int | tuple[int, ...],
dtype: str | np.dtype | cupy.dtype | type = float,
order: Literal["C", "F"] = "C",
) -> cupy.ndarray:
参数与行为要点:
shape:数组形状。传入单个int时会被包装为单元素形状(n,);传入元组则直接使用。dtype:数据类型,默认float(即float64)。可以是 dtype 字符串(如'int64')、NumPy dtype、CuPy dtype 或 Python 类型对象,内部统一经np.dtype(dtype)归一化。order:内存布局,仅支持'C'(行主序)与'F'(列主序)。传入其他值会抛出NcclInvalid,提示 NCCL 数组只支持这两种布局。
该函数与 cupy.empty 的差别在于底层内存来源。源码中的分配路径是:
size = int(np.prod(shape) * dtype.itemsize)
# Allocate buffer on current device (CuPy manages device context)
buf = mem_alloc(size)
# Important! Disable copy to force allocation to stay in NCCL memory
cupy_array = cupy.from_dlpack(buf, copy=False)
return cupy_array.view(dtype).reshape(shape, order=order)
关键点有两个:
mem_alloc(来自 bindings/nccl4py/nccl/core/buffer.py)经由NcclMemoryResource(bindings/nccl4py/nccl/core/memory.py)调用底层ncclMemAlloc,返回一个cuda.core.Buffer;cupy.from_dlpack(buf, copy=False)以 DLPack 协议零拷贝方式把该 Buffer 包装成 CuPy 数组。copy=False是刻意设置的,注释明确说明要“force allocation to stay in NCCL memory”——避免任何隐式拷贝导致数据落入 CuPy 自己的分配器。最后view(dtype)与reshape(shape, order=order)只是调整视图,不会复制数据。
内存的释放由引用计数自动完成:数组被垃圾回收时底层 Buffer 随之释放,无需显式调用 mem_free(mem_free 仍是可选手段,见 docs/userguide/source/nccl4py/memory.rst)。官方文档还建议:若要进一步做零拷贝优化,可将数组通过 Communicator.register_buffer 或 Communicator.register_window 注册(详见 docs/userguide/source/nccl4py/communicator/registration.rst)。
2.2 nccl.core.cupy.resolve_array:解析 CuPy 数组
def resolve_array(array: cupy.ndarray) -> tuple[int, int, NcclDataType, int]:
返回四元组 (ptr, count, dtype, device_id):
ptr:设备指针地址,取自array.data.ptr;count:元素个数,取自array.size;dtype:NcclDataType枚举成员,由 CuPy/NumPy dtype 转换而来;device_id:CUDA 设备号,取自array.device.id。
该函数只接受真正的 CuPy ndarray,传入其他类型会抛出 NcclInvalid,错误信息形如 "array must be a CuPy array, got ..."。
2.3 CuPy 的 dtype 映射规则
dtype 转换由内部函数 _to_nccl_dtype 完成:CuPy 的 dtype 本质是 NumPy dtype 对象,因此先 np.dtype(cupy_dtype) 归一化,再委托给 NcclDataType.from_numpy_dtype(定义于 bindings/nccl4py/nccl/core/typing.py)。两条特殊规则:
bool没有 NCCL 对应类型,统一映射为UINT8(按自然字节宽度处理);- 标准类型按
(kind, itemsize)匹配,例如('f', 4) → FLOAT32、('i', 8) → INT64;bfloat16、float8_e4m3fn、float8_e5m2等 ml-dtypes 类型则先按名字精确匹配。
若 dtype 没有 NCCL 等价类型(如复数、int16、uint16、结构化类型、datetime、字符串),抛出 NcclInvalid。
三、PyTorch 互操作:empty 与 resolve_tensor
PyTorch 互操作模块位于 bindings/nccl4py/nccl/core/interop/torch.py,公开 empty 与 resolve_tensor。
3.1 nccl.core.torch.empty:分配 NCCL 托管的 PyTorch 张量
def empty(
*size,
dtype: torch.dtype | None = None,
device: torch.device | int | str | None = None,
morder: Literal["C", "F"] = "C",
) -> torch.Tensor:
参数要点:
-
*size:形状。既支持empty(4, 8)的可变参数形式,也支持empty((4, 8))的元组/列表形式,内部自动归一化。 -
dtype:默认None,此时使用torch.get_default_dtype(),行为与torch.empty一致。 -
device:目标设备,默认None(当前 CUDA 设备)。由_parse_device统一处理四种情况:None→torch.cuda.current_device();torch.device对象 → 必须是cuda类型,index为None时回退到当前设备;- 字符串(如
'cuda:1')→ 先转torch.device再按上述规则校验; - 整数 → 直接作为设备号使用。
非 CUDA 设备(如
'cpu'、'meta')会抛出NcclInvalid,错误信息为"NCCL tensors must be on CUDA device, got ..."。 -
morder:内存布局,仅'C'/'F'两种取值,默认'C'。'F'时通过as_strided手工构造列主序 strides:对形状(d0, d1, ..., dn-1),strides 依次为1, d0, d0*d1, ...。
分配路径与 CuPy 版本同构:
itemsize = torch.tensor([], dtype=dtype).element_size()
size_bytes = int(np.prod(shape) * itemsize)
# Allocate buffer on the specified device
buf = mem_alloc(size_bytes, device=device)
torch_tensor = torch.from_dlpack(buf)
view = torch_tensor.view(dtype).view(shape)
mem_alloc 支持 device 参数(bindings/nccl4py/nccl/core/buffer.py 中 mem_alloc(size, device) 会先切到目标设备上下文再分配),随后同样通过 DLPack 零拷贝包装为 PyTorch 张量。与 CuPy 版相同:内存随张量垃圾回收自动释放,无需显式 mem_free;若需要零拷贝通信,可把张量交给 Communicator.register_buffer / register_window。
3.2 nccl.core.torch.resolve_tensor:解析 PyTorch 张量
def resolve_tensor(tensor: torch.Tensor) -> tuple[int, int, NcclDataType, int]:
返回 (ptr, count, dtype, device_id):
ptr:tensor.data_ptr();count:tensor.numel()(注意是元素个数而非字节数);dtype:NcclDataType成员;device_id:tensor.device.index。
只接受 torch.Tensor,否则抛出 NcclInvalid。源码注释特别提醒:需要控制元素个数时,应通过切片获得想要的张量视图再传入,因为 numel 会取整个视图的元素数。
3.3 PyTorch 的 dtype 映射表与版本约束
_to_nccl_dtype 维护了一张显式映射表,基础映射如下:
| torch dtype | NCCL 类型 |
|---|---|
torch.float16 |
FLOAT16 |
torch.float32 |
FLOAT32 |
torch.float64 |
FLOAT64 |
torch.bfloat16 |
BFLOAT16 |
torch.int8 |
INT8 |
torch.int32 |
INT32 |
torch.int64 |
INT64 |
torch.uint8 |
UINT8 |
torch.bool |
UINT8(NCCL 无 bool,按其自然字节宽度映射) |
源码还通过 hasattr 做了版本条件式扩展(从代码注释可以确认的兼容性边界):
- PyTorch 2.1+:
torch.float8_e4m3fn → FLOAT8E4M3、torch.float8_e5m2 → FLOAT8E5M2; - PyTorch 2.3+:
torch.uint32 → UINT32、torch.uint64 → UINT64。
查表失败(复数、int16/short、量化类型)会抛出 NcclInvalid,错误信息明确说明:“NCCL does not support complex, int16, or quantized types”。注意 NCCL 侧 FLOAT8E4M3 / FLOAT8E5M2 需要 CUDA ≥ 11.8 且 SM ≥ 90(见 bindings/nccl4py/nccl/core/typing.py 中 NcclDataType 的成员文档)。
四、底层原理:从 mem_alloc 到 DLPack 零拷贝
两个 empty 的实现殊途同归,都建立在两条基础设施之上:
-
NCCL 内存分配器。
mem_alloc(size, device)(bindings/nccl4py/nccl/core/buffer.py)内部调用get_memory_resource(device_id).allocate(size)。get_memory_resource返回线程本地、按设备缓存的NcclMemoryResource(bindings/nccl4py/nccl/core/memory.py),其allocate在CudaDeviceContext保护下调用底层绑定ncclMemAlloc,返回cuda.core.Buffer。文档(docs/userguide/source/nccl4py/memory.rst)同时说明:NCCL 优化可能导致实际分配大小大于请求字节数(对齐粒度),显式mem_free可选、GC 自动释放兜底。 -
DLPack 协议。
cuda.core.Buffer实现了 DLPack 导出,cupy.from_dlpack/torch.from_dlpack直接复用其底层指针,不产生任何数据拷贝,这正是“零拷贝集成”的技术核心。
可以推断,这类由 NCCL 分配器托管的内存对 NCCL 自身的缓冲注册(ncclCommRegister / ncclCommWindowRegister,对应 bindings/nccl4py/nccl/core/communicator.py 的 register_buffer / register_window)最为友好,因为 NCCL 可以识别并利用这些内存的分配来源,从而启用零拷贝传输路径。官方文档(docs/userguide/source/nccl4py/interop.rst 与两个模块的 docstring)也正是这样建议的:分配后接 register_buffer(非集合调用,单 rank 注册)或 register_window(集合调用,所有 rank 必须参与且默认要求各 rank 缓冲等大)。
五、在 NCCL4Py 内部的解析集成:NcclBuffer
理解 resolve_* 的另一个重要视角是看它们如何被核心层消费。NcclBuffer(bindings/nccl4py/nccl/core/buffer.py)在把任意缓冲对象解析成 (ptr, count, dtype, device_id) 时,优先尝试 PyTorch、再尝试 CuPy:
try:
from nccl.core.interop.torch import resolve_tensor
resolved = resolve_tensor(buffer)
except (ImportError, ModuleNotFoundError, NcclInvalid):
pass
if resolved is None:
try:
from nccl.core.interop.cupy import resolve_array
resolved = resolve_array(buffer)
except (ImportError, ModuleNotFoundError, NcclInvalid):
pass
if resolved is not None:
...
else:
view = _resolve_buffer(buffer, self.stream_ptr) # 通用 CAI/DLPack 回退
这意味着:任何 PyTorch 张量或 CuPy 数组都可以直接作为 Communicator 集合通信(如 allreduce、reduce、scatter 等)的缓冲参数,无需手动调用 resolve_*。NcclBuffer 内部会完成解析与校验;只有当两者都不匹配时,才走通用的 StridedMemoryView 路径(接受任何实现 CUDA Array Interface 或 DLPack 的对象)。
同样的策略也出现在 NCCL EP 层:nccl.ep.Tensor 的 _resolve_buffer(bindings/nccl4py/nccl/ep/tensor.py)对 torch.Tensor 优先调用 resolve_tensor,否则回退到 CAI/DLPack 视图。可以推断,resolve_tensor/resolve_array 是整个 NCCL4Py 生态里“框架对象 → NCCL 描述符”的统一入口,核心层与 EP 层都复用了它。
六、实战示例
6.1 PyTorch:经典 AllReduce(来自仓库示例)
仓库自带的 bindings/nccl4py/examples/01_basic/01_allreduce.py 演示了最直接的用法——普通 torch.tensor(而非 interop.empty)直接传入集合通信:
import torch
import nccl.core as nccl
device = torch.device(f"cuda:{rank % torch.cuda.device_count()}")
torch.cuda.set_device(device)
unique_id = nccl.get_unique_id() if rank == root else None
unique_id = comm_mpi.bcast(unique_id, root=root)
nccl_comm = nccl.Communicator.init(nranks=nranks, rank=rank, unique_id=unique_id)
data = torch.tensor([float(rank)], dtype=torch.float32, device=device)
# [NCCL4Py] AllReduce: Sum all rank values
nccl_comm.reduce(data, data, nccl.SUM)
torch.cuda.synchronize()
运行方式为 mpirun -np 4 python 01_allreduce.py。这里 data 虽是 PyTorch 分配的内存,NcclBuffer 也会经由 resolve_tensor 正确解析其指针、个数、dtype 与设备号。
6.2 CuPy + 窗口注册:GIN 设备端 PUT(来自仓库示例)
bindings/nccl4py/examples/cute/main.py 展示了 nccl.core.cupy.empty 与 register_window 的配合:
send_buf = nccl.cupy.empty(NUM_ELEMS, dtype='int64')
recv_buf = nccl.cupy.empty(NUM_ELEMS, dtype='int64')
# ... 填充数据、device.sync() ...
send_win = nccl_comm.register_window(send_buf)
recv_win = nccl_comm.register_window(recv_buf)
assert send_win is not None and send_win.is_valid
assert recv_win is not None and recv_win.is_valid
reqs = nccl.NCCLDevCommRequirements(
gin_connection_type=nccl.NcclGinConnectionType.FULL,
gin_signal_count=SIGNAL_ID + 1,
)
dev_comm = nccl_comm.create_dev_comm(requirements=reqs)
test_nccl_put(dev_comm.ptr, send_win.handle, recv_win.handle)
流程要点:用 nccl.cupy.empty 分配 NCCL 托管内存 → 填充数据并 device.sync() 让主机侧写入对内核可见 → 两 rank 共同调用集合性质的 register_window 获得窗口句柄 → 创建设备端通信句柄(create_dev_comm)后,在设备内核里通过 GIN 直接发起 PUT,实现 GPU 线程直达的远程写入。
6.3 手动解析缓冲
如果需要亲自拿到描述符(例如自定义封装),可以直接调用:
import nccl.core as nccl
arr = nccl.cupy.empty((1024,), dtype='float32')
ptr, count, dtype, dev = nccl.cupy.resolve_array(arr)
# ptr: 设备指针; count: 1024; dtype: NcclDataType.FLOAT32; dev: 当前设备号
t = nccl.torch.empty(1024, 1024, dtype=torch.float32, device='cuda:0', morder='F')
ptr, count, dtype, dev = nccl.torch.resolve_tensor(t)
七、常见错误与使用边界
结合源码可归纳出以下几类高频错误,均以 NcclInvalid 或 ModuleNotFoundError 抛出:
- 未安装对应框架:
CuPy is not installed/PyTorch is not installed。模块使用懒加载,未安装时访问nccl.core.cupy.empty等函数才报错。 - 类型不匹配:
resolve_array只接受cupy.ndarray,resolve_tensor只接受torch.Tensor,传入 numpy 数组或其他对象会抛出NcclInvalid。 - dtype 无 NCCL 等价:复数、
int16/short、uint16、量化类型、结构化/字符串类型均不支持;bool被特殊映射为UINT8。 - 非法内存布局:
order/morder只接受'C'与'F'。 - 非 CUDA 设备:PyTorch 版
empty的device必须解析到 CUDA 设备,'cpu'等会被拒绝。
版本相关边界(从 bindings/nccl4py/nccl/core/interop/torch.py 源码可确认):float8 类型要求 PyTorch 2.1+,uint32/uint64 要求 PyTorch 2.3+;NCCL 侧 float8 还需要 CUDA ≥ 11.8 且 SM ≥ 90(bindings/nccl4py/nccl/core/typing.py)。
八、延伸阅读
- 内存分配与释放:
mem_alloc/mem_free详见 docs/userguide/source/nccl4py/memory.rst 与实现 bindings/nccl4py/nccl/core/buffer.py; - 数据类型与常量:
NcclDataType完整枚举及转换逻辑见 docs/userguide/source/nccl4py/types.rst 与 bindings/nccl4py/nccl/core/typing.py; - 零拷贝注册:
register_buffer/register_window及WindowFlag见 docs/userguide/source/nccl4py/communicator/registration.rst; - NCCL 内存分配器背景:C 层语义可参考 docs/userguide/source/usage/bufferreg.rst 中关于
ncclMemAlloc与 VMM 分配器的说明。