CSC 8608 – Concepts avancés et applications du deep learning

CI : Deep learning pour audio

Ce TP introduit une première chaîne de bout en bout pour l’apprentissage sur graphes avec des Graph Neural Networks (GNN), dans un cadre pragmatique orienté ingénieur. Vous travaillerez sur un dataset public de taille modérée (Cora) afin de comparer une approche tabulaire (MLP, sans structure de graphe) à deux modèles GNN (GCN et GraphSAGE). L’objectif est de comprendre ce que “rajoute” le graphe en pratique, mais aussi ce que cela coûte en temps de calcul.

Le TP est modérément guidé : le code est presque entièrement fourni, et vous devrez compléter quelques emplacements marqués ________. Vous exécuterez de préférence vos entraînements sur le cluster GPU (Slurm), mais le dataset restant petit, un test local est possible (plus lent). Les livrables prennent la forme d’un rapport en Markdown (TP4/rapport.md) rempli au fil de l’eau, avec des résultats synthétiques, des extraits de terminal et des captures d’écran légères (éviter les fichiers volumineux).

Mettre en place un pipeline de node classification sur le dataset Cora avec PyTorch Geometric.
Entraîner et comparer trois modèles : MLP (baseline tabulaire), GCN (baseline GNN), GraphSAGE (GNN scalable via neighbor sampling).
Évaluer les performances avec des métriques adaptées : Accuracy et Macro-F1.
Mesurer et comparer des métriques d’ingénierie : temps d’entraînement (par epoch et total) et latence d’inférence (batch de nœuds).
Produire un rapport concis et exploitable qui justifie les choix (modèle, hyperparamètres simples, protocole de mesure) et discute les compromis.

Initialisation du TP et smoke test PyG (Cora)

Créez le dossier TP4/ dans le dépôt du TP précédent, avec la structure minimale suivante :

TP4/
  rapport.md
  src/
    smoke_test.py
    utils.py
  configs/
    baseline_mlp.yaml
    gcn.yaml
    sage_sampling.yaml
    

Ne commitez pas de données. Le dataset Cora sera téléchargé automatiquement par PyG dans un répertoire de cache. Si vous créez un dossier local TP4/data/ pour vos tests, ajoutez-le au .gitignore.

À mettre dans le rapport : une capture (ou un copier-coller) de la commande tree -L 3 TP4 montrant la structure (inutile d’ajouter d’autres détails ici).

Installer Pytorch Geometric scipy avec pip install torch-geometric scipy

Installer pyg-lib. Pour cela, exécutez la commande suivante pour savoir quelle est la commande pip install à utiliser.

python -

Implémentez un script de vérification rapide TP4/src/smoke_test.py qui : (i) vérifie l’accès GPU (si disponible), (ii) importe PyTorch + PyTorch Geometric, (iii) charge le dataset Cora, (iv) affiche des statistiques utiles (taille, dimensions, masques).

Copiez le code ci-dessous et complétez uniquement les zones ________.

# TP4/src/smoke_test.py
import os
import torch

from torch_geometric.datasets import Planetoid


def main() -> None:
    print("=== Environment ===")
    print("torch:", torch.__version__)
    print("cuda available:", torch.cuda.is_available())

    device = torch.device(________)  # ex: "cuda" or "cpu"
    print("device:", device)

    if device.type == "cuda":
        print("gpu:", torch.cuda.get_device_name(0))
        props = torch.cuda.get_device_properties(0)
        print("gpu_total_mem_gb:", round(props.total_memory / (1024**3), 2))

    print("\n=== Dataset (Cora) ===")
    root = os.environ.get("PYG_DATA_ROOT", os.path.expanduser("~/.cache/pyg_data"))
    dataset = Planetoid(root=root, name=________)  # ex: "Cora"
    data = dataset[0]

    # Basic stats
    print("num_nodes:", data.num_nodes)
    print("num_edges:", data.num_edges)
    print("num_node_features:", dataset.num_node_features)
    print("num_classes:", dataset.num_classes)

    # Masks (provided by Planetoid)
    train_count = int(data.train_mask.sum())
    val_count = int(data.val_mask.sum())
    test_count = int(data.test_mask.sum())
    print("train/val/test:", train_count, val_count, test_count)

    # Quick sanity checks
    assert data.x is not None and data.y is not None
    assert data.x.shape[0] == data.num_nodes
    assert data.y.shape[0] == data.num_nodes

    print("\nOK: smoke test passed.")


if __name__ == "__main__":
    main()
    

Si vous voulez forcer un répertoire de cache propre au TP, vous pouvez définir PYG_DATA_ROOT dans votre environnement (ex: dans votre session Slurm) afin d’éviter de télécharger plusieurs fois le dataset.

Exécutez le smoke test de préférence sur le cluster GPU (Slurm). Un test local est accepté si vous n’avez pas de GPU sous la main, mais il sera moins représentatif.

