GraphConv 要求节点特征维度必须严格匹配 in_feats 参数，否则报 mat1/mat2 形状错误；feat 需为 float32；train_mask 必须是布尔张量或索引张量且长度等于节点数；NodeDataLoader 中 drop_last 和 batch_size 需协调避免小批量归一化异常；模型保存需同步图结构与特征，防止加载后 key 缺失或 NaN。
节点特征维度对 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 左右（接近随机）、验证集指标波动极大。
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- 正确做法：用
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 到第三层嵌套。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
