pytorch geometric安装需严格匹配pytorch与cuda版本，须按官网链接用--find-links安装对应wheel；数据加载需确保x与edge_index设备一致且索引不越界；训练需归一化输入、调低学习率、正确使用mask；推理须启用eval()和no_grad()。
PyTorch Geometric 安装失败或 import 报错
直接用 pip install torch 后尝试 import torch_geometric 大概率失败——PyTorch Geometric（PyG）不是纯 Python 包，它依赖与当前 PyTorch 和 CUDA 版本严格匹配的预编译二进制。官方 wheel 名称里带 cu118、cpu 等后缀，错一个就 ModuleNotFoundError 或 undefined symbol。
正确做法是：先查清环境
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
再按 PyG 官网（pytorch-geometric.readthedocs.io）顶部「Install」栏，选对应组合执行命令，例如：
- CUDA 11.8 + PyTorch 2.0 → 用
pip install torch_geometric --find-links https://data.pyg.org/whl/torch-2.0.0+cu118.html - CPU-only → 换成
https://data.pyg.org/whl/torch-2.0.0+cpu.html
跳过 conda 安装（太慢且版本常滞后），也别用 git clone && python setup.py install（编译失败率高，且不兼容 Windows）。
Dataset 加载后 data.x / data.edge_index 形状不对
常见报错：RuntimeError: Expected all tensors to be on the same device 或 IndexError: index is out of bounds。根本原因往往是数据没对齐：节点特征 data.x 是 CPU tensor，但 data.edge_index 是 GPU tensor；或者 edge_index 最大索引值 ≥ data.x.size(0)（即边连到了不存在的节点上）。
检查步骤：
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 打印
data.x.device和data.edge_index.device，不一致就统一调用.to(device) - 运行
data.edge_index.max().item() ，False 就说明边索引越界，需检查原始图构建逻辑（比如邻接矩阵转 <code>edge_index时漏了coalesce()） - 若用自定义数据，确保
data.train_mask、data.y长度都等于data.x.size(0)
GNN 模型训练时 loss 不下降或 acc 停在 baseline
这不是模型写错了，大概率是训练流程细节被忽略。PyG 的 GNN 层（如 GCNConv、GATConv）默认不做 dropout，也不自动归一化输入特征——而真实图数据常有长尾分布或量纲差异。
关键调整点：
- 在送入第一层前加
torch.nn.BatchNorm1d或F.normalize(x, p=2, dim=1)，尤其当data.x各列方差差 10 倍以上时 -
GCNConv的improved=True参数会改用更稳定的归一化（加自环后再除以deg + 1），小图或稀疏图建议打开 - 学习率别设 0.01 —— 图卷积易梯度爆炸，从
0.005或0.001起手，配合torch.optim.AdamW（比 SGD 更稳） - 验证集指标用
data.val_mask索引计算，别用data.train_mask或全量，否则看不到过拟合信号
推理时 predict 出来全是同一类标签
典型表现：训练时 val_acc 到 70%，但 model(data).argmax(dim=1) 输出几乎全是一个数字。问题不在模型，而在 data 对象状态残留——PyG 的 Data 是可变对象，训练循环中若反复复用同一个 data 实例，train_mask 可能被意外覆盖，导致 forward 时 mask 错位，输出 logits 全偏向某类。
安全做法：
- 每次 forward 前确认
data.train_mask.sum().item() > 0，否则说明 mask 被清空 - 避免在训练循环里修改
data属性；需要不同子图时，显式用data.subgraph(...)或新建Data实例 - 推理阶段务必用
model.eval()+torch.no_grad()，否则 BatchNorm 层统计量乱跑，输出失真
图神经网络的「节点级」行为高度依赖数据结构完整性，比起模型堆叠，更多时候卡在 tensor 对齐、mask 生命周期和设备一致性这些地方。动手前花两分钟打印 shape 和 device，能省掉半天 debug 时间。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