À mettre dans le rapport : la sortie du script (copie terminal ou capture) montrant au minimum : torch version, device, gpu name (si GPU), et les stats de Cora (num_nodes, num_edges, num_features, num_classes, tailles des masques).

Évitez de coller des pages entières de logs : 15–25 lignes propres suffisent.

Baseline tabulaire : MLP (features seules) + entraînement et métriques

Créez les fichiers suivants (vides pour l’instant) : TP4/src/data.py, TP4/src/models.py, TP4/src/train.py, et complétez le fichier TP4/configs/baseline_mlp.yaml.

À mettre dans le rapport : rien pour cette étape (structure déjà vérifiée au TP précédent).

Implémentez TP4/src/data.py pour charger Cora et renvoyer un objet simple contenant : x, y, train_mask, val_mask, test_mask, ainsi que num_features et num_classes. Copiez le code et complétez uniquement les ________.

# TP4/src/data.py
import os
from dataclasses import dataclass
import torch
from torch_geometric.datasets import Planetoid


@dataclass
class CoraData:
    x: torch.Tensor
    y: torch.Tensor
    train_mask: torch.Tensor
    val_mask: torch.Tensor
    test_mask: torch.Tensor
    num_features: int
    num_classes: int


def load_cora() -> CoraData:
    root = os.environ.get("PYG_DATA_ROOT", os.path.expanduser("~/.cache/pyg_data"))
    dataset = Planetoid(root=root, name=________)
    data = dataset[0]

    return CoraData(
        x=________,
        y=________,
        train_mask=________,
        val_mask=________,
        test_mask=________,
        num_features=________,
        num_classes=________,
    )
    

Pour la baseline MLP, vous n’utilisez pas edge_index. Vous utilisez uniquement x (features des nœuds). C’est volontaire : cela permet de mesurer ce que “rajoute” réellement le graphe ensuite.

Créez TP4/src/utils.py (ou complétez-le) avec : une fonction de seed, un timer simple, et le calcul de Accuracy + Macro-F1. Copiez le code et complétez uniquement les ________.

# TP4/src/utils.py
from __future__ import annotations
from dataclasses import dataclass
import time
import random
import os
import numpy as np
import torch


def set_seed(seed: int) -> None:
    random.seed(seed)
    np.random.seed(seed)
    torch.manual_seed(seed)
    if torch.cuda.is_available():
        torch.cuda.manual_seed_all(seed)
    os.environ["PYTHONHASHSEED"] = str(seed)


@dataclass
class Timer:
    t0: float = 0.0
    t1: float = 0.0

    def __enter__(self) -> "Timer":
        self.t0 = time.perf_counter()
        return self

    def __exit__(self, exc_type, exc, tb) -> None:
        self.t1 = time.perf_counter()

    @property
    def elapsed_s(self) -> float:
        return float(self.t1 - self.t0)


def accuracy(pred: torch.Tensor, y: torch.Tensor) -> float:
    return float((pred == y).float().mean().item())


def macro_f1(pred: torch.Tensor, y: torch.Tensor, num_classes: int) -> float:
    # pred, y: shape [N], int64
    f1_sum = 0.0
    for c in range(num_classes):
        tp = int(((pred == c) & (y == c)).sum().item())
        fp = int(((pred == c) & (y != c)).sum().item())
        fn = int(((pred != c) & (y == c)).sum().item())

        precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
        recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0

        f1_c = (2 * precision * recall / (precision + recall)) if (precision + recall) > 0 else ________
        f1_sum += f1_c

    return float(f1_sum / ________)


def compute_metrics(logits: torch.Tensor, y: torch.Tensor, num_classes: int) -> dict:
    pred = torch.argmax(logits, dim=-1)
    return {
        "acc": accuracy(pred, y),
        "macro_f1": macro_f1(pred, y, num_classes),
    }
    

Cette implémentation de Macro-F1 est volontairement explicite (TP/FP/FN). Elle est suffisante ici et évite une dépendance externe.

Implémentez le modèle MLP dans TP4/src/models.py. Il doit prendre x et produire des logits de taille num_classes. Copiez le code et complétez uniquement les ________.

# TP4/src/models.py
import torch
import torch.nn as nn


class MLP(nn.Module):
    def __init__(self, in_dim: int, hidden_dim: int, out_dim: int, dropout: float) -> None:
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(in_dim, hidden_dim),
            nn.ReLU(),
            nn.Dropout(dropout),
            nn.Linear(hidden_dim, out_dim),
        )

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        return self.net(________)
    

Ici, on retourne des logits (pas un softmax). La loss CrossEntropyLoss s’occupe du softmax numériquement stable.

Complétez TP4/configs/baseline_mlp.yaml (hyperparamètres simples). Copiez le fichier et complétez uniquement les ________.

