Начало работы
Установка и тензоры
Тензоры PyTorch — основная структура данных. to(device) переносит тензоры на GPU. torch.randn возвращает случайные числа из нормального распределения. Выбирайте wheel-файл под свою версию CUDA; сборки только для CPU меньше по размеру и удобны для разработки.
# 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)Атрибуты тензоров
У каждого тензора есть атрибуты shape, dtype и device. Обычные dtype: float32 (по умолчанию), float16, int64, bool. numel() возвращает общее число элементов. Для mixed precision выбирайте float16 — это вдвое уменьшает память и ускоряет вычисления на 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()) # 3Создание тензоров
torch.zeros/ones/full создают тензоры-константы. arange и linspace создают тензоры с диапазоном значений. rand — равномерное распределение, randn — нормальное. randint не включает верхнюю границу. Перед случайными операциями вызывайте torch.manual_seed(42) для воспроизводимости.
# 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))Преобразование типов
to(dtype) меняет тип тензора. Сокращения: .float(), .long(), .int(), .bool(). numpy() делит память с тензором (zero-copy на CPU). item() извлекает одно Python-число из 0-мерного тензора. Тензоры на GPU нужно сначала перенести на CPU, и только потом вызывать 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.5Индексация и срезы
Индексация в PyTorch повторяет NumPy. Целочисленный индекс возвращает 0-мерный тенз ор (для Python-числа используйте .item()). Булевы маски выравнивают результат в плоский вид. Индексация LongTensor выбирает по первой размерности. Продвинутая индексация создаёт копии, базовая нарезка — представления (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 2Изменение формы и представления
view требует непрерывной памяти; reshape работает всегда (при необходимости копирует). unsqueeze/squeeze добавляют и убирают размерности длины 1. permute переставляет все размерности, transpose меняет две. reshape(-1) выравнивает в вектор. После операций вроде permute тензор может стать не непрерывным — перед view() нужен .contiguous().
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) # equivalentОперации с тензорами
Арифметические операции
Арифметические операторы (+, -, *, /) работают поэлементно. In-place операции заканчиваются на _ и экономят память, но ломают историю autograd — не применяйте их к тензорам, для которых нужен градиент. Бродкастинг подчиняется правилам NumPy: последние размерности совпадают или растягиваются до 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.5Поэлементная математика
Поэлементные функции повторяют методы torch.* и tensor.*. clamp — это название клиппинга в PyTorch. Используйте torch.finfo(x.dtype).eps вместо жёстко заданного 1e-8 для численно безопасного log. Функции активации также доступны как модули nn (nn.ReLU()) для моделей.
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)Операции редукции
Редукции схлопывают одну или несколько размерностей. Параметр dim задаёт ось; keepdim=True сохраняет свёрнутую ось размером 1 (критично для бродкастинга). max/min с dim возвращают именованный кортеж (values, indices). item() превращает 0-мерный тензор в 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 normОперации сравнения
Операторы сравнения возвращают булевы тензоры. torch.equal проверяет точное равенство и возвращает Python bool. torch.where(cond, x, y) — векторизованный тернарный оператор, идеален для маскирования и выбора. topk возвращает и значения, и индексы — удобно для top-1 / top-5 accuracy.
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 + indicesМатричные операции
@ и torch.matmul выполняют умножение матриц и бродкастинг по батч-размерностям. Для строгого 3D-батчевого умножения используйте torch.bmm (без бродкастинга). einsum выразителен для много-тензорных свёрток, но на части железа медленнее matmul. Не инвертируйте матрицы, если можно решить систему через 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 dotКонкатенация и стек
cat соединяет тензоры по существующей оси; stack добавляет новую ось. split делит по размеру части, chunk — по числу частей. expand создаёт представление с бродкаст ингом (без копирования памяти) — используйте его вместо repeat, когда это возможно. repeat физически дублирует данные.
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
Установите requires_grad=True, чтобы autograd отслеживал операции. Вызов .backward() на скалярном тензоре вычисляет градиенты этого тензора по всем листовым тензорам с requires_grad=True. Градиенты накапливаются в .grad — между итерациями вызывайте optimizer.zero_grad() или обнуляйте x.grad=None.
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.])Вычисление градиентов
backward() работает только для скалярного выхода; для тензоров сначала примените sum или mean. torch.autograd.grad возвращает градиенты кортежем, не записывая их в .grad. Это предпочтительно внутри библиотек или когда нужны градиенты нелистовых тензоров.
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 = 8Отключение отслеживания градиентов
Для инференса используйте torch.no_grad() — граф не строится, экономятся память и время. .detach() возвращает тензор, который делит данные, но отрезан от графа; удобно для логирования или передачи в код вне PyTorch. model.eval() переводит слои (dropout, BN) в режим инференса, но НЕ отключает autograd — комбинируйте с 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 gradГрадиенты высших порядков
create_graph=True сохраняет граф самого градиента, чтобы дифференцировать ещё раз. Полезно для штрафов на градиент (WGAN-GP), мета-обучения и физически обоснованных лоссов. Это стоит дополнительной памяти — освобождайте промежуточные графы через retain_graph=False, когда закончили.
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()Хуки градиентов
register_hook на тензоре позволяет посмотреть или изменить его градиент во время backward — удобно для отладки NaN или клиппинга конкретных тензоров. register_full_backward_hook на модуле видит градиенты и по входу, и по выходу. Всегда возвращайте изменённый градиент, если хотите, чтобы правки применились.
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)Детали вычислительного графа
Листовые тензоры создаёт пользователь (requires_grad=True, без grad_fn). Промежуточные результаты — нелистовые. По умолчанию граф освобождается после backward(); передайте retain_graph=True, чтобы вызывать backward несколько раз. create_graph=True сохраняет граф градиента для производных высших порядков. Память быстро растёт — очищайте через x.grad=None между итерациями.
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)Загрузка данных
Dataset и DataLoader
DataLoader собирает батчи, перемешивает и параллельно загружает Dataset. num_workers>0 использует подпроцессы — ставьте 2–8 на GPU. pin_memory=True ускоряет передачу CPU→GPU. Для небольших датасетов, помещающихся в RAM, ставьте num_workers=0, чтобы избежать накладных расходов.
from torch.utils.data import Dataset, DataLoader
# built-in datasets
from torchvision import datasets
mnist = datasets.MNIST("./data", train=True, download=True)
# wrap in DataLoader
loader = DataLoader(
mnist,
batch_size=64,
shuffle=True,
num_workers=4,
pin_memory=True,
)
for x, y in loader:
print(x.shape, y.shape) # (64, 1, 28, 28), (64,)
breakСэмплирование батчей
Передайте batch_sampler, чтобы точно контролировать, какие индексы попадают в каждый батч. WeightedRandomSampler балансирует несбалансированные классы за счёт оверсэмплинга редких. drop_last=True отбрасывает последний неполный батч — важно для стабильности BatchNorm. Сэмплеры перебирают индексы, а данные фактически достаёт DataLoader.
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)Перемешивание и сэмплирование
shuffle=True случайно перемешивает порядок каждую эпоху (хорошо для обучения); для валидации оставляйте shuffle=False, чтобы метрики были воспроизводимы. random_split удобен, но его RNG нельзя засидить напрямую — используйте Subset с torch.randperm и Generator для полного контроля. Subset — это лишь представление индексов, данные не копируются.
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
collate_fn превращает список сэмплов в батч. По умолчанию тензоры складываются по новой размерности 0. Переопределяйте его для последовательностей переменной длины (паддинг, затем сортировка по длине для pack_padded_sequence), сэмплов-словарей и смешанных данных. Функция должна быть дешёвой — она выполняется в воркерах загрузки данных.
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)Параллельная загрузка
num_workers распараллеливает загрузку данных, чтобы GPU не простаивал. persistent_workers=True убирает затраты на запуск воркеров каждую эпоху. prefetch_factor (по умолчанию 2) задаёт, сколько батчей каждый воркер готовит заранее. В Windows и Jupyter multiprocessing бывает нестабильным — для отладки вернитесь к num_workers=0. Учтите: каждый воркер наследует всё состояние процесса, включая открытые файлы и контексты 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
Определение модуля
Наследуйтесь от nn.Module и реализуйте forward(). Объявляйте подмодули и параметры как атрибуты, чтобы они регистрировались автоматически (именно это включает .to(device), .parameters() и state_dict). Всегда вызывайте super().__init__(). Избегайте произвольной Python-логики в forward — он должен оставаться дифференцируемым и работать только с тензорами.
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 structureЛинейные слои и активации
nn.Linear вычисляет y = xW^T + b. Форма веса — (out, in). Предпочитайте модули активации, когда нужна регистрация (state_dict, хуки); функциональные F.* — для разовых операций. В архитектурах трансформеров доминируют GELU и активации в стиле SwiGLU. Softmax обычно убирают из модели и доверяют 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))Параметры и подмодули
named_parameters() выдаёт пары (имя, тензор) по всему дереву — удобно для заморозки, weight decay и отладки. .modules() рекурсивно обходит потомков; .children() — только один уровень. Буферы (например, running stats в BatchNorm) попадают в state_dict, но не в parameters(); смотрите их через named_buffers().
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-modulesПоследовательные модели
nn.Sequential соединяет модули так, что выход каждого становится входом следующего — идеально для линейных пайплайнов. Используйте OrderedDict, чтобы дать стадиям имена и обращаться по атрибуту (model.fc1). Для моделей с ветвлениями, skip connections или несколькими входами/выходами наследуйтесь от nn.Module и явно пишите forward().
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))Методы модуля
to(device) переносит параметры и буферы; .double()/.half()/.float() меняют dtype. train()/eval() переключают флаг self.training — от него зависят Dropout и BatchNorm. state_dict() возвращает OrderedDict всех параметров и буферов; load_state_dict восстанавливает их. .apply(fn) рекурсивно обходит все подмодули — удобно для своей инициализации.
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)Инициализация
По умолчанию PyTorch использует инициализацию Kaiming He для Linear/Conv, что подходит для большинства случаев. Переопределяйте через функции torch.nn.init (суффикс _ означает in-place). Kaiming подходит для семейства ReLU; Xavier/Glorot — для tanh/sigmoid. Обнулять смещения — стандартная практика. .apply(fn) вызывает fn на каждом подмодуле — идеально для массовой инициализации или сброса весов.
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)Функции потерь
CrossEntropyLoss
CrossEntropyLoss внутри применяет log-softmax + NLLLoss — передавайте сырые логиты, никогда не выходы softmax. Цели — целочисленные индексы классов (не one-hot). weight используйте для несбалансированных классов, ignore_index=-100 — для маскирования паддинг-токенов. label_smoothing=0.1 — популярная регуляризация для классификации и 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 и L1Loss
MSELoss штрафует большие ошибки квадратично (чувствителен к выбросам); L1 линеен и устойчивее. SmoothL1Loss ведёт себя как L2 около нуля и как L1 вдали от него — применяется в детекции объектов (Fast R-CNN). reduction='none' возвращает тензор по элементам, чтобы вы могли сами применить маску или веса перед .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 и BCEWithLogitsLoss
Всегда предпочитайте BCEWithLogitsLoss вместо BCELoss+sigmoid — внутри используется трюк log-sum-exp для численной стабильности. pos_weight умножает положительный член, чтобы компенсировать дисбаланс классов (упрощённый focal loss). Для multi-label классификации (каждый класс независим) используйте BCEWithLogitsLoss с формой (N, C) и выходами 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)Своя функция потерь
Своя функция потерь — это просто функция (или nn.Module), возвращающая скалярный тензор; остальное сделает autograd. Держите все операции дифференцируемыми (torch.where с дифференцируемыми ветками — нормально). Форма модуля предпочтительна, когда нужны гиперпараметры, сериализация или регистрация в конфиге. Указывайте reduction явно (mean/sum/none), чтобы поведение было предсказуемым.
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()Reduction и комбинирование лоссов
reduction='none' даёт лосс по каждому сэмплу, чтобы можно было маскировать, перевешивать или агрегировать вручную. Многозадачные лоссы комбинируйте взвешенной суммой — веса балансируют градиенты, а не только масштабы (подбирайте их). Каждый под-лосс должен оставаться дифференцируемым и на том же устройстве/dtype. Отсоединяйте член лосса через .detach(), если хотите логировать его без обратного распространения.
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 и другие лоссы
NLLLoss + LogSoftmax математически идентичны CrossEntropyLoss, но позволяют переиспользовать лог-вероятности. TripletMarginLoss обучает эмбеддинги для metric learning. KLDivLoss ожидает на входе лог-вероятности, а в цели — вероятности. CTCLoss выравнивает несегментированные последовательности с целями — передавайте input_lengths и target_lengths, чтобы избежать ошибок вып олнения.
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)Оптимизаторы
SGD
SGD + momentum по-прежнему отличный выбор для обучения CNN на больших батчах и обобщает лучше Adam на части задач. Момент 0.9 — стандарт; Nesterov даёт небольшой прирост. weight_decay добавляет L2-регуляризацию. SGD требует аккуратного расписания LR и warmup; он не подстраивается автоматически, как 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 и AdamW
Adam хранит моменты для каждого параметра и автоматически адаптирует размер шага — хороший выбор по умолчанию для NLP и небольших датасетов. AdamW развязывает weight decay и обновление по градиенту, что важно в больших масштабах (трансформеры). betas=(0.9, 0.999) — стандарт; некоторые vision-модели используют (0.9, 0.95). В transfer learning задавайте разные LR через группы параметров.
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)Паттерн шага оптимизатора
Три шага — zero_grad, backward, step — сердце обучения в PyTorch. set_to_none=True (по умолчанию в новых версиях) быстрее зануления, потому что пропускает memset и позволяет оптимизатору пропустить параметр. Между backward() и step() можно вручную править p.grad.data для клиппинга или своих обновлений.
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()Клиппинг градиентов
clip_grad_norm_ масштабирует градиенты, если их глобальная L2-норма превышает max_norm — стабильный выбор для RNN и трансформеров. clip_grad_value_ жёстко ограничивает каждый элемент (реже используется). Клиппинг предотвращает взрыв градиентов, не меняя направление. Логируйте норму до клиппинга, чтобы рано замечать нестабильность (резкие скачки > 100 — признак проблем).
# 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)Learning rate и расписания
У каждой param_group свой lr — пройдитесь по ним, чтобы задать всем. Ручной warmup линейно повышает LR первые N шагов и стабилизирует начало обучения (критично для трансформеров без коррекции смещения). Для косинусного затухания, OneCycle и прочего используйте объект scheduler (следующий раздел). Вызывайте scheduler.step() после optimizer.step(), если в документации не сказано иначе.
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)Другие оптимизаторы
RMSprop — классический оптимизатор для RNN, и он до сих пор неплохо работает. Adagrad накапливает квадраты градиентов и может застрять на старте — подходит для разреженных признаков, но не для глубоких сетей. LBFGS требует closure и оценки на полном батче — хорош для небольших выпуклых задач или файнтюнинга, но слишком медленный для больших сетей. Для большинства новых проектов начинайте с 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)Цикл обучения
Базовый цикл обучения
Минимальный цикл: zero_grad, forward, loss, backward, step. Переносите данные на GPU внутри цикла (асинхронно, с перекрытием за счёт num_workers). loss.item() достаёт число в Python — делайте так для логирования, а не с самим тензором лосса (иначе порвёте граф). Оберните цикл в функцию, чтобы переиспользовать.
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}")Валидация в цикле
Нужны оба: model.eval() + torch.no_grad(). eval переключает dropout/BN, no_grad отключает граф. Накапливайте взвешенный лосс (умножайте на размер батча), чтобы среднее было корректным даже с последним неполным батчем. argmax(dim=1) даёт индексы предсказанных классов. Сохраняйте лучшую модель, когда метрика валидации улучшается (см. раздел сохранения и загрузки).
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}")Накопление градиентов
Накопление градиентов имитирует больший батч, суммируя градиенты нескольких мини-батчей перед шагом. Делите лосс на accum_steps, чтобы эффективный градиент соответствовал одному большому батчу. Следите, чтобы длина датасета делилась на accum_steps, либо делайте шаг на остатке градиентов в конце эпохи. Особенно полезно для файнтюнинга трансформеров на одной 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 sizeОбучение со смешанной точностью
Mixed precision выполняет прямой проход в float16 (или bfloat16 на Ampere+) — ускорение в 1.5–3 раза и вдвое меньше памяти. GradScaler умножает лосс, чтобы градиенты float16 не уходили в ноль, а перед optimizer.step() возвращает масштаб. На H100/A100 предпочитайте bfloat16 — у него тот же диапазон, что у float32, и скалер не нужен. Контекстный менеджер autocast влияет только на прямой проход.
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 lossПрогресс и логирование
tqdm показывает прогресс-бар в реальном времени — set_postfix выводит текущий лосс. Экспоненциальное скользящее среднее (running = 0.9*running + 0.1*loss) сглаживает шум лучше, чем сырое значение последнего батча. Для серьёзных запусков логируйте в TensorBoard или Weights & Biases, а не в stdout, чтобы сравнивать эксперименты. Не логируйте каждый шаг, если это замедляет обучение.
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)Воспроизводимость
Для полной воспроизводимости нужны seed для Python, NumPy, PyTorch CPU и CUDA. cudnn.deterministic=True отключает недетерминированные алгоритмы (некоторые обратные операции свёрток). Воркерам DataLoader нужен свой seed через worker_init_fn, потому что они форкаются со своим состоянием RNG. Даже тогда multi-GPU и часть операций cuDNN могут не быть бит-в-бит воспроизводимыми — стремитесь к статистической воспроизводимости.
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)Оценка и метрики
Режим eval и no_grad
Всегда сочетайте model.eval() с torch.no_grad() при оценке. eval() переводит dropout и BatchNorm в режим инференса (BN использует running stats); no_grad() отключает autograd, экономя память и время. Умножайте лосс на размер батча при накоплении, чтобы итоговое среднее было несмещённым даже при неполном последнем батче.
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}")Accuracy и top-k
argmax(dim=1) возвращает предсказанный класс для каждой строки. topk возвращает k наибольших значений и их индексы — сравнение с целями, развёрнутыми до (N,1), и .any(dim=1) даёт корректность top-k. Точность по классам вскрывает дисбаланс, который скрывает общая accuracy. Всегда переносите тензоры на CPU и вызывайте .item() перед print или логированием.
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())Матрица ошибок
Накапливайте предсказания на GPU, а на CPU переносите один раз в конце, чтобы избежать синхронизаций на каждом батче. confusion_matrix показывает, где модель путает классы — идеально для отладки. classification_report даёт precision, recall и F1 по каждому классу. Для очень больших датасетов пишите предсказания на диск, а не держите в памяти.
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))Precision, recall и F1
torchmetrics накапливает состояние по батчам и корректно считает метрику даже при дисбалансе классов или меняющемся размере батча. average='macro' считает все классы равными; 'weighted' взвешивает по support; 'micro' для одноклассовых задач совпадает с accuracy. Вызывайте .reset() между эпохами или оценками, чтобы очистить аккумулятор.
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())Кросс-валидация
K-fold кросс-валидация даёт устойчивую оценку качества модели и его разброса. Пересоздавайте модель на каждом фолде, чтобы веса не протекали между фолдами. Для больших датасетов обычно достаточно 5 фолдов; для маленьких используйте стратифицированное разбиение (StratifiedKFold), чтобы сохранить баланс классов. Сообщайте mean +/- std, чтобы читатель видел стабильность.
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}")Сравнение моделей
Всегда сравнивайте модели на одном и том же отложенном тестовом наборе с одним seed и одной метрикой. Помимо accuracy смотрите на калибровку, задержку инференса и память. Если различия на тесте малы, используйте бутстрэп-доверительные интервалы. Ведите таблицу результатов (CSV или W&B), чтобы сравнивать с будущими экспериментами, а не только с последним запуском.
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}")Сохранение и загрузка
Сохранение и загрузка state_dict
state_dict() — это OrderedDict тензоров параметров; сохранять его (а не модель целиком) — рекомендованный подход, потому что он переносим и не зависит от точной структуры классов и файлов. map_location позволяет загрузить CUDA-чекпоинт на CPU. strict=False загружает только совпадающие ключи — удобно, когда архитектура немного изменилась.
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)Сохранение модели целиком
Сохранение всей модели пиклит Python-объект и привязывает его к точному классу и структуре файлов на момент с охранения. Это хрупко — любой рефакторинг ломает загрузку. Используйте только для быстрых экспериментов. Для всего, что вы будете деплоить или передавать другим, сохраняйте state_dict, а архитектуру держите в коде или конфиге.
# 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 productionЧекпоинты обучения
Полный чекпоинт хранит всё нужное для точного возобновления обучения: модель, оптимизатор, scheduler, эпоху и состояния RNG. Состояние оптимизатора (буферы momentum, моменты Adam) обязательно — без него оптимизатор фактически переинициализируется, и лосс может подскочить. Состояние RNG сохраняйте только если нужна бит-в-бит воспроизводимость.
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'])Сохранение лучшей модели
Сохраняйте лучший чекпоинт по метрике валидации, чтобы вернуть лучшую модель, даже если поздние эпохи переобучились. Для большинства задач достаточно только лучшего чекпоинта, чтобы экономить диск; для исследований храните чекпоинты по эпохам, чтобы можно было откатиться. Дополните CSV-логом (epoch, train_loss, val_loss, val_acc, path), чтобы понимать, какой чекпоинт выбирать.
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)Загрузка части модели
strict=False возвращает списки missing и unexpected ключей — просмотрите их и убедитесь, что пропущены только ожидаемые слои. Переименование ключей позволяет адаптировать чекпоинт к переименованной архитектуре. После загрузки backbone заморозьте его веса для чистого извлечения признаков или обучайте с заметно меньшим LR, чем у новой головы.
# 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)Экспорт в TorchScript
TorchScript создаёт самодостаточный граф, который можно загрузить в LibTorch (C++) или Python без исходного класса — идеально для деплоя. trace фиксирует одну ветку control flow; script обрабатывает зависящий от данных control flow, но требует аннотаций типов. ONNX экспортирует для инференса в ONNX Runtime, TensorRT или OpenVINO. Используйте dynamic_axes для переменного размера батча.
# 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
Слой Conv2d
Форма веса Conv2d — (out_channels, in_channels/groups, kH, kW). NCHW — стандартный layout памяти. padding='same' (PyTorch 1.9+) сохраняет пространственный размер при stride 1. groups=in_channels делает свёртку depthwise (как в MobileNet). Формула выходного размера: (H + 2P - K) / S + 1.
import torch.nn as nn
conv = nn.Conv2d(
in_channels=3, # RGB input
out_channels=16, # number of filters
kernel_size=3, # 3x3 filter
stride=1,
padding=1, # 'same' for kernel 3, stride 1
bias=True,
)
print(conv.weight.shape) # (16, 3, 3, 3)
x = torch.randn(4, 3, 32, 32) # NCHW
out = conv(x)
print(out.shape) # (4, 16, 32, 32) with padding=1
# depthwise separable conv
dw = nn.Conv2d(16, 16, 3, padding=1, groups=16)Слои пулинга
Пулинг уменьшает пространственные размерности, добавляя инвариантность к небольшим сдвигам. MaxPool сохраняет самый сильный отклик; AvgPool сглаженнее. AdaptiveAvgPool2d(1) схлопывает пространственные оси до 1x1 — стандартный global average pool, которым признаки свёрток подают в Linear-голову. В современных архитектурах для обучаемого даунсэмплинга предпочитайте свёртки со stride, а не пулинг.
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)Архитектура CNN
Канонический блок CNN: Conv -> BatchNorm -> ReLU -> Pool. AdaptiveAvgPool2d(1) делает сеть независимой от размера входа — можно обучать на одном разрешении, а тестировать на другом. BatchNorm2d ставится после свёртки, до активации. Держите ядра 3x3 с padding=1 (стиль VGG) — они эффективны по числу параметров и хорошо сливаются.
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))Карты признаков и рецептивное поле
Карты признаков показывают, что детектирует каждый канал: ранние слои находят края и цвета, глубокие — текстуры и части объектов. register_forward_hook позволяет захватить активации, не меняя forward. Рецептивное поле растёт с глубиной и пулингом; грубо говоря, выходной пиксель (i,j) зависит от участка входа с центром там же и размером, равным сумме stride и ядер до этого слоя.
# 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)Batch Normalization
BatchNorm2d нормализует по каналам на (N, H, W), сохраняя скользящие EMA-статистики для инференса. train()/eval() важны: eval использует running stats, поэтому выход детерминирован. BatchNorm связывает примеры внутри батча, что ломается на очень маленьких батчах — тогда переходите на GroupNorm или LayerNorm. Для корректного BN на нескольких GPU нужен SyncBatchNorm.
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 transferПопулярные архитектуры CNN
torchvision.models предоставляет ResNet, EfficientNet, MobileNet, ViT и другие с предобученными весами ImageNet. Замена последнего fc-слоя — стандартная точка входа в transfer learning. Для детекции и сегментации отбросьте голову и используйте признаки свёрток. Смотрите API весов (WeightsEnum) — старый флаг pretrained=True устарел. У каждой модели известны рецептивное поле и бюджет FLOPs; выбирайте под целевые задержки.
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 и LSTM
Слой RNN
batch_first=True делает вход (batch, seq, feature), что совпадает с большинством соглашений NLP; без него PyTorch использует (seq, batch, feature). Обычная RNN страдает от затухания градиентов на длинных последовательностях — на практике предпочитайте LSTM или GRU. out содержит состояния каждого шага с последнего слоя; h_n — финальное состояние каждого слоя.
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)Слой LSTM
LSTM возвращает и скрытое состояние h_n, и состояние ячейки c_n. Bidirectional удваивает размер признаков на выходе. Для классификации используйте финальные скрытые состояния обоих направлений (h_n[-2] — последний прямой слой, h_n[-1] — последний обратный). dropout в nn.LSTM применяется только между слоями стека, не к входу — если нужно, оберните вход в nn.Dropout.
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)Слой GRU
У GRU только скрытое состояние (нет состояния ячейки) и два гейта вместо трёх, поэтому параметров меньше, и он обучается чуть быстрее LSTM. На пр актике GRU и LSTM работают на большинстве задач похоже; GRU — хороший выбор по умолчанию для небольших датасетов. Как и в LSTM, dropout применяется только между слоями стека.
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 tasksУпакованные последовательности
Упаковка пропускает паддинг-токены в вычислениях RNN — это быстрее и не искажает скрытое состояние нулями. В старых версиях PyTorch последовательности нужно было сортировать по убыванию длины; enforce_sorted=False сортирует внутри (с небольшими накладными расходами). pad_packed_sequence возвращает обычный тензор с паддингом. Комбинируйте с collate_fn, который динамически паддит батчи.
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)Классификация последовательностей
Стандартный текстовый классификатор: embedding -> biLSTM -> dropout -> linear. Используйте padding_idx в nn.Embedding, чтобы у паддинг-токена был нулевой градиент. Передавайте lengths.cpu() в pack_padded_sequence, потому что она работает на CPU. Финальные скрытые состояния обоих направлений конкатенируются, чтобы захватить всю последовательность. На длинных последовательностях трансформеры превосходят LSTM, но требуют больше данных и вычислений.
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)Генерация последовательностей (декодер)
Декодер работает по одному шагу, обусловливаясь предыдущим выходным токеном. LSTMCell — это одношаговый LSTM; используйте его для тонкого контроля цикла. Teacher forcing подаёт на следующем шаге эталонный токен, что сходится гораздо быстрее, чем подача собственных предсказаний модели. На инференсе переходите к подаче argmax (или сэмплированию) из логитов предыдущего шага.
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 outputТрансформер
nn.MultiheadAttention
nn.MultiheadAttention вычисляет scaled dot-product attention по головам параллельно. batch_first соответствует соглашению NLP (batch, seq, dim). attn_mask используйте для каузального декодирования (нижнетреугольная маска), а key_padding_mask — чтобы игнорировать паддинг-токены. need_weights=True возвращает матрицу внимания — полезно для визуализации и анализа.
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)Энкодер трансформера
TransformerEncoderLayer — блок self-attention + FFN с residual-связями и LayerNorm. norm_first=True (pre-LN) устойчивее при обучении с нуля; post-LN (по умолчанию) требует warmup. Стек из N слоёв собирается через nn.TransformerEncoder. Передавайте src_key_padding_mask, чтобы внимание игнорировало паддинг-позиции. Для классификации усредните выходную последовательность и подайте в 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)Позиционное кодирование
Трансформеры инвариантны к перестановке, поэтому им нужна информация о позиции. Синусоидальное кодирование обобщается на последовательности длиннее тех, что были при обучении. register_buffer сохраняет pe, не делая его параметром — оно переносится вместе с .to(device) и попадает в state_dict. Обучаемые позиционные эмбеддинги (nn.Parameter) тоже работают, но не экстраполируются за пределы длины обучения.
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)Полный трансформер (Seq2Seq)
Полный encoder-decoder трансформер для перевода и суммаризации. Декодер использует каузальное маскирование цели (позиция t видит только <= t) плюс cross-attention на выход энкодера (memory). Передавайте key_padding_mask и для источника, и для цели, чтобы внимание игнорировало паддинг-токены. Голова проецирует выходы декодера в логиты словаря; лосс — CrossEntropyLoss с 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)Блок Vision Transformer (ViT)
Блок ViT — это pre-LN self-attention + pre-LN MLP с residual-связями, по сути тот же слой энкодера трансформера. Vision Transformer нарезает изображение на патчи свёрткой со stride (kernel=stride=patch_size) и трактует патчи как токены. Добавляются CLS-токен и позиционные эмбеддинги. nn.MultiheadAttention возвращает (output, weights) — распаковывайте с need_weights=False, чтобы не считать веса.
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)Внимание с нуля
Scaled dot-product attention: scores = QK^T / sqrt(d_k), softmax, умножение на V. Множитель 1/sqrt(d_k) стабилизирует дисперсию, чтобы softmax не насыщался. masked_fill с -inf до softmax обнуляет ненужные позиции. Multi-head attention делит эмбеддинг на H голов, считает внимание параллельно и конкатенирует результаты. Именно это делает nn.MultiheadAttention — пишите с нуля только для обучения или добавления вариантов вроде linear/flash attention.
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)Обучение на GPU
Выбор устройства
Всегда проверяйте torch.cuda.is_available(), чтобы машины без GPU не падали. Тензоры можно создавать сразу на устройстве аргументом device= (быстрее, чем создать на CPU и переносить). Контекст torch.device (PyTorch 2.x) задаёт устройство по умолчанию для новых тензоров. MPS поддерживает GPU Apple Silicon, но не все возможности CUDA — проверяйте поддержку операторов, прежде чем полагаться на него.
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'Перенос моделей и данных
model.to(device) переносит параметры и буферы на месте. Входные тензоры переносите внутри цикла обучения, чтобы DataLoader мог читать с диска. non_blocking=True перекрывает копирование CPU→GPU с вычислениями, если исходный тензор в pinned memory (включите pin_memory=True в DataLoader). .cpu() / .numpy() перед любой операцией NumPy — тензоры GPU нельзя преобразовать напрямую.
model = MLP(784, 128, 10).to(device)
for x, y in train_loader:
x, y = x.to(device), y.to(device)
# non-blocking copy if pin_memory=True
x = x.to(device, non_blocking=True)
...
# check placement
print(next(model.parameters()).device) # cuda:0
print(x.device)
# move a tensor to CPU for numpy / saving
arr = x.detach().cpu().numpy()
# half precision
model = model.half() # float16
x = x.half()Несколько GPU (DataParallel)
DataParallel (DP) реплицирует модель на каждой GPU, делит батч и собирает выходы на GPU 0 — просто, но медленно и несбалансированно (GPU 0 делает gather и считает лосс). Это один процесс, поэтому GIL ограничивает масштабирование. Для любой серьёзной работы на нескольких GPU используйте DistributedDataParallel. DP годится для быстрого прототипа на 2–4 GPU.
import torch.nn as nn
# simple, single-process data parallelism
model = MLP(784, 512, 10).to(device)
model = nn.DataParallel(model) # wrap AFTER .to(device)
# now model behaves normally
out = model(x)
loss = criterion(out, y)
loss.backward() # gradients are summed across GPUs
# access underlying module
inner = model.module
# specify which GPUs
model = nn.DataParallel(model, device_ids=[0, 1, 2])DistributedDataParallel
DistributedDataParallel (DDP) запускает по процессу на GPU, у каждого своя реплика модели; градиенты all-reduce, так что все GPU видят одинаковый градиент. Это намного быстрее и масштабируемее DataParallel. Запускайте через torchrun (или torch.distributed.launch). Всегда вызывайте sampler.set_epoch(epoch), чтобы каждая эпоха перемешивалась заново. Подробнее — в разделе распределённого обучения.
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()Управление памятью
empty_cache() возвращает кэшированную память ОС, но не освобождает тензоры в работе — вызывайте после большого пика, а не в горячем цикле. memory_allocated — это тензоры в работе; memory_reserved — пул кэширующего аллокатора. Чтобы снизить OOM: уменьшите батч, включите mixed precision, gradient checkpointing или накопление градиентов. expandable_segments:True снижает фрагментацию при переменных формах. Не держите ссылки на ненужные тензоры (например, лоссы в списке).
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 и производительность
cudnn.benchmark=True позволяет cuDNN профилировать алгоритмы на первом прямом проходе и кэшировать самый быстрый — отлично при фиксированных формах входа (типичная CNN), вредно, если формы меняются каждый шаг (RNN переменной длины). TF32 использует 19-битную мантиссу на Ampere+ для ~3x ускорения matmul с минимальной потерей точности; включайте, если не нужна строгая воспроизводимость fp32. Детерминированный режим отключает недетерминированные алгоритмы.
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 = FalseТрансформации и предобработка
Частые трансформации
ToTensor превращает PIL-изображение (0–255) в float-тензор в [0,1] и переставляет HWC -> CHW. Normalize стандартизирует по каналам статистиками ImageNet (де-факто стандарт для предобученных моделей — всегда используйте статистики, с которыми обучался backbone). Применяйте трансформации в Dataset, чтобы они выполнялись в воркерах; тогда GPU не ждёт 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)Аугментация данных
Аугментация регуляризует мод ель, показывая ей разнообразные входы. RandomResizedCrop + flip — классическая аугментация ImageNet. ColorJitter меняет цвет, не затрагивая геометрию. TrivialAugmentWide и RandAugment сэмплируют случайные операции со случайной силой — мощно, просто и на удивление эффективно. Для валидации используйте отдельные трансформации без аугментации, чтобы метрики были стабильными.
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 (новый API)
Transforms v2 (torchvision 0.17+) — новый API: быстрее, скриптуется через JIT и, что важно, работает совместно с изображением, маской и bbox, поэтому аугментации для детекции и сегментации остаются согласованными. ToDtype + scale=True заменяет ToTensor. Для resize-операций всегда передавайте antialias=True — даунсэмплинг чище. Старый модуль transforms работает, но новых возможностей в нём не будет.
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(),
])Своя трансформация
Своя трансформация — любой вызываемый объект, принимающий тензор (или PIL-изображение) и возвращающий его же. Собирайте их через transforms.Compose. Шум добавляйте после ToTensor, чтобы он работал с float. Для случайности на каждый сэмпл используйте torch.rand внутри __call__, чтобы каждое применение получало новое решение. Transforms v2 позволяет писать классы тран сформаций, работающие с совместным входом (image, label), через переопределение 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 xПредобработка текста и табличных данных
Для текста постройте словарь по обучающему набору (никогда по val/test) и переведите токены в целочисленные id; <unk> закрывает незнакомые слова, <pad> нужен для батчей переменной длины. Для табличных данных стандартизируйте признаки статистиками, посчитанными только на обучающем наборе — утечка статистик val/test завышает метрики. Сохраняйте scaler и словарь вместе с чекпоинтом модели, чтобы инференс предобрабатывал так же.
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/testСвой Dataset
Класс Dataset
Dataset требует только __len__ и __getitem__. Открывайте файлы лениво внутри __getitem__, чтобы дёшево держать в памяти миллионы путей. Возвращайте кортежи (input, target), а collate по умолчанию соберёт их в батчи. __getitem__ должен быть дешёвым и без побочных эффектов, потому что он выполняется в воркерах — не меняйте общее состояние.
from torch.utils.data import Dataset
class ImageDataset(Dataset):
def __init__(self, paths, labels, transform=None):
self.paths = paths
self.labels = labels
self.transform = transform
def __len__(self):
return len(self.paths)
def __getitem__(self, idx):
from PIL import Image
img = Image.open(self.paths[idx]).convert('RGB')
label = self.labels[idx]
if self.transform:
img = self.transform(img)
return img, label
dataset = ImageDataset(paths, labels, transform=train_tf)
img, label = dataset[0]Dataset из папок с изображениями
ImageFolder ожидает по одному подкаталогу на класс и выводит метки из имён папок — самый быстрый старт для классификации изображений. class_to_idx сопоставляет имена целочисленным меткам; сохраняйте его одинаковым для train/val/test, переиспользуя одно отображение. random_split возвращает Subset, которые делят базовые данные, поэтому память не дублируется.
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
Токенизируйте текст один раз и храните целочисленные id, чтобы не токенизировать заново каждую эпоху. Для последовательностей переменной длины возвращайте сырые списки и паддите в collate_fn, чтобы каждый батч дополнялся только до своей максимальной длины. pack_padded_sequence затем пропускает паддинг-позиции в RNN. Для обучения трансформера возвращайте attention-маски, чтобы паддинг-токены игнорировались вниманием.
from torch.utils.data import Dataset
import torch
class TextDataset(Dataset):
def __init__(self, texts, labels, vocab, max_len=128):
self.texts = texts
self.labels = labels
self.vocab = vocab
self.max_len = max_len
def __len__(self):
return len(self.texts)
def __getitem__(self, idx):
tokens = self.texts[idx].split()[:self.max_len]
ids = [self.vocab[t] for t in tokens]
ids += [0] * (self.max_len - len(ids)) # pad
return torch.tensor(ids), self.labels[idx]
# variable length: use custom collate
def text_collate(batch):
ids, labels = zip(*batch)
lens = torch.tensor([len(x) for x in ids])
padded = torch.nn.utils.rnn.pad_sequence(ids, batch_first=True)
return padded, lens, torch.tensor(labels)IterableDataset
IterableDataset потоково отдаёт данные вместо случайного доступа — необходимо для огромных или потоковых источников (логи, базы данных, S3). Воркеры должны явно делить поток (itertools.islice), иначе каждый прочитает одни и те же данные. shuffle напрямую не поддерживается; вместо этого буферизуйте сэмплы и перемешивайте внутри буфера. Используйте для датасетов, слишком больших, чтобы индексировать их по длине.
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 и ConcatDataset
TensorDataset — самый быстрый путь, когда данные помещаются в RAM: он возвращает кортежи тензоров, которые collate по умолчанию собирает в батчи. ConcatDataset сцепляет датасеты подряд; удобно для объединения размеченных и псевдоразмеченных данных. Subset оборачивает датасет со списком индексов, позволяя random_split и произвольную нарезку без копирования данных.
from torch.utils.data import TensorDataset, ConcatDataset, DataLoader
# wrap in-memory tensors
X = torch.randn(1000, 784)
y = torch.randint(0, 10, (1000,))
dataset = TensorDataset(X, y)
x, label = dataset[0]
# combine multiple datasets
full = ConcatDataset([dataset_a, dataset_b])
print(len(full)) # len(a) + len(b)
# Subset for indexing
from torch.utils.data import Subset
half = Subset(dataset, range(500))
# random splits
from torch.utils.data import random_split
train, val = random_split(dataset, [0.8, 0.2])Scheduler LR
StepLR и MultiStepLR
StepLR и MultiStepLR — простейшие scheduler'ы: умножают LR на gamma в фиксированные эпохи. Они предсказуемы и хорошо работают для CNN, обучаемых с нуля. Вызывайте scheduler.step() после обучения в эпохе, а не внутри цикла по батчам. get_last_lr() показывает текущий LR для логирования. Обратите внимание: step_size считает эпохи, а не шаги.
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
Косинусное затухание плавно снижает LR — часто даёт небольшой прирост точности по сравнению со ступенчатым. Warm restarts (SGDR) сбрасывают LR к базовому в начале каждого цикла, что помогает выйти из острых минимумов; T_mult=2 удваивает длину каждого следующего цикла. Косинусные scheduler'ы — современный выбор по умолчанию для классификации изображений и предобучения.
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 следит за метрикой и снижает LR, когда она перестаёт улучшаться — идеально, когда правильное расписание заранее неизвестно. mode='min' для лоссов, 'max' для accuracy. patience=N ждёт N эпох без улучшения перед снижением. В отличие от других scheduler'ов, метрику нужно передавать в step(metric). При слишком большом patience легко переобучиться; комбинируйте с early stopping.
from torch.optim.lr_scheduler import ReduceLROnPlateau
scheduler = ReduceLROnPlateau(
optimizer,
mode='min', # 'min' for loss, 'max' for accuracy
factor=0.5, # multiply LR by factor on plateau
patience=3, # epochs to wait before reducing
min_lr=1e-7,
threshold=1e-4,
)
for epoch in range(epochs):
train(...)
val_loss = validate(...)
scheduler.step(val_loss) # pass the metric!OneCycleLR и CyclicLR
OneCycleLR (super-convergence) делает warmup, пик и спад — часто самый быстрый способ обучить модель до заданной точности. Он делает шаг на каждый батч, поэтому задайте total_steps = epochs * batches_per_epoch. pct_start=0.3 отводит 30% шагов на warmup. CyclicLR колеблется между base и max LR — полезно для подбора LR (LR range test).
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 и затухание
Warmup стабилизирует первые шаги, когда оценка второго момента у Adam плохо обусловлена, — критично для обучения трансформеров. LinearLR + SequentialLR аккуратно совмещают warmup с любым расписанием затухания. LambdaLR даёт полный контроль через функцию от номера шага — самый гибкий scheduler. Для расписаний в стиле HuggingFace смотрите 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
LambdaLR умножает базовый LR на lambda(step) — самый гибкий способ задать своё расписание. Передайте список lambda (по одной на param_group) для расписаний по группам: например, затухание для весов, но не для смещений, или разные расписания для backbone и головы в transfer learning. Lambda должны быть дешёвыми, потому что выполняются каждый шаг. Избегайте замыканий с изменяемым состоянием — держите их чистыми.
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
Предобученные модели
Всегда используйте API WeightsEnum (DEFAULT выбирает лучшие доступные веса) — старый pretrained=True устарел. У каждого объекта весов есть .transforms(), возвращ ающий точную предобработку, с которой обучалась модель, — применяйте её, чтобы входы совпадали. Классификационная голова выдаёт 1000 классов ImageNet; замените её под свою задачу.
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])Извлечение признаков
Извлечение признаков замораживает backbone и обучает только новую голову — самый быстрый baseline в transfer learning, часто достигающий высокой точности за минуты обучения на небольшом датасете. Так как backbone заморожен, признаки можно вычислить один раз и обучить на них дешёвый классификатор, сильно экономя вычисления. Включите model.eval(), чтобы BatchNorm использовал running stats даже во время обучения головы.
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)Файнтюнинг
Файнтюнинг обучает всю модель (или её часть) с небольшим LR, чтобы предобученные признаки адаптировались к задаче. Использ уйте разные LR: меньше для ранних слоёв (общие признаки), больше для головы (специфичные для задачи). Постепенная разморозка — сначала обучить голову, затем открывать более глубокие слои — устойчивее, чем обучать всё сразу, особенно на небольших датасетах.
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.Заморозка и разморозка слоёв
requires_grad_(False) останавливает отслеживание и обновление параметра autograd'ом, но градиенты всё равно текут через замороженные слои к обучаемым ниже. Используйте named_parameters() для фильтрации по имени слоя при выборочной заморозке. Всегда логируйте число обучаемых параметров, чтобы случайно не заморозить всё (частая тихая ошибка). После разморозки пересоздайте оптимизатор, чтобы он подхватил новые обучаемые параметры.
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 autogradЗамена классификатора
В каждой архитектуре классификатор лежит в своём атрибуте: ResNet использует .fc, EfficientNet — .classifier[1], ViT — .heads.head. Новую голову задавайте с requires_grad=True, чтобы сначала обучалась только она. Для многозадачного обучения замените голову несколькими Linear-слоями с общим backbone. nn.Identity() — no-op модуль, удобный, чтобы аккуратно убрать исходную голову.
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)Визуализация
Настройка TensorBoard
SummaryWriter пишет события в каталог логов; запускайте TensorBoard командой tensorboard --logdir=runs. add_scalar рисует одну метрику по шагам; add_scalars накладывает несколько кривых на один график. Держите отдельные подкаталоги для экспериментов (runs/exp1, runs/exp2), чтобы сравнивать запуски в одном UI. В конце вызовите writer.close(), чтобы последние события записались.
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=runsЛогирование графов и гистограмм
add_graph визуализирует архитектуру модели на вкладке Graphs — полезно для отладки прямого потока. add_histogram показывает распределение весов или градиентов во времени; при здоровом обучении градиенты не нулевые, а веса примерно колоколообразные. Резкие всплески на гистограммах градиентов намекают на нестабильность. Логировать каждый шаг медленно — сэмплируйте каждый N-й шаг.
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()Логирование изображений
add_image принимает тензор CHW; используйте make_grid, чтобы собрать батч в одно изображение, с normalize=True для приведения к отображаемому диапазону. add_figure логирует matplotlib Figure напрямую. draw_segmentation_masks и draw_bounding_boxes (torchvision.utils) накладывают предсказания для быстрой визуальной проверки. Логируйте несколько примеров валидации за эпоху, чтобы следить за качественным прогрессом, а не только за скалярными метриками.
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)Граф torchviz
torchviz рисует граф autograd одного прямого прохода — отлично для отл адки несовпадений форм, неожиданных ветвлений и отсоединённых тензоров. Каждый узел — операция; рёбра показывают поток тензоров. show_saved=True также показывает промежуточные тензоры, сохранённые для backward, — именно они определяют расход памяти. Установка: pip install torchviz и Graphviz в системном PATH.
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)Анализ весов и активаций
Визуализация фильтров первого слоя показывает, что модель ищет: края, цвета, текстуры. Forward-хуки захватывают активации, не меняя forward, — идеально для анализа промежуточных слоёв или построения экстракторов признаков. Отслеживайте статистики весов и градиентов (mean, std, norm) по шагам, чтобы ловить мёртвые нейроны (нулевые градиенты) или взрыв активаций. torchsummary или torchinfo печатают аккуратную таблицу параметров по слоям.
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)Распределённое обучение
Настройка DDP
DistributedDataParallel (DDP) — стандартный паттерн обучения на нескольких GPU: один процесс на GPU, градиенты all-reduce, поэтому все реплики синхронны. nccl — самый быстрый backend на GPU NVIDIA. torchrun сам выставляет переменные окружения (RANK, WORLD_SIZE, LOCAL_RANK). В конце всегда вызывайте dist.destroy_process_group(), чтобы задача завершилась корректно. Полный цикл — в разделе про обучение на GPU.
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 разбивает датасет между процессами, так что каждая GPU получает уникальное подмножество каждого батча (эффективный батч = batch_size * world_size). ОБЯЗАТЕЛЬНО вызывайте sampler.set_epoch(epoch) каждую эпоху — иначе перемешивание будет одинаковым, и модель увидит один и тот же порядок. Не передавайте shuffle=True в DataLoader при использовании сэмплера; порядок задаёт сэмплер.
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
...Запуск на нескольких узлах
torchrun запускает по процессу на GPU и связывает их по TCP. Для нескольких узлов запустите torchrun на каждом узле с одинаковым master_addr и уникальным node_rank. Rendezvous-эндпоинт (--rdzv_endpoint) позволяет узлам найти друг друга и поддерживает эластичные перезапуски. Убедитесь, что master_port открыт в файрволе и все узлы видят master_addr. NCCL также нуждается в высокоскоростном interconnect (InfiniBand/NVLink) для хорошего масштабирования.
# 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.pyСинхронизация градиентов
DDP перекрывает all-reduce градиентов с обратным проходом — поэтому он так хорошо масштабируется. find_unused_parameters=True нужен, когда некоторые параметры не получают градиент на каждом шаге (например, условные ветвления), но добавляет накладные расходы — избегайте, если можно. model.no_sync() пропускает синхронизацию на шаг — полезно с накоплением градиентов, чтобы синхронизироваться раз на эффективный батч, а не на каждый микро-батч.
# 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()Логирование и чекпоинты
Всегда ограничивайте логирование и сохранение чекпоинтов условием rank==0, чтобы избежать дублей и гонок. При сохранении DDP-модели используйте model.module.state_dict() — DDP оборачивает базовый модуль, и сохранение обёртки делает чекпоинт специфичным для DDP и трудным для загрузки вне распределённого кода. Загружайте чекпоинт на каждом ранге до обёртки в DDP, чтобы все реплики стартовали с одинаковыми весами.
# 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 шардит параметры, градиенты и состояния оптимизатора по GPU — так модель, не влезающая в одну GPU, обучается на нескольких. В отличие от DDP, который держит полные реплики, FSDP собирает шарды по требованию во время прямого и обратного прохода. Используйте, когда модель не помещается в память одной GPU. Сохранение сложнее: оберните сбор state_dict в режим FULL_STATE_DICT, чтобы rank 0 материализовал полную модель. Mixed precision + FSDP + activation checkpointing позволяют обучать очень большие модели.
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')Связанные сниппеты PyTorch
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?