torch-geometric

torch-geometric 技能概览

torch-geometric 是用来做什么的

torch-geometric 是用于构建图神经网络的 PyTorch Geometric 技能，而不是通用的深度学习提示词。它最适合需要 torch-geometric 安装指引、模型选择，或图数据任务实现帮助的用户，例如节点分类、链路预测、图分类、异构图、消息传递，以及大图采样。

最适合的读者

当你在处理关系型数据，并且需要实用的 PyG 选择时，就该用这个 torch-geometric 技能：比如图该怎么表示、该用哪种 loader 或切分策略、怎样扩展训练、或者如何实现自定义层。它非常适合已经有 PyTorch 代码、但需要图结构专属支持的 Machine Learning 用户，而不是只想看理论解释的人。

它的区别在哪里

这个技能围绕 PyG 的真实工作流展开：Data 和 HeteroData、MessagePassing、RandomLinkSplit、NeighborLoader，以及可解释性工具。它的核心价值，是降低用户在常见卡点上的上手阻力：安装依赖、图输入形状约定、避免数据泄漏的切分方式，以及大图采样选择。

如何使用 torch-geometric 技能

正确安装 torch-geometric

基础安装 torch-geometric 时，先装核心包，只有在确实需要加速时再补充性能组件。仓库建议是 uv add torch_geometric 或 uv pip install torch_geometric；前提是你已经安装了 PyTorch。可选的性能包包括 pyg-lib、torch-scatter、torch-sparse 和 torch-cluster。如果你在排查安装失败，先确认 PyTorch 版本，再把对应的 binary wheel 和你的 CUDA 或 CPU 环境对齐。

把模糊目标改写成有用的提示词

像“帮我用 torch-geometric”这种弱请求，留给模型的选择太多。更强的提示词应该明确任务、数据形状和约束：

• “我有一个 citation graph，包含 x、edge_index 和节点标签。请给我一个用于节点分类的 torch-geometric 使用模式，并带上 train/val/test masks。”
• “我需要一个用于无向图链路预测的 torch-geometric 指南，要求支持 negative sampling。”
• “我有保存在 HeteroData 里的 paper/author/institution 异构数据；请帮我搭建模型和 dataloader。”

要说明图是单图还是异构图，标签是 node-level、edge-level 还是 graph-level，以及图是否能放进内存。

先读对文件

先看 SKILL.md，然后根据任务阅读对应参考：references/message_passing.md 用于自定义层，references/link_prediction.md 用于边预测，references/heterogeneous.md 用于多类型图，references/custom_datasets.md 用于数据接入，references/scaling.md 用于大图，references/explainability.md 用于解释分析。这个顺序能让你从安装直接走到可运行代码，避免猜 PyG 的约定。

能产出更好结果的工作流

按这个顺序来：先识别图类型，再确定训练目标，然后决定切分策略，最后选数据加载器。比如，单图上的节点分类通常需要 Data、mask，必要时还会用 NeighborLoader；链路预测通常需要 RandomLinkSplit；异构数据通常需要 HeteroData 和按类型编写的模型代码。如果跳过这些决策，输出往往在语法上没问题，但不适合你的任务。

torch-geometric 技能常见问题

torch-geometric 难安装吗？

有一定难度。基础包 torch_geometric 本身不复杂，但可选的加速库可能需要和 PyTorch 以及 CUDA 栈做版本匹配。如果你只是想先做原型，建议先装核心包，再加扩展组件。

什么时候该用 torch-geometric，而不是普通提示词？

当图结构本身很重要时，就该用 torch-geometric 技能：邻居、边、异构节点类型，或者消息传递。普通提示词往往不够了解 PyG 的数据模型，可能给出忽略图采样或切分泄漏的代码。

torch-geometric 适合新手吗？

适合，前提是你的数据本身已经是图结构，并且你想要一条从原始边到模型的明确路径。它对完全不知道自己的任务是节点预测、边预测还是图预测的新手就没那么友好，因为这个选择会改变整个流水线。

什么时候不该用它？

如果你的问题只是表格机器学习、纯 NLP，或者没有图结构的图像分类，就不必用 torch-geometric。若你只需要高层概念解释、不需要实现细节，也不适合用它。

如何改进 torch-geometric 技能

把关键图信息给全

提升最大的地方，是明确说明图类型、特征形状和目标。对于 torch-geometric，这意味着你有没有 x、edge_index、edge_attr、mask、多种节点类型，还是只有邻接数据。如果是异构图，就把每种节点类型和边类型都写出来；如果是链路预测，也要说明图是有向还是无向。

先说清训练约束

如果图很大，要提前说明内存限制和 batch 方式。torch-geometric 的使用答案会因为你是否需要 full-batch 训练、NeighborLoader，或者自定义采样策略而明显不同。如果不写这一点，第一版答案可能是对的，但在规模上根本跑不动。

直接提出你需要的 PyG 产物

当你要求具体产物时，torch-geometric 指南最有用：数据集类、模型骨架、loader 配置、训练循环，或者调试帮助。例如：“为 CSV 边数据写一个 InMemoryDataset”、“把这个图转换成 HeteroData”，或者“重构我的 MessagePassing 层以支持 bipartite inputs”。越具体，越能减少空话，也越容易直接运行。

基于第一版结果继续迭代

如果第一版已经接近目标但还不能用，就一次补一个缺失约束：版本、设备、图大小、标签类型，或输出格式。对于 Machine Learning 场景里的 torch-geometric，最常见的失败模式是模型结构没问题，但切分方式或 loader 用错了。通常把这些细节迭代到位，比换模型类更重要。