Premiers pas
Installation et tenseurs
Les tenseurs PyTorch sont la structure de données cœur. Utilisez to(device) pour déplacer les tenseurs vers le GPU. torch.randn retourne des nombres aléatoires d'une distribution normale. Choisissez l'URL de wheel adaptée à votre version CUDA ; les builds CPU-only sont plus petits pour le développement.
# install PyTorch (CUDA 11.8)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
import torch
# create a tensor
x = torch.tensor([[1, 2], [3, 4]])
y = torch.zeros(3, 3)
z = torch.randn(2, 3) # standard normal
# tensor on GPU
device = "cuda" if torch.cuda.is_available() else "cpu"
x = x.to(device)Attributs des tenseurs
Chaque tenseur a des attributs shape, dtype et device. Dtypes courants : float32 (défaut), float16, int64, bool. numel() retourne le nombre total d'éléments. Choisissez float16 pour la précision mixte afin de réduire la mémoire de moitié et accélérer le calcul GPU.
x = torch.randn(3, 4, 5)
print(x.shape) # torch.Size([3, 4, 5])
print(x.dtype) # torch.float32
print(x.device) # cpu or cuda:0
print(x.requires_grad) # False
# specify dtype at creation
x = torch.zeros(3, dtype=torch.int64)
x = torch.tensor([1.0, 2.0], dtype=torch.float16)
# check number of elements
print(x.numel()) # 3Création de tenseurs
torch.zeros/ones/full créent des tenseurs constants. arange et linspace créent des tenseurs de plages. rand est uniforme, randn normale. randint exclut la borne haute. Utilisez torch.manual_seed(42) avant les opérations aléatoires pour la reproductibilité.
# from Python lists
a = torch.tensor([1, 2, 3])
# special tensors
zeros = torch.zeros(2, 3)
ones = torch.ones(2, 3)
eye = torch.eye(3) # identity matrix
full = torch.full((2, 3), 7.0)
# ranges
arange = torch.arange(0, 10, 2) # [0, 2, 4, 6, 8]
linspace = torch.linspace(0, 1, 5) # [0, 0.25, 0.5, 0.75, 1.0]
# random
rand = torch.rand(2, 3) # uniform [0, 1)
randn = torch.randn(2, 3) # normal N(0, 1)
randint = torch.randint(0, 10, (3, 3))Conversion de types
to(dtype) convertit le type du tenseur. Raccourcis : .float(), .long(), .int(), .bool(). numpy() partage la mémoire avec le tenseur (zero-copy sur CPU). item() extrait un unique scalaire Python d'un tenseur 0-d. Les tenseurs GPU doivent être ramenés sur CPU avant numpy().
x = torch.tensor([1.5, 2.5, 3.5])
# change dtype
y = x.to(torch.int32) # tensor([1, 2, 3])
y = x.int() # shortcut
y = x.float()
y = x.bool()
y = x.long() # int64
# to numpy and back
arr = x.numpy() # shares memory (CPU)
t = torch.from_numpy(arr)
# 0-d tensor to Python scalar
val = x[0].item() # 1.5Indexation et slicing
L'indexation PyTorch reflète NumPy. L'indexation entière retourne un tenseur 0-d (utilisez .item() pour un scalaire Python). Les masques booléens aplatissent le résultat. Indexer avec un LongTensor sélectionne le long de la première dimension. L'indexation avancée crée des copies ; le slicing simple crée des vues.
x = torch.arange(12).reshape(3, 4)
# tensor([[ 0, 1, 2, 3],
# [ 4, 5, 6, 7],
# [ 8, 9, 10, 11]])
x[0] # first row
x[1, 2] # element at (1, 2) -> 6
x[:, 1] # second column
x[0:2] # first two rows
x[:, ::2] # every other column
# boolean mask
mask = x > 5
x[mask] # tensor([6, 7, 8, 9, 10, 11])
# index with LongTensor
idx = torch.tensor([0, 2])
x[idx] # rows 0 and 2Reformage et vues
view exige une mémoire contiguë ; reshape marche toujours (copie si nécessaire). unsqueeze/squeeze ajoutent/retirent des dimensions de taille 1. permute réordonne toutes les dimensions ; transpose en échange deux. reshape(-1) aplati. Des opérations comme permute peuvent rendre les tenseurs non contigus, exigeant .contiguous() avant view().
x = torch.arange(12)
# reshape (returns view when possible)
y = x.reshape(3, 4)
y = x.view(3, 4) # only for contiguous tensors
# add/remove dimensions
y = x.unsqueeze(0) # shape (1, 12)
y = x.squeeze() # remove size-1 dims
# transpose / permute
a = torch.randn(3, 4, 5)
b = a.permute(2, 0, 1) # shape (5, 3, 4)
b = a.transpose(0, 1) # swap dims 0 and 1
# flatten
flat = a.flatten() # shape (60,)
flat = a.reshape(-1) # equivalentOpérations sur tenseurs
Opérations arithmétiques
Les opérateurs arithmétiques (+, -, *, /) sont élément par élément. Les opérations in-place finissent par _ et économisent la mémoire mais invalident l'historique autograd — évitez-les sur les tenseurs qui requirent grad. Le broadcasting suit les règles NumPy : les dimensions finales sont appariées ou étirées à 1.
a = torch.tensor([1.0, 2.0, 3.0])
b = torch.tensor([4.0, 5.0, 6.0])
# element-wise ops
a + b # tensor([5., 7., 9.])
a * b # tensor([ 4., 10., 18.])
a / b # element-wise division
a ** 2 # tensor([1., 4., 9.])
# in-place (suffix _)
a.add_(1) # a = a + 1, modifies in place
a.mul_(2) # a = a * 2
# scalar ops
a + 10
b * 0.5Maths élément par élément
Les maths élément par élément reflètent les méthodes torch.* et tensor.*. clamp est le nom PyTorch du clipping. Utilisez torch.finfo(x.dtype).eps au lieu d'un 1e-8 codé en dur pour un log numériquement sûr. Les fonctions d'activation existent aussi en modules nn (nn.ReLU()) pour les modèles.
x = torch.tensor([-1.0, 0.0, 1.0, 2.0])
torch.abs(x) # absolute value
torch.sqrt(torch.abs(x))
torch.exp(x) # e^x
torch.log(x.abs() + 1e-8)
torch.sin(x)
torch.clamp(x, -0.5, 1.5) # clip values
# activation functions
torch.sigmoid(x) # 1 / (1 + e^-x)
torch.tanh(x)
torch.relu(x) # max(0, x)
# rounding
y = torch.tensor([1.4, 1.5, 2.6])
torch.round(y) # tensor([1., 2., 3.])
torch.floor(y)
torch.ceil(y)Opérations de réduction
Les réductions effondrent une ou plusieurs dimensions. Passez dim pour choisir l'axe ; keepdim=True garde l'axe réduit à taille 1 (critique pour le broadcasting). max/min avec un dim retournent un tuple nommé (values, indices). item() tire un tenseur 0-d vers un scalaire Python.
x = torch.arange(12).reshape(3, 4).float()
x.sum() # 66.0 (scalar tensor)
x.sum(dim=0) # sum over rows -> shape (4,)
x.sum(dim=1) # sum over columns -> shape (3,)
x.mean(dim=1)
x.max() # returns value tensor
x.max(dim=1) # returns (values, indices)
x.argmin(dim=1) # indices of min along dim
# keep dimensions
x.sum(dim=1, keepdim=True) # shape (3, 1)
# norm
x.norm() # Frobenius norm
x.norm(dim=1) # per-row normOpérations de comparaison
Les opérateurs de comparaison retournent des tenseurs booléens. torch.equal vérifie l'égalité exacte et retourne un booléen Python. torch.where(cond, x, y) est le ternaire vectorisé — parfait pour masquer ou sélectionner. topk retourne à la fois valeurs et indices, utile pour la précision top-1 / top-5.
a = torch.tensor([1, 2, 3, 4])
b = torch.tensor([3, 2, 1, 4])
a == b # tensor([False, True, False, True])
a > b # tensor([False, False, True, False])
a != b
torch.equal(a, b) # False (single bool)
# where: pick from two tensors
torch.where(a > b, a, b) # element-wise max
# boolean helpers
(a > 2).any() # True
(a > 2).all() # False
(a == b).sum() # 2 (count of True)
# top-k
torch.topk(a, 2) # returns top 2 values + indicesOpérations matricielles
@ et torch.matmul font la multiplication matricielle et broadcastent sur les dims de batch. Utilisez torch.bmm pour un matmul batché strictement 3D (sans broadcasting). einsum est expressif pour les contractions multi-tenseurs mais peut être plus lent que matmul sur certains matériels. Évitez d'inverser des matrices quand vous pouvez résoudre avec torch.solve / linalg.solve.
a = torch.randn(2, 3)
b = torch.randn(3, 4)
# matrix multiplication
c = a @ b # shape (2, 4)
c = torch.matmul(a, b) # equivalent
# batched matmul
A = torch.randn(10, 2, 3)
B = torch.randn(10, 3, 4)
C = A @ B # shape (10, 2, 4)
# element-wise product
e = a * a # shape (2, 3)
# other ops
torch.inverse(a[:, :3]) # inverse of square slice
torch.det(a[:, :3])
torch.svd(a) # singular value decomposition
torch.einsum('bi,i->b', torch.randn(5,3), torch.randn(3)) # batched dotConcaténation et empilement
cat joint des tenseurs le long d'un axe existant ; stack ajoute un nouvel axe. split divise par taille de chunk, chunk par nombre de morceaux. expand crée une vue avec données broadcastées (pas de copie mémoire) — préférez-le à repeat quand possible. repeat duplique physiquement les données.
a = torch.randn(2, 3)
b = torch.randn(2, 3)
# concat along existing dim
c = torch.cat([a, b], dim=0) # shape (4, 3)
c = torch.cat([a, b], dim=1) # shape (2, 6)
# stack along new dim
s = torch.stack([a, b], dim=0) # shape (2, 2, 3)
# split / chunk
x = torch.arange(6).reshape(2, 3)
parts = torch.split(x, 2, dim=0) # split into chunks of size 2
chunks = torch.chunk(x, 3, dim=1) # split into 3 chunks
# repeat / expand
r = a.repeat(2, 3) # repeat whole tensor
e = a.unsqueeze(0).expand(4, 2, 3) # broadcast without copyAutograd
Autograd de base
Réglez requires_grad=True pour suivre les opérations pour autograd. Appeler .backward() sur un tenseur scalaire calcule les gradients de ce tenseur par rapport à tous les tenseurs feuilles avec requires_grad=True. Les gradients s'accumulent dans .grad — appelez optimizer.zero_grad() ou x.grad=None entre les itérations.
import torch
# tensors that require gradient tracking
x = torch.tensor([2.0], requires_grad=True)
y = torch.tensor([3.0], requires_grad=True)
# build a computation graph
z = x * y + x ** 2 # z = xy + x^2
print(z.grad_fn) # <AddBackward0 object>
# backprop
z.backward()
# dz/dx = y + 2x = 3 + 4 = 7
print(x.grad) # tensor([7.])
# dz/dy = x = 2
print(y.grad) # tensor([2.])Calculer les gradients
backward() ne marche que sur des sorties scalaires ; pour des tenseurs, sommez ou moyennez d'abord. torch.autograd.grad retourne les gradients en tuple sans les stocker dans .grad. Préférable dans les bibliothèques ou quand on a besoin des gradients de tenseurs non feuilles.
import torch
x = torch.linspace(-3, 3, steps=10, requires_grad=True)
y = torch.sin(x)
# sum needed for backward on non-scalar
y.sum().backward()
print(x.grad) # cos(x)
# gradient w.r.t. intermediate tensor
a = torch.tensor(1.0, requires_grad=True)
b = a * 2
c = b ** 2
grads = torch.autograd.grad(c, a)
print(grads) # (tensor(8.),) dc/da = 4b * 2 = 8Désactiver le suivi de gradient
Utilisez torch.no_grad() pour l'inférence afin de sauter la construction du graphe — économise mémoire et temps. .detach() retourne un tenseur partageant les données mais coupé du graphe ; pratique pour logger ou alimenter du code non-PyTorch. model.eval() passe les couches (dropout, BN) en mode inférence mais ne désactive PAS autograd — combinez avec torch.no_grad().
x = torch.tensor([1.0], requires_grad=True)
# option 1: context manager (preferred)
with torch.no_grad():
y = x * 2 # y.requires_grad == False
# option 2: decorator
@torch.no_grad()
def inference(x):
return model(x)
# option 3: detach from graph
y = (x * 2).detach() # y is a new tensor, no grad
# enable grad inside no_grad
with torch.no_grad():
with torch.enable_grad():
z = x * 3 # z requires gradGradients d'ordre supérieur
create_graph=True garde le graphe du gradient lui-même pour différencier à nouveau. Utile pour les pénalités de gradient (WGAN-GP), le meta-learning et les pertes informées par la physique. Coûte de la mémoire supplémentaire — libérez les graphes intermédiaires avec retain_graph=False une fois terminé.
x = torch.tensor(0.5, requires_grad=True)
# first derivative
y = torch.sin(x)
y.backward(create_graph=True)
print(x.grad) # cos(0.5)
# second derivative (gradient of gradient)
x.grad.zero_()
g = torch.autograd.grad(torch.sin(x), x, create_graph=True)[0]
g2 = torch.autograd.grad(g, x)[0]
print(g2) # -sin(0.5)
# practical use: penalize gradient (e.g. gradient penalty)
loss = g.norm()Hooks de gradient
register_hook sur un tenseur permet d'inspecter ou modifier son gradient pendant le backward — pratique pour déboguer les NaN ou implémenter un clipping de gradient sur des tenseurs précis. register_full_backward_hook sur un module voit les gradients d'entrée et de sortie. Retournez toujours un gradient modifié si vous voulez que les changements se propagent.
x = torch.tensor([1.0, 2.0], requires_grad=True)
y = (x ** 2).sum()
# full backward hook on a tensor
def print_grad(grad):
print("grad:", grad)
return grad * 2 # can modify gradient
y.register_hook(print_grad)
y.backward()
print(x.grad) # 2x but doubled by hook
# module hook
def hook_fn(module, grad_input, grad_output):
print(module.__class__.__name__, grad_output)
model.layer.register_full_backward_hook(hook_fn)Détails du graphe de calcul
Les tenseurs feuilles sont créés par l'utilisateur (requires_grad=True, sans grad_fn). Les résultats intermédiaires sont non feuilles. Par défaut, le graphe est libéré après backward() ; passez retain_graph=True pour appeler backward plusieurs fois. create_graph=True retient le graphe du gradient pour les dérivées d'ordre supérieur. La mémoire croît vite — nettoyez avec x.grad=None entre les itérations.
x = torch.tensor(2.0, requires_grad=True)
w = torch.tensor(3.0, requires_grad=True)
b = torch.tensor(1.0, requires_grad=True)
y = w * x + b
print(y.is_leaf) # False
print(x.is_leaf) # True
# retain graph for multiple backward passes
loss = (y - 5) ** 2
loss.backward(retain_graph=True)
# can call backward again
loss.backward()
# double backward
loss.backward(create_graph=True)
print(x.grad)Chargement des données
Dataset et DataLoader
DataLoader batche, mélange et charge en parallèle un Dataset. num_workers>0 utilise des sous-processus — réglez 2 à 8 par GPU. pin_memory=True accélère le transfert CPU→GPU. Pour les petits jeux qui tiennent en RAM, réglez num_workers=0 pour éviter l'overhead.
from torch.utils.data import Dataset, DataLoader
# built-in datasets
from torchvision import datasets
mnist = datasets.MNIST("./data", train=True, download=True)
# wrap in DataLoader
loader = DataLoader(
mnist,
batch_size=64,
shuffle=True,
num_workers=4,
pin_memory=True,
)
for x, y in loader:
print(x.shape, y.shape) # (64, 1, 28, 28), (64,)
breakÉchantillonnage de batchs
Passez un batch_sampler pour contrôler exactement quels indices forment chaque batch. WeightedRandomSampler rééquilibre les classes déséquilibrées en suréchantillonnant les rares. drop_last=True jette le dernier batch court — important pour la stabilité du BatchNorm. Les samplers itèrent sur les indices ; le DataLoader va chercher les vraies données.
from torch.utils.data import DataLoader, BatchSampler, RandomSampler
dataset = list(range(100))
sampler = RandomSampler(dataset)
batch_sampler = BatchSampler(sampler, batch_size=10, drop_last=True)
loader = DataLoader(dataset, batch_sampler=batch_sampler)
# custom sampler
class EvenSampler:
def __init__(self, data): self.data = data
def __iter__(self): return iter(range(0, len(self.data), 2))
def __len__(self): return len(self.data) // 2
# weighted sampling for imbalanced classes
from torch.utils.data import WeightedRandomSampler
weights = [0.1] * 50 + [1.0] * 50
sampler = WeightedRandomSampler(weights, num_samples=100)Mélange et échantillonnage
shuffle=True randomise l'ordre à chaque époque (bien pour l'entraînement) ; gardez validation shuffle=False pour des métriques reproductibles. random_split est pratique mais son RNG n'est pas directement seedable — utilisez Subset avec torch.randperm et un Generator pour un contrôle total. Subset n'est qu'une fine vue d'indices, pas de copie de données.
from torch.utils.data import DataLoader, random_split
# train/val split
train, val = random_split(dataset, [80, 20])
train_loader = DataLoader(train, batch_size=16, shuffle=True)
val_loader = DataLoader(val, batch_size=32, shuffle=False)
# reproducible split
from torch.utils.data import Subset
import numpy as np
gen = torch.Generator().manual_seed(42)
idx = torch.randperm(len(dataset), generator=gen).tolist()
train_idx, val_idx = idx[:80], idx[80:]
train, val = Subset(dataset, train_idx), Subset(dataset, val_idx)Collate personnalisé
collate_fn transforme une liste d'échantillons en batch. Le défaut empile les tenseurs le long d'une nouvelle dim 0. Surchargez-le pour les séquences de longueur variable (bourrez puis triez par longueur pour pack_padded_sequence), les échantillons en dict, ou les données mixtes tenseur/non-tenseur. Gardez la fonction légère — elle tourne sur les workers de chargement.
from torch.utils.data import default_collate
# variable-length sequences: pad in collate
def pad_collate(batch):
# batch is list of (tensor, label)
seqs, labels = zip(*batch)
lens = torch.tensor([len(s) for s in seqs])
max_len = lens.max()
padded = torch.zeros(len(seqs), max_len)
for i, s in enumerate(seqs):
padded[i, :len(s)] = s
return padded, lens, torch.tensor(labels)
loader = DataLoader(dataset, batch_size=4, collate_fn=pad_collate)
# stack batch as dict
def dict_collate(batch):
return default_collate(batch)Chargement parallèle
num_workers parallélise le chargement pour que le GPU n'attende jamais. persistent_workers=True évite le coût de démarrage des workers à chaque époque. prefetch_factor (défaut 2) contrôle combien de batchs chaque worker prépare en avance. Sous Windows et Jupyter, le multiprocessing peut être capricieux — retombez à num_workers=0 pour déboguer. Attention : chaque worker hérite de tout l'état du processus, y compris handles de fichiers ouverts et contextes CUDA.
loader = DataLoader(
dataset,
batch_size=128,
num_workers=8, # one process per worker
pin_memory=True, # page-locked memory for fast H2D copy
persistent_workers=True, # keep workers alive across epochs
prefetch_factor=4, # batches prefetched per worker
)
# avoid CPU bottleneck
import os
os.cpu_count() # check available cores
# in Jupyter / Windows: set start method
import torch.multiprocessing as mp
# mp.set_start_method('spawn') # uncomment if needednn.Module
Définir un module
Sous-classez nn.Module et implémentez forward(). Déclarez sous-modules et paramètres comme attributs pour qu'ils s'enregistrent automatiquement (c'est ce qui permet .to(device), .parameters() et state_dict). Appelez toujours super().__init__(). Évitez la logique Python arbitraire dans forward — gardez-le différentiable et à base de tenseurs seulement.
import torch.nn as nn
class MLP(nn.Module):
def __init__(self, in_dim, hidden, out_dim):
super().__init__()
self.fc1 = nn.Linear(in_dim, hidden)
self.fc2 = nn.Linear(hidden, hidden)
self.fc3 = nn.Linear(hidden, out_dim)
self.act = nn.ReLU()
def forward(self, x):
x = self.act(self.fc1(x))
x = self.act(self.fc2(x))
return self.fc3(x) # logits
model = MLP(784, 128, 10)
print(model) # prints structureCouches linéaires et activations
nn.Linear applique y = xW^T + b. La forme du poids est (out, in). Préférez les modules d'activation quand vous voulez qu'ils s'enregistrent (state_dict, hooks) ; utilisez le fonctionnel F.* pour des ops ponctuelles. Les activations GELU et style SwiGLU dominent les architectures transformer. Softmax devrait généralement être omis du modèle et confié à CrossEntropyLoss.
import torch.nn as nn
linear = nn.Linear(in_features=20, out_features=10, bias=True)
print(linear.weight.shape) # (10, 20)
print(linear.bias.shape) # (10,)
# common activations
nn.ReLU() # max(0, x)
nn.LeakyReLU(0.01)
nn.GELU() # smooth, used in transformers
nn.Sigmoid() # (0, 1)
nn.Tanh() # (-1, 1)
nn.Softmax(dim=1)
nn.ELU()
# functional API (no parameters)
import torch.nn.functional as F
out = F.relu(linear(x)) # same as nn.ReLU()(linear(x))Paramètres et sous-modules
named_parameters() produit (nom, tenseur) pour tout l'arbre — pratique pour geler, la weight decay ou le débogage. .modules() recurse dans les enfants ; .children() un seul niveau. Les buffers (ex. stats courantes du BatchNorm) apparaissent dans state_dict mais pas dans parameters() ; utilisez named_buffers() pour les voir.
model = MLP(784, 128, 10)
# iterate parameters
for name, p in model.named_parameters():
print(name, p.shape, p.requires_grad)
# only trainable params
trainable = filter(lambda p: p.requires_grad, model.parameters())
# count parameters
n_params = sum(p.numel() for p in model.parameters())
print(f"{n_params:,} parameters")
# access submodules by name
model.fc1 # the Linear layer
model['fc1'] # equivalent if using nn.ModuleDict
# children vs modules
list(model.children()) # direct children
list(model.modules()) # recursively all sub-modulesModèles séquentiels
nn.Sequential enchaîne des modules où chaque sortie alimente l'entrée suivante — parfait pour les pipelines linéaires. Utilisez OrderedDict pour nommer les étapes et indexer par attribut (model.fc1). Pour des modèles à branches, skip connections ou entrées/sorties multiples, sous-classez nn.Module et écrivez forward() explicitement.
import torch.nn as nn
# simple stack
model = nn.Sequential(
nn.Linear(784, 256),
nn.ReLU(),
nn.Dropout(0.5),
nn.Linear(256, 10),
)
# named layers via OrderedDict
from collections import OrderedDict
model = nn.Sequential(OrderedDict([
('fc1', nn.Linear(784, 256)),
('relu', nn.ReLU()),
('dropout', nn.Dropout(0.5)),
('fc2', nn.Linear(256, 10)),
]))
print(model.fc1) # access by name
# append at runtime
model.append(nn.Softmax(dim=1))Méthodes de module
to(device) déplace paramètres et buffers ; .double()/.half()/.float() castent les dtypes. train()/eval() basculent le flag self.training — Dropout et BatchNorm branchent dessus. state_dict() retourne un OrderedDict de tous les paramètres et buffers ; load_state_dict les restaure. .apply(fn) recurse dans tous les sous-modules, utile pour l'initialisation custom.
model = MLP(784, 128, 10)
# move to device / dtype
model = model.to('cuda')
model = model.to(torch.float16)
# train vs eval mode
model.train() # enable dropout, update BN stats
model.eval() # disable dropout, freeze BN stats
# state dict
sd = model.state_dict()
model.load_state_dict(sd)
# apply a function to all submodules
model.apply(lambda m: print(type(m).__name__))
# set requires_grad on all parameters
for p in model.parameters():
p.requires_grad_(False)Initialisation
PyTorch utilise l'init de Kaiming He pour Linear/Conv par défaut, ce qui convient à la plupart des cas. Surchargez avec les fonctions torch.nn.init (le suffixe _ signifie in-place). Kaiming convient à la famille ReLU ; Xavier/Glorot à tanh/sigmoid. Initialiser les biais à zéro est standard. .apply(fn) exécute fn sur chaque sous-module — parfait pour l'initialisation en masse ou la réinitialisation des poids.
import torch.nn as nn
import torch.nn.init as init
class Net(nn.Module):
def __init__(self):
super().__init__()
self.fc1 = nn.Linear(100, 50)
self.fc2 = nn.Linear(50, 10)
self._init_weights()
def _init_weights(self):
init.kaiming_normal_(self.fc1.weight, nonlinearity='relu')
init.zeros_(self.fc1.bias)
init.xavier_uniform_(self.fc2.weight)
init.zeros_(self.fc2.bias)
# apply to existing model
def init_all(m):
if isinstance(m, nn.Linear):
init.kaiming_normal_(m.weight)
if m.bias is not None:
init.zeros_(m.bias)
model.apply(init_all)Fonctions de perte
CrossEntropyLoss
CrossEntropyLoss applique log-softmax + NLLLoss en interne — passez des logits bruts, jamais des sorties softmax. Les cibles sont des indices de classe entiers (pas du one-hot). Utilisez weight pour les classes déséquilibrées et ignore_index=-100 pour masquer les tokens de padding. label_smoothing=0.1 est un régularisateur populaire pour la classification et le NLP.
import torch
import torch.nn as nn
# logits shape (N, C), targets shape (N,) with class indices
logits = torch.randn(4, 3) # 4 samples, 3 classes
targets = torch.tensor([0, 2, 1, 0])
criterion = nn.CrossEntropyLoss()
loss = criterion(logits, targets)
# equivalently, combine LogSoftmax + NLLLoss
log_softmax = nn.LogSoftmax(dim=1)
nll = nn.NLLLoss()
loss2 = nll(log_softmax(logits), targets)
# weight classes (handle imbalance)
weights = torch.tensor([1.0, 2.0, 1.0])
criterion = nn.CrossEntropyLoss(weight=weights)
# ignore padding index (NLP)
criterion = nn.CrossEntropyLoss(ignore_index=-100)MSELoss et L1Loss
MSELoss pénalise les grandes erreurs quadratiquement (sensible aux valeurs aberrantes) ; L1 est linéaire et plus robuste. SmoothL1Loss se comporte comme L2 près de zéro et L1 loin — utilisée en détection d'objets (Fast R-CNN). reduction='none' retourne un tenseur par élément pour que vous puissiez le masquer ou pondérer vous-même avant .mean().
import torch.nn as nn
pred = torch.randn(4, 1)
target = torch.randn(4, 1)
# mean squared error (L2)
mse = nn.MSELoss()
loss = mse(pred, target) # mean over all elements
# L1 (mean absolute error)
l1 = nn.L1Loss()
loss = l1(pred, target)
# smooth L1 (Huber) — robust to outliers
smooth = nn.SmoothL1Loss(beta=0.1)
# reduction options
mse_sum = nn.MSELoss(reduction='sum')
mse_none = nn.MSELoss(reduction='none') # per-elementBCELoss et BCEWithLogitsLoss
Préférez toujours BCEWithLogitsLoss à BCELoss+sigmoid — elle utilise l'astuce log-sum-exp pour la stabilité numérique. pos_weight multiplie le terme positif pour contrer le déséquilibre des classes (comme une focal loss allégée). Pour la classification multi-labels (chaque classe indépendante), utilisez BCEWithLogitsLoss avec forme (N, C) et sorties sigmoid.
import torch.nn as nn
# binary classification, multi-label, or sigmoid outputs
logits = torch.randn(4, 1)
target = torch.tensor([[1.0], [0.0], [1.0], [0.0]])
# preferred: combines sigmoid + BCE, numerically stable
criterion = nn.BCEWithLogitsLoss()
loss = criterion(logits, target)
# BCELoss expects probabilities (apply sigmoid first)
criterion = nn.BCELoss()
probs = torch.sigmoid(logits)
loss = criterion(probs, target)
# positive weight for imbalanced binary tasks
pos_weight = torch.tensor([5.0])
criterion = nn.BCEWithLogitsLoss(pos_weight=pos_weight)Fonction de perte personnalisée
Une perte custom est simplement une fonction (ou nn.Module) qui retourne un tenseur scalaire — autograd gère le reste. Rendez chaque opération différentiable (torch.where avec branches différentiables convient). La forme module est préférée quand vous avez besoin d'hyperparamètres, de sérialisation ou de l'enregistrer dans une config. Gardez la réduction explicite (mean/sum/none) pour un comportement prévisible.
import torch
import torch.nn as nn
import torch.nn.functional as F
# as a function
def huber_loss(pred, target, delta=1.0):
error = pred - target
abs_err = error.abs()
quad = torch.where(abs_err <= delta,
0.5 * error ** 2,
delta * (abs_err - 0.5 * delta))
return quad.mean()
# as a module (so it can have parameters / state)
class FocalLoss(nn.Module):
def __init__(self, alpha=0.25, gamma=2.0):
super().__init__()
self.alpha = alpha
self.gamma = gamma
def forward(self, logits, targets):
bce = F.binary_cross_entropy_with_logits(logits, targets, reduction='none')
p = torch.sigmoid(logits)
pt = p * targets + (1 - p) * (1 - targets)
loss = self.alpha * (1 - pt) ** self.gamma * bce
return loss.mean()
criterion = FocalLoss()Réduction et combinaison des pertes
reduction='none' donne des pertes par échantillon pour masquer, repondérer ou agréger manuellement. Combinez les pertes multi-tâches par somme pondérée — les poids équilibrent les gradients, pas seulement les magnitudes (réglez-les). Chaque sous-perte doit rester différentiable et sur le même device/dtype. Détachez un terme de perte avec .detach() pour le logger sans rétropropager à travers lui.
import torch.nn as nn
import torch
criterion = nn.CrossEntropyLoss(reduction='none')
loss_per = criterion(logits, targets) # shape (N,)
loss = loss_per.mean()
# class-wise mask
mask = targets != -100
loss = criterion(logits[mask], targets[mask])
# multi-task loss
loss_cls = nn.CrossEntropyLoss()(logits, labels)
loss_box = nn.L1Loss()(boxes_pred, boxes_gt)
total = 1.0 * loss_cls + 0.5 * loss_box
# gradient-weighted
total = loss_cls + 0.5 * loss_box
total.backward()NLLLoss et autres pertes
NLLLoss + LogSoftmax est mathématiquement identique à CrossEntropyLoss mais permet de réutiliser les log-probs. TripletMarginLoss entraîne des embeddings de métrique. KLDivLoss attend des log-probs en entrée et des probs en cible. CTCLoss aligne des séquences non segmentées aux cibles — passez input_lengths et target_lengths pour éviter des erreurs à l'exécution.
import torch.nn as nn
# NLLLoss expects log-probabilities (use LogSoftmax first)
log_probs = torch.log_softmax(logits, dim=1)
loss = nn.NLLLoss()(log_probs, targets)
# triplet loss for embeddings
anchor = torch.randn(4, 128)
positive = torch.randn(4, 128)
negative = torch.randn(4, 128)
loss = nn.TripletMarginLoss(margin=1.0)(anchor, positive, negative)
# KL divergence (distributions)
loss = nn.KLDivLoss(reduction='batchmean')(log_probs, target_dist)
# cosine embedding loss
loss = nn.CosineEmbeddingLoss()(x1, x2, torch.tensor([1, -1, 1, -1]))
# CTCLoss for sequence alignment (ASR/OCR)
loss = nn.CTCLoss(blank=0, zero_infinity=True)(log_probs, targets, in_lens, out_lens)Optimiseurs
SGD
SGD + momentum reste un choix de premier plan pour l'entraînement CNN à grands batchs et généralise mieux qu'Adam sur certaines tâches. Momentum 0.9 standard ; Nesterov apporte un petit plus. weight_decay ajoute la régularisation L2. SGD exige une planification de LR soignée et du warmup ; il n'auto-règle pas comme Adam.
import torch.optim as optim
# basic SGD
optimizer = optim.SGD(model.parameters(), lr=0.01)
# SGD with momentum (classic: 0.9)
optimizer = optim.SGD(model.parameters(), lr=0.01, momentum=0.9)
# Nesterov momentum
optimizer = optim.SGD(
model.parameters(),
lr=0.01,
momentum=0.9,
nesterov=True,
)
# weight decay (L2 regularization)
optimizer = optim.SGD(model.parameters(), lr=0.01, momentum=0.9, weight_decay=1e-4)Adam et AdamW
Adam stocke des moments par paramètre, donc il adapte le pas automatiquement — excellent défaut pour le NLP et les petits jeux. AdamW découple la weight decay de la mise à jour du gradient, ce qui compte à l'échelle (transformers). betas=(0.9, 0.999) standard ; certains modèles vision utilisent (0.9, 0.95). Utilisez des groupes de paramètres pour des taux d'apprentissage différentiels en transfer learning.
import torch.optim as optim
# Adam — adaptive, default-friendly
optimizer = optim.Adam(model.parameters(), lr=1e-3)
# AdamW — decoupled weight decay (preferred for transformers)
optimizer = optim.AdamW(
model.parameters(),
lr=3e-4,
betas=(0.9, 0.999),
weight_decay=0.01,
)
# per-parameter group settings
optimizer = optim.Adam([
{'params': model.encoder.parameters(), 'lr': 1e-4},
{'params': model.head.parameters(), 'lr': 1e-3},
], lr=1e-3)Motif de pas de l'optimiseur
Le motif à 3 étapes — zero_grad, backward, step — est le cœur de l'entraînement PyTorch. set_to_none=True (défaut dans les versions récentes) est plus rapide que remplir de zéros car il saute un memset et laisse l'optimiseur sauter le paramètre. Éditez manuellement p.grad.data entre backward() et step() pour le clipping ou des mises à jour custom.
optimizer = optim.Adam(model.parameters(), lr=1e-3)
# standard training step
optimizer.zero_grad() # clear old grads
loss = criterion(model(x), y)
loss.backward() # compute gradients
optimizer.step() # update parameters
# set gradients to None (faster, recommended)
optimizer.zero_grad(set_to_none=True)
# manual gradient modification
for p in model.parameters():
if p.grad is not None:
p.grad.data.clamp_(-1, 1) # gradient clipping
optimizer.step()Clipping de gradient
clip_grad_norm_ remet à l'échelle les gradients si leur norme L2 globale dépasse max_norm — un défaut stable pour les RNN et transformers. clip_grad_value_ borne durement chaque élément (moins courant). Le clipping prévient l'explosion des gradients sans changer la direction. Loggez la norme de gradient pré-clip pour détecter l'instabilité tôt (des pics soudains > 100 signalent des problèmes).
# gradient norm clipping (most common)
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
# gradient value clipping
torch.nn.utils.clip_grad_value_(model.parameters(), clip_value=0.5)
# in a training loop
optimizer.zero_grad()
loss = criterion(model(x), y)
loss.backward()
torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
optimizer.step()
# inspect gradient norm
total_norm = torch.norm(torch.stack([
p.grad.norm(2) for p in model.parameters() if p.grad is not None
]), 2)Taux d'apprentissage et plannings
Chaque param_group a son propre lr — itérez pour les régler tous. Le warmup manuel rampe le LR linéairement sur les N premiers pas pour stabiliser le début d'entraînement (critique pour les transformers sans correction de biais). Utilisez un objet scheduler (section suivante) pour la décroissance cosinus, OneCycle, etc. Step toujours le scheduler après optimizer.step() sauf indication contraire de la doc.
import torch.optim as optim
# get / set learning rate
for g in optimizer.param_groups:
print(g['lr'])
g['lr'] = 1e-4
# manual warmup
for step in range(warmup_steps):
lr = base_lr * (step + 1) / warmup_steps
for g in optimizer.param_groups:
g['lr'] = lr
# optimizer also accepts schedulers (see lr-scheduler section)
from torch.optim.lr_scheduler import StepLR
scheduler = StepLR(optimizer, step_size=10, gamma=0.1)Autres optimiseurs
RMSprop est l'optimiseur RNN classique et marche toujours bien. Adagrad accumule les gradients au carré et peut caler tôt — bien pour des caractéristiques sparses, pas pour les nets profonds. LBFGS exige une closure et une évaluation full-batch — génial pour les petits problèmes convexes ou le fine-tuning, trop lent pour les grands nets profonds. Pour la plupart des nouveaux projets, commencez par AdamW.
import torch.optim as optim
# RMSprop — good for RNNs
optim.RMSprop(model.parameters(), lr=1e-3, alpha=0.99)
# Adagrad — adapts per-parameter, accumulates squared grads
optim.Adagrad(model.parameters(), lr=1e-2)
# Adadelta — Adagrad variant with running average
optim.Adadelta(model.parameters(), rho=0.9)
# LBFGS — full-batch quasi-Newton, second-order
optim.LBFGS(model.parameters(), lr=1.0, max_iter=20)
# NAdam — Nesterov-accelerated Adam
optim.NAdam(model.parameters(), lr=1e-3)Boucle d'entraînement
Boucle d'entraînement simple
La boucle minimale : zero_grad, forward, loss, backward, step. Déplacez les données vers le GPU dans la boucle (chevauchement asynchrone avec num_workers). loss.item() tire un scalaire vers Python — faites-le pour le logging, pas sur le tenseur de perte lui-même (vous casseriez le graphe). Enveloppez la boucle dans une fonction pour la réutiliser.
model = MLP(784, 128, 10).to(device)
optimizer = optim.Adam(model.parameters(), lr=1e-3)
criterion = nn.CrossEntropyLoss()
for epoch in range(epochs):
model.train()
for x, y in train_loader:
x, y = x.to(device), y.to(device)
optimizer.zero_grad()
logits = model(x)
loss = criterion(logits, y)
loss.backward()
optimizer.step()
print(f"epoch {epoch}, loss={loss.item():.4f}")Validation dans la boucle
model.eval() + torch.no_grad() sont tous deux requis : eval bascule dropout/BN, no_grad saute le graphe. Accumulez la perte pondérée (multipliez par la taille de batch) pour que la moyenne soit correcte même sur le dernier batch court. argmax(dim=1) donne les indices de classe prédits. Sauvegardez le meilleur modèle quand la métrique de validation progresse (voir section save-load).
for epoch in range(epochs):
model.train()
for x, y in train_loader:
# ... training step ...
# validation
model.eval()
val_loss, correct, total = 0.0, 0, 0
with torch.no_grad():
for x, y in val_loader:
x, y = x.to(device), y.to(device)
logits = model(x)
val_loss += criterion(logits, y).item() * x.size(0)
correct += (logits.argmax(1) == y).sum().item()
total += x.size(0)
print(f"val_loss={val_loss/total:.4f}, acc={correct/total:.4f}")Accumulation de gradients
L'accumulation de gradients simule un batch plus grand en sommant les gradients de plusieurs mini-batchs avant de stepper. Divisez la perte par accum_steps pour que le gradient effectif corresponde à un seul grand batch. Assurez-vous que la longueur du dataset est divisible par accum_steps, ou steppes sur les gradients restants à la fin de l'époque. Surtout utile pour le fine-tuning de transformers sur un seul GPU.
accum_steps = 4
optimizer.zero_grad()
for i, (x, y) in enumerate(train_loader):
x, y = x.to(device), y.to(device)
loss = criterion(model(x), y) / accum_steps
loss.backward()
if (i + 1) % accum_steps == 0:
optimizer.step()
optimizer.zero_grad()
# equivalent effective batch = accum_steps * batch_size
# useful when GPU memory limits batch sizeEntraînement en précision mixte
La précision mixte exécute les ops du forward en float16 (ou bfloat16 sur Ampere+) pour un gain de 1,5 à 3x et la moitié de la mémoire. GradScaler multiplie la perte pour prévenir l'underflow des gradients float16, puis unscale avant optimizer.step(). Sur H100/A100 préférez bfloat16 — même plage que float32 et pas besoin de scaler. Le gestionnaire de contexte autocast n'affecte que le forward.
from torch.amp import autocast, GradScaler
scaler = GradScaler('cuda')
for x, y in train_loader:
x, y = x.to(device), y.to(device)
optimizer.zero_grad()
with autocast('cuda'):
logits = model(x)
loss = criterion(logits, y)
scaler.scale(loss).backward()
scaler.step(optimizer)
scaler.update()
# autocast casts select ops to float16/bf16 for speed
# GradScaler prevents underflow by scaling the lossProgression et logging
tqdm montre une barre de progression live — utilisez set_postfix pour afficher la perte courante. Une moyenne mobile exponentielle (running = 0.9*running + 0.1*loss) lisse le bruit mieux que la valeur brute du dernier batch. Pour des runs sérieux, loggez vers TensorBoard ou Weights & Biases plutôt que stdout pour comparer les runs. Évitez de logger à chaque pas si cela ralentit l'entraînement.
from tqdm import tqdm
for epoch in range(epochs):
model.train()
pbar = tqdm(train_loader, desc=f"epoch {epoch}")
running = 0.0
for i, (x, y) in enumerate(pbar):
x, y = x.to(device), y.to(device)
optimizer.zero_grad()
loss = criterion(model(x), y)
loss.backward()
optimizer.step()
running = 0.9 * running + 0.1 * loss.item()
pbar.set_postfix(loss=f"{running:.4f}")
# TensorBoard logging (see visualization section)
writer.add_scalar('train/loss', loss.item(), global_step)Reproductibilité
La reproductibilité totale exige des graines pour Python, NumPy, PyTorch CPU et CUDA. cudnn.deterministic=True désactive les algorithmes non déterministes (certaines ops conv backward). Les workers de DataLoader exigent chacun un seed via worker_init_fn car ils forkent avec leur propre état RNG. Même alors, multi-GPU et certaines ops cuDNN peuvent ne pas être bit-reproductibles — visez la reproductibilité statistique.
import torch, numpy as np, random
def set_seed(seed=42):
random.seed(seed)
np.random.seed(seed)
torch.manual_seed(seed)
torch.cuda.manual_seed_all(seed)
# cudnn determinism (may slow down)
torch.backends.cudnn.deterministic = True
torch.backends.cudnn.benchmark = False
set_seed(42)
# DataLoader worker seeding
def seed_worker(worker_id):
worker_seed = torch.initial_seed() % 2**32
np.random.seed(worker_seed)
random.seed(worker_seed)
g = torch.Generator().manual_seed(42)
loader = DataLoader(ds, batch_size=32, worker_init_fn=seed_worker, generator=g)Évaluation et métriques
Mode eval et no_grad
Accouplez toujours model.eval() à torch.no_grad() pour l'évaluation. eval() bascule dropout et BatchNorm en mode inférence (le BN utilise les stats courantes) ; no_grad() désactive autograd pour économiser mémoire et temps. Multipliez la perte par la taille de batch en accumulant pour que la moyenne finale soit non biaisée même si le dernier batch est court.
model.eval()
test_loss, correct, total = 0.0, 0, 0
with torch.no_grad():
for x, y in test_loader:
x, y = x.to(device), y.to(device)
logits = model(x)
test_loss += criterion(logits, y).item() * x.size(0)
preds = logits.argmax(dim=1)
correct += (preds == y).sum().item()
total += x.size(0)
print(f"test_loss={test_loss/total:.4f}, acc={correct/total:.4f}")Exactitude et top-k
argmax(dim=1) retourne la classe prédite par ligne. topk retourne les k plus grandes valeurs et leurs indices — les comparer aux cibles étendues en (N,1) avec .any(dim=1) donne la justesse top-k. La précision par classe expose les problèmes de déséquilibre que l'exactitude globale cache. Déplacez toujours les tenseurs vers CPU et appelez .item() avant print ou log.
logits = torch.randn(8, 10)
targets = torch.randint(0, 10, (8,))
# top-1 accuracy
preds = logits.argmax(dim=1)
acc = (preds == targets).float().mean().item()
# top-k accuracy
topk = 3
_, idx = logits.topk(topk, dim=1) # shape (N, k)
correct = idx.eq(targets.view(-1, 1)).any(dim=1)
topk_acc = correct.float().mean().item()
# per-class accuracy
for c in range(10):
mask = targets == c
print(c, (preds[mask] == targets[mask]).float().mean().item())Matrice de confusion
Accumulez les prédictions sur GPU, puis déplacez vers CPU une fois à la fin pour éviter les syncs par batch. confusion_matrix montre où le modèle confond les classes — parfait pour le débogage. classification_report donne précision, rappel et F1 par classe. Pour les très grands jeux, streamez les prédictions sur disque plutôt que de les garder en mémoire.
from sklearn.metrics import confusion_matrix, classification_report
import numpy as np
all_preds, all_labels = [], []
model.eval()
with torch.no_grad():
for x, y in test_loader:
logits = model(x.to(device))
all_preds.append(logits.argmax(1).cpu())
all_labels.append(y)
preds = torch.cat(all_preds).numpy()
labels = torch.cat(all_labels).numpy()
cm = confusion_matrix(labels, preds)
print(cm)
print(classification_report(labels, preds))Précision, rappel et F1
torchmetrics accumule l'état entre batchs et calcule la métrique correctement même avec déséquilibre ou tailles de batch variables. average='macro' traite toutes les classes également ; 'weighted' pondère par support ; 'micro' égale l'exactitude pour les tâches mono-label. Appelez .reset() entre époques ou évaluations pour vider l'accumulateur.
from torchmetrics import Accuracy, Precision, Recall, F1Score
acc = Accuracy(task='multiclass', num_classes=10).to(device)
prec = Precision(task='multiclass', num_classes=10, average='macro').to(device)
rec = Recall(task='multiclass', num_classes=10, average='macro').to(device)
f1 = F1Score(task='multiclass', num_classes=10, average='macro').to(device)
model.eval()
with torch.no_grad():
for x, y in test_loader:
logits = model(x.to(device))
preds = logits.argmax(1)
acc.update(preds, y.to(device))
prec.update(preds, y.to(device))
print(acc.compute(), prec.compute(), f1.compute())Validation croisée
La validation croisée k-fold donne une estimation robuste de la performance du modèle et de sa variance. Ré-instanciez le modèle par fold pour que les poids ne fuient pas entre folds. Pour les grands jeux, 5 folds suffisent généralement ; pour les petits, utilisez des découpes stratifiées (StratifiedKFold) pour préserver l'équilibre des classes. Rapportez moyenne +/- écart-type pour que les lecteurs voient la stabilité.
from sklearn.model_selection import KFold
kfold = KFold(n_splits=5, shuffle=True, random_state=42)
fold_accs = []
for fold, (train_idx, val_idx) in enumerate(kfold.split(dataset)):
train = torch.utils.data.Subset(dataset, train_idx)
val = torch.utils.data.Subset(dataset, val_idx)
model = build_model() # fresh model per fold
train_model(model, train) # your training function
acc = evaluate(model, val)
fold_accs.append(acc)
print(f"fold {fold}: acc={acc:.4f}")
print(f"mean={np.mean(fold_accs):.4f} +/- {np.std(fold_accs):.4f}")Comparaison de modèles
Comparez toujours les modèles sur le même jeu de test retenu avec la même graine et métrique. Au-delà de l'exactitude, regardez la calibration, la latence d'inférence et la mémoire. Utilisez des intervalles de confiance bootstrap quand les différences sur le test sont faibles. Gardez une table de résultats (CSV ou W&B) pour comparer contre les expériences futures, pas seulement le dernier run.
results = {}
for name, model in models.items():
model.eval()
accs, losses = [], []
with torch.no_grad():
for x, y in test_loader:
x, y = x.to(device), y.to(device)
logits = model(x)
losses.append(criterion(logits, y).item())
accs.append((logits.argmax(1) == y).float().mean().item())
results[name] = {
'acc': np.mean(accs),
'loss': np.mean(losses),
}
for name, r in sorted(results.items(), key=lambda kv: -kv[1]['acc']):
print(f"{name:20s} acc={r['acc']:.4f} loss={r['loss']:.4f}")Sauvegarde et chargement
Sauver et charger le state dict
state_dict() est un OrderedDict de tenseurs de paramètres — le sauvegarder (pas le modèle entier) est le motif recommandé car il est portable et découplé de la disposition exacte de classe/fichier. map_location permet de charger un checkpoint CUDA sur CPU. strict=False ne charge que les clés correspondantes, pratique quand l'architecture a légèrement changé.
import torch
# save (recommended: only state_dict)
torch.save(model.state_dict(), 'model.pth')
# load
model = MLP(784, 128, 10) # must match the saved architecture
model.load_state_dict(torch.load('model.pth', map_location='cpu'))
model.eval()
# load on GPU that was trained on GPU
model.load_state_dict(torch.load('model.pth'))
model.to(device)
# strict=False allows partial loading (transfer learning)
model.load_state_dict(torch.load('model.pth'), strict=False)Sauver le modèle entier
Sauvegarder le modèle entier pickle l'objet Python, le liant à la classe et structure de fichiers exactes au moment de la sauvegarde. C'est fragile — tout refactoring casse le chargement. Réservez-le aux expériences rapides. Pour tout ce que vous pourriez déployer ou partager, sauvez state_dict et gardez l'architecture en code ou config.
# save entire model (uses pickle) — NOT recommended
torch.save(model, 'model_full.pth')
# load
model = torch.load('model_full.pth', map_location='cpu')
model.eval()
# pickle limitations:
# - class definition must be importable at load time
# - breaks if you refactor or rename the class
# - not portable across PyTorch versions
# prefer state_dict for productionCheckpoints d'entraînement
Un checkpoint complet stocke tout le nécessaire pour reprendre l'entraînement exactement : modèle, optimiseur, scheduler, époque et états RNG. L'état de l'optimiseur (buffers de momentum, moments Adam) est essentiel — reprendre sans lui réinitialise en pratique l'optimiseur et peut faire pic la perte. Ne sauvez l'état RNG que si vous avez besoin d'une reproductibilité bit-exacte.
checkpoint = {
'epoch': epoch,
'model_state': model.state_dict(),
'optimizer_state': optimizer.state_dict(),
'scheduler_state': scheduler.state_dict() if scheduler else None,
'loss': loss.item(),
'rng_state': torch.get_rng_state(),
'cuda_rng_state': torch.cuda.get_rng_state_all(),
}
torch.save(checkpoint, f'ckpt_epoch{epoch}.pth')
# resume
ckpt = torch.load('ckpt_epoch10.pth', map_location='cpu')
model.load_state_dict(ckpt['model_state'])
optimizer.load_state_dict(ckpt['optimizer_state'])
start_epoch = ckpt['epoch'] + 1
torch.set_rng_state(ckpt['rng_state'])Sauver le meilleur modèle
Sauvez le meilleur checkpoint selon la métrique de validation pour pouvoir récupérer le meilleur modèle même si les époques ultérieures surapprennent. Pour la plupart des tâches, gardez seulement le meilleur checkpoint pour économiser le disque ; pour la recherche, gardez des checkpoints par époque pour pouvoir revenir en arrière. Combinez avec un log CSV de (epoch, train_loss, val_loss, val_acc, path) pour savoir quel checkpoint choisir.
best_acc = 0.0
for epoch in range(epochs):
train_one_epoch(model, ...)
acc = evaluate(model, val_loader)
if acc > best_acc:
best_acc = acc
torch.save(model.state_dict(), 'best.pth')
print(f"new best {acc:.4f} saved")
# load best at the end
model.load_state_dict(torch.load('best.pth'))
final_acc = evaluate(model, test_loader)Charger des modèles partiels
strict=False retourne les listes de clés manquantes et inattendues — inspectez-les pour confirmer que seules les couches attendues ont été sautées. Renommer des clés permet d'adapter un checkpoint à une architecture renommée. Après avoir chargé un backbone, gelez ses poids pour de l'extraction pure de caractéristiques ou entraînez avec un LR bien plus petit que la nouvelle tête.
# transfer learning: load a backbone, drop the classifier
pretrained = torch.load('resnet_backbone.pth')
model = ResNet(num_classes=100)
# drop mismatched keys (e.g. final fc)
missing, unexpected = model.load_state_dict(pretrained, strict=False)
print('missing:', missing) # e.g. ['fc.weight', 'fc.bias']
print('unexpected:', unexpected)
# rename keys before loading
pretrained = {k.replace('encoder.', 'backbone.'): v
for k, v in pretrained.items()}
# freeze loaded weights
for name, p in model.named_parameters():
if 'fc' not in name:
p.requires_grad_(False)Export vers TorchScript
TorchScript produit un graphe autonome chargeable dans LibTorch (C++) ou Python sans la classe d'origine — idéal pour le déploiement. trace capture un seul chemin de flux de contrôle ; script gère le flux dépendant des données mais exige des annotations de type. ONNX exporte pour l'inférence dans ONNX Runtime, TensorRT ou OpenVINO. Utilisez dynamic_axes pour une taille de batch variable.
# scripted (production-ready, runs without Python)
scripted = torch.jit.script(model)
scripted.save('model_scripted.pt')
# traced (records a static graph from sample input)
example = torch.randn(1, 3, 224, 224)
traced = torch.jit.trace(model, example)
traced.save('model_traced.pt')
# load TorchScript in C++ / Python
loaded = torch.jit.load('model_scripted.pt')
loaded.eval()
out = loaded(example)
# export to ONNX (cross-framework)
torch.onnx.export(model, example, 'model.onnx',
input_names=['input'],
output_names=['output'],
dynamic_axes={'input': {0: 'batch'}})CNN
Couche Conv2d
La forme du poids de Conv2d est (out_channels, in_channels/groups, kH, kW). NCHW est la disposition mémoire par défaut. padding='same' (PyTorch 1.9+) garde la taille spatiale pour un stride de 1. groups=in_channels le rend depthwise (utilisé dans MobileNet). Taille de sortie : (H + 2P - K) / S + 1.
import torch.nn as nn
conv = nn.Conv2d(
in_channels=3, # RGB input
out_channels=16, # number of filters
kernel_size=3, # 3x3 filter
stride=1,
padding=1, # 'same' for kernel 3, stride 1
bias=True,
)
print(conv.weight.shape) # (16, 3, 3, 3)
x = torch.randn(4, 3, 32, 32) # NCHW
out = conv(x)
print(out.shape) # (4, 16, 32, 32) with padding=1
# depthwise separable conv
dw = nn.Conv2d(16, 16, 3, padding=1, groups=16)Couches de pooling
Le pooling sous-échantillonne les dimensions spatiales, ajoutant de l'invariance aux petites translations. MaxPool garde la réponse la plus forte ; AvgPool plus lisse. AdaptiveAvgPool2d(1) effondre les dims spatiales en 1x1 — le « global average pool » standard pour alimenter les caractéristiques conv dans une tête Linear. Préférez les convs à pas aux poolings pour un sous-échantillonnage apprenable dans les architectures modernes.
import torch.nn as nn
x = torch.randn(4, 16, 32, 32)
# max pooling
pool = nn.MaxPool2d(kernel_size=2, stride=2)
out = pool(x) # shape (4, 16, 16, 16)
# average pooling
avg = nn.AvgPool2d(2, stride=2)
# adaptive pool — output size fixed regardless of input
gap = nn.AdaptiveAvgPool2d(1) # global average pool
out = gap(x) # shape (4, 16, 1, 1)
# fractional max pool (slightly improves accuracy)
fmp = nn.FractionalMaxPool2d(2, output_ratio=0.5)Architecture CNN
Un bloc CNN canonique est Conv -> BatchNorm -> ReLU -> Pool. AdaptiveAvgPool2d(1) rend le réseau agnostique à la taille d'entrée, permettant d'entraîner à une résolution et tester à une autre. BatchNorm2d va après la conv, avant l'activation. Gardez les noyaux conv à 3x3 avec padding=1 (style VGG) — économes en paramètres et bien fusibles.
import torch.nn as nn
class TinyCNN(nn.Module):
def __init__(self, num_classes=10):
super().__init__()
self.features = nn.Sequential(
nn.Conv2d(3, 32, 3, padding=1),
nn.BatchNorm2d(32),
nn.ReLU(inplace=True),
nn.MaxPool2d(2), # 32 -> 16
nn.Conv2d(32, 64, 3, padding=1),
nn.BatchNorm2d(64),
nn.ReLU(inplace=True),
nn.MaxPool2d(2), # 16 -> 8
)
self.classifier = nn.Sequential(
nn.AdaptiveAvgPool2d(1),
nn.Flatten(),
nn.Linear(64, num_classes),
)
def forward(self, x):
return self.classifier(self.features(x))Feature maps et champ réceptif
Les feature maps montrent ce que chaque canal détecte — les premières couches trouvent contours et couleurs, les profondes textures et parties. register_forward_hook permet de capturer les activations sans modifier forward. Le champ réceptif croît avec profondeur et pooling ; grosso modo, le pixel de sortie (i,j) dépend d'un patch d'entrée centré là, de taille égale à la somme des strides et noyaux jusqu'à cette couche.
# visualize feature maps
model.eval()
x = images[0:1].to(device)
with torch.no_grad():
feat = model.features[0](x) # first conv output
print(feat.shape) # (1, 32, H, W)
import matplotlib.pyplot as plt
fig, axes = plt.subplots(4, 8, figsize=(12, 6))
for i, ax in enumerate(axes.flat):
if i < feat.shape[1]:
ax.imshow(feat[0, i].cpu(), cmap='viridis')
ax.axis('off')
# hook to capture intermediate activations
acts = {}
def hook(module, inp, out): acts['layer'] = out
model.features[3].register_forward_hook(hook)Normalisation par batch
BatchNorm2d normalise par canal sur (N, H, W), en gardant des stats EMA courantes pour l'inférence. train()/eval() importe — eval utilise les stats courantes donc la sortie est déterministe. BatchNorm couple les exemples d'un batch, ce qui casse avec de très petits batchs ; passez alors à GroupNorm ou LayerNorm. SyncBatchNorm est nécessaire pour un BN multi-GPU correct.
import torch.nn as nn
# 2D BN for conv outputs
bn = nn.BatchNorm2d(64)
bn.weight.shape # (64,) — learnable scale gamma
bn.bias.shape # (64,) — learnable shift beta
bn.running_mean.shape # (64,) — EMA of batch means
bn.running_var.shape # (64,) — EMA of batch vars
# 1D BN for linear / time-series
bn1d = nn.BatchNorm1d(128)
# in training mode: use batch stats, update running stats
model.train()
# in eval mode: use running stats (deterministic)
model.eval()
# alternatives
nn.LayerNorm(128) # normalize over features (transformers)
nn.GroupNorm(8, 64) # split channels into 8 groups
nn.InstanceNorm2d(64) # per-sample, style transferArchitectures CNN populaires
torchvision.models expose ResNet, EfficientNet, MobileNet, ViT et plus avec poids ImageNet préentraînés. Remplacer la couche fc finale est le point d'entrée standard du transfer learning. Pour détection/segmentation, retirez la tête et utilisez les caractéristiques conv. Consultez l'API weights (WeightsEnum) — le vieux flag pretrained=True est déprécié. Chaque modèle a un champ réceptif et un budget FLOPs connus ; choisissez celui qui colle à votre cible de latence.
import torchvision.models as M
# pretrained backbones
resnet = M.resnet50(weights=M.ResNet50_Weights.DEFAULT)
effnet = M.efficientnet_b0(weights=M.EfficientNet_B0_Weights.DEFAULT)
vgg = M.vgg16(weights=M.VGG16_Weights.DEFAULT)
mobnet = M.mobilenet_v3_small(weights=M.MobileNet_V3_Small_Weights.DEFAULT)
# replace classifier head
num_classes = 100
resnet.fc = nn.Linear(resnet.fc.in_features, num_classes)
# feature extractor (drop head)
backbone = nn.Sequential(*list(resnet.children())[:-1]) # outputs (N, 2048, 1, 1)
features = backbone(images).flatten(1) # (N, 2048)RNN et LSTM
Couche RNN
batch_first=True rend l'entrée (batch, seq, feature), conforme à la plupart des conventions NLP ; sans lui PyTorch utilise (seq, batch, feature). Le RNN vanilla souffre de gradients disparaissants sur les longues séquences — préférez LSTM ou GRU en pratique. out contient les états cachés par pas de temps de la dernière couche ; h_n l'état final de chaque couche.
import torch.nn as nn
rnn = nn.RNN(
input_size=64,
hidden_size=128,
num_layers=2,
batch_first=True, # input shape (batch, seq, feature)
bidirectional=False,
nonlinearity='tanh',
)
x = torch.randn(32, 10, 64) # (batch, seq, input)
out, h_n = rnn(x)
print(out.shape) # (32, 10, 128) — per-step hidden states
print(h_n.shape) # (2, 32, 128) — final hidden state per layer
# last-step output for classification
last = out[:, -1, :] # shape (32, 128)Couche LSTM
LSTM retourne à la fois l'état caché h_n et l'état de cellule c_n. Le bidirectionnel double la taille de caractéristiques en sortie. Pour la classification, utilisez l'état caché final de chaque direction (h_n[-2] est la dernière couche forward, h_n[-1] la dernière backward). Le dropout de nn.LSTM ne s'applique qu'entre couches empilées, pas sur l'entrée — enveloppez l'entrée avec nn.Dropout si besoin.
import torch.nn as nn
lstm = nn.LSTM(
input_size=64,
hidden_size=128,
num_layers=2,
batch_first=True,
bidirectional=True,
dropout=0.5, # between stacked layers
)
x = torch.randn(32, 10, 64)
out, (h_n, c_n) = lstm(x)
print(out.shape) # (32, 10, 256) — 128 * 2 directions
print(h_n.shape) # (4, 32, 128) — 2 layers * 2 directions
print(c_n.shape) # (4, 32, 128) — cell state
# concatenate final forward + backward for classification
last = torch.cat([h_n[-2], h_n[-1]], dim=1) # shape (32, 256)Couche GRU
GRU n'a qu'un état caché (pas d'état de cellule) et deux portes au lieu de trois, donc moins de paramètres et un entraînement légèrement plus rapide que LSTM. Empiriquement GRU et LSTM performent de façon similaire sur la plupart des tâches ; GRU est un bon défaut pour les petits jeux. Comme LSTM, le dropout ne s'applique qu'entre couches empilées.
import torch.nn as nn
gru = nn.GRU(
input_size=64,
hidden_size=128,
num_layers=2,
batch_first=True,
)
x = torch.randn(32, 10, 64)
out, h_n = gru(x) # GRU has no cell state
print(out.shape) # (32, 10, 128)
print(h_n.shape) # (2, 32, 128)
# GRU vs LSTM: fewer parameters, slightly faster,
# often similar performance on many tasksSéquences compactées
Le packing saute les tokens de padding dans le calcul RNN, ce qui est plus rapide et évite de biaiser l'état caché avec des zéros de padding. Les séquences doivent être triées par longueur décroissante dans les vieux PyTorch ; enforce_sorted=False trie en interne (léger overhead). pad_packed_sequence reconvertit en tenseur bourré. Combinez avec un collate_fn custom qui bourre les batchs dynamiquement.
from torch.nn.utils.rnn import pack_padded_sequence, pad_packed_sequence
# variable-length sequences in a batch
seqs = [torch.randn(5, 64), torch.randn(3, 64), torch.randn(8, 64)]
lens = torch.tensor([5, 3, 8])
# pad to (batch, max_len, feature)
padded = torch.nn.utils.rnn.pad_sequence(seqs, batch_first=True)
# sort by length descending (required by older versions)
padded = padded[torch.argsort(lens, descending=True)]
lens_sorted = lens[torch.argsort(lens, descending=True)]
packed = pack_padded_sequence(padded, lens_sorted,
batch_first=True, enforce_sorted=True)
out_packed, h_n = lstm(packed)
out, _ = pad_packed_sequence(out_packed, batch_first=True)Classification de séquences
Un classifieur de texte standard : embedding -> biLSTM -> dropout -> linear. Utilisez padding_idx dans nn.Embedding pour que le token de padding ait un gradient nul. Passez lengths.cpu() à pack_padded_sequence car il tourne sur CPU. L'état caché final des deux directions est concaténé pour capturer toute la séquence. Pour les longues séquences, les transformers surpassent les LSTM mais exigent plus de données et de calcul.
import torch.nn as nn
class TextClassifier(nn.Module):
def __init__(self, vocab, emb_dim=128, hidden=256, classes=10):
super().__init__()
self.emb = nn.Embedding(vocab, emb_dim, padding_idx=0)
self.lstm = nn.LSTM(emb_dim, hidden, batch_first=True,
bidirectional=True, num_layers=2)
self.dropout = nn.Dropout(0.5)
self.fc = nn.Linear(hidden * 2, classes)
def forward(self, x, lengths):
x = self.emb(x)
packed = pack_padded_sequence(x, lengths.cpu(),
batch_first=True, enforce_sorted=False)
_, (h_n, _) = self.lstm(packed)
last = torch.cat([h_n[-2], h_n[-1]], dim=1)
return self.fc(self.dropout(last))
model = TextClassifier(vocab=10000)Génération de séquences (décodeur)
Un décodeur s'exécute un pas à la fois, conditionné au token de sortie précédent. LSTMCell est un LSTM à pas unique — utilisez-le pour un contrôle fin de la boucle. Le teacher forcing alimente le token de vérité terrain au pas suivant pendant l'entraînement, convergeant bien plus vite que d'alimenter les prédictions du modèle. À l'inférence, passez à alimenter l'argmax (ou un échantillon) des logits du pas précédent.
import torch.nn as nn
class Decoder(nn.Module):
def __init__(self, vocab, emb_dim=128, hidden=256):
super().__init__()
self.emb = nn.Embedding(vocab, emb_dim)
self.lstm = nn.LSTMCell(emb_dim, hidden)
self.fc = nn.Linear(hidden, vocab)
def forward(self, tgt, hidden):
# tgt shape (batch, T)
outputs = []
h, c = hidden
for t in range(tgt.size(1)):
emb = self.emb(tgt[:, t])
h, c = self.lstm(emb, (h, c))
outputs.append(self.fc(h))
return torch.stack(outputs, dim=1) # (batch, T, vocab)
# teacher forcing: feed ground truth next token
# at inference: feed argmax of previous outputTransformer
nn.MultiheadAttention
nn.MultiheadAttention calcule l'attention par produit scalaire mis à l'échelle sur les têtes en parallèle. batch_first suit la convention NLP (batch, seq, dim). Utilisez attn_mask pour le décodage causal (masque triangulaire inférieur) et key_padding_mask pour ignorer les tokens de padding. need_weights=True retourne la matrice d'attention, utile pour visualisation et sondage.
import torch.nn as nn
attn = nn.MultiheadAttention(
embed_dim=512,
num_heads=8,
dropout=0.1,
batch_first=True, # input (batch, seq, dim)
)
q = k = v = torch.randn(32, 10, 512)
out, weights = attn(q, k, v, need_weights=True)
print(out.shape) # (32, 10, 512)
print(weights.shape) # (32, 10, 10) — attention scores
# causal / self-attention mask
mask = nn.Transformer.generate_square_subsequent_mask(10)
out, _ = attn(q, k, v, attn_mask=mask) # masked attention
# key padding mask (ignore pad positions)
key_padding_mask = (tokens == 0) # True = ignore
out, _ = attn(q, k, v, key_padding_mask=key_padding_mask)Encodeur Transformer
TransformerEncoderLayer est un bloc self-attention + FFN avec résidus et LayerNorm. norm_first=True (pre-LN) est plus stable pour un entraînement from scratch ; post-LN (défaut) exige du warmup. Empilez N couches avec nn.TransformerEncoder. Passez src_key_padding_mask pour que l'attention ignore les positions de padding. Pour la classification, mean-pool la séquence de sortie et alimentez une tête Linear.
import torch.nn as nn
enc_layer = nn.TransformerEncoderLayer(
d_model=512,
nhead=8,
dim_feedforward=2048,
dropout=0.1,
activation='relu',
batch_first=True,
norm_first=True, # pre-LN, more stable
)
encoder = nn.TransformerEncoder(enc_layer, num_layers=6)
x = torch.randn(32, 10, 512)
out = encoder(x)
print(out.shape) # (32, 10, 512)
# with padding mask
pad_mask = (tokens == 0)
out = encoder(x, src_key_padding_mask=pad_mask)Encodage positionnel
Les transformers sont invariants à la permutation, donc ils ont besoin d'information de position. L'encodage sinusoïdal généralise à des séquences plus longues que vues à l'entraînement. register_buffer stocke pe sans en faire un paramètre — il se déplace avec .to(device) et se sauve dans state_dict. Les embeddings de position appris (nn.Parameter) marchent aussi mais n'extrapolent pas au-delà de la longueur d'entraînement.
import torch
import torch.nn as nn
import math
class PositionalEncoding(nn.Module):
def __init__(self, d_model=512, max_len=5000, dropout=0.1):
super().__init__()
self.dropout = nn.Dropout(dropout)
pe = torch.zeros(max_len, d_model)
pos = torch.arange(0, max_len).unsqueeze(1).float()
div = torch.exp(torch.arange(0, d_model, 2).float()
* (-math.log(10000.0) / d_model))
pe[:, 0::2] = torch.sin(pos * div)
pe[:, 1::2] = torch.cos(pos * div)
self.register_buffer('pe', pe.unsqueeze(0)) # (1, max_len, d_model)
def forward(self, x):
x = x + self.pe[:, :x.size(1)]
return self.dropout(x)
# usage
emb = nn.Embedding(vocab, 512)
pos = PositionalEncoding(512)
x = pos(emb(tokens)) # (batch, seq, 512)Transformer complet (Seq2Seq)
Un transformer encodeur-décodeur complet pour traduction/résumé. Le décodeur utilise un masquage causal sur la cible (la position t ne peut prêter attention qu'au <= t) plus une cross-attention vers la sortie de l'encodeur (memory). Passez les key_padding_masks pour source et cible pour que l'attention ignore les tokens de padding. La tête projette les sorties du décodeur en logits du vocabulaire ; la perte est CrossEntropyLoss avec ignore_index=0.
import torch.nn as nn
class Seq2SeqTransformer(nn.Module):
def __init__(self, vocab_src, vocab_tgt, d=512, h=8, layers=6):
super().__init__()
self.src_emb = nn.Embedding(vocab_src, d, padding_idx=0)
self.tgt_emb = nn.Embedding(vocab_tgt, d, padding_idx=0)
self.pos = PositionalEncoding(d)
enc_layer = nn.TransformerEncoderLayer(d, h, d*4, batch_first=True, norm_first=True)
dec_layer = nn.TransformerDecoderLayer(d, h, d*4, batch_first=True, norm_first=True)
self.encoder = nn.TransformerEncoder(enc_layer, layers)
self.decoder = nn.TransformerDecoder(dec_layer, layers)
self.head = nn.Linear(d, vocab_tgt)
def forward(self, src, tgt, src_pad, tgt_pad):
src = self.pos(self.src_emb(src))
tgt = self.pos(self.tgt_emb(tgt))
memory = self.encoder(src, src_key_padding_mask=src_pad)
causal = nn.Transformer.generate_square_subsequent_mask(tgt.size(1))
out = self.decoder(tgt, memory,
tgt_mask=causal,
tgt_key_padding_mask=tgt_pad,
memory_key_padding_mask=src_pad)
return self.head(out)Bloc Vision Transformer (ViT)
Un bloc ViT est self-attention pre-LN + MLP pre-LN avec résidus — essentiellement comme une couche d'encodeur transformer. Les Vision Transformers patchifient l'image avec une Conv2d à pas (kernel=stride=patch_size) puis traitent les patchs comme tokens. Ajoutez un token CLS et des embeddings de position. nn.MultiheadAttention retourne (sortie, poids) — déballez avec need_weights=False pour sauter les poids.
import torch.nn as nn
class ViTBlock(nn.Module):
def __init__(self, dim=768, heads=12, mlp=3072, dropout=0.1):
super().__init__()
self.norm1 = nn.LayerNorm(dim)
self.attn = nn.MultiheadAttention(dim, heads, dropout=dropout, batch_first=True)
self.norm2 = nn.LayerNorm(dim)
self.mlp = nn.Sequential(
nn.Linear(dim, mlp),
nn.GELU(),
nn.Dropout(dropout),
nn.Linear(mlp, dim),
nn.Dropout(dropout),
)
def forward(self, x):
h = self.norm1(x)
a, _ = self.attn(h, h, h, need_weights=False)
x = x + a
x = x + self.mlp(self.norm2(x))
return x
# patchify: (B, 3, 224, 224) -> (B, 196, 768) via Conv2d(3, 768, 16, 16)Attention depuis zéro
Attention par produit scalaire mis à l'échelle : scores = QK^T / sqrt(d_k), softmax, multiplié par V. Le 1/sqrt(d_k) garde la variance stable pour que le softmax ne sature pas. masked_fill avec -inf avant le softmax met à zéro ces positions. Le multi-head attention découpe l'embedding en H têtes, prête attention en parallèle et concatène. C'est exactement ce que fait nn.MultiheadAttention — écrivez-le from scratch seulement pour apprendre ou ajouter des variantes comme l'attention linéaire/flash.
import torch
import torch.nn.functional as F
import math
def attention(q, k, v, mask=None, dropout=None):
# q, k, v shape (batch, heads, seq, dim)
d_k = q.size(-1)
scores = (q @ k.transpose(-2, -1)) / math.sqrt(d_k)
if mask is not None:
scores = scores.masked_fill(mask == 0, float('-inf'))
attn = F.softmax(scores, dim=-1)
if dropout is not None:
attn = dropout(attn)
out = attn @ v
return out, attn
# multi-head: reshape (batch, seq, dim) -> (batch, heads, seq, dim//heads)
def split_heads(x, heads):
b, s, d = x.shape
return x.view(b, s, heads, d // heads).transpose(1, 2)Entraînement GPU
Sélection du device
Testez toujours torch.cuda.is_available() pour que les machines CPU-only ne crashent pas. On peut créer des tenseurs directement sur un device avec l'argument device= (plus rapide que créer sur CPU puis déplacer). Le contexte torch.device (PyTorch 2.x) règle un device par défaut pour les nouveaux tenseurs. MPS supporte les GPU Apple Silicon mais manque de certaines fonctionnalités CUDA — vérifiez le support des opérateurs avant de vous y fier.
import torch
# pick device
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
print(device) # cuda or cpu
print(torch.cuda.device_count()) # number of GPUs
print(torch.cuda.get_device_name(0)) # GPU name
# use a specific GPU
torch.cuda.set_device(0)
x = torch.randn(3, device='cuda:1') # directly on GPU 1
# default device context (PyTorch 2.x)
with torch.device('cuda'):
y = torch.randn(4) # on GPU
# Apple Silicon
device = 'mps' if torch.backends.mps.is_available() else 'cpu'Déplacer modèles et données
model.to(device) déplace paramètres et buffers en place. Déplacez les tenseurs d'entrée dans la boucle d'entraînement pour que le DataLoader puisse streamer depuis le disque. non_blocking=True chevauche la copie CPU→GPU avec le calcul quand le tenseur source est en mémoire épinglée (réglez pin_memory=True sur le DataLoader). .cpu() / .numpy() avant toute opération NumPy — les tenseurs GPU ne se convertissent pas directement.
model = MLP(784, 128, 10).to(device)
for x, y in train_loader:
x, y = x.to(device), y.to(device)
# non-blocking copy if pin_memory=True
x = x.to(device, non_blocking=True)
...
# check placement
print(next(model.parameters()).device) # cuda:0
print(x.device)
# move a tensor to CPU for numpy / saving
arr = x.detach().cpu().numpy()
# half precision
model = model.half() # float16
x = x.half()GPU multiples (DataParallel)
DataParallel (DP) réplique le modèle sur chaque GPU, découpe le batch et regroupe les sorties sur GPU 0 — simple mais lent et déséquilibré (le GPU 0 fait le gather et le calcul de perte). Il est mono-processus donc le GIL limite le scaling. Pour tout travail multi-GPU sérieux, utilisez DistributedDataParallel. DP convient au prototypage rapide sur 2 à 4 GPU.
import torch.nn as nn
# simple, single-process data parallelism
model = MLP(784, 512, 10).to(device)
model = nn.DataParallel(model) # wrap AFTER .to(device)
# now model behaves normally
out = model(x)
loss = criterion(out, y)
loss.backward() # gradients are summed across GPUs
# access underlying module
inner = model.module
# specify which GPUs
model = nn.DataParallel(model, device_ids=[0, 1, 2])DistributedDataParallel
DistributedDataParallel (DDP) spawn un processus par GPU, chacun avec sa réplique de modèle ; les gradients sont all-reduced pour que chaque GPU voie le même gradient. Bien plus rapide et scalable que DataParallel. Utilisez torchrun (ou torch.distributed.launch) pour démarrer les processus. Appelez toujours sampler.set_epoch(epoch) pour que chaque époque remélange. Voir la section entraînement distribué pour plus.
import os
import torch.distributed as dist
import torch.nn as nn
# launch with: torchrun --nproc_per_node=4 train.py
dist.init_process_group(backend='nccl')
local_rank = int(os.environ['LOCAL_RANK'])
torch.cuda.set_device(local_rank)
model = MLP(784, 512, 10).to(local_rank)
model = nn.parallel.DistributedDataParallel(
model, device_ids=[local_rank], output_device=local_rank,
)
sampler = torch.utils.data.distributed.DistributedSampler(dataset)
loader = DataLoader(dataset, batch_size=64, sampler=sampler)
for epoch in range(epochs):
sampler.set_epoch(epoch) # shuffle differently each epoch
for x, y in loader:
x, y = x.to(local_rank), y.to(local_rank)
loss = criterion(model(x), y)
loss.backward()
optimizer.step()
optimizer.zero_grad()Gestion de la mémoire
empty_cache() rend la mémoire cachée à l'OS mais ne libère pas les tenseurs encore en usage — appelez-le après un gros pic, pas dans la boucle chaude. memory_allocated est les tenseurs en usage ; memory_reserved le pool de l'allocateur de cache. Pour réduire l'OOM : baissez la taille de batch, utilisez la précision mixte, le gradient checkpointing ou l'accumulation de gradients. expandable_segments:True réduit la fragmentation pour les charges à formes variables. Évitez de garder des références à des tenseurs dont vous n'avez plus besoin (ex. pertes loggées dans une liste).
import torch
# release unused memory
torch.cuda.empty_cache()
# current memory usage
print(torch.cuda.memory_allocated() / 1e9, 'GB allocated')
print(torch.cuda.memory_reserved() / 1e9, 'GB reserved')
# per-tensor memory
x = torch.randn(1000, 1000, device='cuda')
print(x.element_size() * x.nelement() / 1e6, 'MB')
# peak memory tracking
torch.cuda.reset_peak_memory_stats()
# ... run training ...
print(torch.cuda.max_memory_allocated() / 1e9, 'GB peak')
# out-of-memory debugging
import os
os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'CuDNN et performance
cudnn.benchmark=True laisse cuDNN profiler les algorithmes au premier forward et cacher le plus rapide — génial quand les formes d'entrée sont fixes (CNN typique), nuisible si les formes changent à chaque pas (RNN à longueur variable). TF32 utilise une mantisse 19 bits sur Ampere+ pour un gain de matmul ~3x avec perte de précision minimale ; activez-le sauf besoin strict de reproductibilité fp32. Le mode déterministe désactive les algorithmes non déterministes.
import torch.backends.cudnn as cudnn
# benchmark finds the fastest conv algorithm (good for fixed input sizes)
cudnn.benchmark = True
# deterministic mode (slower, reproducible)
cudnn.deterministic = True
cudnn.benchmark = False
# allow TF32 on Ampere+ (big speedup, slight precision loss)
torch.backends.cuda.matmul.allow_tf32 = True
cudnn.allow_tf32 = True
# disable cudnn (debugging)
cudnn.enabled = FalseTransforms et prétraitement
Transforms courants
ToTensor convertit une image PIL (0-255) en tenseur flottant dans [0,1] et réarrange HWC -> CHW. Normalize standardise ensuite par canal avec les statistiques ImageNet (le standard de facto des modèles préentraînés — matchez toujours les stats avec lesquelles le backbone a été entraîné). Appliquez les transforms dans le Dataset pour qu'ils tournent sur les processus workers ; le GPU n'attend jamais le prétraitement CPU.
from torchvision import transforms
transform = transforms.Compose([
transforms.Resize(256),
transforms.CenterCrop(224),
transforms.ToTensor(), # PIL -> Tensor, scales to [0,1]
transforms.Normalize( # per-channel standardize
mean=[0.485, 0.456, 0.406],
std=[0.229, 0.224, 0.225],
),
])
# apply to a PIL image
img = transform(pil_image)
print(img.shape) # (3, 224, 224)
print(img.min(), img.max()) # standardized
dataset = datasets.ImageFolder('data/', transform=transform)Augmentation de données
L'augmentation régularise le modèle en lui montrant des entrées variées. RandomResizedCrop + flip est l'augmentation ImageNet classique. ColorJitter change la couleur sans affecter la géométrie. TrivialAugmentWide et RandAugment échantillonnent des ops aléatoires avec magnitudes aléatoires — forts, simples et étonnamment efficaces. Utilisez un transform séparé non augmenté pour la validation afin que les métriques restent stables.
from torchvision import transforms
train_tf = transforms.Compose([
transforms.RandomResizedCrop(224),
transforms.RandomHorizontalFlip(),
transforms.ColorJitter(brightness=0.2, contrast=0.2,
saturation=0.2, hue=0.1),
transforms.RandomRotation(15),
transforms.ToTensor(),
transforms.Normalize(mean=[0.485, 0.456, 0.406],
std=[0.229, 0.224, 0.225]),
])
# stronger augmentation: RandAugment / TrivialAugment
train_tf = transforms.Compose([
transforms.TrivialAugmentWide(),
transforms.Resize(256),
transforms.CenterCrop(224),
transforms.ToTensor(),
transforms.Normalize(mean=[0.485, 0.456, 0.406],
std=[0.229, 0.224, 0.225]),
])Transforms v2 (nouvelle API)
Transforms v2 (torchvision 0.17+) est la nouvelle API — plus rapide, scriptable JIT, et surtout marche conjointement sur image/masque/bbox pour que les augmentations de détection et segmentation restent cohérentes. ToDtype + scale=True remplace ToTensor. Passez toujours antialias=True aux ops de resize pour un sous-échantillonnage plus propre. Le module transforms legacy marche encore mais ne recevra plus de nouvelles fonctionnalités.
from torchvision.transforms import v2
transform = v2.Compose([
v2.RandomResizedCrop(224, antialias=True),
v2.RandomHorizontalFlip(),
v2.ToDtype(torch.float32, scale=True), # scale to [0,1]
v2.Normalize(mean=[0.485, 0.456, 0.406],
std=[0.229, 0.224, 0.225]),
])
# v2 works on images, videos, masks, and bounding boxes together
imgs, masks = transform(imgs, masks)
imgs, bboxes, labels = transform(imgs, bboxes, labels)
# supports more ops and JIT scripting
transform = v2.RandomChoice([
v2.RandomHorizontalFlip(),
v2.RandomVerticalFlip(),
])Transform personnalisé
Un transform custom est n'importe quel appelable qui prend un tenseur (ou image PIL) et en retourne un. Composez-les avec transforms.Compose. Appliquez le bruit après ToTensor pour qu'il opère sur des flottants. Pour de l'aléa par échantillon, utilisez torch.rand dans __call__ pour que chaque appel ait une décision fraîche. Transforms v2 permet d'écrire des classes de transform qui gèrent les entrées conjointes (image, label) en surchargeant forward.
import torch
from torchvision import transforms
class RandomGaussianNoise:
def __init__(self, std=0.1):
self.std = std
def __call__(self, x):
if self.std > 0:
return x + torch.randn_like(x) * self.std
return x
# compose with built-ins
transform = transforms.Compose([
transforms.ToTensor(),
RandomGaussianNoise(0.05),
transforms.Normalize([0.5], [0.5]),
])
# callable with probability
class RandomApply:
def __init__(self, fn, p=0.5):
self.fn, self.p = fn, p
def __call__(self, x):
return self.fn(x) if torch.rand(1) < self.p else xPrétraitement texte et tabulaire
Pour le texte, bâtissez un vocabulaire depuis le jeu d'entraînement (jamais val/test) et convertissez les tokens en ids entiers ; <unk> gère les mots inconnus et <pad> sert au batch de séquences de longueur variable. Pour le tabulaire, standardisez les caractéristiques avec des statistiques calculées sur le seul jeu d'entraînement — fuir les stats val/test gonfle les métriques. Sauvegardez le scaler/vocabulaire à côté du checkpoint du modèle pour que l'inférence prétraite identiquement.
import torch
from torchtext.vocab import build_vocab_from_iterator
# tokenize and numericalize text
tokens = ['hello', 'world', 'this', 'is', 'nlp']
vocab = build_vocab_from_iterator([tokens], specials=['<unk>', '<pad>'])
vocab.set_default_index(vocab['<unk>'])
# text -> token ids
ids = vocab(['hello', 'world', 'unknownword'])
print(ids) # e.g. [3, 4, 0]
# tabular: standardize features
from sklearn.preprocessing import StandardScaler
scaler = StandardScaler().fit(X_train)
X_train_t = torch.tensor(scaler.transform(X_train), dtype=torch.float32)
X_test_t = torch.tensor(scaler.transform(X_test), dtype=torch.float32)
# fit scaler ONLY on training data, apply to val/testDataset personnalisé
Classe Dataset
Un Dataset n'a besoin que de __len__ et __getitem__. Ouvrez les fichiers paresseusement dans __getitem__ pour tenir des millions de chemins en mémoire à peu de frais. Retournez des tuples (entrée, cible) et laissez le collate par défaut du DataLoader les empiler en batchs. Gardez __getitem__ léger et sans effets de bord car il tourne sur les workers — ne mutez pas d'état partagé.
from torch.utils.data import Dataset
class ImageDataset(Dataset):
def __init__(self, paths, labels, transform=None):
self.paths = paths
self.labels = labels
self.transform = transform
def __len__(self):
return len(self.paths)
def __getitem__(self, idx):
from PIL import Image
img = Image.open(self.paths[idx]).convert('RGB')
label = self.labels[idx]
if self.transform:
img = self.transform(img)
return img, label
dataset = ImageDataset(paths, labels, transform=train_tf)
img, label = dataset[0]Dataset ImageFolder
ImageFolder attend un sous-répertoire par classe et infère les labels des noms de dossiers — le moyen le plus rapide de démarrer en classification d'images. class_to_idx mappe les noms aux labels entiers ; gardez-le cohérent entre train/val/test en réutilisant le même mapping. random_split retourne des Subsets partageant les données sous-jacentes, donc pas de duplication mémoire.
from torchvision import datasets
# convention: data/train/cat/*.jpg, data/train/dog/*.jpg
dataset = datasets.ImageFolder('data/train', transform=train_tf)
print(dataset.class_to_idx) # {'cat': 0, 'dog': 1}
# train / val split
from torch.utils.data import random_split
train, val = random_split(dataset, [0.8, 0.2])
# custom split with same class mapping
val_dataset = datasets.ImageFolder('data/val', transform=val_tf)
val_dataset.class_to_idx = dataset.class_to_idx # keep consistent
# use with DataLoader
loader = DataLoader(dataset, batch_size=32, shuffle=True, num_workers=4)Dataset texte
Pré-tokenisez le texte une fois et stockez les ids entiers pour éviter de re-tokeniser chaque époque. Pour des séquences de longueur variable, retournez des listes brutes et bourrez dans collate_fn pour que chaque batch ne bourre qu'à sa propre longueur max. pack_padded_sequence saute alors les positions de padding dans le RNN. Pour l'entraînement transformer, retournez les masques d'attention pour que les tokens de padding soient ignorés par l'attention.
from torch.utils.data import Dataset
import torch
class TextDataset(Dataset):
def __init__(self, texts, labels, vocab, max_len=128):
self.texts = texts
self.labels = labels
self.vocab = vocab
self.max_len = max_len
def __len__(self):
return len(self.texts)
def __getitem__(self, idx):
tokens = self.texts[idx].split()[:self.max_len]
ids = [self.vocab[t] for t in tokens]
ids += [0] * (self.max_len - len(ids)) # pad
return torch.tensor(ids), self.labels[idx]
# variable length: use custom collate
def text_collate(batch):
ids, labels = zip(*batch)
lens = torch.tensor([len(x) for x in ids])
padded = torch.nn.utils.rnn.pad_sequence(ids, batch_first=True)
return padded, lens, torch.tensor(labels)Iterable Dataset
IterableDataset streame les données au lieu de l'accès aléatoire — essentiel pour des sources énormes ou en flux (logs, bases, S3). Les workers doivent explicitement se partager le flux (itertools.islice) pour éviter que chaque worker ne lise les mêmes données. shuffle n'est pas supporté directement ; à la place, bufférisez les échantillons et mélangez dans le buffer. À utiliser pour des datasets trop grands pour être indexés par longueur.
from torch.utils.data import IterableDataset, DataLoader
import itertools
class StreamDataset(IterableDataset):
def __init__(self, file_path):
self.file_path = file_path
def __iter__(self):
# split work across workers
worker_info = torch.utils.data.get_worker_info()
with open(self.file_path) as f:
if worker_info is None:
lines = f
else:
lines = itertools.islice(f, worker_info.id,
None, worker_info.num_workers)
for line in lines:
yield self._parse(line)
def _parse(self, line):
# parse line into tensor + label
return torch.tensor([...]), label
loader = DataLoader(StreamDataset('big.csv'), batch_size=32)TensorDataset et ConcatDataset
TensorDataset est le chemin le plus rapide quand les données tiennent en RAM — il retourne des tuples de tenseurs que le collate par défaut empile en batchs. ConcatDataset chaîne des datasets bout à bout ; utile pour combiner données labellisées et pseudo-labellisées. Subset enveloppe un dataset avec une liste d'indices, permettant random_split et du slicing custom sans copier les données.
from torch.utils.data import TensorDataset, ConcatDataset, DataLoader
# wrap in-memory tensors
X = torch.randn(1000, 784)
y = torch.randint(0, 10, (1000,))
dataset = TensorDataset(X, y)
x, label = dataset[0]
# combine multiple datasets
full = ConcatDataset([dataset_a, dataset_b])
print(len(full)) # len(a) + len(b)
# Subset for indexing
from torch.utils.data import Subset
half = Subset(dataset, range(500))
# random splits
from torch.utils.data import random_split
train, val = random_split(dataset, [0.8, 0.2])Scheduler LR
StepLR et MultiStepLR
StepLR et MultiStepLR sont les schedulers les plus simples — multiplient le LR par gamma à des époques fixes. Prévisibles et bien adaptés aux CNN entraînés from scratch. Appelez toujours scheduler.step() après l'entraînement de l'époque, pas dans la boucle de batch. get_last_lr() montre le LR courant pour le logging. Attention : step_size compte des époques, pas des pas.
from torch.optim.lr_scheduler import StepLR, MultiStepLR
# decay by gamma every step_size epochs
scheduler = StepLR(optimizer, step_size=10, gamma=0.1)
# LR: 1e-3 -> 1e-4 (epoch 10) -> 1e-5 (epoch 20)
# decay at specific epochs
scheduler = MultiStepLR(optimizer, milestones=[30, 60, 80], gamma=0.1)
# in the training loop
for epoch in range(epochs):
train(...)
val(...)
scheduler.step() # call once per epoch
# inspect current LR
print(scheduler.get_last_lr())CosineAnnealingLR
L'annealing cosinus décroît doucement le LR — souvent un petit gain d'exactitude sur la décroissance par pas. Les redémarrages chauds (SGDR) réinitialisent le LR à la valeur de base au début de chaque cycle, aidant le modèle à s'échapper des minima pointus ; T_mult=2 double la durée de chaque cycle. Les schedulers cosinus sont le défaut moderne de la classification d'images et du préentraînement.
from torch.optim.lr_scheduler import CosineAnnealingLR
# cosine decay to eta_min over T_max epochs
scheduler = CosineAnnealingLR(optimizer, T_max=50, eta_min=1e-6)
# LR follows cosine from base_lr down to eta_min
# with warm restarts
from torch.optim.lr_scheduler import CosineAnnealingWarmRestarts
scheduler = CosineAnnealingWarmRestarts(
optimizer,
T_0=10, # length of first cycle
T_mult=2, # each cycle is T_mult longer
eta_min=1e-6,
)ReduceLROnPlateau
ReduceLROnPlateau surveille une métrique et réduit le LR quand elle cesse de progresser — parfait quand on ignore le bon planning à l'avance. mode='min' pour les pertes, 'max' pour l'exactitude. patience=N attend N époques sans amélioration avant de réduire. Contrairement aux autres schedulers, il faut passer la métrique à step(metric). Facile de surapprendre avec trop de patience ; combinez avec l'early stopping.
from torch.optim.lr_scheduler import ReduceLROnPlateau
scheduler = ReduceLROnPlateau(
optimizer,
mode='min', # 'min' for loss, 'max' for accuracy
factor=0.5, # multiply LR by factor on plateau
patience=3, # epochs to wait before reducing
min_lr=1e-7,
threshold=1e-4,
)
for epoch in range(epochs):
train(...)
val_loss = validate(...)
scheduler.step(val_loss) # pass the metric!OneCycleLR et CyclicLR
OneCycleLR (super-convergence) fait un warmup, culmine, puis anneale — souvent le moyen le plus rapide d'entraîner un modèle à une exactitude donnée. Il step par batch, donc réglez total_steps = époques * batchs_par_époque. pct_start=0.3 passe 30 % des pas en warmup. CyclicLR oscille entre LR de base et max, utile pour trouver de bons LRs (test de plage de LR).
from torch.optim.lr_scheduler import OneCycleLR
# one cycle: warm up, peak, anneal down
scheduler = OneCycleLR(
optimizer,
max_lr=1e-3,
total_steps=epochs * len(loader), # or steps_per_epoch + epochs
pct_start=0.3, # fraction spent warming up
anneal_strategy='cos',
)
# step per BATCH (not per epoch)
for epoch in range(epochs):
for x, y in loader:
train_step(...)
scheduler.step() # call once per batch
# simpler cyclic LR
from torch.optim.lr_scheduler import CyclicLR
scheduler = CyclicLR(optimizer, base_lr=1e-5, max_lr=1e-3, step_size_up=500)Warmup + décroissance
Le warmup stabilise les premiers pas quand l'estimation du second moment d'Adam est mal conditionnée — essentiel à l'entraînement transformer. LinearLR + SequentialLR combine proprement le warmup à tout planning de décroissance. LambdaLR donne le contrôle total via une fonction du compteur de pas — le scheduler le plus flexible. Pour les plannings style HuggingFace, regardez transformers.get_cosine_schedule_with_warmup.
from torch.optim.lr_scheduler import LinearLR, SequentialLR, CosineAnnealingLR
# linear warmup for first N steps
warmup = LinearLR(optimizer, start_factor=0.1, total_iters=500)
# cosine decay after warmup
cosine = CosineAnnealingLR(optimizer, T_max=total_steps - 500, eta_min=1e-6)
# combine
scheduler = SequentialLR(
optimizer,
schedulers=[warmup, cosine],
milestones=[500],
)
# manual warmup (transformers-style)
def lr_lambda(step):
if step < 500:
return step / 500
return 0.5 * (1 + math.cos(math.pi * (step - 500) / (total - 500)))
from torch.optim.lr_scheduler import LambdaLR
scheduler = LambdaLR(optimizer, lr_lambda)Scheduler personnalisé
LambdaLR multiplie le LR de base par lambda(step) — la façon la plus flexible d'implémenter des plannings custom. Passez une liste de lambdas (une par param_group) pour des plannings par groupe, ex. décroître les poids mais pas les biais, ou utiliser des plannings différents pour backbone et tête en transfer learning. Les lambdas doivent être bon marché car ils tournent à chaque pas. Évitez les closures Python capturant un état mutable — gardez-les pures.
from torch.optim.lr_scheduler import LambdaLR
import math
# any function of step / epoch
def warmup_cosine(step, warmup=500, total=10000):
if step < warmup:
return step / warmup
progress = (step - warmup) / (total - warmup)
return 0.5 * (1 + math.cos(math.pi * progress))
scheduler = LambdaLR(optimizer, lr_lambda=warmup_cosine)
# per-parameter-group schedule (e.g. decay only weights, not bias)
scheduler = LambdaLR(
optimizer,
lr_lambda=[lambda s: 0.9 ** s, lambda s: 1.0], # one per group
)
# inspect
for step in range(0, total, 1000):
print(step, scheduler.get_last_lr())
scheduler.step()Transfer learning
Modèles préentraînés
Utilisez toujours l'API WeightsEnum (DEFAULT prend le meilleur disponible) — le vieux pretrained=True est déprécié. Chaque objet weights expose .transforms() retournant le prétraitement exact avec lequel le modèle a été entraîné — utilisez-le pour que vos entrées matchent. La tête de classifieur sort les 1000 classes d'ImageNet ; remplacez-la pour votre tâche.
import torchvision.models as M
# load a model with pretrained ImageNet weights
weights = M.ResNet50_Weights.DEFAULT
model = M.resnet50(weights=weights)
# get the matching preprocessing transform
preprocess = weights.transforms()
print(preprocess) # resize, crop, normalize with ImageNet stats
# model is ready for 1000-class ImageNet inference
model.eval()
with torch.no_grad():
out = model(preprocess(img).unsqueeze(0))
pred = out.argmax(1)
print(weights.meta['categories'][pred])Extraction de caractéristiques
L'extraction de caractéristiques gèle le backbone et n'entraîne qu'une nouvelle tête — le baseline de transfer learning le plus rapide, atteignant souvent une haute exactitude en minutes d'entraînement sur un petit jeu. Le backbone étant gelé, on peut précalculer les caractéristiques une fois et entraîner un classifieur bon marché dessus, économisant beaucoup de calcul. Réglez model.eval() pour que le BatchNorm utilise ses stats courantes même en entraînant la tête.
import torch.nn as nn
import torchvision.models as M
# load backbone, freeze it, replace head
model = M.resnet50(weights=M.ResNet50_Weights.DEFAULT)
# freeze all parameters
for p in model.parameters():
p.requires_grad_(False)
# replace classifier for new task (10 classes)
model.fc = nn.Linear(model.fc.in_features, 10)
# only the new fc has requires_grad=True
# train only the head
optimizer = torch.optim.Adam(model.fc.parameters(), lr=1e-3)
# inference-friendly: extract features once
features = torch.nn.Sequential(*list(model.children())[:-1])
feat = features(images).flatten(1) # (N, 2048)Fine-tuning
Le fine-tuning entraîne tout le modèle (ou une partie) avec un petit LR pour que les caractéristiques préentraînées s'adaptent à votre tâche. Utilisez des LRs différentiels : plus petits pour les premières couches (caractéristiques générales), plus grands pour la tête (spécifique à la tâche). Le unfreezing progressif — entraîner la tête d'abord, puis dégeler les couches profondes — est plus stable que tout entraîner d'un coup, surtout sur les petits jeux.
import torch.nn as nn
import torch.optim as optim
import torchvision.models as M
model = M.resnet50(weights=M.ResNet50_Weights.DEFAULT)
model.fc = nn.Linear(model.fc.in_features, 10)
# differential learning rates: lower for backbone, higher for head
optimizer = optim.Adam([
{'params': [p for n, p in model.named_parameters() if 'fc' not in n], 'lr': 1e-4},
{'params': model.fc.parameters(), 'lr': 1e-3},
])
# gradual unfreezing: train head first, then unfreeze later layers
def unfreeze(layer_idx):
for n, p in model.named_parameters():
if f'layer{layer_idx}' in n:
p.requires_grad_(True)
# warmup head only for a few epochs, then unfreeze layer4, etc.Geler et dégeler les couches
requires_grad_(False) empêche autograd de suivre et mettre à jour un paramètre — mais les gradients traversent quand même les couches gelées vers les entraînables en aval. Utilisez named_parameters() pour filtrer par nom de couche et geler sélectivement. Loggez toujours le compte de paramètres entraînables pour ne pas geler tout accidentellement (un bug silencieux courant). Après le dégel, recréez l'optimiseur pour qu'il prenne les nouveaux paramètres entraînables.
model = M.resnet50(weights=M.ResNet50_Weights.DEFAULT)
model.fc = nn.Linear(model.fc.in_features, 10)
# freeze everything except fc
for name, p in model.named_parameters():
p.requires_grad = ('fc' in name)
# freeze specific submodule
for p in model.layer1.parameters():
p.requires_grad_(False)
# count trainable params
n = sum(p.numel() for p in model.parameters() if p.requires_grad)
print(f"trainable: {n:,}")
# unfreeze after warmup
for p in model.layer4.parameters():
p.requires_grad_(True)
# trainable params still need grad to flow: ensure no torch.no_grad
# and that frozen layers don't break autogradRemplacer le classifieur
Chaque architecture garde son classifieur dans un attribut différent — ResNet utilise .fc, EfficientNet .classifier[1], ViT .heads.head. Régler la nouvelle tête avec requires_grad=True signifie que seule elle s'entraîne au début. Pour le multi-tâches, remplacez la tête par plusieurs couches Linear partageant le backbone. nn.Identity() est un module no-op pratique pour retirer proprement la tête d'origine.
import torch.nn as nn
import torchvision.models as M
model = M.resnet50(weights=M.ResNet50_Weights.DEFAULT)
# ResNet: model.fc
model.fc = nn.Linear(model.fc.in_features, num_classes)
# EfficientNet: model.classifier[1]
model = M.efficientnet_b0(weights=M.EfficientNet_B0_Weights.DEFAULT)
model.classifier[1] = nn.Linear(model.classifier[1].in_features, num_classes)
# ViT: model.heads.head
model = M.vit_b_16(weights=M.ViT_B_16_Weights.DEFAULT)
model.heads.head = nn.Linear(model.heads.head.in_features, num_classes)
# multi-task head
class MultiTask(nn.Module):
def __init__(self, backbone, n_cls, n_reg):
super().__init__()
self.backbone = backbone
in_f = backbone.fc.in_features
backbone.fc = nn.Identity()
self.cls = nn.Linear(in_f, n_cls)
self.reg = nn.Linear(in_f, n_reg)
def forward(self, x):
f = self.backbone(x)
return self.cls(f), self.reg(f)Visualisation
Mise en place TensorBoard
SummaryWriter streame les événements vers un répertoire de logs ; lancez TensorBoard avec `tensorboard --logdir=runs` pour visualiser. add_scalar trace une métrique unique vs pas ; add_scalars superpose plusieurs courbes sur un graphique. Utilisez des sous-répertoires séparés par expérience (runs/exp1, runs/exp2) pour comparer les runs dans la même UI. Flush avec writer.close() à la fin pour que les derniers événements s'écrivent.
from torch.utils.tensorboard import SummaryWriter
writer = SummaryWriter('runs/experiment_1')
# log scalars (loss, accuracy, LR)
writer.add_scalar('train/loss', loss.item(), step)
writer.add_scalar('val/accuracy', acc, step)
writer.add_scalar('lr', optimizer.param_groups[0]['lr'], step)
# log multiple metrics together
writer.add_scalars('losses', {
'train': train_loss,
'val': val_loss,
}, step)
# close at the end
writer.close()
# launch: tensorboard --logdir=runsLogger graphes et histogrammes
add_graph visualise l'architecture du modèle dans l'onglet Graphs — utile pour déboguer le flux forward. add_histogram montre la distribution des poids ou gradients dans le temps ; un entraînement sain garde les gradients non nuls et les poids grossièrement en cloche. Des pics soudains dans les histogrammes de gradients trahissent l'instabilité. Logger chaque pas est lent — échantillonnez tous les N pas.
writer = SummaryWriter('runs/exp')
# log model graph (needs a sample input)
model = MLP(784, 128, 10)
writer.add_graph(model, torch.randn(1, 784))
# weight histograms (per layer, over training)
for name, p in model.named_parameters():
writer.add_histogram(f'weights/{name}', p, step)
if p.grad is not None:
writer.add_histogram(f'grads/{name}', p.grad, step)
# text
writer.add_text('config', 'lr=1e-3, batch=32', 0)
# close at the end
writer.close()Logger des images
add_image prend un tenseur CHW ; utilisez make_grid pour tuiler un batch en une image avec normalize=True pour qu'il passe à une plage affichable. add_figure logge directement une Figure matplotlib. draw_segmentation_masks et draw_bounding_boxes (torchvision.utils) superposent les prédictions pour un QA visuel rapide. Loggez quelques échantillons de validation par époque pour suivre la progression qualitative, pas seulement les métriques scalaires.
writer = SummaryWriter('runs/exp')
# single image (CHW tensor in [0,1] or [0,255])
writer.add_image('val/sample', img_tensor, step)
# grid of images
from torchvision.utils import make_grid
grid = make_grid(images, nrow=8, normalize=True)
writer.add_image('val/batch', grid, step)
# figure from matplotlib
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot([1,2,3], [1,4,9])
writer.add_figure('curves/loss', fig, step)
# overlay segmentation mask on image
from torchvision.utils import draw_segmentation_masks
overlay = draw_segmentation_masks(img, masks, alpha=0.5)
writer.add_image('val/masks', overlay, step)Graphe torchviz
torchviz dessine le graphe autograd d'une passe forward — génial pour déboguer les mismatchs de forme, branches involontaires ou tenseurs détachés. Chaque nœud est une op ; les arêtes montrent le flux de tenseurs. show_saved=True affiche aussi les tenseurs intermédiaires conservés pour le backward, ce qui détermine l'usage mémoire. Installez avec `pip install torchviz` et Graphviz sur le PATH système.
from torchviz import make_dot
x = torch.randn(1, 784, requires_grad=True)
y = model(x)
loss = criterion(y, torch.tensor([1]))
loss.backward()
# render the autograd graph
dot = make_dot(loss, params=dict(model.named_parameters()))
dot.render('model_graph', format='png') # saves model_graph.png
# also show saved tensors (memory)
dot = make_dot(loss, params=dict(model.named_parameters()),
show_attrs=True, show_saved=True)Sondage des poids et activations
Visualiser les filtres de première couche montre ce que le modèle « cherche » — contours, couleurs, textures. Les forward hooks capturent les activations sans modifier forward, parfaits pour sonder les couches intermédiaires ou bâtir des extracteurs de caractéristiques. Suivez les statistiques de poids et gradients (moyenne, écart-type, norme) par pas pour attraper les neurones morts (gradients nuls) ou les activations explosives. torchsummary ou torchinfo imprime une table de paramètres propre par couche.
import matplotlib.pyplot as plt
# visualize conv filters
filters = model.features[0].weight.data.clone().cpu()
fig, axes = plt.subplots(4, 8, figsize=(10, 5))
for i, ax in enumerate(axes.flat):
if i < filters.size(0):
ax.imshow(filters[i, 0], cmap='gray')
ax.axis('off')
# hook to capture activations
acts = {}
def hook(name):
def fn(mod, inp, out): acts[name] = out.detach().cpu()
return fn
model.features[3].register_forward_hook(hook('l1'))
# activation statistics over training
for name, p in model.named_parameters():
print(name, p.data.mean().item(), p.data.std().item(),
p.grad.norm().item() if p.grad is not None else None)Entraînement distribué
Mise en place DDP
DistributedDataParallel (DDP) est le motif standard d'entraînement multi-GPU : un processus par GPU, gradients all-reduced pour que toutes les répliques restent synchronisées. nccl est le backend le plus rapide sur GPU NVIDIA. torchrun règle les variables d'env (RANK, WORLD_SIZE, LOCAL_RANK) pour vous. Appelez toujours dist.destroy_process_group() à la fin pour que le job quitte proprement. Voir la section entraînement GPU pour la boucle complète.
import os, torch
import torch.distributed as dist
import torch.nn as nn
def setup():
dist.init_process_group(backend='nccl')
local_rank = int(os.environ['LOCAL_RANK'])
torch.cuda.set_device(local_rank)
return local_rank
def cleanup():
dist.destroy_process_group()
# launch with torchrun
# torchrun --nproc_per_node=4 train.py
# rank, world_size, LOCAL_RANK are set by torchrun
local_rank = setup()
model = model.to(local_rank)
model = nn.parallel.DistributedDataParallel(
model, device_ids=[local_rank], output_device=local_rank,
)DistributedSampler
DistributedSampler répartit le dataset entre processus pour que chaque GPU voie un sous-ensemble unique de chaque batch (batch effectif = batch_size * world_size). Vous DEVEZ appeler sampler.set_epoch(epoch) à chaque époque — sans cela, chaque époque utilise le même mélange et le modèle voit le même ordre. Ne passez pas shuffle=True au DataLoader quand vous utilisez un sampler ; le sampler gère l'ordre.
from torch.utils.data import DataLoader
from torch.utils.data.distributed import DistributedSampler
sampler = DistributedSampler(
dataset,
num_replicas=dist.get_world_size(),
rank=dist.get_rank(),
shuffle=True,
drop_last=True,
)
loader = DataLoader(dataset, batch_size=64, sampler=sampler,
num_workers=4, pin_memory=True)
for epoch in range(epochs):
sampler.set_epoch(epoch) # reshuffle per epoch
for x, y in loader:
# each GPU sees a non-overlapping subset
...Lancement multi-nœuds
torchrun lance un processus par GPU et les connecte via TCP. Pour le multi-nœud, lancez torchrun sur chaque nœud avec le même master_addr et un node_rank unique. Le point de rendez-vous (--rdzv_endpoint) permet aux nœuds de se trouver et supporte les redémarrages élastiques. Assurez-vous que master_port est ouvert au pare-feu et que tous les nœuds joignent master_addr. NCCL exige aussi un interconnect haut débit (InfiniBand/NVLink) pour un bon scaling.
# single-node, 4 GPUs
torchrun --nproc_per_node=4 train.py
# multi-node (2 nodes, 4 GPUs each = 8 total)
# node 0 (master):
torchrun --nproc_per_node=4 --nnodes=2 --node_rank=0 \
--master_addr=10.0.0.1 --master_port=29500 train.py
# node 1:
torchrun --nproc_per_node=4 --nnodes=2 --node_rank=1 \
--master_addr=10.0.0.1 --master_port=29500 train.py
# in code, world_size = nnodes * nproc_per_node
print(dist.get_world_size()) # 8
# also supports elastic restart on node failure
torchrun --nproc_per_node=4 --rdzv_backend=c10d \
--rdzv_endpoint=10.0.0.1:29500 train.pySynchronisation des gradients
DDP chevauche l'all-reduce des gradients avec le calcul du backward, d'où son excellent scaling. find_unused_parameters=True est nécessaire quand certains paramètres ne reçoivent pas de gradient à chaque pas (ex. branches conditionnelles) mais coûte de l'overhead — évitez-le si possible. model.no_sync() saute la sync pour un pas, utile avec l'accumulation de gradients pour ne sync qu'une fois par batch effectif au lieu de chaque micro-batch.
# DDP all-reduces gradients after backward by default
loss.backward() # gradients synchronized across GPUs
# skip sync for unused parameters (small speedup)
model = nn.parallel.DistributedDataParallel(
model, device_ids=[local_rank],
find_unused_parameters=False, # set True if some params unused
)
# manual gradient sync (advanced)
for p in model.parameters():
if p.grad is not None:
dist.all_reduce(p.grad, op=dist.ReduceOp.SUM)
p.grad /= dist.get_world_size()
# only sync on the last micro-batch (gradient accumulation)
# use model.no_sync() context for the non-final steps
with model.no_sync():
loss.backward()Logging et checkpointing
Conditionnez toujours logging et checkpointing à rank==0 pour éviter doublons et conditions de course. En sauvegardant un modèle DDP, utilisez model.module.state_dict() — DDP enveloppe le module sous-jacent, et sauvegarder l'enveloppe rend le checkpoint spécifique DDP et difficile à charger en code non distribué. Chargez le checkpoint sur chaque rank avant d'envelopper avec DDP pour que toutes les répliques partent des mêmes poids.
# only log from rank 0 to avoid duplicates
if dist.get_rank() == 0:
writer.add_scalar('train/loss', loss.item(), step)
print(f'step {step}: loss={loss.item():.4f}')
# only save checkpoint from rank 0
if dist.get_rank() == 0:
torch.save({
'model': model.module.state_dict(), # unwrap DDP
'optimizer': optimizer.state_dict(),
'epoch': epoch,
}, 'ckpt.pt')
# load on all ranks, then wrap with DDP
state = torch.load('ckpt.pt', map_location='cpu')
model.load_state_dict(state['model'])
model = model.to(local_rank)
model = nn.parallel.DistributedDataParallel(model, device_ids=[local_rank])FullyShardedDataParallel (FSDP)
FSDP répartit paramètres, gradients et états d'optimiseur entre GPU — un modèle trop grand pour un GPU peut s'entraîner sur plusieurs. Contrairement à DDP (qui garde des répliques complètes), FSDP rassemble les morceaux à la demande pendant forward/backward. À utiliser quand le modèle ne tient pas dans la mémoire d'un seul GPU. La sauvegarde est plus délicate : enveloppez la collecte de state_dict en mode FULL_STATE_DICT pour que le rank 0 matérialise le modèle complet. Précision mixte + FSDP + activation checkpointing permet d'entraîner de très grands modèles.
from torch.distributed.fsdp import FullyShardedDataParallel as FSDP
from torch.distributed.fsdp import ShardingStrategy
model = LargeModel().to(local_rank)
model = FSDP(
model,
sharding_strategy=ShardingStrategy.FULL_SHARD,
device_id=local_rank,
use_orig_params=True, # needed for save/load compatibility
)
# forward / backward as usual
loss = criterion(model(x), y)
loss.backward()
optimizer.step()
# save: only the full state on rank 0
from torch.distributed.fsdp import FullyShardedDataParallel as FSDP
import torch.distributed.fsdp.api as fsdp_api
with FSDP.state_dict_type(model, fsdp_api.StateDictType.FULL_STATE_DICT):
state = model.state_dict()
if dist.get_rank() == 0:
torch.save(state, 'fsdp_ckpt.pt')Snippets PyTorch associés
Copy-paste ready code for common tasks.
Tensor Basics
Create, index, and operate on tensors.
Autograd
Compute gradients automatically with backward().
Dataset and DataLoader
Build custom datasets and batch them with DataLoader.
Model Definition
Define models with nn.Module and Sequential.
Training Loop
Run a full train-eval loop with loss and optimizer.
GPU and CUDA
Move models and tensors to GPU and handle availability.
Save and Load
Checkpoint models, optimizer state, and weights.
Transfer Learning
Fine-tune a pretrained torchvision model.
Was this helpful?