Primeros pasos
Instalación y tensores
Los tensores de PyTorch son la estructura de datos central. Usa to(device) para mover tensores a GPU. torch.randn devuelve números aleatorios de una distribución normal. Elige la URL del wheel correcta para tu versión de CUDA; las compilaciones solo CPU son menores para desarrollo.
# 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)Atributos del tensor
Cada tensor tiene atributos shape, dtype y device. Dtypes comunes: float32 (por defecto), float16, int64, bool. numel() devuelve el número total de elementos. Elige float16 para precisión mixta y reducir a la mitad la memoria y acelerar el cómputo en 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()) # 3Creación de tensores
torch.zeros/ones/full crean tensores constantes. arange y linspace crean tensores de rango. rand es uniforme, randn es normal. randint excluye el límite alto. Usa torch.manual_seed(42) antes de las operaciones aleatorias por reproducibilidad.
# 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))Conversión de tipos
to(dtype) convierte el tipo del tensor. Atajos: .float(), .long(), .int(), .bool(). numpy() comparte memoria con el tensor (copia cero en CPU). item() extrae un único escalar de Python de un tensor 0-d. Los tensores de GPU deben moverse a CPU antes de 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.5Indexación y slicing
La indexación de PyTorch refleja a NumPy. La indexación con enteros devuelve un tensor 0-d (usa .item() para un escalar de Python). Las máscaras booleanas aplanan el resultado. Indexar con un LongTensor selecciona a lo largo de la primera dimensión. La indexación avanzada crea copias; el slicing básico crea vistas.
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 2Reformar y vistas
view exige memoria contigua; reshape funciona siempre (copia si hace falta). unsqueeze/squeeze añaden/quitan dimensiones de tamaño 1. permute reordena todas las dimensiones; transpose intercambia dos. reshape(-1) aplana. Operaciones como permute pueden dejar los tensores no contiguos, exigiendo .contiguous() antes de 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) # equivalentOperaciones de tensor
Operaciones aritméticas
Los operadores aritméticos (+, -, *, /) son elemento a elemento. Las operaciones in situ terminan en _ y ahorran memoria pero invalidan el historial de autograd — evítalas en tensores que requieran grad. El broadcasting sigue las reglas de NumPy: las dimensiones finales se emparejan o se estiran a 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.5Matemática elemento a elemento
La matemática elemento a elemento refleja las funciones torch.* y tensor.*. clamp es el nombre de PyTorch para el recorte. Usa torch.finfo(x.dtype).eps en lugar de un 1e-8 fijo para un log numéricamente seguro. Las funciones de activación también están disponibles como módulos nn (nn.ReLU()) para los modelos.
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)Operaciones de reducción
Las reducciones colapsan una o más dimensiones. Pasa dim para elegir el eje; keepdim=True conserva el eje reducido como tamaño 1 (crítico para el broadcasting). max/min con un dim devuelven una tupla con nombre (values, indices). item() pasa un tensor 0-d a un escalar de 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 normOperaciones de comparación
Los operadores de comparación devuelven tensores bool. torch.equal comprueba la igualdad exacta y devuelve un bool de Python. torch.where(cond, x, y) es el ternario vectorizado — perfecto para enmascarar o seleccionar. topk devuelve tanto valores como índices, útil para la exactitud 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 + indicesOperaciones de matriz
@ y torch.matmul hacen multiplicación de matrices y difunden sobre las dimensiones de lote. Usa torch.bmm para un matmul estricto por lotes 3D (sin broadcasting). einsum es expresivo para contracciones de múltiples tensores pero puede ser más lento que matmul en algún hardware. Evita invertir matrices cuando puedas resolver con 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 dotConcatenación y apilado
cat une tensores a lo largo de un eje existente; stack añade un eje nuevo. split divide por tamaño de fragmento, chunk por número de piezas. expand crea una vista con datos difundidos (sin copia de memoria) — úsalo en lugar de repeat cuando puedas. repeat duplica físicamente los datos.
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 básico
Fija requires_grad=True para rastrear las operaciones en autograd. Llamar a .backward() sobre un tensor escalar computa los gradientes de ese tensor respecto de cada tensor hoja con requires_grad=True. Los gradientes se acumulan en .grad — llama a optimizer.zero_grad() o x.grad=None entre iteraciones.
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.])Computar gradientes
backward() solo funciona sobre salidas escalares; para tensores, suma o haz media primero. torch.autograd.grad devuelve los gradientes como tupla sin guardarlos en .grad. Es lo preferido dentro de librerías o cuando necesitas gradientes de tensores no hoja.
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 = 8Desactivar el rastreo de gradientes
Usa torch.no_grad() para inferencia y saltarte la construcción del grafo — ahorra memoria y tiempo. .detach() devuelve un tensor que comparte datos pero está cortado del grafo; genial para logging o alimentar tensores a código no PyTorch. model.eval() cambia las capas (dropout, BN) a modo inferencia pero NO desactiva autograd — combínalo con 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 gradGradientes de orden superior
create_graph=True conserva el grafo del propio gradiente para que puedas diferenciar de nuevo. Útil para penalizaciones de gradiente (WGAN-GP), meta-aprendizaje y pérdidas informadas por física. Cuesta memoria extra — libera los grafos intermedios con retain_graph=False al terminar.
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 gradiente
register_hook sobre un tensor te permite inspeccionar o modificar su gradiente durante backward — práctico para depurar NaNs o implementar el recorte de gradientes sobre tensores concretos. register_full_backward_hook sobre un módulo ve tanto los gradientes de entrada como de salida. Devuelve siempre un gradiente modificado si quieres que los cambios se propaguen.
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)Detalles del grafo computacional
Los tensores hoja son creados por el usuario (requires_grad=True, sin grad_fn). Los resultados intermedios son no hoja. Por defecto el grafo se libera tras backward(); pasa retain_graph=True para llamar a backward varias veces. create_graph=True retiene el grafo del gradiente para derivadas de orden superior. La memoria crece rápido — limpia con x.grad=None entre iteraciones.
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)Carga de datos
Dataset y DataLoader
DataLoader agrupa en lotes, baraja y carga en paralelo un Dataset. num_workers>0 usa subprocesos — fija 2-8 por GPU. pin_memory=True acelera la transferencia CPU→GPU. Para datasets pequeños que caben en RAM, fja num_workers=0 para evitar la sobrecarga.
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,)
breakMuestreo de lotes
Pasa un batch_sampler para controlar exactamente qué índices forman cada lote. WeightedRandomSampler reequilibra clases desequilibradas sobremuestreando las raras. drop_last=True descarta el último lote corto — importante para la estabilidad de BatchNorm. Los samplers itera sobre índices; el DataLoader obtiene los datos reales.
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)Barajar y muestrear
shuffle=True aleatoriza el orden en cada época (bueno para entrenar); mantén la validación con shuffle=False por métricas reproducibles. random_split es cómodo pero su RNG no es directamente sembrable — usa Subset con torch.randperm y un Generator para control total. Subset es solo una vista fina de índices, sin copia de datos.
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 personalizado
collate_fn convierte una lista de muestras en un lote. La de por defecto apila tensores a lo largo de una nueva dim 0. Sobrescríbela para secuencias de longitud variable (rellena y luego ordena por longitud para pack_padded_sequence), muestras basadas en dict o datos mixtos tensor/no-tensor. Mantén la función barata — corre en los workers de carga de datos.
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)Carga en paralelo
num_workers paraleliza la carga de datos para que la GPU nunca espere. persistent_workers=True evita el coste de arranque del worker por época. prefetch_factor (2 por defecto) controla cuántos lotes prepara cada worker por adelantado. En Windows y Jupyter, el multiproceso puede ser inestable — recurre a num_workers=0 para depurar. Cuidado: cada worker hereda el estado completo del proceso, incluidos manejadores de archivos abiertos y contextos 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
Definir un módulo
Hereda de nn.Module e implementa forward(). Declara submódulos y parámetros como atributos para que se registren automáticamente (esto es lo que habilita .to(device), .parameters() y state_dict). Llama siempre a super().__init__(). Evita la lógica de Python arbitraria en forward — manténla diferenciable y solo con tensores.
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 structureCapas lineales y de activación
nn.Linear aplica y = xW^T + b. La forma del peso es (out, in). Prefiere los módulos de activación cuando quieras que se registren (state_dict, hooks); usa las funcionales F.* para operaciones puntuales. Las activaciones GELU y estilo SwiGLU dominan las arquitecturas transformer. Softmax normalmente debería omitirse del modelo y manejarlo 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))Parámetros y submódulos
named_parameters() cede (nombre, tensor) para el árbol completo — genial para congelar, weight decay o depurar. .modules() recursa en los hijos; .children() solo un nivel. Los buffers (por ejemplo, estadísticas acumuladas de BatchNorm) aparecen en state_dict pero no en parameters(); usa named_buffers() para verlos.
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-modulesModelos Sequential
nn.Sequential encadena módulos donde cada salida alimenta la siguiente entrada — perfecto para pipelines lineales. Usa OrderedDict para nombrar etapas y poder indexar por atributo (model.fc1). Para modelos con ramas, conexiones de salto o múltiples entradas/salidas, hereda de nn.Module y escribe forward() explícitamente.
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))Funciones de módulo
to(device) mueve parámetros y buffers; .double()/.half()/.float() castea dtypes. train()/eval() alterna el flag self.training — Dropout y BatchNorm ramifican según él. state_dict() devuelve un OrderedDict de la totalidad de los parámetros y buffers; load_state_dict los restaura. .apply(fn) recursa en cada submódulo, útil para inicialización personalizada.
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)Inicialización
PyTorch usa la inicialización de Kaiming He para Linear/Conv por defecto, que funciona para la mayoría de casos. Sobrescríbela con las funciones torch.nn.init (el sufijo _ significa in situ). Kaiming encaja con la familia ReLU; Xavier/Glorot con tanh/sigmoid. Inicializar los sesgos a cero es lo estándar. .apply(fn) corre fn en cada submódulo — perfecto para inicialización masiva o reinicio de pesos.
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)Funciones de pérdida
CrossEntropyLoss
CrossEntropyLoss aplica log-softmax + NLLLoss internamente — pasa logits crudos, nunca salidas de softmax. Los objetivos son índices de clase enteros (no one-hot). Usa weight para clases desequilibradas e ignore_index=-100 para enmascarar tokens de padding. label_smoothing=0.1 es un regularizador popular para clasificación y 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 y L1Loss
MSELoss penaliza los errores grandes cuadráticamente (sensible a atípicos); L1 es lineal y más robusta. SmoothL1Loss se comporta como L2 cerca de cero y L1 lejos — se usa en detección de objetos (Fast R-CNN). reduction='none' devuelve un tensor por elemento para que puedas enmascararlo o ponderarlo tú mismo antes de llamar a .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 y BCEWithLogitsLoss
Prefiere siempre BCEWithLogitsLoss a BCELoss+sigmoid — usa el truco log-sum-exp para estabilidad numérica. pos_weight multiplica el término positivo para contrarrestar el desequilibrio de clases (como una focal loss ligera). Para clasificación multi-etiqueta (cada clase independiente), usa BCEWithLogitsLoss con forma (N, C) y salidas 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)Función de pérdida personalizada
Una pérdida personalizada es solo una función (o nn.Module) que devuelve un tensor escalar — autograd maneja el resto. Haz que cada operación sea diferenciable (torch.where con ramas diferenciables está bien). La forma de módulo es preferida cuando necesitas hiperparámetros, serialización o registrarlo en una configuración. Mantén la reducción explícita (mean/sum/none) para que el comportamiento sea predecible.
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()Reducción y combinación de pérdidas
reduction='none' da pérdidas por muestra para que puedas enmascarar, reponderar o agregar manualmente. Combina pérdidas multitarea con una suma ponderada — los pesos equilibran gradientes, no solo magnitudes (ajústalos). Cada subpérdida debe seguir siendo diferenciable y en el mismo device/dtype. Desacopla un término de pérdida con .detach() si quieres registrarlo sin retropropagar a través de él.
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 y otras pérdidas
NLLLoss + LogSoftmax es matemáticamente idéntico a CrossEntropyLoss pero te permite reutilizar los log-probs. TripletMarginLoss entrena embeddings de aprendizaje métrico. KLDivLoss espera log-probs como entrada y probs como objetivo. CTCLoss alinea secuencias sin segmentar con objetivos — pasa input_lengths y target_lengths para evitar errores de runtime.
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)Optimizadores
SGD
SGD + momentum sigue siendo una gran elección para el entrenamiento CNN con lotes grandes y generaliza mejor que Adam en algunas tareas. Momentum 0.9 es el estándar; Nesterov da una pequeña ventaja extra. weight_decay añade regularización L2. SGD necesita una programación de LR cuidadosa y warmup; no se autoajusta como 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 y AdamW
Adam guarda momentos por parámetro, así que adapta el tamaño del paso automáticamente — un gran valor por defecto para NLP y datasets pequeños. AdamW desacopla el weight decay de la actualización del gradiente, lo que importa a escala (transformers). betas=(0.9, 0.999) es el estándar; algunos modelos de visión usan (0.9, 0.95). Usa grupos de parámetros para tasas de aprendizaje diferenciales en transferencia de aprendizaje.
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)Patrón de paso del optimizador
El patrón de 3 pasos — zero_grad, backward, step — es el corazón del entrenamiento de PyTorch. set_to_none=True (por defecto en versiones recientes) es más rápido que rellenar con ceros porque se salta un memset y deja que el optimizador salte el parámetro. Edita manualmente p.grad.data entre backward() y step() para recortar o actualizaciones personalizadas.
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()Recorte de gradientes
clip_grad_norm_ reescala los gradientes si su norma L2 global excede max_norm — un valor por defecto estable para RNNs y transformers. clip_grad_value_ acorta duramente cada elemento (menos común). El recorte previene gradientes explosivos sin cambiar la dirección. Registra la norma del gradiente previa al recorte para detectar la inestabilidad temprano (picos súbitos > 100 indican problemas).
# 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)Tasa de aprendizaje y programaciones
Cada param_group tiene su propio lr — itera para fijar cada uno. El warmup manual sube el LR linealmente durante los primeros N pasos para estabilizar el entrenamiento temprano (crítico para transformers sin corrección de sesgo). Usa un objeto scheduler (siguiente sección) para la decadencia coseno, OneCycle, etc. Avanza siempre el scheduler después de optimizer.step() salvo que la documentación diga lo contrario.
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)Otros optimizadores
RMSprop es el optimizador clásico de RNNs y sigue funcionando bien. Adagrad acumula gradientes al cuadrado y puede estancarse temprano — bien para características dispersas pero no para redes profundas. LBFGS necesita una closure y evaluación de lote completo — genial para problemas convexos pequeños o fine-tuning, demasiado lento para redes profundas grandes. Para la mayoría de proyectos nuevos, empieza con 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)Bucle de entrenamiento
Bucle de entrenamiento básico
El bucle de entrenamiento mínimo: zero_grad, forward, loss, backward, step. Mueve los datos a GPU dentro del bucle (solape asíncrono con num_workers). loss.item() pasa un escalar a Python — hazlo para el logging, no para el tensor de pérdida en sí (romperías el grafo). Envuelve el bucle en una función para poder reutilizarlo.
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}")Validación en el bucle
model.eval() + torch.no_grad() son ambos necesarios: eval cambia dropout/BN, no_grad se salta el grafo. Acumula la pérdida ponderada (multiplica por el tamaño del lote) para que el promedio sea correcto incluso en el último lote corto. argmax(dim=1) da los índices de clase predichos. Guarda el mejor modelo cuando la métrica de validación mejore (ver la sección de guardado-carga).
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}")Acumulación de gradientes
La acumulación de gradientes simula un lote mayor sumando gradientes sobre varios mini-lotes antes de avanzar. Divide la pérdida entre accum_steps para que el gradiente efectivo coincida con un solo lote grande. Asegúrate de que la longitud del dataset sea divisible entre accum_steps, o avanza con los gradientes restantes al final de la época. Especialmente útil para el fine-tuning de transformers en una sola 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 sizeEntrenamiento con precisión mixta
La precisión mixta corre las operaciones de forward en float16 (o bfloat16 en Ampere+) para una aceleración de 1.5-3 veces y la mitad de memoria. GradScaler multiplica la pérdida para prevenir el subdesbordamiento del gradiente en float16 y luego desescala antes de optimizer.step(). En H100/A100 prefiere bfloat16 — tiene el mismo rango que float32 y no necesita scaler. El context manager autocast solo afecta al 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 lossProgreso y logging
tqdm muestra una barra de progreso en vivo — usa set_postfix para mostrar la pérdida acumulada. Una media móvil exponencial (running = 0.9*running + 0.1*loss) suaviza el ruido mejor que el valor crudo del último lote. Para ejecuciones serias, registra en TensorBoard o Weights & Biases en lugar de stdout para poder comparar ejecuciones. Evita registrar cada paso si ralentiza el entrenamiento.
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)Reproducibilidad
La reproducibilidad completa necesita semillas para Python, NumPy, PyTorch CPU y CUDA. cudnn.deterministic=True deshabilita los algoritmos no deterministas (algunas operaciones backward de conv). Los workers de DataLoader necesitan cada uno su semilla vía worker_init_fn porque se bifurcan con su propio estado RNG. Aun así, multi-GPU y algunas operaciones cuDNN pueden no ser bit-reproducibles — apunta a la reproducibilidad estadística.
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)Evaluación y métricas
Modo eval y no grad
Emparéja siempre model.eval() con torch.no_grad() para evaluar. eval() pasa dropout y BatchNorm a modo inferencia (BN usa estadísticas acumuladas); no_grad() desactiva autograd para ahorrar memoria y tiempo. Multiplica la pérdida por el tamaño del lote al acumular para que el promedio final sea sin sesgo incluso si el último lote es corto.
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}")Exactitud y top-k
argmax(dim=1) devuelve la clase predicha por fila. topk devuelve los k valores mayores y sus índices — igualándolos a los objetivos expandidos a (N,1) y usando .any(dim=1) obtienes la corrección top-k. La exactitud por clase expone problemas de desequilibrio que la exactitud global oculta. Mueve siempre los tensores a CPU y llama a .item() antes de pasarlos a print o 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())Matriz de confusión
Acumula predicciones en GPU y muévelas a CPU una vez al final para evitar sincronizaciones por lote. confusion_matrix muestra dónde confunde clases el modelo — perfecta para depurar. classification_report da precisión, recall y F1 por clase. Para datasets muy grandes, transmite las predicciones a disco en lugar de sostenerlas en memoria.
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))Precisión, recall y F1
torchmetrics acumula estado entre lotes y computa la métrica correctamente incluso con desequilibrio de clases o tamaños de lote cambiantes. average='macro' trata todas las clases por igual; 'weighted' pondera por soporte; 'micro' equivale a exactitud para tareas de etiqueta única. Llama a .reset() entre épocas o evaluaciones para limpiar el acumulador.
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())Validación cruzada
La validación cruzada k-fold da una estimación robusta del rendimiento del modelo y su varianza. Reinstantia el modelo por pliegue para que los pesos no se filtren entre pliegues. Para datasets grandes, 5 pliegues suelen bastar; para pequeños, usa divisiones estratificadas (StratifiedKFold) para conservar el equilibrio de clases. Reporta media +/- desviación para que los lectores vean la estabilidad.
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}")Comparación de modelos
Compara siempre los modelos en el mismo conjunto de prueba apartado con la misma semilla y métrica. Más allá de la exactitud, mira la calibración, la latencia de inferencia y la memoria. Usa intervalos de confianza bootstrap cuando las diferencias del conjunto de prueba sean pequeñas. Conserva una tabla de resultados (CSV o W&B) para poder comparar contra experimentos futuros en lugar de solo la última ejecución.
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}")Guardar y cargar
Guardar y cargar el state dict
state_dict() es un OrderedDict de tensores de parámetros — guardarlo (no el modelo entero) es el patrón recomendado porque es portable y desacoplado de la estructura exacta de clases/archivos. map_location te permite cargar un checkpoint de CUDA en CPU. strict=False carga solo las claves coincidentes, práctico cuando la arquitectura cambió ligeramente.
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)Guardar el modelo entero
Guardar el modelo entero serializa el objeto de Python, atándolo a la clase exacta y estructura de archivos del momento del guardado. Es frágil — cualquier refactor rompe la carga. Úsalo solo para experimentos rápidos. Para cualquier cosa que vayas a desplegar o compartir, guarda el state_dict y conserva la arquitectura en código o configuración.
# 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 de entrenamiento
Un checkpoint completo guarda la totalidad de lo necesario para reanudar el entrenamiento exactamente: modelo, optimizador, scheduler, época y estados RNG. El estado del optimizador (búferes de momentum, momentos de Adam) es esencial — reanudar sin él reinicia efectivamente al optimizador y puede disparar la pérdida. Guarda el estado RNG solo si necesitas reproducibilidad bit-exacta.
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'])Guardar el mejor modelo
Guarda el mejor checkpoint por métrica de validación para poder recuperar el mejor modelo incluso si épocas posteriores sobreajustan. Para la mayoría de tareas conserva solo el mejor checkpoint para ahorrar disco; para investigación, conserva checkpoints por época para poder volver atrás. Combínalo con un log CSV de (época, train_loss, val_loss, val_acc, ruta) para saber qué checkpoint elegir.
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)Cargar modelos parciales
strict=False devuelve listas de claves faltantes e inesperadas — inspéctalas para confirmar que solo se saltaron las capas esperadas. Renombrar claves te permite adaptar un checkpoint a una arquitectura renombrada. Tras cargar un backbone, congela sus pesos para extracción pura de características o entrena con un LR mucho menor que el de la cabeza nueva.
# 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)Exportar a TorchScript
TorchScript produce un grafo autosuficiente que puedes cargar en LibTorch (C++) o Python sin la clase original — ideal para desplegar. trace captura un camino de flujo de control; script maneja el flujo dependiente de datos pero exige anotaciones de tipo. ONNX exporta para inferencia en ONNX Runtime, TensorRT u OpenVINO. Usa dynamic_axes para tamaño de lote 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
Capa Conv2d
La forma del peso de Conv2d es (canales_salida, canales_entrada/grupos, kH, kW). NCHW es el layout de memoria por defecto. padding='same' (PyTorch 1.9+) conserva el tamaño espacial para stride 1. groups=in_channels lo hace depthwise (usado en MobileNet). Computa el tamaño de salida: (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)Capas de pooling
El pooling submuestrea las dimensiones espaciales, añadiendo invariancia a pequeñas traslaciones. MaxPool conserva la respuesta más fuerte; AvgPool es más suave. AdaptiveAvgPool2d(1) colapsa las dimensiones espaciales a 1x1 — el 'pool de promedio global' estándar usado para alimentar características de conv a una cabeza Linear. Prefiere las convs con stride al pooling para el submuestreo aprendible en arquitecturas modernas.
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)Arquitectura CNN
Un bloque CNN canónico es Conv -> BatchNorm -> ReLU -> Pool. AdaptiveAvgPool2d(1) hace la red agnóstica al tamaño de entrada para que puedas entrenar a una resolución y probar a otra. BatchNorm2d va después de la conv, antes de la activación. Mantén los kernels de conv a 3x3 con padding=1 (estilo VGG) — son eficientes en parámetros y se fusionan bien.
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))Mapas de características y campo receptivo
Los mapas de características muestran qué detecta cada canal — las capas tempranas hallan bordes y colores, las profundas texturas y partes. register_forward_hook te permite capturar activaciones sin modificar forward. El campo receptivo crece con la profundidad y el pooling; aproximadamente, el píxel de salida (i,j) depende de un parche de entrada centrado ahí con tamaño = suma de strides y kernels hasta esa capa.
# 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)Normalización por lotes
BatchNorm2d normaliza por canal sobre (N, H, W), conservando estadísticas EMA acumuladas para inferencia. train()/eval() importa — eval usa las estadísticas acumuladas así que la salida es determinista. BatchNorm acopla ejemplos dentro de un lote, lo que se rompe con lotes muy pequeños; pásate a GroupNorm o LayerNorm entonces. SyncBatchNorm es necesaria para un BN correcto multi-GPU.
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 transferArquitecturas CNN populares
torchvision.models expone ResNet, EfficientNet, MobileNet, ViT y más con pesos preentrenados de ImageNet. Reemplazar la capa fc final es el punto de entrada estándar de la transferencia de aprendizaje. Para detección/segmentación, quita la cabeza y usa las características de conv. Comprueba la API de pesos (WeightsEnum) — el antiguo flag pretrained=True está obsoleto. Cada modelo tiene un campo receptivo y presupuesto de FLOPs conocidos; elige uno que encaje con tu objetivo de latencia.
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 y LSTM
Capa RNN
batch_first=True hace la entrada (lote, seq, característica) que coincide con la mayoría de convenciones NLP; sin él PyTorch usa (seq, lote, característica). La RNN vanilla sufre gradientes que se desvanecen en secuencias largas — prefiere LSTM o GRU en la práctica. out contiene los estados ocultos por paso de tiempo de la última capa; h_n contiene el estado final de cada capa.
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)Capa LSTM
LSTM devuelve tanto el estado oculto h_n como el estado de celda c_n. Bidireccional duplica el tamaño de la característica de salida. Para clasificación, usa el estado oculto final de cada dirección (h_n[-2] es la última capa hacia adelante, h_n[-1] la última hacia atrás). El dropout en nn.LSTM solo aplica entre capas apiladas, no en la entrada — envuelve la entrada con nn.Dropout si lo necesitas.
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)Capa GRU
GRU tiene solo estado oculto (sin estado de celda) y dos compuertas en lugar de tres, así que tiene menos parámetros y entrena ligeramente más rápido que LSTM. Empíricamente GRU y LSTM rinden similar en la mayoría de tareas; GRU es un buen valor por defecto para datasets menores. Como LSTM, el dropout solo aplica entre capas apiladas.
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 tasksSecuencias empaquetadas
Empaquetar se salta los tokens de padding en la computación de la RNN, lo que es más rápido y evita sesgar el estado oculto con ceros de relleno. Las secuencias deben ordenarse por longitud descendente para PyTorch antiguos; enforce_sorted=False ordena internamente (con una pequeña sobrecarga). pad_packed_sequence convierte de vuelta a un tensor con relleno. Combínalo con un collate_fn personalizado que rellene los lotes dinámicamente.
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)Clasificación de secuencias
Un clasificador de texto estándar: embedding -> biLSTM -> dropout -> linear. Usa padding_idx en nn.Embedding para que el token de padding tenga gradiente cero. Pasa lengths.cpu() a pack_padded_sequence porque corre en CPU. El estado oculto final de ambas direcciones se concatena para capturar la secuencia entera. Para secuencias largas, los transformers superan a los LSTMs pero necesitan más datos y cómputo.
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)Generación de secuencias (decoder)
Un decoder corre un paso a la vez, condicionándose al token de salida previo. LSTMCell es una LSTM de un solo paso — úsalo para control fino del bucle. Teacher forcing alimenta el token verdadero en el siguiente paso durante el entrenamiento, lo que converge mucho más rápido que alimentar las predicciones del propio modelo. En inferencia, cambia a alimentar el argmax (o muestrear) de los logits del paso previo.
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 computa la atención de producto punto escalado sobre cabezas en paralelo. batch_first coincide con la convención NLP (lote, seq, dim). Usa attn_mask para la decodificación causal (máscara triangular inferior) y key_padding_mask para ignorar los tokens de padding. need_weights=True devuelve la matriz de atención, útil para visualizar y sondear.
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)Encoder Transformer
TransformerEncoderLayer es un bloque de autoatención + FFN con residuales y LayerNorm. norm_first=True (pre-LN) es más estable para entrenar desde cero; post-LN (por defecto) necesita warmup. Apila N capas con nn.TransformerEncoder. Pasa src_key_padding_mask para que la atención ignore las posiciones de padding. Para clasificación, haz promediado por media de la secuencia de salida y alimenta una cabeza 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)Codificación posicional
Los transformers son invariantes a la permutación, así que necesitan información posicional. La codificación sinusoidal generaliza a secuencias más largas que las vistas en el entrenamiento. register_buffer guarda pe sin convertirlo en parámetro — se mueve con .to(device) y se guarda en state_dict. Los embeddings de posición aprendidos (nn.Parameter) también funcionan pero no extrapolan más allá de la longitud de entrenamiento.
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 completo (Seq2Seq)
Un transformer encoder-decoder completo para traducción/resumición. El decoder usa enmascaramiento causal sobre el objetivo (así la posición t solo puede atender a <= t) más atención cruzada a la salida del encoder (memoria). Pasa key_padding_masks tanto para la fuente como para el objetivo para que la atención ignore los tokens de padding. La cabeza proyecta las salidas del decoder a logits de vocabulario; la pérdida es CrossEntropyLoss con 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)Bloque Vision Transformer (ViT)
Un bloque ViT es autoatención pre-LN + MLP pre-LN con residuales — esencialmente lo mismo que una capa de encoder transformer. Los Vision Transformers trocean la imagen con un Conv2d con stride (kernel=stride=patch_size) y luego tratan los parches como tokens. Añade un token CLS y embeddings posicionales. nn.MultiheadAttention devuelve (salida, pesos) — desempaqueta con need_weights=False para omitir los pesos.
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)Atención desde cero
Atención de producto punto escalado: scores = QK^T / sqrt(d_k), softmax, multiplicar por V. El 1/sqrt(d_k) mantiene estable la varianza para que el softmax no sature. masked_fill con -inf antes del softmax pone a cero esas posiciones. La atención multi-cabeza divide el embedding en H cabezas, atiende en paralelo y concatena. Esto es exactamente lo que hace nn.MultiheadAttention — escríbelo desde cero solo para aprender o para añadir variantes como atención lineal/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)Entrenamiento en GPU
Selección de dispositivo
Comprueba siempre torch.cuda.is_available() para que las máquinas solo CPU no caigan. Puedes crear tensores directamente en un dispositivo con el argumento device= (más rápido que crear en CPU y mover). El context torch.device (PyTorch 2.x) fija un device por defecto para los tensores nuevos. MPS soporta GPUs de Apple Silicon pero carece de algunas características de CUDA — comprueba el soporte de operadores antes de depender de él.
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'Mover modelos y datos
model.to(device) mueve parámetros y buffers en el sitio. Mueve los tensores de entrada dentro del bucle de entrenamiento para que el DataLoader pueda transmitir desde disco. non_blocking=True solapa la copia CPU→GPU con el cómputo cuando el tensor fuente está en memoria fijada (fja pin_memory=True en el DataLoader). .cpu() / .numpy() antes de cualquier operación de NumPy — los tensores de GPU no pueden convertirse directamente.
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()Múltiples GPUs (DataParallel)
DataParallel (DP) replica el modelo en cada GPU, divide el lote y reúne las salidas en la GPU 0 — fácil pero lento y desequilibrado (la GPU 0 hace el gather y el cómputo de pérdida). Es de un solo proceso así que el GIL limita el escalado. Para cualquier trabajo multi-GPU serio, usa DistributedDataParallel en su lugar. DP está bien para prototipar rápido en 2-4 GPUs.
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) genera un proceso por GPU, cada uno con su propia réplica del modelo; los gradientes se all-reducen para que cada GPU vea el mismo gradiente. Es mucho más rápido y escalable que DataParallel. Usa torchrun (o torch.distributed.launch) para arrancar los procesos. Llama siempre a sampler.set_epoch(época) para que cada época vuelva a barajar. Mira la secci ón de entrenamiento distribuido para más.
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()Gestión de memoria
empty_cache() devuelve la memoria cacheada al sistema operativo pero no libera tensores aún en uso — llámalo tras un gran pico, no en el bucle caliente. memory_allocated son los tensores en uso; memory_reserved es el pool del asignador de caché. Para reducir OOM: baja el tamaño del lote, usa precisión mixta, checkpointing de gradiente o acumulación de gradiente. expandable_segments:True reduce la fragmentación para cargas de forma variable. Evita retener referencias a tensores que ya no necesitas (por ejemplo, pérdidas registradas en una lista).
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 y rendimiento
cudnn.benchmark=True deja que cuDNN perfile algoritmos en el primer forward y cachee el más rápido — genial cuando las formas de entrada son fijas (CNN típica), dañino si las formas cambian en cada paso (RNNs de longitud variable). TF32 usa mantisa de 19 bits en Ampere+ para ~3 veces de aceleración de matmul con pérdida mínima de exactitud; actívalo salvo que necesites reproducibilidad estricta fp32. El modo determinista deshabilita los algoritmos no deterministas.
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 y preprocesamiento
Transforms comunes
ToTensor convierte una imagen PIL (0-255) a un tensor float en [0,1] y reordena HWC -> CHW. Normalize luego estandariza por canal usando estadísticas de ImageNet (el estándar de facto para modelos preentrenados — iguala siempre las estadísticas con las que se entrenó el backbone). Aplica los transforms en el Dataset para que corran en los procesos worker; la GPU nunca espera al preprocesamiento de 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)Aumentación de datos
La aumentación regulariza al modelo mostrándole entradas variadas. RandomResizedCrop + flip es la aumentación clásica de ImageNet. ColorJitter cambia el color sin afectar a la geometría. TrivialAugmentWide y RandAugment muestrean operaciones aleatorias con magnitudes aleatorias — fuertes, simples y sorprendentemente efectivas. Usa un transform separado sin aumentación para validación y que las métricas sean estables.
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 (nueva API)
Transforms v2 (torchvision 0.17+) es la API nueva — más rápida, scriptable por JIT y crucialmente funciona conjuntamente sobre imagen/máscara/bbox para que las aumentaciones de detección y segmentación se mantengan consistentes. ToDtype + scale=True reemplaza a ToTensor. Pasa siempre antialias=True a las operaciones de redimensionado para un submuestreo más limpio. El módulo transforms heredado sigue funcionando pero no recibirá características nuevas.
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 personalizado
Un transform personalizado es cualquier callable que toma un tensor (o imagen PIL) y devuelve uno. Compónlos con transforms.Compose. Aplica el ruido después de ToTensor para que opere sobre floats. Para aleatoriedad por muestra usa torch.rand dentro de __call__ para que cada llamada tome una decisión fresca. Transforms v2 te permite escribir clases de transform que manejen entradas conjuntas (imagen, etiqueta) sobrescribiendo 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 xPreprocesamiento de texto y tabular
Para texto, construye un vocabulario desde el conjunto de entrenamiento (nunca val/test) y convierte los tokens a ids enteros; <unk> maneja las palabras no vistas y <pad> se usa para agrupar secuencias de longitud variable. Para datos tabulares, estandariza las características usando estadísticas computadas solo sobre el conjunto de entrenamiento — filtrar estadísticas de val/test infla las métricas. Guarda el scaler/vocab junto al checkpoint del modelo para que la inferencia preprocese de forma idéntica.
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 personalizado
Clase Dataset
Un Dataset solo necesita __len__ y __getitem__. Abre los archivos perezosamente dentro de __getitem__ para poder sostener millones de rutas en memoria baratamente. Devuelve tuplas (entrada, objetivo) y deja que el collate por defecto del DataLoader las apile en lotes. Mantén __getitem__ barato y sin efectos secundarios porque corre en procesos worker — no mutés estado compartido.
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 de carpetas de imágenes
ImageFolder espera un subdirectorio por clase e infiere las etiquetas de los nombres de carpeta — la forma más rápida de empezar con clasificación de imágenes. class_to_idx mapea nombres a etiquetas enteras; mantenlo consistente entre train/val/test reutilizando el mismo mapeo. random_split devuelve Subsets que comparten los datos subyacentes, así que la memoria no se duplica.
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 de texto
Pre-tokeniza el texto una vez y guarda ids enteros para no volver a tokenizar cada época. Para secuencias de longitud variable, devuelve listas crudas y rellena en collate_fn para que cada lote rellene solo hasta su propia longitud máxima. pack_padded_sequence luego se salta las posiciones de relleno en la RNN. Para entrenar transformers, devuelve máscaras de atención para que la atención ignore los tokens de relleno.
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 transmite datos en lugar de acceso aleatorio — esencial para fuentes enormes o en streaming (logs, bases de datos, S3). Los workers deben dividir el stream explícitamente (itertools.islice) para evitar que cada worker lea los mismos datos. shuffle no está soportado directamente; en su lugar, guarda muestras en búfer y barájalas dentro del búfer. Úsalo para datasets demasiado grandes para indexar por longitud.
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 y ConcatDataset
TensorDataset es el camino más rápido cuando los datos caben en RAM — devuelve tuplas de tensores que el collate por defecto apila en lotes. ConcatDataset encadena datasets de extremo a extremo; útil para combinar datos etiquetados y pseudo-etiquetados. Subset envuelve un dataset con una lista de índices, habilitando random_split y slicing personalizado sin copiar datos.
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 de LR
StepLR y MultiStepLR
StepLR y MultiStepLR son los schedulers más simples — multiplican el LR por gamma en épocas fijas. Son predecibles y funcionan bien para CNNs entrenadas desde cero. Llama siempre a scheduler.step() tras el entrenamiento de la época, no dentro del bucle de lotes. get_last_lr() muestra el LR actual para el logging. Cuidado: step_size cuenta épocas, no pasos.
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
El annealing coseno decae suavemente el LR — a menudo una pequeña mejora de exactitud frente a la decadencia por pasos. Los reinicios calientes (SGDR) reinician el LR al valor base al inicio de cada ciclo, lo que puede ayudar al modelo a escapar de mínimos agudos; T_mult=2 hace cada ciclo el doble de largo. Los schedulers coseno son el valor por defecto moderno para clasificación de imágenes y preentrenamiento.
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 vigila una métrica y reduce el LR cuando deja de mejorar — perfecto cuando no conoces de antemano la programación correcta. mode='min' para pérdidas, 'max' para exactitud. patience=N espera N épocas sin mejora antes de reducir. A diferencia de otros schedulers, debes pasar la métrica a step(metric). Fácil de sobreajustar con demasiada paciencia; combínalo con 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 y CyclicLR
OneCycleLR (superconvergencia) calienta, alcanza el pico y luego hace annealing — a menudo la forma más rápida de entrenar un modelo a una exactitud dada. Avanza por lote, así que fija total_steps = épocas * lotes_por_época. pct_start=0.3 gasta el 30% de los pasos calentando. CyclicLR oscila entre el LR base y el máximo, útil para hallar buenos LRs (test de rango 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 + decadencia
El warmup estabiliza los primeros pasos cuando la estimación del segundo momento de Adam está mal condicionada — esencial para el entrenamiento de transformers. LinearLR + SequentialLR combina limpiamente el warmup con cualquier programación de decadencia. LambdaLR da control total vía una función del conteo de pasos — el scheduler más flexible. Para programaciones estilo HuggingFace, mira 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 personalizado
LambdaLR multiplica el LR base por lambda(paso) — la forma más flexible de implementar programaciones personalizadas. Pasa una lista de lambdas (una por param_group) para programaciones por grupo, por ejemplo decaer pesos pero no sesgos, o usar programaciones distintas para backbone y cabeza en transferencia de aprendizaje. Las lambdas deben ser baratas porque corren en cada paso. Evita las closures de Python que capturan estado mutable — mantenlas puras.
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()Transferencia de aprendizaje
Modelos preentrenados
Usa siempre la API WeightsEnum (DEFAULT elige la mejor disponible) — el antiguo pretrained=True está obsoleto. Cada objeto de pesos expone .transforms() que devuelve el preprocesamiento exacto con el que se entrenó el modelo — úsalo para que tus entradas coincidan. La cabeza clasificadora genera las 1000 clases de ImageNet; reemplázala para tu propia tarea.
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])Extracción de características
La extracción de características congela el backbone y entrena solo una cabeza nueva — la línea base de transferencia de aprendizaje más rápida, a menudo alcanzando alta exactitud con minutos de entrenamiento en un dataset pequeño. Como el backbone está congelado, puedes precomputar las características una vez y entrenar un clasificador barato sobre ellas, ahorrando enormes cantidades de cómputo. Fja model.eval() para que BatchNorm use estadísticas acumuladas incluso mientras entrenas la cabeza.
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
El fine-tuning entrena el modelo entero (o parte de él) con un LR pequeño para que las características preentrenadas se adapten a tu tarea. Usa LRs diferenciales: menores para las capas tempranas (características generales), mayores para la cabeza (específica de la tarea). El descongelado gradual — entrenar la cabeza primero y luego descongelar capas más profundas — es más estable que entrenarlo de una sola vez, especialmente en datasets pequeños.
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.Congelar y descongelar capas
requires_grad_(False) evita que autograd rastree y actualice un parámetro — pero los gradientes siguen fluyendo a través de las capas congeladas hacia las entrenables aguas abajo. Usa named_parameters() para filtrar por nombre de capa para congelar selectivamente. Registra siempre el conteo de parámetros entrenables para no congelar accidentalmente el modelo entero (un bug silencioso común). Tras descongelar, vuelve a crear el optimizador para que recoja los parámetros recién entrenables.
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 autogradReemplazar el clasificador
Cada arquitectura tiene su clasificador en un atributo distinto — ResNet usa .fc, EfficientNet usa .classifier[1], ViT usa .heads.head. Fjar la cabeza nueva con requires_grad=True significa que solo ella entrena inicialmente. Para aprendizaje multitarea, reemplaza la cabeza con varias capas Linear que compartan el backbone. nn.Identity() es un módulo no-op práctico para descartar limpiamente la cabeza original.
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)Visualización
Configuración de TensorBoard
SummaryWriter transmite eventos a un directorio de logs; lanza TensorBoard con `tensorboard --logdir=runs` para verlo. add_scalar grafica una métrica única frente al paso; add_scalars superpone varias curvas en un gráfico. Usa subdirectorios separados por experimento (runs/exp1, runs/exp2) para comparar ejecuciones en la misma UI. Vacía con writer.close() al final para que se escriban los últimos eventos.
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=runsRegistrar grafos e histogramas
add_graph visualiza la arquitectura del modelo en la pestaña Graphs — útil para depurar el flujo de forward. add_histogram muestra la distribución de pesos o gradientes a lo largo del tiempo; un entrenamiento sano mantiene los gradientes no cero y los pesos aproximadamente en forma de campana. Los picos súbitos en los histogramas de gradiente insinúan inestabilidad. Registrar cada paso es lento — muestrea cada N pasos.
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()Registrar imágenes
add_image toma un tensor CHW; usa make_grid para teselar un lote en una imagen con normalize=True para que escale a un rango mostrable. add_figure registra un Figure de matplotlib directamente. draw_segmentation_masks y draw_bounding_boxes (torchvision.utils) superponen predicciones para un QA visual rápido. Registra unas pocas muestras de validación por época para monitorear el progreso cualitativo, no solo métricas escalares.
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)Grafo de torchviz
torchviz dibuja el grafo de autograd de una pasada de forward — genial para depurar discrepancias de forma, ramas no intencionadas o tensores desacoplados. Cada nodo es una operación; las aristas muestran el flujo de tensores. show_saved=True también muestra los tensores intermedios conservados para backward, que es lo que determina el uso de memoria. Instala con `pip install torchviz` y Graphviz en el PATH de tu sistema.
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)Sondeo de pesos y activaciones
Visualizar los filtros de la primera capa muestra qué 'busca' el modelo — bordes, colores, texturas. Los forward hooks capturan activaciones sin modificar forward, perfectos para sondear capas intermedias o construir extractores de características. Sigue las estadísticas de pesos y gradientes (media, desviación, norma) por paso para atrapar neuronas muertas (gradientes cero) o activaciones explosivas. torchsummary o torchinfo imprimen una tabla limpia de parámetros por capa.
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)Entrenamiento distribuido
Configuración de DDP
DistributedDataParallel (DDP) es el patrón estándar de entrenamiento multi-GPU: un proceso por GPU, gradientes all-reducidos para que todas las réplicas se mantengan sincronizadas. nccl es el backend más rápido en GPUs NVIDIA. torchrun fija las variables de env (RANK, WORLD_SIZE, LOCAL_RANK) por ti. Llama siempre a dist.destroy_process_group() al final para que el trabajo salga limpiamente. Mira la sección de entrenamiento en GPU para el bucle completo.
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 fragmenta el dataset entre procesos para que cada GPU vea un subconjunto único de cada lote (lote efectivo = batch_size * world_size). DEBES llamar a sampler.set_epoch(época) en cada época — sin ello, cada época usa el mismo barajado y el modelo ve el mismo ordenamiento. No pases shuffle=True al DataLoader al usar un sampler; el sampler maneja el ordenamiento.
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
...Lanzamiento multi-nodo
torchrun lanza un proceso por GPU y los conecta vía TCP. Para multi-nodo, corre torchrun en cada nodo con el mismo master_addr y un node_rank único. El endpoint de rendezvous (--rdzv_endpoint) permite a los nodos encontrarse y soporta reinicios elásticos. Asegúrate de que master_port está abierto en el firewall y de que cada nodo puede alcanzar master_addr. NCCL también necesita una interconexión de alto ancho de banda (InfiniBand/NVLink) para buen escalado.
# 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.pySincronización de gradientes
DDP solapa el all-reduce de gradientes con el cómputo de backward, razón por la que escala tan bien. find_unused_parameters=True es necesario cuando algunos parámetros no reciben gradiente en cada paso (por ejemplo, ramas condicionales) pero cuesta sobrecarga — evítalo si puedes. model.no_sync() se salta la sincronización de un paso, útil con acumulación de gradientes para sincronizar solo una vez por lote efectivo en lugar de en cada micro-lote.
# 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 y checkpointing
Acota siempre el logging y el checkpointing a rank==0 para evitar duplicados y condiciones de carrera. Al guardar un modelo DDP, usa model.module.state_dict() — DDP envuelve al módulo subyacente, y guardar el envoltorio hace el checkpoint específico de DDP y difícil de cargar en código no distribuido. Carga el checkpoint en cada rank antes de envolver con DDP para que todas las réplicas partan de los mismos pesos.
# 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 fragmenta parámetros, gradientes y estados del optimizador entre GPUs — así un modelo demasiado grande para una GPU puede entrenarse entre varias. A diferencia de DDP (que conserva réplicas completas), FSDP reúne los fragmentos bajo demanda durante forward/backward. Úsalo cuando el modelo no quepa en la memoria de una GPU. Guardar es más delicado: envuelve la recolección de state_dict en modo FULL_STATE_DICT para que el rank 0 materialice el modelo completo. Precisión mixta + FSDP + checkpointing de activaciones te permiten entrenar modelos muy grandes.
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')Fragmentos de PyTorch relacionados
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?