# TP4/configs/baseline_mlp.yaml
seed: ________
device: "cuda"
epochs: ________
lr: ________
weight_decay: ________

mlp:
  hidden_dim: ________
  dropout: ________
    

Ces valeurs sont “raisonnables par défaut”. Vous pourrez ajuster hidden_dim ou lr si vous observez une instabilité, mais ne partez pas dans une grille de recherche : le but est la comparaison MLP vs GNN.

Implémentez TP4/src/train.py pour entraîner la baseline MLP et journaliser : (i) Accuracy + Macro-F1 sur train/val/test, (ii) temps par epoch et temps total. Copiez le code et complétez uniquement les ________.

# TP4/src/train.py
from __future__ import annotations
import argparse
import yaml
import torch
import torch.nn as nn
import time

from data import load_cora
from models import MLP
from utils import set_seed, Timer, compute_metrics


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser()
    p.add_argument("--config", type=str, required=True)
    return p.parse_args()


def main() -> None:
    args = parse_args()
    cfg = yaml.safe_load(open(args.config, "r", encoding="utf-8"))

    set_seed(int(cfg["seed"]))

    device_str = cfg.get("device", "cuda")
    device = torch.device(device_str if torch.cuda.is_available() else "cpu")

    data = load_cora()
    x = data.x.to(device)
    y = data.y.to(device)

    train_mask = data.train_mask.to(device)
    val_mask = data.val_mask.to(device)
    test_mask = data.test_mask.to(device)

    model = MLP(
        in_dim=data.num_features,
        hidden_dim=int(cfg["mlp"]["hidden_dim"]),
        out_dim=data.num_classes,
        dropout=float(cfg["mlp"]["dropout"]),
    ).to(device)

    optimizer = torch.optim.Adam(
        model.parameters(),
        lr=float(cfg["lr"]),
        weight_decay=float(cfg["weight_decay"]),
    )
    criterion = nn.CrossEntropyLoss()

    epochs = int(cfg["epochs"])
    print("device:", device)
    print("epochs:", epochs)

    total_train_s = 0.0
    train_start = time.time()
    for epoch in range(1, epochs + 1):
        model.train()
        with Timer() as t:
            logits = model(________)
            loss = criterion(logits[train_mask], y[train_mask])

            optimizer.zero_grad()
            loss.backward()
            optimizer.step()
        total_train_s += t.elapsed_s

        model.eval()
        with torch.no_grad():
            logits = model(x)

            m_train = compute_metrics(logits[train_mask], y[train_mask], data.num_classes)
            m_val = compute_metrics(logits[val_mask], y[val_mask], data.num_classes)
            m_test = compute_metrics(logits[test_mask], y[test_mask], data.num_classes)

        if epoch == 1 or epoch % 20 == 0 or epoch == epochs:
            print(
                f"epoch={epoch:03d} "
                f"loss={loss.item():.4f} "
                f"train_acc={m_train['acc']:.4f} val_acc={m_val['acc']:.4f} test_acc={m_test['acc']:.4f} "
                f"train_f1={m_train['macro_f1']:.4f} val_f1={m_val['macro_f1']:.4f} test_f1={m_test['macro_f1']:.4f} "
                f"epoch_time_s={t.elapsed_s:.4f}"
            )

    print(f"total_train_time_s={total_train_s:.4f}")
    train_loop_time = time.time() - train_start
    print(f"train_loop_time={train_loop_time:.4f}")


if __name__ == "__main__":
    main()
    

Dans votre rapport, expliquez en 4–6 lignes pourquoi on calcule les métriques sur train_mask, val_mask et test_mask séparément (pas besoin de reciter le cours, restez concret “ingénieur”).

Pensez “protocole d’évaluation” : on veut suivre l’apprentissage (train), régler des choix (val), et estimer la performance finale (test) sans biais.

Oui, ce script évalue à chaque epoch : Cora est petit, c’est acceptable. Sur un gros graphe, on ferait autrement.

Exécutez l’entraînement de la baseline MLP (cluster vivement conseillé). À mettre dans le rapport : une capture (ou copie terminal) montrant : la configuration utilisée, les métriques finales (Accuracy et Macro-F1 sur test), et total_train_time_s.

Ne collez pas tout le log : gardez 20–30 lignes max (début + fin + une ligne intermédiaire).

Baseline GNN : GCN (full-batch) + comparaison perf/temps

Complétez TP4/configs/gcn.yaml pour définir les hyperparamètres de la baseline GCN. Copiez le fichier et complétez uniquement les ________.

# TP4/configs/gcn.yaml
seed: ________
device: "cuda"
epochs: ________
lr: ________
weight_decay: ________

gcn:
  hidden_dim: ________
  dropout: ________
    

On part sur des valeurs proches du MLP pour isoler l’effet “graphe”. Libre à vous d’ajuster légèrement si le modèle diverge, mais l’objectif principal est la comparaison.

