DGL 分布式 RGCN 节点分类实战:从 NFS 集群搭建、图分区到 DGL/GraphBolt 训练对比
DGL 分布式 RGCN 节点分类实战:从 NFS 集群搭建、图分区到 DGL/GraphBolt 训练对比
DGL 官方在 examples/distributed/rgcn 目录下提供了一个完整的分布式 RGCN(Relational Graph Convolutional Network)节点分类示例,支持在多机多卡集群上对 ogbn-mag 等异构图进行邻居采样训练。本文以该示例为主线,完整讲解从集群文件系统搭建、IP 配置、图数据分区、分布式任务启动,到使用 DGL 原生采样与 GraphBolt 采样进行节点分类与链路预测训练评测的全过程,并给出两种数据格式在分区体积、采样性能、内存占用上的实测对比,帮助读者直接复现并评估分布式 RGCN 训练流程。
前置准备与整体流程概览
当前示例针对带输入节点特征的异构图训练 RGCN 节点分类模型(对应 node_classification.py)。训练前需要先安装依赖库:
pip3 install ogb pyarrow
ogb 用于加载 ogbn-mag 等 OGB 数据集,pyarrow 用于分布式训练中的特征与数据序列化传输。
示例将分布式训练拆分为四个步骤,后续小节逐一展开:
| 步骤 | 内容 | 对应脚本/产物 |
|---|---|---|
| Step 0 | 搭建分布式文件系统(如 NFS/Ceph),保证多机共享代码与数据 | 系统级配置 |
| Step 1 | 编写 IP 配置文件 ip_config.txt,配置免密 SSH |
文本文件 |
| Step 2 | 对图数据分区(支持 DGL 格式与 GraphBolt 格式) | partition_graph.py |
| Step 3 | 用 DGL 启动器在集群中拉起 server 与 trainer 进程 | tools/launch.py + node_classification.py |
Step 0:搭建分布式文件系统
分布式训练要求多台机器都能访问相同的代码与数据文件,最直接的做法是使用 NFS、Ceph 等分布式文件系统。如果集群已通过其他方式实现了目录同步(例如共享存储或 rsync),本步骤可以跳过。
服务端配置(以 NFS 为例)
在存储服务器上安装 NFS 内核服务:
sudo apt-get install nfs-kernel-server
假设用户名为 ubuntu,在 home 目录下创建工作目录:
mkdir -p /home/ubuntu/workspace
假设集群所有服务器位于 192.168.0.0 至 192.168.255.255 的子网内,编辑 /etc/exports 导出该目录:
sudo vim /etc/exports
# add the following line
/home/ubuntu/workspace 192.168.0.0/16(rw,sync,no_subtree_check)
可以通过 ifconfig 或 ip 命令查看服务器内网 IP。若 IP 不在 192.168 网段,可根据实际网段替换:
# for ip range 10.0.0.0 - 10.255.255.255
/home/ubuntu/workspace 10.0.0.0/8(rw,sync,no_subtree_check)
# for ip range 172.16.0.0 - 172.31.255.255
/home/ubuntu/workspace 172.16.0.0/12(rw,sync,no_subtree_check)
重启 NFS 服务使配置生效(NFS 的详细配置可参考 ArchWiki 上的 NFS 条目):
sudo systemctl restart nfs-kernel-server
客户端配置
所有训练节点需要安装 NFS 客户端工具:
sudo apt-get install nfs-common
可以手动挂载 NFS 目录:
mkdir -p /home/ubuntu/workspace
sudo mount -t nfs <nfs-server-ip>:/home/ubuntu/workspace /home/ubuntu/workspace
也可以写入 /etc/fstab 实现开机自动挂载:
# vim /etc/fstab
## append the following line to the file
<nfs-server-ip>:/home/ubuntu/workspace /home/ubuntu/workspace nfs defaults 0 0
随后执行 mount -a 完成挂载,再进入 /home/ubuntu/workspace 克隆 DGL 仓库代码。注意:所有机器的挂载路径与仓库路径必须保持一致,因为后续启动器会基于统一的 workspace 路径在远端执行命令。
Step 1:编写 IP 配置并配置免密 SSH
训练前需要编写 IP 配置文件 ip_config.txt,每行一台机器的 IP 地址,行数即集群机器数。例如两台机器的集群可写为:
172.31.0.1
172.31.0.2
从 tools/launch.py 的解析逻辑可以看到,ip_config 每一行除 IP 外还可附带端口号(例如 172.31.0.1 2222),未指定端口时启动器会自动探测可用端口(见 get_available_port)。
同时必须保证主节点(node-0)能够免密 SSH 到所有其他节点,因为 launch.py 会通过 ssh 在每台机器上执行远端命令来拉起训练进程(使用 -o StrictHostKeyChecking=no 避免首次连接交互)。免密 SSH 可通过 ssh-keygen 生成密钥并分发公钥到各节点的方式配置。
Step 2:分区图数据(DGL 格式与 GraphBolt 格式)
示例提供了 partition_graph.py 脚本对内置图(当前支持 ogbn-mag)进行分区。在 2 台机器上训练,就需要把图切成 2 份。例如使用 Metis 将 ogbn-mag 切成 2 份,并让训练节点数、边数在分区间保持均衡:
python3 partition_graph.py --dataset ogbn-mag --num_parts 2 --balance_train --balance_edges
若希望用 GraphBolt 训练,追加 --use_graphbolt 直接生成 GraphBolt 格式的分区:
python3 partition_graph.py --dataset ogbn-mag --num_parts 2 --balance_train --balance_edges --use_graphbolt
若已生成 DGL 格式分区,也可以直接转换:
python3 -c "import dgl; dgl.distributed.dgl_partition_to_graphbolt('ogbn-products.json')"
脚本参数与底层实现
partition_graph.py 的参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--dataset |
ogbn-mag |
数据集名,目前仅支持 ogbn-mag |
--num_parts |
4 |
分区数,应与集群机器数一致 |
--part_method |
metis |
分区算法 |
--balance_train |
关闭 | 按训练集规模均衡每个分区的训练样本数 |
--undirected |
关闭 | 将图转为无向图 |
--balance_edges |
关闭 | 均衡每个分区的边数 |
--num_trainers_per_machine |
1 |
每台机器的 trainer 数,会把 trainer_id 写入节点特征 |
--output |
data |
分区输出路径 |
--use_graphbolt |
关闭 | 输出 GraphBolt 格式分区 |
脚本在加载 ogbn-mag 后,会为每种规范边类型(canonical etype)构造正反两个方向的关系(rev- 前缀),并把 OGB 提供的 train/val/test 划分写入 paper 节点的 train_mask/val_mask/test_mask 及 labels 特征(partition_graph.py)。--balance_train 开启时,balance_ntypes 会被设置为 {"paper": train_mask},即 Metis 分区会在不同分区间尽量均衡 paper 节点训练样本数量(partition_graph.py)。
脚本最终调用底层接口 dgl.distributed.partition_graph(...)(实现在 python/dgl/distributed/partition.py)。从该接口的文档与实现可知,分区过程分为三步:1) 运行分区算法(如 Metis)将节点指派到各分区;2) 依据节点归属构建每个分区的图结构(每个分区可包含属于其他分区的 HALO 节点,用于本地采样,local nodes/edges 才真正归属本分区);3) 按分区结果拆分节点特征与边特征。产物组织为:
data_root_dir/
|-- graph_name.json # JSON 分区配置文件
|-- node_map.npy # 每个节点的分区 id(可选)
|-- edge_map.npy # 每条边的分区 id(可选)
|-- part0/
|-- node_feats.dgl # 二进制节点特征
|-- edge_feats.dgl # 二进制边特征
|-- graph.dgl # 本分区图结构(GraphBolt 格式则为 fused_csc_sampling_graph.pt)
|-- part1/...
转换接口 dgl.distributed.dgl_partition_to_graphbolt(part_config, *, store_eids=True, store_inner_node=False, store_inner_edge=False, graph_formats=None, n_jobs=1)(python/dgl/distributed/partition.py)会把 DGL 分区转换为 GraphBolt 专用的 FusedCSCSamplingGraph,新图以 fused_csc_sampling_graph.pt 存放在原分区旁,并更新分区配置 JSON。其中 store_eids 控制是否保存边 ID,graph_formats 可额外指定保存 coo 格式(csc 是 FusedCSCSamplingGraph 的强制格式,无需指定);由于新格式统一使用 int64 节点/边 ID,转换后的文件明显更紧凑(见下文对比)。
Step 3:启动分布式训练任务
DGL 提供启动脚本 tools/launch.py 在集群上统一拉起 server 与 trainer 进程。--part_config 与 --ip_config 都填写相对于 workspace 的路径。下面的命令在每台机器上启动 4 个训练进程(利用 4 块 GPU):
python3 ~/workspace/dgl/tools/launch.py \
--workspace ~/workspace/dgl/examples/distributed/rgcn/ \
--num_trainers 4 \
--num_servers 2 \
--num_samplers 0 \
--part_config data/ogbn-mag.json \
--ip_config ip_config.txt \
"python3 node_classification.py --graph-name ogbn-mag --dataset ogbn-mag --fanout='25,25' --batch-size 1024 --n-hidden 64 --lr 0.01 --eval-batch-size 1024 --low-mem --dropout 0.5 --use-self-loop --n-bases 2 --n-epochs 3 --layer-norm --ip-config ip_config.txt --num_gpus 4"
使用 GraphBolt 训练时只需在命令末尾追加 --use_graphbolt:
python3 ~/workspace/dgl/tools/launch.py \
--workspace ~/workspace/dgl/examples/distributed/rgcn/ \
--num_trainers 4 \
--num_servers 2 \
--num_samplers 0 \
--part_config data/ogbn-mag.json \
--ip_config ip_config.txt \
"python3 node_classification.py --graph-name ogbn-mag --dataset ogbn-mag --fanout='25,25' --batch-size 1024 --n-hidden 64 --lr 0.01 --eval-batch-size 1024 --low-mem --dropout 0.5 --use-self-loop --n-bases 2 --n-epochs 3 --layer-norm --ip-config ip_config.txt --num_gpus 4 --use_graphbolt"
注意:如果远端机器使用 conda 或其他虚拟环境,需要把命令字符串(最后一个参数)中的
python3替换为该环境中 Python 解释器的绝对路径。
launch.py 启动器行为解析
从 tools/launch.py 源码看,启动器主要做四件事:
- 读取集群信息:逐行解析
ip_config(支持ip与ip port两种格式),并要求分区数num_parts与机器数严格相等(tools/launch.py); - 启动 server 进程:每台机器启动
--num_servers个 server,通过DGL_ROLE=server、DGL_CONF_PATH、DGL_IP_CONFIG等环境变量标识角色(construct_dgl_server_env_vars),server 负责加载分区数据并通过共享内存供本机 client 访问; - 启动 client(trainer)进程:用
torch.distributed.run包装用户命令,自动识别命令中的python3解释器,注入--nproc_per_node、--nnodes、--node_rank、--master_addr、--master_port等参数(wrap_udf_in_torch_dist_launcher),同时通过DGL_ROLE=client、DGL_DIST_MODE=distributed等环境变量指定客户端角色(construct_dgl_client_env_vars); - 清理保障:额外启动一个 cleanup 进程,当训练被中断(如 Ctrl+C)时,通过 SSH 远程杀掉所有残留训练进程(cleanup_proc)。
启动器还支持 --num_omp_threads(每 trainer 的 OMP 线程数,未指定时按 CPU 核数自动估算)、--num_server_threads(server 内 OMP 线程数,默认 1,server 与 trainer 同机时应保持较小)、--graph_format(分区图格式,默认 csc,可组合 csr,csc)以及 --extra_envs(透传额外环境变量,如 NCCL_DEBUG=INFO)等参数。
node_classification.py 训练脚本核心参数
训练脚本 node_classification.py 的参数按用途可分为三类:
分布式相关
| 参数 | 默认值 | 说明 |
|---|---|---|
--graph-name |
必填 | 图名称,须与分区时一致 |
--ip-config |
必填 | IP 配置文件 |
--conf-path |
无 | 分区配置 JSON 路径 |
--num_gpus |
-1 |
GPU 数量,-1 表示纯 CPU 训练 |
--standalone |
关闭 | 单机调试模式(配合单分区数据) |
RGCN 模型相关
| 参数 | 默认值 | 说明 |
|---|---|---|
--n-hidden |
16 |
隐藏层维度(示例命令中用 64) |
--n-bases |
-1 |
基分解(basis decomposition)数量,-1 表示每个关系独立权重矩阵 |
--n-layers |
2 |
传播层数 |
--dropout |
0 |
Dropout 概率 |
--use-self-loop |
关闭 | 把自身特征作为一条特殊关系加入聚合 |
--layer-norm |
关闭 | 使用 Layer Normalization |
--l2norm |
0 |
权重 L2 正则系数 |
--sparse-embedding / --dgl-sparse |
关闭 | 为无特征节点类型使用(DGL 分布式)稀疏嵌入 |
--low-mem |
关闭 | 低显存模式的 RelGraphConv |
训练/采样相关
| 参数 | 默认值 | 说明 |
|---|---|---|
--fanout |
"4, 4" |
各层邻居采样扇出,逗号分隔 |
--validation-fanout |
同 --fanout |
验证时的采样扇出 |
--batch-size |
100 |
训练 mini-batch 大小 |
--eval-batch-size |
128 |
验证/测试 mini-batch 大小 |
-e/--n-epochs |
50 |
训练轮数 |
--lr |
1e-2 |
学习率 |
--log-every |
20 |
日志打印间隔 |
脚本内部执行链路
结合 node_classification.py 的 main 与 run 函数,训练流程为:
dgl.distributed.initialize(ip_config, use_graphbolt=...)初始化分布式环境;若--num_gpus == -1则使用gloo后端,否则使用nccl(若同时启用 DGL 稀疏嵌入,则回退到gloo,因为 nccl 未完全支持 DistDGL 稀疏优化器);dgl.distributed.DistGraph(graph_name, part_config=...)创建分布式图对象。根据 python/dgl/distributed/dist_graph.py 的说明,DistGraph支持两种模式:直接运行脚本时为 standalone 模式(要求分区数=1,用于调试);通过 launch.py 启动时为分布式模式,server 加载分区数据并通过共享内存供本机 client 访问,因此 server 与 trainer 通常部署在同一组机器上以获得最佳性能;- 通过
dgl.distributed.node_split结合train_mask/val_mask/test_mask与分区簿(partition book)为每个进程分配本地的训练/验证/测试节点(开启--num_trainers_per_machine分区时会使用trainer_id做均衡切分); - 构建
dgl.distributed.DistNodeDataLoader(内部使用MultiLayerNeighborSampler)产出(input_nodes, seeds, blocks)mini-batch; - 模型
EntityClassify由多层RelGraphConvLayer组成:每层内部使用dgl.nn.HeteroGraphConv对每种关系做GraphConv,并通过dgl.nn.WeightBasis实现基分解参数共享(当num_bases < 关系数时),支持 self-loop 权重、bias、ReLU 激活与 dropout(node_classification.py); - 每轮训练后调用
evaluate,把各 rank 的预测写入dgl.distributed.DistTensor,最终由 rank 0 汇总计算验证集/测试集准确率(node_classification.py)。
DGL 与 GraphBolt 训练对比
示例 README 给出了同一台集群(2 节点)上使用 DGL 原生采样与 GraphBolt 采样的实测对比,衡量指标包括分区体积、每 epoch 采样时间、准确率、内存与 CPU 利用率。
节点分类任务对比
分区体积:GraphBolt 的 fused_csc_sampling_graph.pt 相比 DGL 的 graph.dgl 缩减到约 19%。
ogbn-mag
| 数据格式 | 文件名 | Part 0 | Part 1 |
|---|---|---|---|
| DGL | graph.dgl | 714MB | 716MB |
| GraphBolt | fused_csc_sampling_graph.pt | 137MB | 136MB |
训练性能:GraphBolt 的采样器显著更快,每 epoch 采样时间缩减到约 16%。表中的 Min/Max 是所有机器上所有 trainer 进程的统计值;RAM 方面,由于分区更小,共享内存(free 命令的 shared 字段)占用下降,进程峰值内存(used 字段)也随之下降。
ogbn-mag
| 数据格式 | 每 Epoch 采样时间 (CPU) | 测试准确率 (3 epochs) | shared | used (peak) | CPU Util |
|---|---|---|---|---|---|
| DGL | Min: 48.2s, Max: 91.4s | 42.76% | 1.3GB | 9.2GB | 10.4% |
| GraphBolt | Min: 9.2s, Max: 11.9s | 42.46% | 742MB | 5.9GB | 18.1% |
从源码层面看,这一收益主要来自两点:其一,GraphBolt 分区使用 int64 统一节点/边 ID 且以 FusedCSCSamplingGraph 紧凑格式存储(见 dgl_partition_to_graphbolt 的说明),显著减小了分区体积与共享内存占用;其二,GraphBolt 面向采样场景的融合 CSC 结构减少了采样时的格式转换开销。
链路预测采样性能评测
示例还提供 lp_perf.py(内部评测用)来演示并剖析链路预测任务中采样的性能,可分别基于 DGL 与 GraphBolt 运行。
DGL 模式
python3 ~/workspace/dgl/tools/launch.py \
--workspace ~/workspace/dgl/examples/distributed/rgcn/ \
--num_trainers 4 \
--num_servers 2 \
--num_samplers 0 \
--part_config ~/data/ogbn_mag_lp/ogbn-mag.json \
--ip_config ~/workspace/ip_config.txt \
"python3 lp_perf.py --fanout='25,25' --batch-size 1024 --n-epochs 1 --graph-name ogbn-mag --ip-config ~/workspace/ip_config.txt --num_gpus 4 --remove_edge"
GraphBolt 模式
先用转换命令把 DGL 分区转成 GraphBolt 格式(注意链路预测需要保存边 ID 并额外保存 coo 格式):
python3 -c "import dgl;dgl.distributed.dgl_partition_to_graphbolt('/home/ubuntu/workspace/data/ogbn_mag_lp/ogbn-mag.json', store_eids=True, graph_formats='coo')"
然后同样追加 --use_graphbolt 启动:
python3 ~/workspace/dgl/tools/launch.py \
--workspace ~/workspace/dgl/examples/distributed/rgcn/ \
--num_trainers 4 \
--num_servers 2 \
--num_samplers 0 \
--part_config ~/data/ogbn_mag_lp/ogbn-mag.json \
--ip_config ~/workspace/ip_config.txt \
"python3 lp_perf.py --fanout='25,25' --batch-size 1024 --n-epochs 1 --graph-name ogbn-mag --ip-config ~/workspace/ip_config.txt --num_gpus 4 --remove_edge --use_graphbolt"
链路预测分区体积对比
链路预测需要保留边 ID 并保存 coo 格式,因此体积缩减幅度小于节点分类场景,约为 72%。
ogbn-mag
| 数据格式 | 文件名 | Part 0 | Part 1 |
|---|---|---|---|
| DGL | graph.dgl | 714MB | 716MB |
| GraphBolt | fused_csc_sampling_graph.pt | 512MB | 514MB |
采样性能对比
本次评测的主要参数如下:
- 2 节点(g4dn.metal),每节点 4 个 trainer、2 个 server,采样在主进程执行;
- 2 层;
- 所有边类型的 fanout = 25, 25;
- batch_size = 1024;
- 种子边为 ("author", "writes", "paper") 的全部边,约 7M 条;
- 负采样比例为 3;
- exclude = "reverse_types"。
下表为 60 次迭代(取最慢 rank)的每次迭代平均采样时间,单位:秒。可见 GraphBolt 的采样时间缩减到 DGL 的约 15%;而 exclude(排除反向类型边)带来的额外开销约为 5%,若使用更大的 fanout 或 batch size,该开销比例会更高。
ogbn-mag
| 数据格式 | No Exclude | Exclude |
|---|---|---|
| DGL | 6.50 | 6.86 |
| GraphBolt | 0.95 | 1.00 |
lp_perf.py 实现要点
从 lp_perf.py 源码看,该脚本使用 dgl.dataloading.DistEdgeDataLoader 加载边 mini-batch,结合 dgl.dataloading.negative_sampler.Uniform(3) 做 1:3 负采样;开启 --remove_edge 时以 exclude="reverse_types" 排除反向类型边,并显式构造 8 组正反向规范边类型的映射(lp_perf.py)。此外脚本会为每条边创建随机的 prob/mask 分布式张量(lp_perf.py),配合 --debug 模式可验证概率/掩码采样的取值以及 exclude 行为是否符合预期(lp_perf.py),便于在剖析采样性能的同时校验正确性。
小结
本文基于 examples/distributed/rgcn 的官方示例完整复现了 DGL 分布式 RGCN 训练的四个步骤:NFS 集群文件系统搭建、IP 配置与免密 SSH、图数据分区(DGL/GraphBolt 两种格式)、以及基于 tools/launch.py 的多机多卡任务启动,并对 node_classification.py 的参数与执行链路、lp_perf.py 的链路预测采样评测做了源码级展开。实测对比显示,GraphBolt 格式在分区体积、共享内存占用与采样速度上相比 DGL 原生格式均有数量级的收益,同时保持了几乎一致的测试准确率,适合作为大规模异构图上 RGCN 分布式训练的基准方案。