pytorch geometric是大规模gnn训练默认选择，因其原生支持图数据封装（data/heterodata）、邻居采样（neighborloader）、稀疏算子加速及分布式训练，而原生pytorch缺乏这些能力，直接实现易导致oom或低效。
PyTorch Geometric 为什么是大规模 GNN 训练的默认选择
因为原生 PyTorch 没有图结构数据的批处理、邻域采样和稀疏矩阵算子支持，直接用 torch.nn.Module 写 GNN 层会卡在内存和速度上。必须用 torch_geometric（简称 PyG），它把图数据封装成 Data 对象，底层用 torch_sparse 和 CUDA 加速稀疏消息传递。
常见错误现象：自己用 torch.tensor 存邻接矩阵 + 特征矩阵，在 10 万节点图上训练时 OOM 或单 epoch 耗时超 20 分钟——这说明没走 PyG 的 NeighborSampler 或 ClusterData 流水线。
- 小图（torch_geometric.loader.DataLoader
- 中大图（10 万–100 万节点）必须用
torch_geometric.loader.NeighborLoader做分层采样 - 超大图（>100 万节点）推荐
ClusterData+ClusterLoader或GraphSAINT预处理
NeighborLoader 如何避免全图加载和冗余计算
NeighborLoader 不是简单切 batch，而是对每个 seed node 向外采样固定跳数的邻居，生成子图再 collate。这样每个 batch 只含相关节点，显存占用与 batch size 和采样数量线性相关，而非全图规模。
关键参数容易踩坑：num_neighbors=[10, 5] 表示第 1 层采 10 个邻居、第 2 层对每个一级邻居再采 5 个；若设成 [20, 20]，二阶子图节点数可能爆炸，GPU 显存瞬间打满。
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 采样深度建议 ≤2，除非任务明确需要长程依赖（如分子性质预测）
-
replace=False更稳定，replace=True在小度数节点上易重复采样导致梯度偏差 - 务必设
shuffle=True，否则同一批 seed node 总是触发相同子图，收敛变慢
from torch_geometric.loader import NeighborLoader
loader = NeighborLoader(
data,
num_neighbors=[10, 5],
batch_size=1024,
shuffle=True,
num_workers=4,
)
模型训练时如何避免梯度爆炸和特征缩放失衡
GNN 多层叠加后，节点表征方差极易指数级放大，尤其在 GCNConv 或 GATv2Conv 连续堆叠时。不加控制的话，loss 会在前 100 步内突增至 nan，grad.norm() 超过 1e4。
不是所有归一化都有效：BatchNorm1d 在图上效果差（batch 内节点数不固定），LayerNorm 对稀疏消息传递也不鲁棒。实测最稳的是在每层 conv 后加 torch.nn.functional.normalize(x, p=2, dim=-1)，或用 PyG 自带的 GraphNorm。
- 学习率必须调低：GNN 推荐
lr=0.001起步，比 CNN 小一个数量级 - 用
torch.cuda.amp.GradScaler不仅提速，还能缓解 FP16 下的梯度溢出 - 验证集指标波动大？检查是否漏了
model.eval()——DropPath或DropEdge在 eval 模式下不生效会导致评估失真
分布式训练时 DataParallel 为什么不能用，该选什么
nn.DataParallel 会把整个 Data 对象复制到每张卡，而不是按子图切分——结果是 4 卡显存各占满，batch size 却没变大。必须换 torch.distributed 原生方案。
PyG 官方推荐 DistributedNeighborSampler + torch.distributed.launch，但要注意：它要求每个进程只加载图的一部分（通过 data.train_mask 切分 seed nodes），且 torch.distributed.barrier() 必须插在每个 epoch 开头，否则各卡 loader 步调不同，loss 曲线会锯齿状抖动。
- 不要手动调
torch.nn.parallel.DistributedDataParallel包裹 GNN 模型——PyG 的MessagePassing子类内部已有分布式兼容逻辑 - 多机训练时，确保
MASTER_PORT不被防火墙拦截，且所有机器时间同步（ntpd或chrony），否则init_process_group卡死 - 混合精度训练必须用
torch.cuda.amp.autocast(enabled=True)包住model.forward()，不能只包 loss 计算
NeighborLoader 的参数里、normalize 的位置里、barrier() 的时机里。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