Mettez à jour TP4/src/data.py pour exposer aussi edge_index (nécessaire pour GCN). Copiez le code et complétez uniquement les ________.

# TP4/src/data.py (mise à jour)
import os
from dataclasses import dataclass
import torch
from torch_geometric.datasets import Planetoid


@dataclass
class CoraData:
    x: torch.Tensor
    y: torch.Tensor
    edge_index: torch.Tensor
    train_mask: torch.Tensor
    val_mask: torch.Tensor
    test_mask: torch.Tensor
    num_features: int
    num_classes: int


def load_cora() -> CoraData:
    root = os.environ.get("PYG_DATA_ROOT", os.path.expanduser("~/.cache/pyg_data"))
    dataset = Planetoid(root=root, name=________)
    data = dataset[0]

    return CoraData(
        x=data.x,
        y=data.y,
        edge_index=________,
        train_mask=data.train_mask,
        val_mask=data.val_mask,
        test_mask=data.test_mask,
        num_features=dataset.num_node_features,
        num_classes=dataset.num_classes,
    )
    

edge_index est une liste d’arêtes au format COO : un tenseur [2, E]. Vous n’avez pas besoin de construire une matrice d’adjacence dense.

Implémentez un modèle GCN dans TP4/src/models.py avec PyG (GCNConv). Copiez le code et complétez uniquement les ________.

# TP4/src/models.py (ajout)
import torch
import torch.nn as nn
from torch_geometric.nn import GCNConv


class GCN(nn.Module):
    def __init__(self, in_dim: int, hidden_dim: int, out_dim: int, dropout: float) -> None:
        super().__init__()
        self.conv1 = GCNConv(in_dim, hidden_dim)
        self.conv2 = GCNConv(hidden_dim, out_dim)
        self.dropout = float(dropout)

    def forward(self, x: torch.Tensor, edge_index: torch.Tensor) -> torch.Tensor:
        x = self.conv1(x, edge_index)
        x = torch.relu(x)
        x = nn.functional.dropout(x, p=self.dropout, training=self.training)
        x = self.conv2(________, edge_index)
        return x
    

Ici, on reste volontairement simple : 2 couches GCN. Sur Cora, c’est un bon point de départ.

Mettez à jour TP4/src/train.py pour supporter aussi l’entraînement GCN. Pour éviter un gros refactor, vous allez ajouter un mode --model et brancher MLP/GCN. Copiez le code ci-dessous (version complète) et complétez uniquement les ________.

# TP4/src/train.py (version avec --model)
from __future__ import annotations
import argparse
import yaml
import torch
import torch.nn as nn

from data import load_cora
from models import MLP, GCN
from utils import set_seed, Timer, compute_metrics


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser()
    p.add_argument("--config", type=str, required=True)
    p.add_argument("--model", type=str, choices=["mlp", "gcn"], required=True)
    return p.parse_args()


def main() -> None:
    args = parse_args()
    cfg = yaml.safe_load(open(args.config, "r", encoding="utf-8"))

    set_seed(int(cfg["seed"]))

    device_str = cfg.get("device", "cuda")
    device = torch.device(device_str if torch.cuda.is_available() else "cpu")

    data = load_cora()
    x = data.x.to(device)
    y = data.y.to(device)
    edge_index = data.edge_index.to(device)

    train_mask = data.train_mask.to(device)
    val_mask = data.val_mask.to(device)
    test_mask = data.test_mask.to(device)

    if args.model == "mlp":
        model = MLP(
            in_dim=data.num_features,
            hidden_dim=int(cfg["mlp"]["hidden_dim"]),
            out_dim=data.num_classes,
            dropout=float(cfg["mlp"]["dropout"]),
        ).to(device)
    else:
        model = GCN(
            in_dim=data.num_features,
            hidden_dim=int(cfg["gcn"]["hidden_dim"]),
            out_dim=data.num_classes,
            dropout=float(cfg["gcn"]["dropout"]),
        ).to(device)

    optimizer = torch.optim.Adam(
        model.parameters(),
        lr=float(cfg["lr"]),
        weight_decay=float(cfg["weight_decay"]),
    )
    criterion = nn.CrossEntropyLoss()

    epochs = int(cfg["epochs"])
    print("device:", device)
    print("model:", args.model)
    print("epochs:", epochs)

    total_train_s = 0.0
    train_start = time.time()
    for epoch in range(1, epochs + 1):
        model.train()
        with Timer() as t:
            if args.model == "mlp":
                logits = model(________)
            else:
                logits = model(________, ________)

            loss = criterion(logits[train_mask], y[train_mask])

            optimizer.zero_grad()
            loss.backward()
            optimizer.step()
        total_train_s += t.elapsed_s

        model.eval()
        with torch.no_grad():
            if args.model == "mlp":
                logits = model(x)
            else:
                logits = model(x, edge_index)

            m_train = compute_metrics(logits[train_mask], y[train_mask], data.num_classes)
            m_val = compute_metrics(logits[val_mask], y[val_mask], data.num_classes)
            m_test = compute_metrics(logits[test_mask], y[test_mask], data.num_classes)

        if epoch == 1 or epoch % 20 == 0 or epoch == epochs:
            print(
                f"epoch={epoch:03d} "
                f"loss={loss.item():.4f} "
                f"train_acc={m_train['acc']:.4f} val_acc={m_val['acc']:.4f} test_acc={m_test['acc']:.4f} "
                f"train_f1={m_train['macro_f1']:.4f} val_f1={m_val['macro_f1']:.4f} test_f1={m_test['macro_f1']:.4f} "
                f"epoch_time_s={t.elapsed_s:.4f}"
            )

    print(f"total_train_time_s={total_train_s:.4f}")
    train_loop_time = time.time() - train_start
    print(f"train_loop_time={train_loop_time:.4f}")


