DGL 多进程模块(dgl.multiprocessing)实战指南:fork 与 OpenMP 兼容包装、共享张量与多 GPU 训练
DGL 多进程模块(dgl.multiprocessing)实战指南:fork 与 OpenMP 兼容包装、共享张量与多 GPU 训练
dgl.multiprocessing 是 DGL 对 Python 原生 multiprocessing 模块做的最小化包装,其核心使命是让进程 fork 与 DGL 核心库中的 OpenMP 并行机制安全共存,从而为多 GPU 训练铺平道路。本文以 docs/source/api/python/dgl.multiprocessing.rst 为骨架,结合仓库源码与官方多 GPU 示例,讲解该模块的设计动机、后端自适应机制、PyTorch 后端专属的共享张量 API(call_once_and_share / shared_tensor),以及它们在真实训练代码中的落地方式。读完本文,你将掌握如何在 DGL 多 GPU 训练中安全使用 fork 启动子进程、如何在进程组内共享只写一次的张量,并理解其底层共享内存机制。
一、模块定位:一个"零成本"的 multiprocessing 兼容层
根据 API 文档,dgl.multiprocessing 是 Python 原生 multiprocessing 的最小化包装(minimal wrapper),文档明确了两点关键事实:
- 它修改了
multiprocessing.Process类,使得 fork 能在 DGL 核心库的 OpenMP 环境下正常工作; - 由于 API 用法与原生模块完全一致,DGL 不提供额外的 API 文档——原生
multiprocessing的文档就是它的使用说明书。
如果你使用 PyTorch 作为后端,该模块还会与 torch.multiprocessing 兼容,因此 Process、Queue、spawn 等用法与你在 PyTorch 生态中习惯的完全一致。
这个设计背后的工程动机,在 python/dgl/multiprocessing/init.py 的模块注释中有直接说明:
- 为了避免在多 GPU 训练中为每个子进程重复复制整张图结构,DGL 推荐使用
fork()而非spawn()来启动子进程(fork 的写时复制机制让子进程几乎零成本地继承父进程内存中的图); - 但直接使用 fork 时,OpenMP 的线程池与 fork 存在兼容性问题(与 PyTorch 社区已知的 fork/OpenMP 死锁问题同类),因此必须通过包装来规避。
# python/dgl/multiprocessing/__init__.py(节选)
# To avoid duplicating the graph structure for node classification or link prediction
# training we recommend using fork() rather than spawn() for multiple GPU training.
# However, we need to work around ... to make fork() and openmp work together.
from .. import backend as F
if F.get_preferred_backend() == "pytorch":
# Wrap around torch.multiprocessing...
from torch.multiprocessing import *
# ... and override the Process initializer.
from .pytorch import *
else:
# Just import multiprocessing module.
from multiprocessing import * # pylint: disable=redefined-builtin
从源码结构可以清晰看到该模块的两条分支策略:
| 后端 | 行为 | 依据 |
|---|---|---|
| PyTorch | 转发到 torch.multiprocessing,并用 python/dgl/multiprocessing/pytorch.py 中重写的 Process 覆盖默认初始化器 |
__init__.py 中 F.get_preferred_backend() == "pytorch" 分支 |
| 其他后端(如 MXNet、TensorFlow) | 直接透传标准库 multiprocessing,不加修改 |
else 分支 |
这种"按需覆盖"的设计保证了:无论后端如何,用户都只需 from dgl import multiprocessing,就能获得与原生模块一致的 API,同时自动获得 OpenMP 兼容性。
二、核心机制:thread_wrapped_func 与重写的 Process
DGL 解决 fork/OpenMP 兼容问题的关键,是 python/dgl/multiprocessing/pytorch.py 中的 thread_wrapped_func 装饰器:
def thread_wrapped_func(func):
"""
Wraps a process entry point to make it work with OpenMP.
"""
@wraps(func)
def decorated_function(*args, **kwargs):
queue = mp.Queue()
def _queue_result():
exception, trace, res = None, None, None
try:
res = func(*args, **kwargs)
except Exception as e: # pylint: disable=broad-except
exception = e
trace = traceback.format_exc()
queue.put((res, exception, trace))
start_new_thread(_queue_result, ())
result, exception, trace = queue.get()
if exception is None:
return result
else:
assert isinstance(exception, Exception)
raise exception.__class__(trace)
return decorated_function
它的工作原理是:把进程入口函数放到一个新线程里执行,通过 mp.Queue 把(结果、异常、完整回溯)传回主线程。这样即使 OpenMP 内部状态在新进程中有问题,目标函数也运行在一个干净的线程上下文中,从而规避 fork 后 OpenMP 线程池与父进程锁状态不一致导致的死锁。同时,异常信息会被保留并重新抛回,便于调试。
随后,重写的 Process 类在初始化时用 thread_wrapped_func 包装 target:
class Process(mp.Process):
def __init__(self, group=None, target=None, name=None,
args=(), kwargs={}, *, daemon=None):
target = thread_wrapped_func(target)
super().__init__(group, target, name, args, kwargs, daemon=daemon)
可以看到,Process 的签名与 torch.multiprocessing.Process 完全一致(group、target、name、args、kwargs、daemon),这保证了用户无需学习任何新 API。实际使用中,官方示例正是以 dgl.multiprocessing as dmp 的方式引用它,例如 examples/pytorch/argo/argo.py 中的 dmp.Process(...)。
三、PyTorch 专属 API:在进程组内共享张量
除了兼容层,dgl.multiprocessing.pytorch 还提供了两个对多 GPU 训练非常有用的增强 API(对应文档中 autosummary 列出的两个符号):
3.1 shared_tensor(shape, dtype=torch.float32)
在同一个 torch.distributed 进程组内的所有进程之间创建一个共享内存张量,内容未初始化:
def shared_tensor(shape, dtype=torch.float32):
"""Create a tensor in shared memory accessible by all processes within the same
``torch.distributed`` process group.
The content is uninitialized.
"""
return call_once_and_share(
lambda: torch.empty(*shape, dtype=dtype), shape, dtype
)
它本质上是 call_once_and_share 的一个便捷封装,底层用 torch.empty 分配未初始化内存。适用于"所有进程共写一个大张量的不同区域"的场景,例如逐层推理时各 GPU 分别写各自的输出节点行。
3.2 call_once_and_share(func, shape, dtype, rank=0)
在进程组内仅让一个进程执行函数,然后把结果共享给所有进程。参数含义如下(来自源码 docstring):
| 参数 | 类型 | 说明 |
|---|---|---|
func |
callable | 任意不接受参数、返回任意对象的可调用对象 |
shape |
tuple[int] | 共享张量的形状,必须与 func 的输出匹配 |
dtype |
torch.dtype | 共享张量的数据类型,必须与 func 的输出匹配 |
rank |
int, 可选 | 实际执行函数的那一个进程 ID,默认 0 |
其执行流程可以概括为四步:
current_rank = torch.distributed.get_rank()
dist_buf = torch.LongTensor([1])
if torch.distributed.get_backend() == "nccl":
dist_buf = dist_buf.cuda() # NCCL 后端下把广播缓冲放到对应设备
# 1. 只有 rank 指定的进程创建共享内存并写入结果
if current_rank == rank:
random_ = random.Random()
id_ = random_.getrandbits(32)
name = _get_shared_mem_name(id_)
result = create_shared_mem_array(name, shape, dtype)
result[:] = func()
dist_buf[0] = id_
# 2. 通过 torch.distributed.broadcast 把共享内存名称广播给其他进程
torch.distributed.broadcast(dist_buf, rank)
# 3. 其余进程打开同一个共享内存对象
if current_rank != rank:
id_ = dist_buf.item()
name = _get_shared_mem_name(id_)
result = get_shared_mem_array(name, shape, dtype)
return result
实现细节值得注意:
- NCCL 兼容:当进程组后端是
nccl时,广播缓冲会被.cuda()转移到正确设备(源码注释提醒,PyTorch 建议在torch.multiprocessing.spawn()进入后先调用set_device()); - 随机共享内存名:共享内存的命名采用 32 位随机数,来源注释指出这是为了应对 PyTorch Lightning 1.6+ 在 spawn 子进程时设置相同随机种子的问题;
- 零拷贝:其他进程通过名称打开同一块共享内存,不复制数据。
四、底层支撑:create_shared_mem_array 与 get_shared_mem_array
call_once_and_share 依赖的两个底层工具位于 python/dgl/ndarray.py:
create_shared_mem_array(name, shape, dtype):以指定名称创建共享内存张量;get_shared_mem_array(name, shape, dtype):以指定名称获取已有的共享内存张量。
两者都通过 empty_shared_mem 申请共享内存,再用 DLPack 的 zerocopy_from_dlpack 零拷贝地转换成后端张量:
# python/dgl/ndarray.py(节选)
def get_shared_mem_array(name, shape, dtype):
new_arr = empty_shared_mem(name, False, shape, F.reverse_data_type_dict[dtype])
dlpack = new_arr.to_dlpack()
return F.zerocopy_from_dlpack(dlpack)
def create_shared_mem_array(name, shape, dtype):
new_arr = empty_shared_mem(name, True, shape, F.reverse_data_type_dict[dtype])
dlpack = new_arr.to_dlpack()
return F.zerocopy_from_dlpack(dlpack)
另外,python/dgl/utils/shared_mem.py 是一个兼容性转发模块:为兼容旧代码中 dgl.utils.shared_mem 的命名空间,其内容已迁移到 dgl.ndarray,旧路径直接 re-export 这两个函数。
这套共享内存机制不止服务于 dgl.multiprocessing,同样被 DGL 的稀疏嵌入与分布式优化器复用,例如 python/dgl/nn/pytorch/sparse_emb.py(共享嵌入表)和 python/dgl/optim/pytorch/sparse_optim.py(共享优化器状态、梯度缓冲),从侧面印证了该基础设施的通用性。
五、实战:多 GPU 节点分类中的 shared_tensor 用法
理解理论后,看官方多 GPU 示例 examples/multigpu/node_classification_sage.py(以及 examples/pytorch/multigpu/multi_gpu_node_classification.py)是如何组合这些能力的。
5.1 启动与资源配额
主进程解析 GPU 列表后,用 torch.multiprocessing 的 mp.spawn 启动 nprocs 个子进程,并提前做好两件事:
# 显式创建图格式,避免每个子进程重复创建造成内存浪费
g.create_formats_()
# 线程限制,避免资源竞争
os.environ["OMP_NUM_THREADS"] = str(mp.cpu_count() // 2 // nprocs)
mp.spawn(run, args=(nprocs, devices, g, data, args), nprocs=nprocs)
g.create_formats_()在 fork 之前就把图所需的格式构建好,子进程通过写时复制直接继承,这正是文档强调的"避免复制图结构"的落地实践;- 设置
OMP_NUM_THREADS为cpu_count // 2 // nprocs,防止多个进程的 OpenMP 线程互相争抢 CPU 资源。
5.2 进程初始化与 DDP
每个子进程的入口 run 中,先绑定设备、初始化进程组、构建 DDP 模型:
device = devices[proc_id]
torch.cuda.set_device(device)
dist.init_process_group(
backend="nccl", init_method="tcp://127.0.0.1:12345",
world_size=nprocs, rank=proc_id,
)
model = SAGE(in_size, 256, num_classes).to(device)
model = DistributedDataParallel(model, device_ids=[device], output_device=device)
5.3 逐层推理中的共享输出张量
shared_tensor 最典型的使用场景是逐层推理(layer-wise inference):为了不把整张图塞进 GPU 显存,各进程把当前层的输出写到宿主内存(host memory)的共享张量中,再进入下一层。示例中的关键代码:
# 为避免 GPU 显存耗尽,在宿主内存中分配共享输出张量 y
y = shared_tensor(
(g.num_nodes(),
self.hid_size if l != len(self.layers) - 1 else self.out_size)
)
for input_nodes, output_nodes, blocks in dataloader:
x = blocks[0].srcdata["h"]
h = layer(blocks[0], x)
if l != len(self.layers) - 1:
h = F.relu(h); h = self.dropout(h)
# non_blocking(配合 pinned memory)加速数据传输
y[output_nodes] = h.to(y.device, non_blocking=True)
# 用 barrier 确保所有 GPU 都写完 y
dist.barrier()
g.ndata["h"] = y if use_uva else y.to(device)
这里的编程模式完全吻合 call_once_and_share 的设计意图:
- 每个进程调用
shared_tensor得到同一个共享内存张量(只有 rank 0 真正分配并写入一次空张量,其余进程按广播来的名字打开同一块内存); - 各进程只写属于自己的
output_nodes行,互不冲突; dist.barrier()保证所有进程写完后再读取,避免数据竞争;- 配合
non_blocking=True的拷贝与use_uva(统一虚拟寻址)选项,进一步优化 CPU-GPU 数据搬运。
5.4 训练阶段的分布式规约
训练循环中虽然不直接用 shared_tensor,但依赖 torch.distributed.reduce 把各进程的验证精度归约到 rank 0(示例注释中明确说明默认使用 ReduceOp.SUM,除以 nprocs 取平均),这展示了 DGL 多 GPU 场景下"共享内存 + 分布式集合通信"的组合拳。
六、使用建议与注意事项
综合文档与源码,使用 dgl.multiprocessing 时有几点值得注意:
- API 完全对齐原生模块:无需学习新接口,
Process、Queue、spawn等用法与multiprocessing/torch.multiprocessing相同;本文档亦不重复原生文档。 - 后端决定行为:PyTorch 后端会获得
thread_wrapped_func包装和共享张量增强;其他后端则原样透传标准库multiprocessing。 - 共享张量内容未初始化:
shared_tensor返回的张量内容是随机的,使用前必须写入(例如示例中逐批填充output_nodes行),并通过dist.barrier()等同步手段保证读写次序。 call_once_and_share的 shape/dtype 必须与func输出严格一致,否则共享内存张量的解释会出现问题;rank参数用于指定"谁执行",默认 0。- fork 前做好准备:在
mp.spawn之前显式g.create_formats_()、合理设置OMP_NUM_THREADS,可避免子进程重复构建图格式与 OpenMP 线程竞争。 - 底层共享内存工具通用:
create_shared_mem_array/get_shared_mem_array位于 python/dgl/ndarray.py,同时支撑稀疏嵌入(python/dgl/nn/pytorch/sparse_emb.py)与稀疏优化器(python/dgl/optim/pytorch/sparse_optim.py),如果你要实现自定义的跨进程张量共享,可直接复用这两组 API。
总而言之,dgl.multiprocessing 以极小的 API 面解决了多 GPU 训练中最棘手的进程安全与数据共享问题:向上保持与标准库完全一致的用法,向下通过 thread_wrapped_func 化解 fork/OpenMP 冲突,再以 shared_tensor 与 call_once_and_share 提供进程组内零拷贝共享张量的能力——配合官方多 GPU 示例(examples/multigpu/node_classification_sage.py、examples/pytorch/multigpu/multi_gpu_link_prediction.py),你可以直接将其移植到自己的分布式训练代码中。