Primeiros Passos
Instalação e Tensores
Tensores PyTorch são a estrutura de dados central. Use to(device) para mover tensores para a GPU. torch.randn retorna números aleatórios de uma distribuição normal. Escolha a URL de wheel certa para a sua versão de CUDA; builds só de CPU são menores para desenvolvimento.
# 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 de Tensor
Cada tensor tem os atributos shape, dtype e device. Dtypes comuns: float32 (padrão), float16, int64, bool. numel() retorna o número total de elementos. Escolha float16 para precisão mista, cortando a memória pela metade e acelerando o cálculo na 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()) # 3Criação de Tensores
torch.zeros/ones/full criam tensores constantes. arange e linspace criam tensores de intervalo. rand é uniforme, randn é normal. randint exclui o limite alto. Use torch.manual_seed(42) antes de operações aleatórias, por reprodutibilidade.
# 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))Conversão de Tipo
to(dtype) converte o tipo do tensor. Atalhos: .float(), .long(), .int(), .bool(). numpy() compartilha memória com o tensor (zero-copy na CPU). item() extrai um único escalar Python de um tensor 0-d. Tensores na GPU precisam ser movidos para 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.5Indexação e Slicing
A indexação do PyTorch espelha a do NumPy. Indexação por inteiro retorna um tensor 0-d (use .item() para um escalar Python). Máscaras booleanas achatam o resultado. Indexar com um LongTensor seleciona ao longo da primeira dimensão. Indexação avançada cria cópias; slicing básico cria views.
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 2Remodelagem e Views
view exige memória contígua; reshape funciona sempre (copia se necessário). unsqueeze/squeeze adicionam/removem dimensões de tamanho 1. permute reordena todas as dimensões; transpose troca duas. reshape(-1) achata. Operações como permute podem deixar tensores não contíguos, exigindo .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) # equivalentOperações de Tensor
Operações Aritméticas
Operadores aritméticos (+, -, *, /) são elemento a elemento. Operações in-place terminam com _ e economizam memória, mas invalidam o histórico do autograd — evite-as em tensores que exigem grad. Broadcasting segue as regras do NumPy: dimensões finais são casadas ou esticadas para 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
A matemática elemento a elemento espelha as funções torch.* e tensor.*. clamp é o nome PyTorch para recorte. Use torch.finfo(x.dtype).eps em vez de um 1e-8 fixado no código, para um log numericamente seguro. Funções de ativação também estão disponíveis como módulos nn (nn.ReLU()) para 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)Operações de Redução
Reduções colapsam uma ou mais dimensões. Passe dim para escolher o eixo; keepdim=True mantém o eixo reduzido com tamanho 1 (crítico para broadcasting). max/min com um dim retornam uma tupla nomeada (values, indices). item() puxa um tensor 0-d para um escalar 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 normOperações de Comparação
Operadores de comparação retornam tensores bool. torch.equal verifica igualdade exata e retorna um bool Python. torch.where(cond, x, y) é o ternário vetorizado — perfeito para mascarar ou selecionar. topk retorna valores e índices, útil para acurácia 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 + indicesOperações de Matriz
@ e torch.matmul fazem multiplicação de matrizes e transmitem sobre dimensões de lote. Use torch.bmm para matmul em lote estritamente 3D (sem broadcasting). einsum é expressivo para contrações de múltiplos tensores, mas pode ser mais lento que matmul em alguns hardwares. Evite inverter matrizes quando puder resolver com 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 dotConcatenação e Empilhamento
cat une tensores ao longo de um eixo existente; stack adiciona um eixo novo. split divide por tamanho de chunk, chunk divide por número de pedaços. expand cria uma view com dados transmitidos (sem cópia de memória) — use-o em vez de repeat quando possível. repeat duplica fisicamente os dados.
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
Defina requires_grad=True para acompanhar operações para o autograd. Chamar .backward() num tensor escalar computa os gradientes daquele tensor em relação a cada um dos tensores folha com requires_grad=True. Gradientes se acumulam em .grad — chame optimizer.zero_grad() ou x.grad=None entre iterações.
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.])Computando Gradientes
backward() só funciona em saídas escalares; para tensores, faça sum ou mean primeiro. torch.autograd.grad retorna gradientes como tupla, sem guardá-los em .grad. Preferido dentro de bibliotecas ou quando você precisa dos gradientes de tensores não folha.
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 = 8Desativando o Rastreamento de Gradiente
Use torch.no_grad() para inferência, pulando a construção do grafo — economiza memória e tempo. .detach() retorna um tensor que compartilha os dados, mas é cortado do grafo; ótimo para logs ou para alimentar tensores a código não PyTorch. model.eval() troca camadas (dropout, BN) para modo de inferência, mas NÃO desativa o autograd — combine com 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 Ordem Superior
create_graph=True mantém o grafo do próprio gradiente, para que você possa diferenciar de novo. Útil para penalidades de gradiente (WGAN-GP), meta-aprendizado e perdas informadas pela física. Custa memória extra — libere grafos intermediários com retain_graph=False quando 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 num tensor permite inspecionar ou modificar seu gradiente durante o backward — prático para depurar NaNs ou implementar clipping de gradiente em tensores específicos. register_full_backward_hook num módulo vê gradientes de entrada e saída. Sempre retorne um gradiente modificado se quiser que as mudanças se propaguem.
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)Detalhes do Grafo Computacional
Tensores folha são criados pelo usuário (requires_grad=True, sem grad_fn). Resultados intermediários são não folha. Por padrão, o grafo é liberado após backward(); passe retain_graph=True para chamar backward várias vezes. create_graph=True retém o grafo do gradiente para derivadas de ordem superior. A memória cresce rápido — limpe com x.grad=None entre iterações.
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)Carregamento de Dados
Dataset e DataLoader
DataLoader agrupa, embaralha e carrega em paralelo um Dataset. num_workers>0 usa subprocessos — defina 2-8 por GPU. pin_memory=True acelera a transferência CPU→GPU. Para datasets pequenos que cabem na RAM, defina num_workers=0 para evitar custo extra.
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,)
breakAmostragem de Lotes
Passe um batch_sampler para controlar exatamente quais índices formam cada lote. WeightedRandomSampler rebalanceia classes desbalanceadas por sobreamostragem das raras. drop_last=True descarta o último lote curto — importante para a estabilidade do BatchNorm. Samplers iteram sobre índices; o DataLoader busca os dados reais.
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)Embaralhamento e Amostragem
shuffle=True randomiza a ordem a cada época (bom para treino); mantenha shuffle=False na validação, para métricas reproduzíveis. random_split é conveniente, mas seu RNG não é semeável diretamente — use Subset com torch.randperm e um Generator para controle total. Subset é só uma visão fina de índices, sem cópia de dados.
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 transforma uma lista de amostras num lote. O padrão empilha tensores ao longo de uma nova dim 0. Sobrescreva para sequências de comprimento variável (preencher e depois ordenar por comprimento para pack_padded_sequence), amostras baseadas em dict ou dados mistos tensor/não tensor. Mantenha a função barata — roda nos workers de carregamento de dados.
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)Carregamento Paralelo
num_workers paraleliza o carregamento de dados para que a GPU nunca espere. persistent_workers=True evita o custo de iniciar workers a cada época. prefetch_factor (padrão 2) controla quantos lotes cada worker prepara adiante. No Windows e no Jupyter, multiprocessing pode ser instável — recue para num_workers=0 para depurar. Cuidado: cada worker herda o estado completo do processo, incluindo handles de arquivo abertos e 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
Definindo um Módulo
Subclasseie nn.Module e implemente forward(). Declare submódulos e parâmetros como atributos, para que sejam registrados automaticamente (é isso que habilita .to(device), .parameters() e state_dict). Sempre chame super().__init__(). Evite lógica Python arbitrária em forward — mantenha-a diferenciável e só de 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 structureCamadas Linear e de Ativação
nn.Linear aplica y = xW^T + b. A forma do peso é (out, in). Prefira módulos de ativação quando quiser registrá-los (state_dict, hooks); use o funcional F.* para operações pontuais. Ativações estilo GELU e SwiGLU dominam arquiteturas transformer. Softmax geralmente deve ser omitido do modelo e tratado pela 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 e Submódulos
named_parameters() produz (nome, tensor) para a árvore toda — ótimo para congelar, weight decay ou depurar. .modules() recursa nos filhos; .children() é só um nível. Buffers (ex.: estatísticas móveis do BatchNorm) aparecem no state_dict, mas não em parameters(); use named_buffers() para vê-los.
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 encadeia módulos em que cada saída alimenta a próxima entrada — perfeito para pipelines lineares. Use OrderedDict para nomear estágios e indexar por atributo (model.fc1). Para modelos com ramificações, conexões de salto ou múltiplas entradas/saídas, subclasseie nn.Module e escreva forward() explicitamente.
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))Funções de Módulo
to(device) move parâmetros e buffers; .double()/.half()/.float() convertem dtypes. train()/eval() alternam a flag self.training — Dropout e BatchNorm ramificam sobre ela. state_dict() retorna um OrderedDict de cada um dos parâmetros e buffers; load_state_dict os restaura. .apply(fn) recursa em cada um dos submódulos, útil para inicialização 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)Inicialização
PyTorch usa init de Kaiming He para Linear/Conv por padrão, o que funciona na maioria dos casos. Sobrescreva com funções torch.nn.init (o sufixo _ significa in-place). Kaiming serve à família ReLU; Xavier/Glorot serve a tanh/sigmoid. Inicializar biases com zero é padrão. .apply(fn) roda fn em cada submódulo — perfeito para inicialização em massa ou reset 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)Funções de Perda
CrossEntropyLoss
CrossEntropyLoss aplica log-softmax + NLLLoss internamente — passe logits crus, nunca saídas de softmax. Os alvos são índices de classe inteiros (não one-hot). Use weight para classes desbalanceadas e ignore_index=-100 para mascarar tokens de preenchimento. label_smoothing=0.1 é um regularizador popular para classificação e 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 e L1Loss
MSELoss penaliza erros grandes quadraticamente (sensível a outliers); L1 é linear e mais robusto. SmoothL1Loss comporta-se como L2 perto de zero e L1 longe — usado em detecção de objetos (Fast R-CNN). reduction='none' retorna um tensor por elemento, para que você possa mascarar ou pesar você mesmo antes de chamar .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 e BCEWithLogitsLoss
Sempre prefira BCEWithLogitsLoss a BCELoss+sigmoid — usa o truque log-sum-exp pela estabilidade numérica. pos_weight multiplica o termo positivo para contrabalançar desequilíbrio de classes (tipo focal loss simplificado). Para classificação multi-rótulo (cada classe independente), use BCEWithLogitsLoss com forma (N, C) e saídas 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)Função de Perda Personalizada
Uma perda personalizada é só uma função (ou nn.Module) que retorna um tensor escalar — o autograd cuida do resto. Torne toda operação diferenciável (torch.where com ramos diferenciáveis está ok). A forma de módulo é preferida quando você precisa de hiperparâmetros, serialização ou registrá-la numa config. Mantenha a redução explícita (mean/sum/none), para que o comportamento seja previsível.
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()Redução e Combinação de Perdas
reduction='none' dá perdas por amostra, para que você possa mascarar, repesar ou agregar manualmente. Combine perdas multitarefa por soma ponderada — os pesos equilibram gradientes, não só magnitudes (ajuste-os). Cada sub-perda deve permanecer diferenciável e no mesmo device/dtype. Desanexe um termo de perda com .detach() se quiser registrá-lo sem retropropagar por ele.
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 e Outras Perdas
NLLLoss + LogSoftmax é matematicamente idêntico a CrossEntropyLoss, mas permite reutilizar os log-probs. TripletMarginLoss treina embeddings de aprendizado de métrica. KLDivLoss espera log-probs como entrada e probs como alvo. CTCLoss alinha sequências não segmentadas a alvos — passe input_lengths e target_lengths para evitar erros 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)Otimizadores
SGD
SGD + momentum continua sendo uma escolha de topo para treino de CNNs com lotes grandes e generaliza melhor que Adam em algumas tarefas. Momentum 0.9 é o padrão; Nesterov dá uma pequena vantagem extra. weight_decay adiciona regularização L2. SGD exige agendamento de LR cuidadoso e warmup; não é auto-ajustável 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 e AdamW
Adam guarda momentos por parâmetro, adaptando o tamanho do passo automaticamente — ótimo padrão para NLP e datasets pequenos. AdamW desacopla o weight decay da atualização de gradiente, o que importa em escala (transformers). betas=(0.9, 0.999) é o padrão; alguns modelos de visão usam (0.9, 0.95). Use grupos por parâmetro para taxas de aprendizado diferenciais em transfer learning.
import torch.optim as optim
# Adam — adaptive, default-friendly
optimizer = optim.Adam(model.parameters(), lr=1e-3)
# AdamW — decoupled weight decay (preferred for transformers)
optimizer = optim.AdamW(
model.parameters(),
lr=3e-4,
betas=(0.9, 0.999),
weight_decay=0.01,
)
# per-parameter group settings
optimizer = optim.Adam([
{'params': model.encoder.parameters(), 'lr': 1e-4},
{'params': model.head.parameters(), 'lr': 1e-3},
], lr=1e-3)Padrão de Passo do Otimizador
O padrão de 3 passos — zero_grad, backward, step — é o coração do treino PyTorch. set_to_none=True (padrão em versões mais novas) é mais rápido que preencher com zeros, porque pula um memset e deixa o otimizador pular o parâmetro. Edite p.grad.data manualmente entre backward() e step() para clipping ou atualizações 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()Clipping de Gradiente
clip_grad_norm_ reescala os gradientes se sua norma L2 global exceder max_norm — um padrão estável para RNNs e transformers. clip_grad_value_ recorta cada elemento rigidamente (menos comum). O clipping previne explosão de gradientes sem mudar a direção. Registre a norma do gradiente pré-clip para detectar instabilidade cedo (picos súbitos > 100 indicam 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)Taxa de Aprendizado e Agendamentos
Cada param_group tem seu próprio lr — itere para definir cada um. Warmup manual rampa o LR linearmente nos primeiros N passos para estabilizar o treino inicial (crítico para transformers sem correção de viés). Use um objeto scheduler (próxima seção) para decaimento de cosseno, OneCycle etc. Sempre dê step no scheduler depois de optimizer.step(), a menos que os docs digam o contrário.
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)Outros Otimizadores
RMSprop é o otimizador clássico de RNN e ainda funciona bem. Adagrad acumula gradientes ao quadrado e pode estagnar cedo — serve a features esparsas, mas não a redes profundas. LBFGS precisa de closure e avaliação de lote completo — ótimo para problemas convexos pequenos ou fine-tuning, lento demais para redes profundas grandes. Para a maioria dos projetos novos, comece com 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)Loop de Treino
Loop de Treino Básico
O loop de treino mínimo: zero_grad, forward, loss, backward, step. Mova os dados para a GPU dentro do loop (sobreposição assíncrona com num_workers). loss.item() puxa um escalar para o Python — faça isso para logging, não para o tensor da perda (você quebraria o grafo). Envolva o loop numa função para reutilizá-lo.
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}")Validação no Loop
model.eval() + torch.no_grad() são ambos exigidos: eval troca dropout/BN, no_grad pula o grafo. Acumule a perda ponderada (multiplique pelo tamanho do lote) para que a média esteja correta mesmo no último lote curto. argmax(dim=1) dá os índices de classe previstos. Salve o melhor modelo quando a métrica de validação melhorar (veja a seção save-load).
for epoch in range(epochs):
model.train()
for x, y in train_loader:
# ... training step ...
# validation
model.eval()
val_loss, correct, total = 0.0, 0, 0
with torch.no_grad():
for x, y in val_loader:
x, y = x.to(device), y.to(device)
logits = model(x)
val_loss += criterion(logits, y).item() * x.size(0)
correct += (logits.argmax(1) == y).sum().item()
total += x.size(0)
print(f"val_loss={val_loss/total:.4f}, acc={correct/total:.4f}")Acumulação de Gradiente
A acumulação de gradiente simula um lote maior somando gradientes de vários mini-lotes antes de dar step. Divida a perda por accum_steps, para que o gradiente efetivo corresponda a um único lote grande. Garanta que o comprimento do dataset seja divisível por accum_steps, ou dê step nos gradientes restantes no fim da época. Especialmente útil para fine-tuning de transformers numa única 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 sizeTreino com Precisão Mista
Precisão mista roda operações de forward em float16 (ou bfloat16 em Ampere+) para aceleração de 1.5-3x e memória pela metade. GradScaler multiplica a perda para prevenir underflow de gradiente float16 e depois desescala antes de optimizer.step(). Em H100/A100 prefira bfloat16 — tem o mesmo intervalo do float32 e não precisa de scaler. O gerenciador de contexto autocast afeta só o 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 lossProgresso e Logging
tqdm mostra uma barra de progresso ao vivo — use set_postfix para exibir a perda corrente. Uma média móvel exponencial (running = 0.9*running + 0.1*loss) suaviza ruído melhor que o valor cru do último lote. Para execuções sérias, registre no TensorBoard ou Weights & Biases em vez do stdout, para poder comparar execuções. Evite registrar a cada passo se isso retardar o treino.
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)Reprodutibilidade
Reprodutibilidade total precisa de seeds para Python, NumPy, PyTorch CPU e CUDA. cudnn.deterministic=True desativa algoritmos não determinísticos (alguns ops de backward de conv). Workers do DataLoader precisam cada um de seed via worker_init_fn, porque fazem fork com o próprio estado de RNG. Mesmo assim, multi-GPU e alguns ops cuDNN podem não ser bit-reproduzíveis — mire em reprodutibilidade estatí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)Avaliação e Métricas
Modo Eval e No Grad
Sempre pareie model.eval() com torch.no_grad() na avaliação. eval() troca dropout e BatchNorm para modo de inferência (BN usa estatísticas móveis); no_grad() desativa o autograd, economizando memória e tempo. Multiplique a perda pelo tamanho do lote ao acumular, para que a média final seja não enviesada mesmo se o último lote for curto.
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}")Acurácia e Top-k
argmax(dim=1) retorna a classe prevista por linha. topk retorna os k maiores valores e seus índices — igualá-los a alvos expandidos para (N,1) e usar .any(dim=1) dá correção top-k. A acurácia por classe expõe problemas de desequilíbrio que a acurácia geral esconde. Sempre mova os tensores para a CPU e chame .item() antes de passar a print ou log.
logits = torch.randn(8, 10)
targets = torch.randint(0, 10, (8,))
# top-1 accuracy
preds = logits.argmax(dim=1)
acc = (preds == targets).float().mean().item()
# top-k accuracy
topk = 3
_, idx = logits.topk(topk, dim=1) # shape (N, k)
correct = idx.eq(targets.view(-1, 1)).any(dim=1)
topk_acc = correct.float().mean().item()
# per-class accuracy
for c in range(10):
mask = targets == c
print(c, (preds[mask] == targets[mask]).float().mean().item())Matriz de Confusão
Acumule previsões na GPU e mova para a CPU uma vez só no fim, para evitar sincronizações por lote. confusion_matrix mostra onde o modelo confunde as classes — perfeito para depuração. classification_report dá precisão, recall e F1 por classe. Para datasets muito grandes, transmita as previsões para o disco em vez de guardá-las na memória.
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))Precisão, Recall e F1
torchmetrics acumula estado entre lotes e computa a métrica corretamente mesmo com desequilíbrio de classes ou tamanhos de lote variáveis. average='macro' trata todas as classes igualmente; 'weighted' pesa pelo suporte; 'micro' equivale à acurácia para tarefas de rótulo único. Chame .reset() entre épocas ou avaliações para limpar o 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())Validação Cruzada
A validação cruzada k-fold dá uma estimativa robusta do desempenho do modelo e de sua variância. Reinstitucionalize o modelo por fold, para que os pesos não vazem entre folds. Para datasets grandes, 5 folds costumam bastar; para pequenos, use divisões estratificadas (StratifiedKFold) para preservar o equilíbrio de classes. Reporte média +/- desvio, para que os leitores vejam a estabilidade.
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}")Comparação de Modelos
Sempre compare modelos no mesmo conjunto de teste separado, com a mesma seed e métrica. Além da acurácia, olhe calibração, latência de inferência e memória. Use intervalos de confiança por bootstrap quando as diferenças no conjunto de teste forem pequenas. Mantenha uma tabela de resultados (CSV ou W&B), para poder comparar com experimentos futuros em vez de só a última execução.
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}")Salvar e Carregar
Salvar e Carregar State Dict
state_dict() é um OrderedDict de tensores de parâmetros — salvá-lo (não o modelo inteiro) é o padrão recomendado, porque é portável e desacoplado do layout exato de classe/arquivo. map_location permite carregar um checkpoint CUDA na CPU. strict=False carrega só as chaves que casam, prático quando a arquitetura mudou levemente.
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)Salvar o Modelo Inteiro
Salvar o modelo inteiro faz pickle do objeto Python, vinculando-o à classe e à estrutura de arquivos exatas do momento do salvamento. Isso é frágil — qualquer refatoração quebra o carregamento. Use só para experimentos rápidos. Para qualquer coisa que possa ser implantada ou compartilhada, salve o state_dict e mantenha a arquitetura em código ou config.
# save entire model (uses pickle) — NOT recommended
torch.save(model, 'model_full.pth')
# load
model = torch.load('model_full.pth', map_location='cpu')
model.eval()
# pickle limitations:
# - class definition must be importable at load time
# - breaks if you refactor or rename the class
# - not portable across PyTorch versions
# prefer state_dict for productionCheckpoints de Treino
Um checkpoint completo guarda tudo que é preciso para retomar o treino exatamente: modelo, otimizador, scheduler, época e estados de RNG. O estado do otimizador (buffers de momentum, momentos do Adam) é essencial — retomar sem ele efetivamente reinicializa o otimizador e pode fazer a perda disparar. Salve o estado de RNG só se precisar de reprodutibilidade bit a bit.
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'])Salvar o Melhor Modelo
Salve o melhor checkpoint pela métrica de validação, para poder recuperar o melhor modelo mesmo se épocas posteriores sofriam overfitting. Para a maioria das tarefas, guarde só o melhor checkpoint para economizar disco; para pesquisa, guarde checkpoints por época, para poder voltar atrás. Combine com um log CSV de (época, train_loss, val_loss, val_acc, caminho) para saber qual checkpoint escolher.
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)Carregando Modelos Parciais
strict=False retorna listas de chaves ausentes e inesperadas — inspecione-as para confirmar que só as camadas esperadas foram puladas. Renomear chaves permite adaptar um checkpoint a uma arquitetura renomeada. Depois de carregar um backbone, congele seus pesos para extração pura de features ou treine com um LR muito menor que o da nova cabeça.
# 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 para TorchScript
TorchScript produz um grafo autocontido que você pode carregar em LibTorch (C++) ou Python sem a classe original — ideal para implantação. trace captura um caminho de fluxo de controle; script trata fluxo dependente de dados, mas exige anotações de tipo. ONNX exporta para inferência em ONNX Runtime, TensorRT ou OpenVINO. Use dynamic_axes para tamanho de lote variável.
# 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
Camada Conv2d
A forma do peso do Conv2d é (canais_de_saida, canais_de_entrada/grupos, kA, kL). NCHW é o layout de memória padrão. padding='same' (PyTorch 1.9+) mantém o tamanho espacial para stride 1. groups=in_channels torna-o depthwise (usado no MobileNet). Calcule o tamanho da saída: (A + 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)Camadas de Pooling
O pooling reduz a amostragem das dimensões espaciais, adicionando invariância a pequenas translações. MaxPool mantém a resposta mais forte; AvgPool é mais suave. AdaptiveAvgPool2d(1) colapsa as dimensões espaciais para 1x1 — o 'global average pool' padrão usado para alimentar features conv a uma cabeça Linear. Prefira convs com stride a pooling para redução de amostragem aprendível em arquiteturas 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)Arquitetura CNN
Um bloco CNN canônico é Conv -> BatchNorm -> ReLU -> Pool. AdaptiveAvgPool2d(1) torna a rede agnóstica ao tamanho de entrada, para que você possa treinar numa resolução e testar em outra. BatchNorm2d vai depois do conv, antes da ativação. Mantenha kernels conv em 3x3 com padding=1 (estilo VGG) — são eficientes em parâmetros e fundem bem.
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 Features e Campo Receptivo
Mapas de features mostram o que cada canal detecta — camadas iniciais acham bordas e cores, mais profundas acham texturas e partes. register_forward_hook permite capturar ativações sem modificar o forward. O campo receptivo cresce com a profundidade e o pooling; grosseiramente, o pixel de saída (i,j) depende de um patch da entrada centrado ali, com tamanho = soma de strides e kernels até aquela camada.
# 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)Normalização em Lote (Batch Norm)
BatchNorm2d normaliza por canal sobre (N, A, L), mantendo estatísticas EMA móveis para inferência. train()/eval() importa — eval usa as estatísticas móveis, então a saída é determinística. BatchNorm acopla exemplos dentro de um lote, o que quebra com lotes muito pequenos; então troque para GroupNorm ou LayerNorm. SyncBatchNorm é necessário para BN multi-GPU correto.
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 transferArquiteturas CNN Populares
torchvision.models expõe ResNet, EfficientNet, MobileNet, ViT e mais, com pesos pré-treinados do ImageNet. Substituir a camada fc final é o ponto de entrada padrão de transfer learning. Para detecção/segmentação, descarte a cabeça e use as features conv. Confira a API de pesos (WeightsEnum) — a velha flag pretrained=True está obsoleta. Cada modelo tem campo receptivo e orçamento de FLOPs conhecidos; escolha um que caiba no seu alvo de latência.
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 e LSTM
Camada RNN
batch_first=True faz a entrada (lote, seq, feature), o que casa com a maioria das convenções de NLP; sem isso, PyTorch usa (seq, lote, feature). RNN vanilla sofre com gradientes evanescentes em sequências longas — prefira LSTM ou GRU na prática. out contém os estados ocultos por timestep da última camada; h_n contém o estado final de cada camada.
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)Camada LSTM
LSTM retorna tanto o estado oculto h_n quanto o estado de célula c_n. Bidirecional dobra o tamanho da feature de saída. Para classificação, use o estado oculto final de cada direção (h_n[-2] é a última camada para frente, h_n[-1] a última para trás). dropout em nn.LSTM só se aplica entre camadas empilhadas, não na entrada — envolva a entrada com nn.Dropout se precisar disso.
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)Camada GRU
GRU tem só um estado oculto (sem estado de célula) e duas portas em vez de três, então tem menos parâmetros e treina um pouco mais rápido que LSTM. Empiricamente, GRU e LSTM performam de modo similar na maioria das tarefas; GRU é um bom padrão para datasets menores. Como LSTM, dropout só se aplica entre camadas empilhadas.
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 tasksSequências Empacotadas
Empacotar pula os tokens de preenchimento no cálculo da RNN, o que é mais rápido e evita enviesar o estado oculto com zeros de pad. As sequências precisavam estar ordenadas por comprimento decrescente em PyTorch antigo; enforce_sorted=False ordena internamente (com um pequeno custo). pad_packed_sequence converte de volta a um tensor preenchido. Combine com uma collate_fn personalizada que preencha lotes dinamicamente.
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)Classificação de Sequências
Um classificador de texto padrão: embedding -> biLSTM -> dropout -> linear. Use padding_idx em nn.Embedding para que o token de pad tenha gradiente zero. Passe lengths.cpu() ao pack_padded_sequence, porque roda na CPU. O estado oculto final de ambas as direções é concatenado para capturar a sequência inteira. Para sequências longas, transformers superam LSTMs, mas precisam de mais dados e computação.
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)Geração de Sequência (Decoder)
Um decoder roda um passo por vez, condicionando ao token de saída anterior. LSTMCell é uma LSTM de passo único — use-a para controle fino do loop. Teacher forcing alimenta o token verdadeiro no próximo passo durante o treino, o que converge muito mais rápido que alimentar as próprias previsões do modelo. Na inferência, troque para alimentar argmax (ou amostrar) dos logits do passo anterior.
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 atenção de produto escalar escalado sobre cabeças em paralelo. batch_first casa com a convenção NLP (lote, seq, dim). Use attn_mask para decodificação causal (máscara triangular inferior) e key_padding_mask para ignorar tokens de pad. need_weights=True retorna a matriz de atenção, útil para visualização e sondagem.
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 é um bloco de self-attention + FFN com residuais e LayerNorm. norm_first=True (pre-LN) é mais estável para treinar do zero; post-LN (padrão) precisa de warmup. Empilhe N camadas com nn.TransformerEncoder. Passe src_key_padding_mask para que a atenção ignore posições de pad. Para classificação, faça mean-pool na sequência de saída e alimente uma cabeça 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)Positional Encoding
Transformers são invariantes à permutação, então precisam de informação posicional. A codificação senoidal generaliza para sequências mais longas que as vistas no treino. register_buffer guarda pe sem torná-la parâmetro — move com .to(device) e é salvo no state_dict. Embeddings de posição aprendidos (nn.Parameter) também funcionam, mas não extrapolam além do comprimento de treino.
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)
Um transformer encoder-decoder completo para tradução/resumização. O decoder usa máscara causal no alvo (para que a posição t só atente a <= t) mais cross-attention à saída do encoder (memória). Passe key_padding_masks para fonte e alvo, para que a atenção ignore tokens de pad. A cabeça projeta as saídas do decoder para logits do vocabulário; a perda é CrossEntropyLoss com 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)Bloco Vision Transformer (ViT)
Um bloco ViT é self-attention pre-LN + MLP pre-LN com residuais — essencialmente igual a uma camada de encoder transformer. Vision Transformers fatiam a imagem com um Conv2d com stride (kernel=stride=patch_size) e tratam os patches como tokens. Adicione um token CLS e embeddings posicionais. nn.MultiheadAttention retorna (saída, pesos) — desempacote com need_weights=False para pular os 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)Atenção do Zero
Atenção de produto escalar escalado: scores = QK^T / sqrt(d_k), softmax, multiplicar por V. O 1/sqrt(d_k) mantém a variância estável, para que o softmax não sature. masked_fill com -inf antes do softmax zera essas posições. Multi-head attention divide o embedding em H cabeças, atende em paralelo e concatena. É exatamente o que nn.MultiheadAttention faz — escreva do zero só para aprender ou adicionar variantes como atenção linear/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)Treino em GPU
Seleção de Device
Sempre gateie em torch.cuda.is_available() para que máquinas só de CPU não caiam. Você pode criar tensores direto num device com o argumento device= (mais rápido que criar na CPU e mover). O contexto torch.device (PyTorch 2.x) define um device padrão para novos tensores. MPS suporta GPUs Apple Silicon, mas carece de alguns recursos CUDA — confira o suporte a operadores antes de depender dele.
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'Movendo Modelos e Dados
model.to(device) move parâmetros e buffers no próprio local. Mova os tensores de entrada dentro do loop de treino, para que o DataLoader possa transmitir do disco. non_blocking=True sobrepõe a cópia CPU→GPU com o cálculo quando o tensor fonte está em memória fixada (defina pin_memory=True no DataLoader). .cpu() / .numpy() antes de qualquer operação NumPy — tensores GPU não podem ser convertidos diretamente.
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últiplas GPUs (DataParallel)
DataParallel (DP) replica o modelo em cada GPU, divide o lote e reúne as saídas na GPU 0 — fácil, mas lento e desequilibrado (a GPU 0 faz a coleta e o cálculo da perda). É single-process, então o GIL limita a escala. Para qualquer trabalho multi-GPU sério, use DistributedDataParallel. DP serve para prototipagem rápida em 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) lança um processo por GPU, cada um com sua réplica de modelo; os gradientes passam por all-reduce, para que toda GPU veja o mesmo gradiente. É muito mais rápido e escalável que DataParallel. Use torchrun (ou torch.distributed.launch) para iniciar os processos. Sempre chame sampler.set_epoch(epoca), para que cada época reembaralhe. Veja a seção de treino distribuído para o loop completo.
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()Gestão de Memória
empty_cache() devolve a memória cacheada ao SO, mas não libera tensores ainda em uso — chame-o após um grande pico, não no loop quente. memory_allocated são os tensores em uso; memory_reserved é o pool do alocador de cache. Para reduzir OOM: reduza o tamanho do lote, use precisão mista, checkpointing de gradiente ou acumulação de gradiente. expandable_segments:True reduz fragmentação para cargas de forma variável. Evite reter referências a tensores de que não precisa mais (ex.: perdas registradas numa 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 e Desempenho
cudnn.benchmark=True deixa o cuDNN perfilar algoritmos no primeiro forward e cachear o mais rápido — ótimo quando as formas de entrada são fixas (CNN típica), prejudicial se as formas mudam a cada passo (RNNs de comprimento variável). TF32 usa mantissa de 19 bits em Ampere+ para ~3x de aceleração de matmul com perda mínima de precisão; habilite, a menos que precise de reprodutibilidade fp32 estrita. O modo determinístico desativa algoritmos não determinísticos.
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 e Pré-processamento
Transforms Comuns
ToTensor converte uma imagem PIL (0-255) num tensor float em [0,1] e reorganiza ALC -> CAL. Normalize então padroniza por canal usando estatísticas do ImageNet (o padrão de fato para modelos pré-treinados — sempre case com as estatísticas com que o backbone foi treinado). Aplique transforms no Dataset, para que rodem nos processos de worker; a GPU nunca espera pelo pré-processamento da 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)Aumento de Dados (Augmentation)
Augmentation regulariza o modelo mostrando-lhe entradas variadas. RandomResizedCrop + flip é o aumento clássico do ImageNet. ColorJitter muda a cor sem afetar a geometria. TrivialAugmentWide e RandAugment amostram ops aleatórias com magnitudes aleatórias — fortes, simples e surpreendentemente eficazes. Use um transform separado sem augmentation para a validação, para que as métricas sejam estáveis.
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 (Nova API)
Transforms v2 (torchvision 0.17+) é a nova API — mais rápida, scriptável por JIT e, crucialmente, funciona em conjunto sobre imagem/máscara/bbox, para que as augmentations de detecção e segmentação permaneçam consistentes. ToDtype + scale=True substitui ToTensor. Sempre passe antialias=True aos ops de resize, para uma redução de amostragem mais limpa. O módulo de transforms legado ainda funciona, mas não receberá recursos novos.
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
Um transform personalizado é qualquer chamável que recebe um tensor (ou imagem PIL) e retorna um. Componha-os com transforms.Compose. Aplique ruído depois de ToTensor, para que opere em floats. Para aleatoriedade por amostra, use torch.rand dentro de __call__, para que cada chamada tome uma decisão fresca. Transforms v2 permite escrever classes de transform que tratam entradas conjuntas (imagem, rótulo) sobrescrevendo forward.
import torch
from torchvision import transforms
class RandomGaussianNoise:
def __init__(self, std=0.1):
self.std = std
def __call__(self, x):
if self.std > 0:
return x + torch.randn_like(x) * self.std
return x
# compose with built-ins
transform = transforms.Compose([
transforms.ToTensor(),
RandomGaussianNoise(0.05),
transforms.Normalize([0.5], [0.5]),
])
# callable with probability
class RandomApply:
def __init__(self, fn, p=0.5):
self.fn, self.p = fn, p
def __call__(self, x):
return self.fn(x) if torch.rand(1) < self.p else xPré-processamento de Texto e Tabular
Para texto, construa um vocabulário a partir do conjunto de treino (nunca val/test) e converta tokens em ids inteiros; <unk> trata palavras não vistas e <pad> serve para agrupar sequências de comprimento variável. Para dados tabulares, padronize features usando estatísticas computadas só no conjunto de treino — vazar estatísticas de val/test infla as métricas. Salve o scaler/vocab junto ao checkpoint do modelo, para que a inferência pré-processe de modo idêntico.
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
Classe Dataset
Um Dataset só precisa de __len__ e __getitem__. Abra arquivos preguiçosamente dentro de __getitem__, para que possa segurar milhões de caminhos na memória barato. Retorne tuplas (entrada, alvo) e deixe o collate padrão do DataLoader empilhá-las em lotes. Mantenha __getitem__ barato e sem efeitos colaterais, porque roda em processos de worker — não mute estado compartilhado.
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 Pasta de Imagens
ImageFolder espera um subdiretório por classe e infere rótulos dos nomes das pastas — a forma mais rápida de começar com classificação de imagens. class_to_idx mapeia nomes para rótulos inteiros; mantenha-o consistente entre treino/val/teste reutilizando o mesmo mapeamento. random_split retorna Subsets que compartilham os dados subjacentes, então a memória não é duplicada.
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
Pré-tokenize o texto uma vez e guarde ids inteiros, para evitar re-tokenizar a cada época. Para sequências de comprimento variável, retorne listas cruas e preencha na collate_fn, para que cada lote preencha só até seu próprio comprimento máximo. pack_padded_sequence então pula posições de pad na RNN. Para treino de transformer, retorne máscaras de atenção, para que os tokens de pad sejam ignorados pela atenção.
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 dados em vez de acesso aleatório — essencial para fontes enormes ou em streaming (logs, bancos, S3). Workers precisam dividir explicitamente o stream (itertools.islice) para evitar que cada worker leia os mesmos dados. shuffle não é suportado diretamente; em vez disso, bufferize amostras e embaralhe dentro do buffer. Use isto para datasets grandes demais para indexar por comprimento.
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 e ConcatDataset
TensorDataset é o caminho mais rápido quando os dados cabem na RAM — retorna tuplas de tensores que o collate padrão empilha em lotes. ConcatDataset encadeia datasets de ponta a ponta; útil para combinar dados rotulados e pseudo-rotulados. Subset envolve um dataset com uma lista de índices, habilitando random_split e fatiamento personalizado sem copiar dados.
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 e MultiStepLR
StepLR e MultiStepLR são os schedulers mais simples — multiplicam o LR por gamma em épocas fixas. São previsíveis e funcionam bem para CNNs treinadas do zero. Sempre chame scheduler.step() depois do treino da época, não dentro do loop de lotes. get_last_lr() mostra o LR atual para logging. Cuidado: step_size conta épocas, não passos.
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
O decaimento de cosseno suaviza a queda do LR — frequentemente um pequeno ganho de acurácia sobre o decaimento por passos. Reinícios quentes (SGDR) resetam o LR ao valor base no início de cada ciclo, o que pode ajudar o modelo a escapar de mínimos afiados; T_mult=2 faz cada ciclo duas vezes mais longo. Schedulers de cosseno são o padrão moderno para classificação de imagens e pré-treino.
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 vigia uma métrica e reduz o LR quando ela para de melhorar — perfeito quando você não conhece o agendamento certo de antemão. mode='min' para perdas, 'max' para acurácia. patience=N espera N épocas sem melhoria antes de reduzir. Diferente de outros schedulers, você precisa passar a métrica a step(metric). Fácil de sofrer overfitting com paciência demais; combine com parada antecipada.
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 e CyclicLR
OneCycleLR (superconvergência) aquece, atinge o pico e depois decresce — frequentemente a forma mais rápida de treinar um modelo até uma dada acurácia. Ele dá step por lote, então defina total_steps = epocas * lotes_por_epoca. pct_start=0.3 gasta 30% dos passos aquecendo. CyclicLR oscila entre LR base e máximo, útil para achar bons LRs (teste de intervalo 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 + Decaimento
Warmup estabiliza os primeiros passos quando a estimativa de segundo momento do Adam está mal condicionada — essencial para treino de transformers. LinearLR + SequentialLR combina limpo warmup com qualquer agendamento de decaimento. LambdaLR dá controle total via uma função da contagem de passos — o scheduler mais flexível. Para agendamentos estilo HuggingFace, veja 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 o LR base por lambda(step) — a forma mais flexível de implementar agendamentos personalizados. Passe uma lista de lambdas (um por param_group) para agendamentos por grupo, ex.: decair pesos mas não biases, ou usar agendamentos diferentes para backbone vs cabeça em transfer learning. Lambdas precisam ser baratas, porque rodam a cada passo. Evite closures Python que capturam estado mutável — mantenha-as 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()Transfer Learning
Modelos Pré-treinados
Sempre use a API WeightsEnum (DEFAULT escolhe o melhor disponível) — a velha pretrained=True está obsoleta. Cada objeto de pesos expõe .transforms(), retornando o pré-processamento exato com que o modelo foi treinado — use-o, para que suas entradas casem. A cabeça do classificador produz as 1000 classes do ImageNet; substitua-a para a sua tarefa.
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])Extração de Features
A extração de features congela o backbone e treina só uma nova cabeça — a baseline de transfer learning mais rápida, frequentemente alcançando alta acurácia com minutos de treino num dataset pequeno. Como o backbone está congelado, você pode pré-computar features uma vez e treinar um classificador barato sobre elas, economizando muito cálculo. Defina model.eval() para que BatchNorm use estatísticas móveis mesmo enquanto treina a cabeça.
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
Fine-tuning treina o modelo inteiro (ou parte) com um LR pequeno, para que as features pré-treinadas se adaptem à sua tarefa. Use LRs diferenciais: menores para camadas iniciais (features gerais), maiores para a cabeça (específica da tarefa). Descongelamento gradual — treinar a cabeça primeiro, depois descongelar camadas mais profundas — é mais estável que treinar tudo de uma vez, especialmente em datasets pequenos.
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.Congelando e Descongelando Camadas
requires_grad_(False) impede que o autograd rastreie e atualize um parâmetro — mas os gradientes ainda fluem através de camadas congeladas para as treináveis a jusante. Use named_parameters() para filtrar por nome de camada, para congelamento seletivo. Sempre registre a contagem de parâmetros treináveis, para não congelar tudo acidentalmente (um bug silencioso comum). Após descongelar, recrie o otimizador, para que ele pegue os parâmetros recém-treináveis.
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 autogradSubstituindo o Classificador
Cada arquitetura tem seu classificador num atributo diferente — ResNet usa .fc, EfficientNet usa .classifier[1], ViT usa .heads.head. Definir a nova cabeça com requires_grad=True significa que só ela treina inicialmente. Para aprendizado multitarefa, substitua a cabeça por múltiplas camadas Linear compartilhando o backbone. nn.Identity() é um módulo no-op prático para descartar limpo a cabeça 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)Visualização
Setup do TensorBoard
SummaryWriter transmite eventos para um diretório de log; inicie o TensorBoard com `tensorboard --logdir=runs` para visualizar. add_scalar plota uma métrica única vs passo; add_scalars sobrepõe múltiplas curvas num gráfico. Use subdiretórios separados por experimento (runs/exp1, runs/exp2) para comparar execuções na mesma UI. Faça flush com writer.close() no fim, para que os últimos eventos sejam escritos.
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=runsRegistrando Grafos e Histogramas
add_graph visualiza a arquitetura do modelo na aba Graphs — útil para depurar o fluxo forward. add_histogram mostra a distribuição de pesos ou gradientes ao longo do tempo; um treino saudável mantém gradientes não zero e pesos aproximadamente em forma de sino. Picos súbitos nos histogramas de gradiente sugerem instabilidade. Registrar a cada passo é lento — amostre a cada N passos.
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()Registrando Imagens
add_image recebe um tensor CAL; use make_grid para ladrilhar um lote numa única imagem com normalize=True, para que escale a uma faixa exibível. add_figure registra um Figure do matplotlib diretamente. draw_segmentation_masks e draw_bounding_boxes (torchvision.utils) sobrepõem previsões para QA visual rápido. Registre algumas amostras de validação por época, para monitorar progresso qualitativo, não só 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 torchviz
torchviz desenha o grafo autograd de um único forward — ótimo para depurar mismatches de forma, ramificações não intencionais ou tensores desanexados. Cada nó é um op; as arestas mostram o fluxo de tensores. show_saved=True também exibe tensores intermediários guardados para o backward, que é o que determina o uso de memória. Instale com `pip install torchviz` e Graphviz no PATH do 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)Sondagem de Pesos e Ativações
Visualizar filtros da primeira camada mostra o que o modelo 'procura' — bordas, cores, texturas. Forward hooks capturam ativações sem modificar o forward, perfeitos para sondar camadas intermediárias ou construir extratores de features. Acompanhe estatísticas de pesos e gradientes (média, desvio, norma) por passo para capturar neurônios mortos (gradientes zero) ou ativações explodindo. torchsummary ou torchinfo imprime uma tabela limpa de parâmetros por camada.
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)Treino Distribuído
Setup do DDP
DistributedDataParallel (DDP) é o padrão de treino multi-GPU: um processo por GPU, gradientes com all-reduce para que todas as réplicas fiquem em sincronia. nccl é o backend mais rápido em GPUs NVIDIA. torchrun define as variáveis de ambiente (RANK, WORLD_SIZE, LOCAL_RANK) para você. Sempre chame dist.destroy_process_group() no fim, para que o trabalho saia limpo. Veja a seção gpu-training para o loop 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 divide o dataset entre processos, para que cada GPU veja um subconjunto único de cada lote (lote efetivo = batch_size * world_size). Você PRECISA chamar sampler.set_epoch(epoca) a cada época — sem isso, toda época usa o mesmo embaralhamento e o modelo vê a mesma ordem. Não passe shuffle=True ao DataLoader ao usar um sampler; o sampler cuida da ordenação.
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
...Lançamento Multi-Nó
torchrun lança um processo por GPU e os conecta via TCP. Para multi-nó, rode torchrun em cada nó com o mesmo master_addr e um node_rank único. O endpoint de rendezvous (--rdzv_endpoint) permite que os nós se achem e suporta reinícios elásticos. Garanta que master_port esteja aberto no firewall e que cada um dos nós alcancem master_addr. NCCL também precisa de interconexão de alta banda (InfiniBand/NVLink) para boa escala.
# 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.pySincronização de Gradientes
DDP sobrepõe o all-reduce de gradientes ao cálculo do backward, razão pela qual escala tão bem. find_unused_parameters=True é preciso quando alguns parâmetros não recebem gradiente a cada passo (ex.: ramificações condicionais), mas custa overhead — evite se puder. model.no_sync() pula a sincronização por um passo, útil com acumulação de gradiente, para sincronizar só uma vez por lote efetivo em vez de a 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 e Checkpointing
Sempre gateie logging e checkpointing em rank==0, para evitar duplicatas e condições de corrida. Ao salvar um modelo DDP, use model.module.state_dict() — DDP embrulha o módulo subjacente, e salvar o embrulho torna o checkpoint específico de DDP e difícil de carregar em código não distribuído. Carregue o checkpoint em cada rank antes de embrulhar com DDP, para que todas as réplicas partam dos mesmos 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 divide parâmetros, gradientes e estados de otimizador entre GPUs — então um modelo grande demais para uma GPU pode treinar através de várias. Diferente do DDP (que mantém réplicas completas), FSDP reúne shards sob demanda durante forward/backward. Use quando o modelo não cabe na memória de uma única GPU. Salvar é mais delicado: envolva a coleta de state_dict no modo FULL_STATE_DICT, para que o rank 0 materialize o modelo completo. Precisão mista + FSDP + checkpointing de ativação permite treinar modelos muito 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')Snippets 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?