if __name__ == "__main__":
    main()
    

Entraînez le modèle GCN (cluster GPU conseillé). Puis comparez MLP vs GCN. À mettre dans le rapport : une capture (ou copie terminal) des dernières lignes pour MLP et pour GCN, montrant : test_acc, test_f1, et total_train_time_s.

Ajoutez aussi un mini-tableau (3 lignes max) “modèle / test_acc / test_f1 / temps” (format libre).

Gardez des logs courts. Ne joignez pas de fichiers de sortie volumineux.

Expliquez brièvement (6–10 lignes) : dans ce contexte (Cora), pourquoi GCN peut dépasser (ou non) le MLP ? Restez concret : “signal du graphe”, “homophilie”, “lissage”, “features déjà fortes”, etc.

Vous pouvez mentionner que GCN exploite le voisinage et donc encode de l’information relationnelle que le MLP ignore. À l’inverse, si les features suffisent, le gain peut être faible.

Modèle principal : GraphSAGE + neighbor sampling (mini-batch)

Complétez TP4/configs/sage_sampling.yaml pour définir les hyperparamètres de GraphSAGE et du sampling. Copiez le fichier et complétez uniquement les ________.

# TP4/configs/sage_sampling.yaml
seed: ________
device: "cuda"
epochs: ________
lr: ________
weight_decay: ________

sage:
  hidden_dim: ________
  dropout: ________

sampling:
  batch_size: ________
  num_neighbors_l1: ________
  num_neighbors_l2: ________
    

Mettez à jour TP4/src/data.py pour exposer aussi l’objet PyG complet (torch_geometric.data.Data), nécessaire à NeighborLoader. Copiez le code et complétez uniquement les ________.

# TP4/src/data.py (mise à jour)
import os
from dataclasses import dataclass
import torch
from torch_geometric.datasets import Planetoid
from torch_geometric.data import Data


@dataclass
class CoraData:
    pyg_data: Data
    x: torch.Tensor
    y: torch.Tensor
    edge_index: torch.Tensor
    train_mask: torch.Tensor
    val_mask: torch.Tensor
    test_mask: torch.Tensor
    num_features: int
    num_classes: int


def load_cora() -> CoraData:
    root = os.environ.get("PYG_DATA_ROOT", os.path.expanduser("~/.cache/pyg_data"))
    dataset = Planetoid(root=root, name=________)
    data = dataset[0]

    return CoraData(
        pyg_data=________,
        x=data.x,
        y=data.y,
        edge_index=data.edge_index,
        train_mask=data.train_mask,
        val_mask=data.val_mask,
        test_mask=data.test_mask,
        num_features=dataset.num_node_features,
        num_classes=dataset.num_classes,
    )
    

Implémentez le modèle GraphSAGE dans TP4/src/models.py avec PyG (SAGEConv). Copiez le code et complétez uniquement les ________.

# TP4/src/models.py (ajout)
import torch
import torch.nn as nn
from torch_geometric.nn import SAGEConv


class GraphSAGE(nn.Module):
    def __init__(self, in_dim: int, hidden_dim: int, out_dim: int, dropout: float) -> None:
        super().__init__()
        self.conv1 = SAGEConv(in_dim, hidden_dim)
        self.conv2 = SAGEConv(hidden_dim, out_dim)
        self.dropout = float(dropout)

    def forward(self, x: torch.Tensor, edge_index: torch.Tensor) -> torch.Tensor:
        x = self.conv1(x, edge_index)
        x = torch.relu(x)
        x = nn.functional.dropout(x, p=self.dropout, training=self.training)
        x = self.conv2(________, edge_index)
        return x
    

Le même forward(x, edge_index) fonctionne en full-batch et sur un sous-graphe échantillonné. C’est ce qui rend GraphSAGE pratique avec NeighborLoader.

