من الفكرة إلى النتيجة: سير عمل عملي بـ PyTorch Geometric
From Idea to Result: a Practical PyG Workflow
درس تطبيقي يجمع ما سبق في سير عمل بحثي متكامل: صياغة المشكلة رسماً، وتجهيز البيانات بصيغة PyG، واختيار خط أساس، والتدريب والتقييم ببذور متعددة، وضبط المعاملات، والتشخيص بالتمثيلات والتفسير، ثم التوثيق وإعادة الإنتاج. يتضمن شيفرة كاملة قابلة للتشغيل.
أهداف الدرس
- بناء كائن Data من بيانات جدولية وروابط
- كتابة حلقة تدريب وتقييم قابلة لإعادة الإنتاج
- تنظيم تجربة ببذور متعددة وإبلاغ إحصائي
- معرفة أدوات التشخيص والتفسير المتاحة
1 الخطوة 1: صياغة المشكلة رسماً
إذا كانت الروابط مصنوعة (مثل رسم kNN من الخصائص نفسها)، فاسأل هل يضيف الرسم معلومة جديدة أم يعيد ترتيب المعلومة نفسها؛ وجرّب حساسية النتائج لـ k.
- ما العقد؟ (مرضى، مقالات، حساسات، ذرات)
- ما الروابط ولماذا تحمل معلومة؟ (تشابه، تفاعل، قرب، اقتباس)
- هل الرسم موجه، موزون، غير متجانس، زمني؟
- ما المهمة وعلى أي مستوى؟ وما الإعداد: تحويلي أم استقرائي؟
- ما خط الأساس بلا رسم؟
2 الخطوة 2: تجهيز البيانات
حوّل الخصائص إلى مصفوفة x (n×F)، والروابط إلى edge_index (2×|E|) بفهارس من 0، والوسوم إلى y، والأقنعة إلى train_mask وval_mask وtest_mask. طبّع الخصائص بإحصاءات التدريب فقط. واجعل الرسم غير موجه إذا كانت العلاقة متبادلة، وأزل الروابط المكررة والحلقات الذاتية غير المقصودة.
import numpy as np, torch
from torch_geometric.data import Data
from torch_geometric.utils import to_undirected, remove_self_loops
X = np.load("features.npy"); y = np.load("labels.npy")
edges = np.load("edges.npy") # شكل (|E|, 2)
edge_index = torch.tensor(edges.T, dtype=torch.long)
edge_index, _ = remove_self_loops(edge_index)
edge_index = to_undirected(edge_index)
perm = torch.randperm(len(y), generator=torch.Generator().manual_seed(0))
n = len(y); tr, va = perm[: int(.6*n)], perm[int(.6*n): int(.8*n)]
mu, sd = X[tr].mean(0), X[tr].std(0) + 1e-8 # إحصاءات التدريب فقط
data = Data(x=torch.tensor((X - mu) / sd, dtype=torch.float), edge_index=edge_index,
y=torch.tensor(y))
for name, idx in [("train_mask", tr), ("val_mask", va), ("test_mask", perm[int(.8*n):])]:
m = torch.zeros(n, dtype=torch.bool); m[idx] = True; data[name] = m3 الخطوة 3: التدريب والتقييم ببذور متعددة
اكتب دالة تجربة تأخذ البذرة والمعاملات وتعيد نتيجة الاختبار عند أفضل تحقق، ثم شغّلها على 10 بذور. الإيقاف المبكر والاختيار على التحقق فقط. وقارن مع MLP بالإعداد نفسه.
import torch.nn.functional as F
from torch_geometric.nn import GCNConv
from torch_geometric import seed_everything
from sklearn.metrics import f1_score
def run(seed, hidden=64, lr=0.01, wd=5e-4, epochs=300):
seed_everything(seed)
c1, c2 = GCNConv(data.num_features, hidden), GCNConv(hidden, int(data.y.max()) + 1)
params = list(c1.parameters()) + list(c2.parameters())
opt = torch.optim.Adam(params, lr=lr, weight_decay=wd)
def fwd(train):
h = F.dropout(F.relu(c1(data.x, data.edge_index)), 0.5, train)
return c2(h, data.edge_index)
best_val, test_at_best = -1, 0
for _ in range(epochs):
opt.zero_grad(); out = fwd(True)
F.cross_entropy(out[data.train_mask], data.y[data.train_mask]).backward(); opt.step()
with torch.no_grad():
pred = fwd(False).argmax(1)
f1 = lambda m: f1_score(data.y[m], pred[m], average="macro")
if f1(data.val_mask) > best_val:
best_val, test_at_best = f1(data.val_mask), f1(data.test_mask)
return test_at_best
scores = [run(s) for s in range(10)]
print(f"Macro-F1 = {np.mean(scores):.3f} ± {np.std(scores):.3f}")4 الخطوة 4: الضبط والتشخيص
اضبط المعاملات الأهم بالترتيب: معدل التعلم، والأبعاد المخفية، والـ Dropout، وWeight decay، وعدد الطبقات، والمجمّع. استخدم بحثاً عشوائياً أو أدوات مثل Optuna مع التحقق فقط. ثم شخّص: هل الخطأ متركز في عقد منخفضة الدرجة؟ في فئة نادرة؟ في عقد جيرانها من فئات أخرى (عدم تجانس محلي)؟ اعرض التمثيلات بـ t-SNE، وافحص التفسيرات لعينة من التنبؤات بـ GNNExplainer أو Captum مع التحقق من صدقها.
from torch_geometric.explain import Explainer, GNNExplainer
explainer = Explainer(model=model, algorithm=GNNExplainer(epochs=200),
explanation_type="model", node_mask_type="attributes",
edge_mask_type="object",
model_config=dict(mode="multiclass_classification",
task_level="node", return_type="raw"))
explanation = explainer(data.x, data.edge_index, index=10)
print(explanation.edge_mask.topk(5))5 الخطوة 5: التوثيق وإعادة الإنتاج
ثم انتقل إلى المشاريع البحثية في المختبر، حيث لكل مشروع هدف ومجموعة بيانات وخطوات ومقاييس محددة.
- ثبّت إصدارات PyTorch وPyG وCUDA في ملف بيئة.
- احفظ التقسيمات والبذور، وانشرها مع الشيفرة.
- سجّل كل التجارب (معاملات ونتائج) بأداة مثل MLflow أو Weights & Biases أو ملف CSV.
- اذكر الإعداد (تحويلي/استقرائي) والمقياس وعدد البذور في كل جدول.
- أبلغ عن الكلفة: زمن التدريب والذاكرة وعدد المعاملات.
كل الشيفرات في هذا الدرس مكتوبة لواجهة PyTorch Geometric 2.x. قد تتغير بعض التفاصيل بين الإصدارات؛ راجع التوثيق الرسمي للإصدار الذي تستخدمه.
خلاصة الدرس
- ابدأ بصياغة واضحة للعقد والروابط والمهمة والإعداد
- طبّع بإحصاءات التدريب فقط واحفظ التقسيمات
- بذور متعددة واختيار على التحقق ومقارنة بـ MLP
- شخّص الأخطاء ووثّق كل شيء لإعادة الإنتاج
تحقّق من فهمك
فكّر في الإجابة أولاً، ثم افتح السؤال لترى الجواب.
لماذا تُحسب إحصاءات التطبيع من عقد التدريب فقط؟
لأن استخدام إحصاءات تشمل التحقق والاختبار يسرّب معلومات عنها إلى التدريب.
ما الذي يعيده run() في الشيفرة أعلاه ولماذا؟
نتيجة الاختبار عند أفضل نتيجة تحقق، حتى لا يُختار أي شيء بناءً على الاختبار.
تابع التعلّم
نماذج في هذا الدرس
مفاهيم مرتبطة
المراجع
- Fey, M., & Lenssen, J. E. (2019). Fast Graph Representation Learning with PyTorch Geometric. ICLR 2019 Workshop on Representation Learning on Graphs and Manifolds. arXiv: 1903.02428المكتبة المستخدمة في خادم Python الاختياري ومصدر إحصاءات مجموعات البيانات.
- PyG Team. PyTorch Geometric documentation. Official documentation. pytorch-geometric.readthedocs.ioالتوثيق الرسمي للمكتبة؛ منه أُخذت جداول إحصاءات المجموعات (الإصدار 2.8.1).
- Shchur, O., Mumme, M., Bojchevski, A., & Günnemann, S. (2018). Pitfalls of Graph Neural Network Evaluation. NeurIPS 2018 Workshop on Relational Representation Learning. arXiv: 1811.05868تبيّن أن ترتيب النماذج يتغير مع تغيير التقسيم، وتوصي بتقسيمات وبذور متعددة.
- Ying, R., Bourgeois, D., You, J., Zitnik, M., & Leskovec, J. (2019). GNNExplainer: Generating Explanations for Graph Neural Networks. Advances in Neural Information Processing Systems (NeurIPS). arXiv: 1903.03894تعلّم قناعاً للروابط والخصائص يحافظ على تنبؤ النموذج.
- Errica, F., Podda, M., Bacciu, D., & Micheli, A. (2020). A Fair Comparison of Graph Neural Networks for Graph Classification. International Conference on Learning Representations (ICLR). arXiv: 1912.09893بروتوكول تقييم صارم يكشف أن خطوط أساس بسيطة تنافس نماذج معقدة.
