torch-geometric

torch-geometric スキルの概要

torch-geometric は何のためのものか

torch-geometric は、グラフニューラルネットワークを構築するための PyTorch Geometric スキルであり、汎用の深層学習プロンプトではありません。ノード分類、リンク予測、グラフ分類、異種グラフ、メッセージパッシング、大規模グラフのサンプリングなど、グラフデータのタスクに対して torch-geometric のインストール方法、モデル選定、実装支援が必要な人に最適です。

どんな人に向いているか

リレーショナルデータを扱っていて、グラフの表現方法、どの loader や split 戦略を使うべきか、学習をどうスケールさせるか、カスタム層をどう実装するかといった実践的な PyG の選択が必要なら、この torch-geometric スキルが向いています。PyTorch のコードはすでにあり、理論だけではなくグラフ特有の構造が必要な Machine Learning ユーザーに特に適しています。

何が違うのか

このスキルは、PyG の実際のワークフローである Data と HeteroData、MessagePassing、RandomLinkSplit、NeighborLoader、そして説明可能性ツールに焦点を当てています。主な価値は、ユーザーがつまずきやすい部分、つまりインストール依存関係、グラフ入力の shape 規約、リークを避ける split、そして大規模グラフ向けのサンプリング選択に関する導入障壁を下げることです。

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 のバージョンを確認し、そのうえで CUDA か CPU 環境に合う binary wheel を合わせてください。

あいまいな目的を、使えるプロンプトに変える

“help me use torch-geometric” のような弱い依頼では、選択肢が多すぎます。より強いプロンプトでは、タスク、データ形状、制約を明示します。

• “I have a citation graph with x, edge_index, and node labels. Show a torch-geometric usage pattern for node classification with train/val/test masks.”
• “I need a torch-geometric guide for link prediction on an undirected graph with negative sampling.”
• “I have heterogeneous paper/author/institution data in HeteroData; help me build a model and 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 の規約を推測せずに、インストールから動くコードまで短い道筋で進めます。

より良い出力につながる進め方

次の順で進めると精度が上がります。まずグラフの種類を特定し、次に学習目的を決め、その後で split 戦略を選び、最後に data loader を決めます。たとえば、1つのグラフでのノード分類なら通常 Data、mask、場合によっては NeighborLoader が必要です。リンク予測なら通常 RandomLinkSplit が必要です。異種データなら通常 HeteroData と型を意識したモデルコードが必要です。これらの判断を飛ばすと、出力は Python としては正しくても、タスクには合っていないことがよくあります。

torch-geometric スキルの FAQ

torch-geometric のインストールは難しいですか？

場合によります。基本の torch_geometric パッケージ自体は難しくありませんが、任意の加速ライブラリは PyTorch や CUDA スタックとのバージョン一致が必要になることがあります。まず試作だけしたいなら、追加機能を入れる前にコアパッケージから始めるのが安全です。

普通のプロンプトではなく torch-geometric スキルを使うべきなのはいつですか？

ノードの近傍、エッジ、異種ノード型、メッセージパッシングのように、グラフ構造が重要なときに torch-geometric スキルを使ってください。汎用プロンプトだと PyG 固有のデータモデルを見落としやすく、グラフサンプリングや split のリークを無視したコードを勧めてしまうことがあります。

torch-geometric は初心者向けですか？

はい。すでにデータがグラフ形状になっていて、生のエッジからモデルまでの流れをガイド付きで進めたいなら向いています。いっぽうで、タスクが node / edge / graph のどれなのかまだ分かっていない場合は、パイプライン全体がその選択で変わるため、初心者にはやや難しくなります。

使わないほうがいいのはどんなときですか？

単なる表形式 ML、通常の NLP、グラフ構造のない画像分類なら、torch-geometric を使う必要はありません。また、高レベルの概念説明だけが欲しく、実装の詳細が要らない場合も、別の手段のほうが適しています。

torch-geometric スキルを改善するには

必要なグラフ情報をきちんと渡す

品質が最も大きく上がるのは、グラフの種類、特徴量の shape、ターゲットを明示したときです。torch-geometric では、x、edge_index、edge_attr、mask、複数のノード型、あるいは adjacency のみなのかをはっきりさせることが重要です。異種グラフなら各 node type と edge type を名前付きで示し、リンク予測なら有向か無向かも伝えてください。

学習上の制約を最初に示す

グラフが大きいなら、メモリ制約とバッチ方式を先に伝えてください。torch-geometric の使い方は、フルバッチ学習が必要か、NeighborLoader が必要か、カスタムサンプリング戦略が必要かで大きく変わります。ここを省くと、最初の回答は正しくてもスケールでは使えないことがあります。

必要な PyG の成果物を具体的に頼む

torch-geometric のガイドは、具体的な出力を求めると最も役立ちます。たとえば、dataset class、model skeleton、loader 設定、train loop、デバッグ支援です。例えば: “Write an InMemoryDataset for CSV edges,” “Convert this graph to HeteroData,” “Refactor my MessagePassing layer to support bipartite inputs.” のように、成果物を具体化すると、話がぼやけず、実行しやすい答えになります。

最初の結果を見て、段階的に詰める

最初の出力が惜しいがまだ不十分なら、version、device、graph size、label type、output format のうち、1つだけ足りない制約を追加して改善してください。Machine Learning 向けの torch-geometric では、よくある失敗は、アーキテクチャは正しいのに split や loader が間違っていることです。こうした詳細を詰めるほうが、モデルクラスを変えるより重要なことが多いです。