Mettez à jour TP4/src/train.py pour ajouter le mode --model sage et entraîner GraphSAGE en mini-batch via NeighborLoader. Copiez le code ci-dessous (version complète) et complétez uniquement les ________.

# TP4/src/train.py (ajout sage + NeighborLoader)
from __future__ import annotations
import argparse
import yaml
import torch
import torch.nn as nn

from torch_geometric.loader import NeighborLoader

from data import load_cora
from models import MLP, GCN, GraphSAGE
from utils import set_seed, Timer, compute_metrics


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser()
    p.add_argument("--config", type=str, required=True)
    p.add_argument("--model", type=str, choices=["mlp", "gcn", "sage"], required=True)
    return p.parse_args()


def build_model(args_model: str, cfg: dict, num_features: int, num_classes: int, device: torch.device):
    if args_model == "mlp":
        return MLP(
            in_dim=num_features,
            hidden_dim=int(cfg["mlp"]["hidden_dim"]),
            out_dim=num_classes,
            dropout=float(cfg["mlp"]["dropout"]),
        ).to(device)

    if args_model == "gcn":
        return GCN(
            in_dim=num_features,
            hidden_dim=int(cfg["gcn"]["hidden_dim"]),
            out_dim=num_classes,
            dropout=float(cfg["gcn"]["dropout"]),
        ).to(device)

    return GraphSAGE(
        in_dim=num_features,
        hidden_dim=int(cfg["sage"]["hidden_dim"]),
        out_dim=num_classes,
        dropout=float(cfg["sage"]["dropout"]),
    ).to(device)


def main() -> None:
    args = parse_args()
    cfg = yaml.safe_load(open(args.config, "r", encoding="utf-8"))
    set_seed(int(cfg["seed"]))

    device_str = cfg.get("device", "cuda")
    device = torch.device(device_str if torch.cuda.is_available() else "cpu")

    data = load_cora()
    pyg_data = data.pyg_data.to(device)

    x = pyg_data.x
    y = pyg_data.y
    edge_index = pyg_data.edge_index

    train_mask = pyg_data.train_mask
    val_mask = pyg_data.val_mask
    test_mask = pyg_data.test_mask

    model = build_model(args.model, cfg, data.num_features, data.num_classes, device)

    optimizer = torch.optim.Adam(
        model.parameters(),
        lr=float(cfg["lr"]),
        weight_decay=float(cfg["weight_decay"]),
    )
    criterion = nn.CrossEntropyLoss()

    epochs = int(cfg["epochs"])
    print("device:", device)
    print("model:", args.model)
    print("epochs:", epochs)

    # --- NeighborLoader only for GraphSAGE training ---
    if args.model == "sage":
        bs = int(cfg["sampling"]["batch_size"])
        n1 = int(cfg["sampling"]["num_neighbors_l1"])
        n2 = int(cfg["sampling"]["num_neighbors_l2"])
        train_loader = NeighborLoader(
            pyg_data,
            input_nodes=________,
            num_neighbors=[________, ________],
            batch_size=bs,
            shuffle=True,
        )
    else:
        train_loader = None

    total_train_s = 0.0
    train_start = time.time()
    for epoch in range(1, epochs + 1):
        model.train()

        if args.model in ["mlp", "gcn"]:
            with Timer() as t:
                if args.model == "mlp":
                    logits = model(x)
                else:
                    logits = model(x, edge_index)

                loss = criterion(logits[train_mask], y[train_mask])

                optimizer.zero_grad()
                loss.backward()
                optimizer.step()
            total_train_s += t.elapsed_s

        else:
            # GraphSAGE: mini-batch training on sampled subgraphs
            with Timer() as t:
                total_loss = 0.0
                for batch in train_loader:
                    batch = batch.to(device)

                    out = model(batch.x, batch.edge_index)

                    seed_size = int(batch.batch_size)  # nodes we asked to sample around
                    out_seed = out[:seed_size]
                    y_seed = batch.y[:seed_size]

                    loss = criterion(out_seed, y_seed)

                    optimizer.zero_grad()
                    loss.backward()
                    optimizer.step()

                    total_loss += float(loss.item())

            total_train_s += t.elapsed_s
            loss = torch.tensor(total_loss / max(1, len(train_loader)))

        # --- Evaluation (full-batch for simplicity on Cora) ---
        model.eval()
        with torch.no_grad():
            if args.model == "mlp":
                logits = model(x)
            else:
                logits = model(x, edge_index)

            m_train = compute_metrics(logits[train_mask], y[train_mask], data.num_classes)
            m_val = compute_metrics(logits[val_mask], y[val_mask], data.num_classes)
            m_test = compute_metrics(logits[test_mask], y[test_mask], data.num_classes)

        if epoch == 1 or epoch % 10 == 0 or epoch == epochs:
            print(
                f"epoch={epoch:03d} "
                f"loss={loss.item():.4f} "
                f"train_acc={m_train['acc']:.4f} val_acc={m_val['acc']:.4f} test_acc={m_test['acc']:.4f} "
                f"train_f1={m_train['macro_f1']:.4f} val_f1={m_val['macro_f1']:.4f} test_f1={m_test['macro_f1']:.4f} "
                f"epoch_time_s={t.elapsed_s:.4f}"
            )

    print(f"total_train_time_s={total_train_s:.4f}")
    train_loop_time = time.time() - train_start
    print(f"train_loop_time={train_loop_time:.4f}")


