DGL节点分类实战教程：Python图神经网络入门

本文深入剖析了使用DGL进行图神经网络节点分类时极易踩坑的四大核心细节：GraphConv层对节点特征维度与数据类型的硬性要求、训练掩码（train_mask）必须为布尔张量或索引张量且长度严格匹配节点数、NodeDataLoader中batch_size与drop_last配置不当引发的小批量归一化异常，以及模型保存时遗漏图结构与节点特征导致加载失败或NaN输出；这些看似琐碎却致命的“隐性契约”，往往让初学者在loss不降、准确率停滞或运行报错中反复挣扎——真正决定GNN项目成败的，从来不是模型多复杂，而是数据、图、张量三者生命周期的精准对齐。

节点特征维度对 GraphConv 层输入的硬性要求

DGL 的 GraphConv（比如 dgl.nn.pytorch.conv.GraphConv）不会自动适配特征维度，如果节点特征张量 feat 的最后一维和 in_feats 参数不一致，运行时直接报 RuntimeError: mat1 and mat2 shapes cannot be multiplied。

常见错误是：用 g.ndata['feat'] = torch.randn(g.num_nodes(), 128) 构造特征，但初始化 GraphConv(64, 64) —— 这里 in_feats=64 却期望输入是 64 维，实际给了 128 维，必然崩。

• 检查方式：打印 feat.shape[-1] 和你传给 GraphConv 构造器的第一个参数是否相等
• 特征预处理阶段就该对齐：比如用 nn.Linear 投影到目标维度，别等到进 GNN 层才发现不匹配
• 注意 feat 是 float32 类型，DGL 默认不接受 int64 特征做图卷积（会静默转但可能出错），务必显式 .float()

训练时 train_mask 必须是布尔张量或长整型索引，不能是 Python list

节点分类任务中，model(g, feat)[train_mask] 这类写法很常见，但如果 train_mask 是 [True, False, True, ...] 这样的原生 Python list，DGL 会把它当图节点 ID 索引用，结果取到完全无关的节点，loss 值乱跳甚至为 NaN。

典型表现：loss 不下降、准确率卡在 0.1 左右（接近随机）、验证集指标波动极大。

• 正确做法：用 torch.BoolTensor(train_mask_list) 或 torch.tensor(train_mask_list, dtype=torch.bool)
• 更稳妥的是直接用索引张量：train_idx = torch.nonzero(train_mask, as_tuple=True)[0]，然后 logits[train_idx]
• 注意 mask 长度必须等于节点总数 g.num_nodes()，少一位或多一位都会触发 IndexError

dgl.dataloading.NodeDataLoader 的 shuffle 和 drop_last 实际影响

小图场景下（比如 Cora 只有 2708 个节点），开 shuffle=True 并设 batch_size=1024，会导致每个 epoch 实际只采两个 batch，且第二个 batch 只有 660 个节点——但 NodeDataLoader 默认不丢尾，所以最后一个 batch 尺寸变小，model.forward() 内部若用了依赖 batch size 的归一化（如 BatchNorm1d），就会出错。

• 推荐配置：drop_last=False + 在模型里避免 batch-size 敏感操作；或者干脆 drop_last=True，但得确保训练集节点数能被 batch_size 整除（可用 torch.utils.data.Subset 调整）
• shuffle 对单图训练意义有限，因为所有节点都在同一张图上，真正起作用的是邻居采样（Sampler）的随机性
• 如果用了 MultiLayerFullNeighborSampler(2)，shuffle 几乎没效果，重点应放在 neighbor_sampler 的 replace 和 fanouts 设置上

保存模型时漏掉 g.ndata 和 g.edata 的隐式依赖

训练完模型后只存 torch.save(model.state_dict(), 'model.pt')，下次加载时用新构造的图（哪怕结构完全一样）调用 model(g, g.ndata['feat'])，可能报 KeyError: 'feat' 或输出全 NaN——因为图对象本身不随模型保存，而 DGL 模型前向不校验 g.ndata 是否存在对应 key，只在第一次访问时 lazy 初始化，一旦 key 缺失就崩。

• 最简方案：把图和特征一起存，例如 torch.save({'g': g, 'feat': feat, 'labels': labels}, 'data.pt')
• 更健壮的做法：封装成类，__init__ 中显式检查 g.ndata.keys() 是否包含所需字段，缺失则 raise
• 注意：不同 DGL 版本对空 ndata 的容忍度不同，0.9+ 更严格，别指望“以前能跑现在也能”

图神经网络里最麻烦的不是模型结构，而是数据、图对象、特征张量三者生命周期的对齐。一个 feat 张量被 in-place 修改了，或者图被 to() 到 GPU 但特征还在 CPU，问题当场就来，不会等你 debug 到第三层嵌套。

以上就是《DGL节点分类实战教程：Python图神经网络入门》的详细内容，更多关于的资料请关注golang学习网公众号！