DGL 多进程模块(dgl.multiprocessing)实战指南:fork 与 OpenMP 兼容包装、共享张量与多 GPU 训练

原创2026-09-21 12:13:291,421 阅读
文章标签:深度学习机器学习人工智能图计算分布式训练高性能计算数据科学

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),文档明确了两点关键事实:

  1. 它修改了 multiprocessing.Process 类,使得 fork 能在 DGL 核心库的 OpenMP 环境下正常工作;
  2. 由于 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 的设计意图:

  1. 每个进程调用 shared_tensor 得到同一个共享内存张量(只有 rank 0 真正分配并写入一次空张量,其余进程按广播来的名字打开同一块内存);
  2. 各进程只写属于自己的 output_nodes 行,互不冲突;
  3. dist.barrier() 保证所有进程写完后再读取,避免数据竞争;
  4. 配合 non_blocking=True 的拷贝与 use_uva(统一虚拟寻址)选项,进一步优化 CPU-GPU 数据搬运。

5.4 训练阶段的分布式规约

训练循环中虽然不直接用 shared_tensor,但依赖 torch.distributed.reduce 把各进程的验证精度归约到 rank 0(示例注释中明确说明默认使用 ReduceOp.SUM,除以 nprocs 取平均),这展示了 DGL 多 GPU 场景下"共享内存 + 分布式集合通信"的组合拳。

六、使用建议与注意事项

综合文档与源码,使用 dgl.multiprocessing 时有几点值得注意:

  1. API 完全对齐原生模块:无需学习新接口,Process、Queue、spawn 等用法与 multiprocessing / torch.multiprocessing 相同;本文档亦不重复原生文档。
  2. 后端决定行为:PyTorch 后端会获得 thread_wrapped_func 包装和共享张量增强;其他后端则原样透传标准库 multiprocessing。
  3. 共享张量内容未初始化:shared_tensor 返回的张量内容是随机的,使用前必须写入(例如示例中逐批填充 output_nodes 行),并通过 dist.barrier() 等同步手段保证读写次序。
  4. call_once_and_share 的 shape/dtype 必须与 func 输出严格一致,否则共享内存张量的解释会出现问题;rank 参数用于指定"谁执行",默认 0。
  5. fork 前做好准备:在 mp.spawn 之前显式 g.create_formats_()、合理设置 OMP_NUM_THREADS,可避免子进程重复构建图格式与 OpenMP 线程竞争。
  6. 底层共享内存工具通用: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),你可以直接将其移植到自己的分布式训练代码中。

登录后查看全文
dgl