if __name__ == "__main__":
    main()
    

L’évaluation est faite en full-batch (sur tout le graphe) pour garder la comparaison simple sur Cora. Sur un très grand graphe, on ferait aussi l’inférence avec sampling/caching.

Entraînez GraphSAGE avec sampling, puis comparez MLP, GCN, GraphSAGE. À mettre dans le rapport : une capture (ou copie terminal) des dernières lignes pour GraphSAGE montrant test_acc, test_f1, total_train_time_s, et les hyperparamètres de sampling (batch_size, num_neighbors).

Évitez les logs longs : gardez quelques lignes (début + milieu + fin), et un tableau synthétique (3 lignes) des résultats.

Expliquez (8–12 lignes) le compromis “neighbor sampling” : en quoi cela accélère l’entraînement, et quel risque cela introduit sur l’estimation du gradient / la performance ? Restez concret (fanout, variance, hubs, coût CPU sampling).

Un point important : en sampling, vous ne voyez qu’un sous-ensemble des voisins par itération, ce qui rend l’apprentissage plus “bruité” mais beaucoup plus scalable. Le choix du fanout a donc un impact direct sur coût et qualité.

Benchmarks ingénieur : temps d’entraînement et latence d’inférence (CPU/GPU)

Ajoutez un dossier TP4/runs/ (pour stocker des checkpoints légers) et assurez-vous qu’il n’est pas versionné. Vous pouvez ajouter TP4/runs/ à votre .gitignore.

À mettre dans le rapport : rien (pas besoin de preuve pour le .gitignore).

Modifiez TP4/src/train.py pour sauvegarder un checkpoint léger à la fin de l’entraînement (un fichier .pt dans TP4/runs/). Copiez le patch ci-dessous et complétez uniquement les ________.

# À ajouter en fin de main(), juste avant le print final, dans TP4/src/train.py
import os

# ... après la boucle d'entraînement (après total_train_time_s)
os.makedirs(________, exist_ok=True)

ckpt_path = os.path.join(
    ________,
    f"{args.model}.pt"
)

payload = {
    "model": args.model,
    "config_path": args.config,
    "state_dict": model.state_dict(),
}
torch.save(payload, ckpt_path)
print("checkpoint_saved:", ckpt_path)
    

Un checkpoint pour ces modèles sur Cora est petit (quelques centaines de Ko). Il ne doit pas être commité.

Créez TP4/src/benchmark.py pour mesurer la latence d’inférence (forward) de chaque modèle, en chargeant le checkpoint sauvegardé. Le benchmark doit : faire quelques itérations de warmup, puis mesurer plusieurs forwards, avec synchronisation GPU. Copiez le code et complétez uniquement les ________.

# TP4/src/benchmark.py
from __future__ import annotations
import argparse
import yaml
import torch

from data import load_cora
from models import MLP, GCN, GraphSAGE
from utils import set_seed, Timer


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser()
    p.add_argument("--config", type=str, required=True)
    p.add_argument("--model", type=str, choices=["mlp", "gcn", "sage"], required=True)
    p.add_argument("--ckpt", type=str, required=True)
    return p.parse_args()


def build_model(name: str, cfg: dict, num_features: int, num_classes: int) -> torch.nn.Module:
    if name == "mlp":
        return MLP(
            in_dim=num_features,
            hidden_dim=int(cfg["mlp"]["hidden_dim"]),
            out_dim=num_classes,
            dropout=float(cfg["mlp"]["dropout"]),
        )
    if name == "gcn":
        return GCN(
            in_dim=num_features,
            hidden_dim=int(cfg["gcn"]["hidden_dim"]),
            out_dim=num_classes,
            dropout=float(cfg["gcn"]["dropout"]),
        )
    return GraphSAGE(
        in_dim=num_features,
        hidden_dim=int(cfg["sage"]["hidden_dim"]),
        out_dim=num_classes,
        dropout=float(cfg["sage"]["dropout"]),
    )


def sync_if_cuda(device: torch.device) -> None:
    if device.type == "cuda":
        torch.cuda.synchronize()


