第2章环境搭建

第2章：环境搭建 — PyG、DGL与GPU配置

说实话，很多同学学图神经网络，最后不是被算法难倒的，而是被环境配置劝退的。我自己带过不少新人，光是装个PyG就能折腾一整天。这一章，我就把这些年踩过的坑、总结的经验，一次性给你讲清楚。

2.1 PyTorch Geometric (PyG) 安装

PyG是目前最主流的图神经网络库。我个人的习惯是，先装好PyTorch，再装PyG。顺序搞反了，后面容易出问题。

2.1.1 基础安装命令

# 先确认PyTorch版本
python -c "import torch; print(torch.__version__)"

# 根据PyTorch版本安装对应PyG
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html

pip install torch-geometric

这里有个关键点：${TORCH}和${CUDA}要替换成你实际的版本号。比如你用的是PyTorch 1.13.0，CUDA 11.7，那命令就是：

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv -f https://data.pyg.org/whl/torch-1.13.0+cu117.html

⚠️ 我曾经踩过的坑： 直接 pip install torch-geometric 而不先装那四个依赖包，结果编译时疯狂报错。后来才发现，PyG的底层算子需要单独编译。记住，顺序不能乱。

2.1.2 验证安装是否成功

import torch
from torch_geometric.data import Data

# 创建一个简单的图
edge_index = torch.tensor([[0, 1, 1, 2],
                           [1, 0, 2, 1]], dtype=torch.long)
x = torch.tensor([[-1], [0], [1]], dtype=torch.float)

data = Data(x=x, edge_index=edge_index)
print(data)
# 输出: Data(x=[3, 1], edge_index=[2, 4])

能跑出这个结果，说明PyG装好了。嗯，这里要注意，如果报No module named 'torch_scatter'，那就是前面那四个依赖包没装全。

2.2 DGL安装

DGL是另一个主流框架，由亚马逊维护。我个人觉得DGL在异构图处理上更顺手，但PyG在学术界更流行。两个都装上，干活不愁。

2.2.1 安装命令

# CPU版本
pip install dgl

# GPU版本（以CUDA 11.7为例）
pip install dgl-cu117 dgl

💡 小技巧： DGL的GPU版本和CPU版本不能共存。如果你之前装了CPU版，想换GPU版，记得先 pip uninstall dgl 再装。

2.2.2 验证DGL

import dgl
import torch

# 创建一个简单的图
g = dgl.graph(([0, 1, 2], [1, 2, 3]))
g.ndata['x'] = torch.randn(4, 5)  # 4个节点，每个节点5维特征
print(g)
# 输出: Graph(num_nodes=4, num_edges=3, ...)

你想想看，如果这里报OSError: libcuda.so.1: cannot open shared object file，那就是CUDA驱动没装好。别慌，往下看GPU配置部分。

2.3 GPU环境配置

做图神经网络，没有GPU简直是折磨。我刚开始用CPU跑一个百万节点的图，等了一天还没出结果。后来换了GPU，十分钟搞定。

2.3.1 CUDA与cuDNN安装

组件	推荐版本	说明
CUDA Toolkit	11.7 或 11.8	兼容性最好，PyG和DGL都支持
cuDNN	8.5.0	与CUDA 11.x配套
PyTorch	1.13.0 或 2.0.0	建议用1.13.0，稳定

2.3.2 验证GPU是否可用

import torch
print(torch.cuda.is_available())  # 应该输出 True
print(torch.cuda.get_device_name(0))  # 输出显卡型号，比如 Tesla T4

  🔍 排查思路： 如果输出False，按这个顺序查：
  运行 nvidia-smi 看驱动是否正常
检查CUDA版本是否匹配：nvcc --version
PyTorch的CUDA版本是否和系统一致

2.4 常见踩坑记录

这部分是我最想分享的。这些年帮人调试环境，90%的问题都出在下面这几个地方。

2.4.1 版本不匹配

说白了，就是PyTorch、CUDA、PyG三者版本没对齐。我曾经遇到过，PyTorch 2.0.0 + CUDA 12.0 + PyG 2.3.0，结果编译时各种报错。后来降级到PyTorch 1.13.0 + CUDA 11.7，一切正常。

⚠️ 我的建议： 不要追新。PyTorch 2.0虽然快，但很多图神经网络库还没完全适配。老老实实用1.13.0，省心。

2.4.2 内存不足

图神经网络特别吃显存。我跑过一个千万节点的图，12GB显存直接爆了。解决办法有两个：

使用小批量训练： PyG的NeighborLoader可以按邻居采样
开启梯度检查点： torch.utils.checkpoint 能省一半显存

from torch_geometric.loader import NeighborLoader

# 每个batch只采样10个邻居
loader = NeighborLoader(
    data,
    num_neighbors=[10, 10],
    batch_size=1024,
    shuffle=True
)

2.4.3 Windows系统兼容性

如果你用Windows，我建议你装WSL2。为什么？因为PyG的某些底层算子（比如torch-sparse）在Windows上编译特别麻烦。我有个同事在Windows上折腾了两天没搞定，换了WSL2，半小时就装好了。

💡 WSL2安装步骤：

打开PowerShell（管理员），运行 wsl --install
安装Ubuntu 22.04 LTS
在WSL2里装CUDA Toolkit（NVIDIA官方有WSL2专用版）
然后正常装PyTorch和PyG

2.5 知识体系总览

下面这张图，是我自己总结的环境搭建核心逻辑。你照着这个流程走，基本不会出大问题。

这张图的核心逻辑就是：先底层（CUDA），再中间层（PyTorch），最后上层（PyG/DGL）。顺序搞反了，后面全是坑。

2.6 写在最后

环境搭建这件事，说白了就是耐心活。我第一次装PyG也花了整整一个下午，中间还重装了三次系统。但只要你按照上面的流程走，遇到问题先查版本匹配，基本都能搞定。

嗯，如果你在安装过程中遇到任何报错，别急着搜百度。先看看错误信息里有没有version、compatible、not found这些关键词。90%的问题，都是版本没对齐。

📚 课程目录