def main() -> None:
    args = parse_args()
    cfg = yaml.safe_load(open(args.config, "r", encoding="utf-8"))
    set_seed(int(cfg["seed"]))

    device = torch.device(________)

    data = load_cora()
    x = data.x.to(device)
    y = data.y.to(device)
    edge_index = data.edge_index.to(device)

    model = build_model(args.model, cfg, data.num_features, data.num_classes).to(device)
    model.eval()

    ckpt = torch.load(args.ckpt, map_location=device)
    model.load_state_dict(ckpt["state_dict"])

    # Warmup + runs
    warmup = ________
    runs = ________

    # Forward function (same signature for all models)
    def forward_once() -> torch.Tensor:
        if args.model == "mlp":
            return model(________)
        return model(________, ________)

    # Warmup (important on GPU)
    with torch.no_grad():
        for _ in range(warmup):
            _ = forward_once()
        sync_if_cuda(device)

    # Timed runs
    elapsed = 0.0
    with torch.no_grad():
        for _ in range(runs):
            sync_if_cuda(device)
            with Timer() as t:
                out = forward_once()
            sync_if_cuda(device)
            elapsed += t.elapsed_s

    avg_ms = 1000.0 * elapsed / runs
    print("model:", args.model)
    print("device:", device)
    print("avg_forward_ms:", round(avg_ms, 4))
    print("num_nodes:", int(x.shape[0]))
    print("ms_per_node_approx:", round(avg_ms / float(x.shape[0]), 8))


if __name__ == "__main__":
    main()
    

Sur GPU, sans synchronisation, vous risquez de mesurer uniquement le “temps de lancement” des kernels. La synchronisation force l’attente de fin de calcul avant de lire le chrono.

Lancez le benchmark pour les trois modèles, en utilisant les checkpoints produits après entraînement (TP4/runs/mlp.pt, TP4/runs/gcn.pt, TP4/runs/sage.pt). Exécutez de préférence sur GPU (cluster).

À mettre dans le rapport : une capture (ou copie terminal) des sorties avg_forward_ms pour les trois modèles, puis un tableau synthétique (3 lignes max) : modèle / test_acc / test_f1 / total_train_time_s / avg_forward_ms. Vous pouvez reprendre test_acc, test_f1, total_train_time_s des exercices précédents.

Ne joignez pas les checkpoints au rendu. Une capture des résultats suffit.

Expliquez (6–10 lignes) pourquoi on fait un warmup, et pourquoi on synchronise CUDA avant/après la mesure. Votre explication doit faire le lien avec l’exécution asynchrone GPU et la stabilité des mesures.

Synthèse finale : comparaison, compromis, et recommandations ingénieur

Dans votre rapport (TP4/rapport.md), ajoutez une synthèse finale (format libre) qui contient : un tableau comparatif des trois modèles et une courte discussion sur les compromis. Ne rajoutez pas de logs supplémentaires : réutilisez les résultats déjà obtenus.

Le tableau doit tenir sur quelques lignes. L’objectif est qu’un lecteur puisse décider rapidement “quel modèle choisir” selon la contrainte (qualité vs coût).

Complétez le squelette ci-dessous (à copier-coller dans votre TP4/rapport.md) en remplaçant les ________ par vos valeurs mesurées.

| Modèle      | test_acc | test_macro_f1 | total_train_time_s | train_loop_time | avg_forward_ms |
|------------|----------|---------------|--------------------|----------------|----------------|
| MLP        | ________ | ________      | ________           | ________       | ________       |
| GCN        | ________ | ________      | ________           | ________       | ________       |
| GraphSAGE  | ________ | ________      | ________           | ________       | ________       |
    

Si vos temps varient d’un run à l’autre, utilisez une valeur représentative (un run “propre”) et indiquez-le en une phrase.

Rédigez un paragraphe (8–12 lignes) “recommandation ingénieur” basé sur vos mesures, en répondant à : dans quel cas vous choisissez MLP / GCN / GraphSAGE ? Votre réponse doit s’appuyer explicitement sur au moins : (i) une métrique qualité (Accuracy ou Macro-F1), (ii) une métrique coût (train time ou latence).

Pensez “production” : si le graphe est petit et stable, GCN peut suffire ; si le graphe est grand et dynamique, GraphSAGE + sampling devient naturel. Si le graphe apporte peu de gain, un MLP est parfois le meilleur choix.

Expliquez brièvement (6–10 lignes) un risque de protocole qui pourrait fausser la comparaison entre modèles dans ce TP, et comment vous l’éviteriez dans un vrai projet (ex: seed, data leakage, mesures non comparables CPU/GPU, caching, etc.).

Vérifiez que votre dépôt contient bien TP4/ avec : rapport.md, les scripts src/, et les configs configs/, et qu’il ne contient pas de gros fichiers (datasets, checkpoints, logs massifs).

À mettre dans le rapport : une phrase confirmant que vous n’avez pas commité de fichiers volumineux (pas besoin de captures).