Skip to content

PyTorch チートシート

Meta が開発するオープンソースの深層学習フレームワーク。

01

はじめに

インストールとテンソル

コアデータ構造であるのが、PyTorch のテンソルです。テンソルを GPU へ動かすには、to(device) を使いましょう。正規分布からの乱数を返すのが、torch.randn です。あなたの CUDA バージョンに合う wheel URL を選び、開発には CPU 専用ビルドが小さくて良いです。

pytorch
# 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() です。メモリを半減させ GPU の計算を速くするため、混合精度には float16 を選びましょう。

pytorch
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 です。range テンソルを作るのが、arange と linspace です。一様なのが rand で、正規が randn です。上限を除外するのが、randint です。再現性のため、ランダム操作の前に torch.manual_seed(42) を使いましょう。

pytorch
# 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() です。テンソルとメモリを共有するのが(CPU 上ではゼロコピー)、numpy() です。0 次元テンソルから単一の Python スカラーを取り出すのが、item() です。numpy() の前に、GPU テンソルは CPU へ動かされなければなりません。

pytorch
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

インデックスとスライス

NumPy を映し返すのが、PyTorch のインデックスです。0 次元テンソルを返すのが、整数インデックスです(Python スカラーには .item() を)。結果を平坦化するのが、真偽マスクです。最初の次元に沿って選択するのが、LongTensor によるインデックスです。コピーを作るのが、応用インデックスで、ビューを作るのが、基本のスライスです。

pytorch
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 です。サイズ 1 の次元の追加・除去が、unsqueeze/squeeze です。すべての次元を並べ替えるのが、permute で、2 つを交換するのが、transpose です。平坦化するのが、reshape(-1) です。permute のような操作が、テンソルを非連続にし、view() の前に .contiguous() を必要とさせ得ます。

pytorch
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
02

テンソルの操作

算術の操作

要素ごとであるのが、算術演算子(+、-、*、/)です。_ で終わるのが、インプレースの操作です。メモリを節約しますが autograd の履歴を無効化するため、grad を必要とするテンソル上では避けましょう。NumPy のルールに従うのが、broadcasting です:末尾の次元が一致するか、1 へ引き伸ばされます。

pytorch
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.* のメソッドを映し返すのが、要素ごとの数学です。クリッピングの PyTorch 名が、clamp です。数値的に安全な log のために、ハードコードされた 1e-8 の代わりに、torch.finfo(x.dtype).eps を使いましょう。モデルのために、nn モジュールとしても利用可能なのが(nn.ReLU())、活性化関数です。

pytorch
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)

削減の操作

1 つ以上の次元を折りたたむのが、削減です。軸を選ぶには dim を渡し、削減された軸をサイズ 1 で保つのが(broadcasting には決定的に重要)、keepdim=True です。名前付きタプル(values、indices)を返すのが、dim 付きの max/min です。0 次元テンソルを Python スカラーへ引き出すのが、item() です。

pytorch
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

比較の操作

bool テンソルを返すのが、比較演算子です。正確な等価性を確認し Python の bool を返すのが、torch.equal です。ベクトル化された三項が、torch.where(cond, x, y) です — マスキングや選択に完璧です。値とインデックスの両方を返すのが、topk で、top-1 / top-5 の精度に有用です。

pytorch
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

行列の操作

行列の乗算を行い、バッチ次元上で broadcast するのが、@ と torch.matmul です。厳密な 3D のバッチ化された matmul(broadcasting なし)には、torch.bmm を。マルチテンソルの縮約に表現力豊かなのが、einsum ですが、一部のハードウェアでは matmul より遅くなり得ます。torch.solve / linalg.solve で解けるなら、行列の逆行列を避けましょう。

pytorch
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 です。broadcast されたデータを持つビューを作るのが(メモリコピーなし)、expand です。可能な限り、repeat の代わりにこれを使いましょう。データを物理的に複製するのが、repeat です。

pytorch
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 copy
03

Autograd

基本の Autograd

autograd のために操作を追跡させるには、requires_grad=True を設定しましょう。スカラーテンソル上の .backward() 呼び出しが、requires_grad=True を持つすべてのリーフテンソルに対する、そのテンソルの勾配を計算します。.grad へ蓄積されるのが、勾配です。反復の間に、optimizer.zero_grad() か x.grad=None を呼びましょう。

pytorch
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 しましょう。.grad に保存せず、タプルとして勾配を返すのが、torch.autograd.grad です。ライブラリの内側や、非リーフテンソルの勾配が必要なときに、こちらが推奨です。

pytorch
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 のコードへのテンソル供給に最適です。レイヤー(dropout、BN)を推論モードへ切り替えるのが、model.eval() ですが、autograd を無効化し「ません」 — torch.no_grad() と組み合わせましょう。

pytorch
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 で中間のグラフを解放しましょう。

pytorch
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 です。変化を伝播させたいなら、修正された勾配を必ず返しましょう。

pytorch
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() 後にグラフが解放されるため、backward を複数回呼ぶには、retain_graph=True を渡しましょう。高次の微分のための、勾配のグラフを保持するのが、create_graph=True です。メモリが急速に成長するため、反復の間に x.grad=None で消去しましょう。

pytorch
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)
04

データのローディング

Dataset と DataLoader

Dataset をバッチ化し、シャッフルし、並列ロードするのが、DataLoader です。サブプロセスを使うのが、num_workers>0 で、GPU ごとに 2〜8 を設定しましょう。CPU→GPU の転送を速くするのが、pin_memory=True です。RAM に収まる小さい dataset には、オーバーヘッドを避けるため num_workers=0 を設定しましょう。

pytorch
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 です。

pytorch
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 のままにしましょう。便利だが RNG が直接シード設定できないのが、random_split です。フルの制御のためには、torch.randperm と Generator を使った Subset を使いましょう。薄いインデックスのビューにすぎず、データのコピーはないのが、Subset です。

pytorch
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 です。新しい dim 0 に沿ってテンソルをスタックするのが、デフォルトです。可変長のシーケンス(pack_padded_sequence のためにパディングし長さでソートする)、dict ベースのサンプル、またはテンソル/非テンソルの混合データのために、上書きしましょう。関数は安価に保つこと — データローディングの worker 上で動くためです。

pytorch
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)

並列ローディング

データのローディングを並列化し、GPU が決して待たないのが、num_workers です。エポックごとの worker 起動のコストを避けるのが、persistent_workers=True です。各 worker がどれだけ先にバッチを準備するかの制御が、prefetch_factor(デフォルト 2)です。Windows と Jupyter では、マルチプロセッシングが不調和になり得るため、デバッグには num_workers=0 へフォールバックしましょう。注意:完全なプロセスの状態を各 worker が継承します。開いたファイルハンドルと CUDA のコンテキストを含めて。

pytorch
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 needed
05

nn.Module

モジュールの定義

nn.Module を継承し forward() を実装しましょう。属性としてサブモジュールとパラメータを宣言すれば、自動的に登録されます(.to(device)、.parameters()、state_dict を可能にするものです)。必ず super().__init__() を呼びましょう。forward での任意の Python ロジックは避け、微分可能でテンソルだけに保ちましょう。

pytorch
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

Linear と活性化のレイヤー

y = xW^T + b を適用するのが、nn.Linear です。(out, in) であるのが、weight の形状です。登録(state_dict、hooks)させたいときには、活性化モジュールを推奨し、1 回限りの操作には、関数型の F.* を使いましょう。transformer アーキテクチャを支配するのが、GELU と SwiGLU 風の活性化です。通常、モデルから Softmax を省略し、CrossEntropyLoss に処理させるべきです。

pytorch
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))

パラメータとサブモジュール

ツリー全体のための (name, tensor) を出すのが、named_parameters() です — 凍結、weight decay、デバッグに最適です。子へ再帰するのが、.modules() で、1 レベルだけなのが、.children() です。state_dict には現れるが parameters() には現れないのが、buffer です(BatchNorm の running 統計など)。それを見るには、named_buffers() を。

pytorch
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

Sequential モデル

各出力が次の入力を供給する、モジュールのチェーンが、nn.Sequential です — 線形のパイプラインに完璧です。属性(model.fc1)によりインデックスできるよう、ステージに名前を付けるには、OrderedDict を使いましょう。分岐、skip 接続、複数の入出力を持つモデルのためには、nn.Module を継承し forward() を明示的に書きましょう。

pytorch
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))

モジュールのメソッド

パラメータと buffer を動かすのが、to(device) で、dtype をキャストするのが、.double()/.half()/.float() です。self.training フラグをトグルするのが、train()/eval() です。それ上で分岐するのが、Dropout と BatchNorm です。すべてのパラメータと buffer の OrderedDict を返すのが、state_dict() で、復元するのが、load_state_dict です。すべてのサブモジュールへ再帰するのが、.apply(fn) で、カスタム初期化に有用です。

pytorch
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)

初期化

ほとんどのケースで機能する、Linear/Conv のためのデフォルトが、PyTorch による Kaiming He init です。torch.nn.init の関数で上書きしましょう(接尾辞 _ がインプレースを意味します)。ReLU ファミリーに適したのが、Kaiming で、tanh/sigmoid に適したのが、Xavier/Glorot です。ゼロへのバイアスの初期化が標準です。すべてのサブモジュール上で fn を実行するのが、.apply(fn) で — 一括初期化や重みのリセットに完璧です。

pytorch
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)
06

損失関数

CrossEntropyLoss

内部的に log-softmax + NLLLoss を適用するのが、CrossEntropyLoss です — softmax 出力でなく、生の logits を渡しましょう。整数のクラスインデックスであるのが(one-hot ではない)、ターゲットです。不均衡なクラスには weight を使い、パディングトークンのマスクには、ignore_index=-100 を。分類と NLP の人気のある正則化器が、label_smoothing=0.1 です。

pytorch
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 です。ゼロ近くでは L2 のように、遠くでは L1 のように振る舞うのが、SmoothL1Loss です — オブジェクト検出で使われます(Fast R-CNN)。要素ごとのテンソルを返すのが、reduction='none' で、.mean() を呼ぶ前に、自分でマスクや重み付けできます。

pytorch
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-element

BCELoss と BCEWithLogitsLoss

BCELoss+sigmoid より、BCEWithLogitsLoss を必ず推奨しましょう — 数値的安定のために log-sum-exp のトリックを使うからです。クラスの不均衡を対抗するため、陽性項を掛けるのが、pos_weight です(focal loss lite のような)。マルチラベル分類(各クラスが独立)のためには、形状 (N, C) と sigmoid 出力付きの BCEWithLogitsLoss を使いましょう。

pytorch
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)明示的に保ちましょう。

pytorch
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='none' です。そのため、マスク、重み付け、手動集約ができます。加重和により、マルチタスクの損失を組み合わせましょう — 重みがバランスさせるのは、大きさだけでなく勾配です(調整しましょう)。各サブ損失が、微分可能かつ同じ device/dtype 上に留まらなければなりません。backprop せずログしたい損失項は、.detach() で分離しましょう。

pytorch
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 とその他の損失

数学的に CrossEntropyLoss と同一だが、log-probs を再利用できるのが、NLLLoss + LogSoftmax です。metric-learning の埋め込みを学習するのが、TripletMarginLoss です。log-probs を入力として、probs をターゲットとして期待するのが、KLDivLoss です。未分割のシーケンスをターゲットへ整列させるのが、CTCLoss です — ランタイムエラーを避けるため、input_lengths と target_lengths を渡しましょう。

pytorch
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)
07

オプティマイザー

SGD

大バッチの CNN 学習のトップの選択であり続け、一部のタスクで Adam より良く汎化するのが、SGD + momentum です。標準が momentum 0.9 で、小さな余分な利得を与えるのが、Nesterov です。L2 正則化を加えるのが、weight_decay です。慎重な LR のスケジューリングとウォームアップを必要とするのが、SGD です。Adam のように自動チューニングではありません。

pytorch
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 と小さい dataset への素晴らしいデフォルトです。勾配の更新から weight decay を分離するのが、AdamW です。規模で効きます(transformers)。標準が、betas=(0.9, 0.999) で、一部のビジョンモデルが使うのが、(0.9, 0.95) です。転移学習での差分学習率のために、パラメータごとのグループを使いましょう。

pytorch
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)

オプティマイザーのステップパターン

PyTorch 学習の心臓部が、3 ステップのパターンです — zero_grad、backward、step です。ゼロの充填より速いのが、set_to_none=True(新しいバージョンのデフォルト)です。memset をスキップし、オプティマイザーにパラメータのスキップを許すからです。クリッピングやカスタム更新のためには、backward() と step() の間で p.grad.data を手動編集しましょう。

pytorch
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()

勾配のクリッピング

グローバル L2 ノルムが max_norm を超えれば勾配を再スケールするのが、clip_grad_norm_ です。RNN と transformer への安定したデフォルトです。各要素をハードに制限するのが、clip_grad_value_ です(あまり一般的でない)。方向を変えずに、爆発する勾配を防ぐのが、クリッピングです。不安定性を早く検出するため、クリップ前の勾配ノルムをログしましょう(>100 の急なスパイクが問題を示します)。

pytorch
# 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)

学習率とスケジュール

独自の lr を持つのが、各 param_group です。すべてを設定するには反復しましょう。早い段階の学習を安定させるため、最初の N ステップで LR を線形に立ち上げるのが、手動のウォームアップです(バイアス補正のない transformer には決定的に重要です)。cosine decay、OneCycle などには、(次のセクションの)スケジューラオブジェクトを使いましょう。ドキュメントが別のことを言わない限り、optimizer.step() の後に必ずスケジューラを step しましょう。

pytorch
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)

その他のオプティマイザー

クラシックな RNN のオプティマイザーであり、依然良く機能するのが、RMSprop です。二乗勾配を蓄積し、早く停滞し得るのが、Adagrad です。疎な特徴には良く、深いネットには向きません。closure とフルバッチの評価を必要とするのが、LBFGS です。小さい凸問題やファインチューニングには素晴らしいが、大きい深いネットには遅すぎます。ほとんどの新しいプロジェクトは、AdamW から始めましょう。

pytorch
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)
08

学習ループ

基本の学習ループ

最小の学習ループ:zero_grad、forward、loss、backward、step です。ループ内でデータを GPU へ動かしましょう(num_workers との非同期オーバーラップ)。スカラーを Python へ引き出すのが、loss.item() です。ロギングのためにこれを行い、損失テンソル自体のために行ってはいけません(グラフを壊してしまいます)。再利用できるよう、ループを関数で包みましょう。

pytorch
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() です。dropout/BN を切り替えるのが、eval で、グラフをスキップするのが、no_grad です。(バッチサイズを掛け)加重損失を蓄積し、最後の短いバッチでも平均が正しくなるようにしましょう。予測されたクラスのインデックスを与えるのが、argmax(dim=1) です。val 指標が改善したら、最良のモデルを保存しましょう(save-load のセクションを参照)。

pytorch
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 で割りましょう。dataset の長さが accum_steps で割り切れることを確保するか、エポック末に残りの勾配上で step しましょう。単一 GPU での transformer のファインチューニングに特に有用です。

pytorch
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

混合精度学習

(Ampere+ 上の)bfloat16 での float16 の forward 操作により、1.5〜3 倍の高速化とメモリ半減が得られるのが、混合精度です。float16 の勾配のアンダーフローを防ぐため、損失を掛けるのが、GradScaler で、optimizer.step() の前に unscale します。H100/A100 上では bfloat16 を推奨しましょう — float32 と同じ範囲を持ち、スケーラーを必要としません。forward パスだけに影響するのが、autocast のコンテキストマネージャーです。

pytorch
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 です。running の損失を表示するには、set_postfix を使いましょう。生の最後のバッチの値より、(running = 0.9*running + 0.1*loss の)指数移動平均が、ノイズをより良く平滑化します。本気の実行には、stdout でなく、TensorBoard か Weights & Biases へログしましょう。そうすれば、実行を比較できます。学習を遅くするなら、毎ステップのロギングを避けましょう。

pytorch
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)

再現性

完全な再現性には、Python、NumPy、PyTorch CPU、CUDA のシードが必要です。非決定的なアルゴリズム(一部の conv の backward 操作)を無効化するのが、cudnn.deterministic=True です。独自の RNG 状態と共に fork されるため、DataLoader の worker それぞれが、worker_init_fn 経由でシードを必要とします。それでも、マルチ GPU といくつかの cuDNN の操作が、ビット単位で再現可能でないことがあります — 統計的な再現性を目指しましょう。

pytorch
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)
09

評価と指標

Eval モードと No Grad

評価のためには、model.eval() と torch.no_grad() を必ずペアにしましょう。推論モードへ dropout と BatchNorm を切り替えるのが(BN が running 統計を使います)、eval() で、メモリと時間を節約するため autograd を無効化するのが、no_grad() です。最終平均が、最後のバッチが短くても偏りなくなるよう、蓄積時には損失をバッチサイズで掛けましょう。

pytorch
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) です。k 個の最大値とそのインデックスを返すのが、topk です。ターゲットを (N,1) へ拡張し .any(dim=1) を使えば、top-k の正しさが得られます。全体の精度が隠す不均衡問題を暴露するのが、クラスごとの精度です。print か log へ渡す前に、テンソルを必ず CPU へ動かし .item() を呼びましょう。

pytorch
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 です — デバッグに完璧です。クラスごとの precision、recall、F1 を与えるのが、classification_report です。非常に大きな dataset では、メモリに保持するのでなく、予測をディスクへストリーミングしましょう。

pytorch
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' で、support により重み付けするのが、「weighted」、シングルラベルのタスクで accuracy と等しくなるのが、「micro」です。アキュムレータを消去するには、エポックや評価の間に .reset() を呼びましょう。

pytorch
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 分割クロスバリデーションです。重みが分割をまたいで漏れないよう、分割ごとにモデルを再インスタンス化しましょう。大きな dataset には通常、5 分割が十分で、小さいものには、クラスバランスを保つ層化分割(StratifiedKFold)を使いましょう。読者が安定性を見られるよう、mean +/- std を報告しましょう。

pytorch
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}")

モデルの比較

同じシードと指標で、同じホールドアウトのテストセット上で、モデルを必ず比較しましょう。精度を超えて、キャリブレーション、推論レイテンシ、メモリを見ましょう。テストセットの差が小さいときは、ブートストラップの信頼区間を使いましょう。最後の実行だけと比較するのではなく、将来の実験と比較できるよう、結果の表(CSV か W&B)を保ちましょう。

pytorch
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}")
10

保存と読み込み

State Dict の保存と読み込み

パラメータテンソルの OrderedDict が、state_dict() です。それを保存する(モデル全体ではなく)のが推奨パターンです。移植可能であり、正確なクラス/ファイルのレイアウトから切り離されるためです。CPU 上で CUDA のチェックポイントをロードできるのが、map_location です。一致するキーだけをロードするのが、strict=False で、アーキテクチャがわずかに変わったときに手軽です。

pytorch
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 オブジェクトを pickle するのが、モデル全体の保存です。保存時の正確なクラスとファイル構造に結び付けられます。脆いです — どんなリファクタリングもローディングを壊します。素早い実験のためだけに使いましょう。デプロイか共有するかもしれないものには、state_dict を保存し、アーキテクチャをコードか設定で保ちましょう。

pytorch
# 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

学習チェックポイント

正確に学習を再開するために必要なすべてを保存するのが、フルのチェックポイントです:モデル、オプティマイザー、スケジューラ、エポック、RNG 状態です。不可欠なのが、オプティマイザーの状態です(momentum のバッファ、Adam のモーメント)。それなしでの再開が、実質的にオプティマイザーを再初期化し、損失をスパイクさせ得ます。ビット正確な再現性が必要な場合だけ、RNG 状態を保存しましょう。

pytorch
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'])

最良モデルの保存

検証の指標により、最良のチェックポイントを保存しましょう。そのため、後のエポックが過剰適合しても、最良のモデルを回復できます。ディスクを節約するため、ほとんどのタスクでは、最良のチェックポイントだけを保ち、研究のためには、ロールバックできるよう、エポックごとのチェックポイントを保ちましょう。どのチェックポイントを選ぶべきか知るためには、(epoch, train_loss, val_loss, val_acc, path) の CSV ログと組み合わせましょう。

pytorch
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 です。予想されたレイヤーだけがスキップされたことを確認するため、それらを検査しましょう。改名されたアーキテクチャへチェックポイントを適応させるのが、キーの改名です。バックボーンをロードした後は、純粋な特徴抽出のためにその重みを凍結するか、新しいヘッドよりはるかに小さい LR で学習しましょう。

pytorch
# 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 へのエクスポート

元のクラスなしで、LibTorch(C++)か Python でロードできる、自己完結したグラフを作るのが、TorchScript です。デプロイに理想的です。1 つの制御フローのパスを捕らえるのが、trace で、データ依存の制御フローを扱えるがタイプの注釈を必要とするのが、script です。ONNX Runtime、TensorRT、OpenVINO での推論のための、ONNX エクスポートです。可変のバッチサイズのためには、dynamic_axes を使いましょう。

pytorch
# 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'}})
11

CNN

Conv2d レイヤー

(out_channels, in_channels/groups, kH, kW) であるのが、Conv2d の weight の形状です。デフォルトのメモリレイアウトが、NCHW です。stride 1 のために空間サイズを保つのが、padding='same'(PyTorch 1.9+)です。depthwise にするのが、groups=in_channels です(MobileNet で使われます)。出力サイズの計算:(H + 2P - K) / S + 1 です。

pytorch
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 です。空間次元を 1x1 へ折りたたむのが、AdaptiveAvgPool2d(1) で、conv の特徴を Linear のヘッドへ供給するために使われる、標準の「global average pool」です。モダンなアーキテクチャでの学習可能なダウンサンプリングのためには、プーリングより strided conv を推奨しましょう。

pytorch
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) によるため、ある解像度で学習し別の解像度でテストできます。conv の後、活性化の前に来るのが、BatchNorm2d です。conv のカーネルは、padding=1 付きの 3x3 に保ちましょう(VGG スタイル)— パラメータ効率が良く、良く融合します。

pytorch
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))

特徴マップと受容野

各チャンネルが何を検出するか示すのが、特徴マップです。縁と色を見つけるのが、早いレイヤーで、テクスチャとパーツを見つけるのが、深いレイヤーです。forward を修正せずに活性を捕らえられるのが、register_forward_hook です。深さとプーリングと共に成長するのが、受容野です。大まかに言えば、(i,j)の出力ピクセルが依存するのが、そこを中心とするパッチで、そのレイヤーまでの stride とカーネルの合計のサイズです。

pytorch
# 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

(N, H, W)の上でチャンネルごとに正規化し、推論のための running EMA の統計を保つのが、BatchNorm2d です。効くのが、train()/eval() です。出力が決定的になるよう、eval が running 統計を使います。バッチ内で例を結合するのが、BatchNorm で、非常に小さいバッチでは壊れます。その場合は、GroupNorm か LayerNorm へ切り替えましょう。正しいマルチ GPU BN のためには、SyncBatchNorm が必要です。

pytorch
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 アーキテクチャ

事前学習済みの ImageNet 重み付きで、ResNet、EfficientNet、MobileNet、ViT などを公開するのが、torchvision.models です。最後の fc レイヤーの置き換えが、標準の転移学習の入口です。検出/セグメンテーションのためには、ヘッドを落とし conv の特徴を使いましょう。weights API(WeightsEnum)を確認しましょう — 古い pretrained=True のフラグが非推奨です。既知の受容野と FLOPs の予算を、各モデルが持ちます。あなたのレイテンシのターゲットに合うものを選びましょう。

pytorch
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)
12

RNN と LSTM

RNN レイヤー

入力が(batch, seq, feature)になるのが、batch_first=True です。ほとんどの NLP の慣例と一致し、なければ PyTorch が(seq, batch, feature)を使います。長いシーケンスで消失勾配に苦しむのが、素の RNN です。実際には LSTM か GRU を推奨しましょう。最後のレイヤーからの、タイムステップごとの隠れ状態を含むのが、out で、各レイヤーの最終状態を含むのが、h_n です。

pytorch
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 レイヤー

隠れ状態 h_n とセル状態 c_n の両方を返すのが、LSTM です。出力の特徴サイズが 2 倍になるのが、双方向です。分類のためには、各方向の最終的な隠れ状態を使いましょう(h_n[-2] が最後の forward レイヤーで、h_n[-1] が最後の backward レイヤーです)。スタックされたレイヤーの間にだけ適用されるのが、nn.LSTM の dropout で、入力には適用されません。必要なら、nn.Dropout で入力を包みましょう。

pytorch
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 レイヤー

セル状態のない(隠れ状態だけの)、3 でなく 2 ゲートであるのが、GRU です。そのため、パラメータがより少なく、LSTM よりわずかに速く学習します。ほとんどのタスクで似た性能を出すのが、経験的に、GRU と LSTM であり、小さい dataset の良いデフォルトが、GRU です。LSTM のように、スタックされたレイヤーの間にだけ適用されるのが、dropout です。

pytorch
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

Packed シーケンス

RNN の計算で、パディングトークンをスキップするのが、packing です。より速く、パッドのゼロによる隠れ状態の偏りを避けます。古い PyTorch では、シーケンスが長さの降順でソートされなければなりません。内部的にソートするのが(小さいオーバーヘッド付きで)、enforce_sorted=False です。パディングされたテンソルへ戻すのが、pad_packed_sequence です。バッチを動的にパディングする、カスタムの collate_fn と組み合わせましょう。

pytorch
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 です。パッドトークンがゼロ勾配を持つよう、nn.Embedding の padding_idx を使いましょう。CPU 上で動くため、pack_padded_sequence へ lengths.cpu() を渡しましょう。シーケンス全体を捉えるため、連結されるのが、両方向の最終的な隠れ状態です。長いシーケンスには、transformers が LSTM を上回りますが、より多くのデータと計算を必要とします。

pytorch
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)

シーケンスの生成(デコーダ)

一度に 1 ステップ実行し、前の出力トークンを条件とするのが、デコーダです。単一ステップの LSTM であるのが、LSTMCell です。ループを細かく制御するには、これを使いましょう。学習中に、次のステップでグラウンドトゥルースのトークンを供給するのが、teacher forcing です。モデル自身の予測を供給するより、はるかに速く収束します。推論では、前のステップの logits から、argmax(かサンプリング)を供給するよう切り替えましょう。

pytorch
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
13

Transformer

nn.MultiheadAttention

ヘッドの上で並行にスケールドドット積の attention を計算するのが、nn.MultiheadAttention です。NLP の慣例(batch、seq、dim)と一致するのが、batch_first です。因果的デコーディングのための attn_mask(下三角のマスク)と、パディングトークンを無視する key_padding_mask を使いましょう。attention 行列を返すのが、need_weights=True で、可視化とプロービングに有用です。

pytorch
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)

Transformer エンコーダ

残差と LayerNorm を持つ、self-attention + FFN のブロックが、TransformerEncoderLayer です。スクラッチからの学習に、より安定なのが、norm_first=True(pre-LN)で、ウォームアップを必要とするのが、(デフォルトの)post-LN です。nn.TransformerEncoder で N レイヤーをスタックしましょう。attention が pad の位置を無視するよう、src_key_padding_mask を渡しましょう。分類のためには、出力シーケンスを mean-pool し Linear のヘッドを供給しましょう。

pytorch
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)

位置エンコーディング

順列不変であるため、位置情報を必要とするのが、Transformers です。学習で見たものより長いシーケンスへ一般化するのが、正弦波のエンコーディングです。パラメータにせず pe を保存するのが、register_buffer です。.to(device) と共に動き、state_dict へ保存されます。機能するが、学習の長さを超えて外挿しないのが、学習された位置の埋め込み(nn.Parameter)です。

pytorch
import torch
import torch.nn as nn
import math

class PositionalEncoding(nn.Module):
    def __init__(self, d_model=512, max_len=5000, dropout=0.1):
        super().__init__()
        self.dropout = nn.Dropout(dropout)
        pe = torch.zeros(max_len, d_model)
        pos = torch.arange(0, max_len).unsqueeze(1).float()
        div = torch.exp(torch.arange(0, d_model, 2).float()
                        * (-math.log(10000.0) / d_model))
        pe[:, 0::2] = torch.sin(pos * div)
        pe[:, 1::2] = torch.cos(pos * div)
        self.register_buffer('pe', pe.unsqueeze(0))   # (1, max_len, d_model)

    def forward(self, x):
        x = x + self.pe[:, :x.size(1)]
        return self.dropout(x)

# usage
emb = nn.Embedding(vocab, 512)
pos = PositionalEncoding(512)
x = pos(emb(tokens))   # (batch, seq, 512)

フルの Transformer(Seq2Seq)

翻訳/要約のための、フルの encoder-decoder の transformer です。ターゲット上で因果的マスキングを使うのが(位置 t が <= t にしか attend できない)、デコーダで、エンコーダ出力への cross-attention が、それに加わります(memory)。attention がパッドトークンを無視するよう、ソースとターゲットの両方の key_padding_masks を渡しましょう。デコーダの出力を語彙の logits へ投影するのが、ヘッドで、ignore_index=0 付きの CrossEntropyLoss が、損失です。

pytorch
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)のブロック

残差を持つ pre-LN の self-attention + pre-LN の MLP であるのが、ViT のブロックです。本質的に、transformer のエンコーダレイヤーと同じです。strided の Conv2d(kernel=stride=patch_size)で画像をパッチ化し、その後、パッチをトークンとして扱うのが、Vision Transformers です。CLS トークンと位置の埋め込みを加えましょう。(output, weights)を返すのが、nn.MultiheadAttention で、weights をスキップするには、need_weights=False で unpack しましょう。

pytorch
import torch.nn as nn

class ViTBlock(nn.Module):
    def __init__(self, dim=768, heads=12, mlp=3072, dropout=0.1):
        super().__init__()
        self.norm1 = nn.LayerNorm(dim)
        self.attn = nn.MultiheadAttention(dim, heads, dropout=dropout, batch_first=True)
        self.norm2 = nn.LayerNorm(dim)
        self.mlp = nn.Sequential(
            nn.Linear(dim, mlp),
            nn.GELU(),
            nn.Dropout(dropout),
            nn.Linear(mlp, dim),
            nn.Dropout(dropout),
        )

    def forward(self, x):
        h = self.norm1(x)
        a, _ = self.attn(h, h, h, need_weights=False)
        x = x + a
        x = x + self.mlp(self.norm2(x))
        return x

# patchify: (B, 3, 224, 224) -> (B, 196, 768) via Conv2d(3, 768, 16, 16)

スクラッチからの Attention

スケールドドット積の attention:scores = QK^T / sqrt(d_k)、softmax、V との乗算です。分散を安定させ softmax が飽和しないのが、1/sqrt(d_k) です。softmax の前に -inf での masked_fill が、それらの位置をゼロにします。埋め込みを H ヘッドへ分割し、並行に attend し、連結するのが、multi-head attention です。正確にこれが nn.MultiheadAttention が行うことです。学習するため、または linear/flash attention のようなバリアントを加えるためだけに、スクラッチで書きましょう。

pytorch
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)
14

GPU 学習

デバイスの選択

CPU 専用のマシンがクラッシュしないよう、torch.cuda.is_available() 上で必ず分岐させましょう。device= 引数で、デバイス上に直接テンソルを作れます(CPU 上で作り動かすより速いです)。新しいテンソルのためのデフォルトのデバイスを設定するのが、torch.device のコンテキスト(PyTorch 2.x)です。Apple Silicon の GPU に対応するのが、MPS ですが、一部の CUDA の機能が欠けています。頼る前に、演算子の対応を確認しましょう。

pytorch
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'

モデルとデータの移動

その場でパラメータと buffer を動かすのが、model.to(device) です。DataLoader がディスクからストリーミングできるよう、学習ループの内側で入力テンソルを動かしましょう。ソーステンソルが pinned メモリにあるとき、CPU→GPU のコピーを計算とオーバーラップさせるのが、non_blocking=True です(DataLoader 上の pin_memory=True を設定)。任意の NumPy 操作の前に、.cpu() / .numpy() を — GPU テンソルが直接変換できません。

pytorch
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)

各 GPU 上でモデルを複製し、バッチを分割し、GPU 0 上に出力を集めるのが、DataParallel(DP)です。簡単ですが遅く不均衡です(集約と損失の計算を、GPU 0 が行います)。シングルプロセスであるため、GIL がスケーリングを制限します。本気のマルチ GPU 作業には、代わりに DistributedDataParallel を使うしましょう。2〜4 GPU での素早いプロトタイピングには、DP で構いません。

pytorch
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

GPU ごとに 1 プロセスを spawn し、それぞれが独自のモデルのレプリカを持ち、すべてのレプリカが同じ勾配を見るよう all-reduce されるのが、DDP(DistributedDataParallel)です。DataParallel よりはるかに速くスケーラブルです。プロセスを始めるのが、torchrun(か torch.distributed.launch)です。各エポックがリシャッフルされるよう、必ず sampler.set_epoch(epoch) を呼びましょう。詳細は、分散学習のセクションを。

pytorch
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()

メモリの管理

キャッシュされたメモリを OS へ返すのが、empty_cache() ですが、使用中のテンソルを解放しません。大きなスパイクの後に呼び、ホットなループの中では呼ばないこと。使用中のテンソルが、memory_allocated で、caching アロケータのプールが、memory_reserved です。OOM を減らす方法:バッチサイズを下げる、混合精度、gradient checkpointing、勾配蓄積。可変形状のワークロードのための断片化を減らすのが、expandable_segments:True です。もはや不要なテンソル(リストにログされた損失など)への参照の保持を避けましょう。

pytorch
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 とパフォーマンス

最初の forward で cuDNN がアルゴリズムをプロファイルし最速をキャッシュするのが、cudnn.benchmark=True です。入力の形状が固定されているとき(典型的な CNN)には素晴らしく、形状が毎ステップ変わるなら(可変長の RNN)有害です。Ampere+ では、19 ビットの仮数を使い、精度の損失を最小にして約 3 倍の matmul の高速化を与えるのが、TF32 です。厳密な fp32 の再現性が必要でない限り、有効化しましょう。非決定的なアルゴリズムを無効化するのが、deterministic モードです。

pytorch
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
15

Transform と前処理

よくある Transform

PIL 画像(0〜255)を [0,1] の float テンソルへ変え、HWC -> CHW と並べ替えるのが、ToTensor です。ImageNet の統計を使い、チャンネルごとに標準化するのが、Normalize です(事前学習済みモデルの事実上の標準です — バックボーンが学習された統計に必ず合わせましょう)。Dataset 内で transform を適用し、worker プロセス上で動くようにしましょう。GPU が、CPU の前処理を待つことは決してありません。

pytorch
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)

データ拡張

多様な入力を示すことで、モデルを正則化するのが、データ拡張です。クラシックな ImageNet の拡張が、RandomResizedCrop + flip です。幾何に影響せず色を変えるのが、ColorJitter です。ランダムな大きさでランダムな操作をサンプリングするのが、TrivialAugmentWide と RandAugment です。強く、単純で、驚くほど効果的です。指標が安定するよう、検証のためには非拡張の transform を別に使いましょう。

pytorch
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)

新しい API であるのが、Transforms v2(torchvision 0.17+)です。より速く、JIT スクリプト可能で、決定的に重要なのは、image/mask/bbox 上で共同で機能するため、検出とセグメンテーションの拡張が一貫して留まることです。ToTensor を置き換えるのが、ToDtype + scale=True です。よりきれいなダウンサンプリングのため、resize 操作には必ず antialias=True を渡しましょう。レガシーの transforms モジュールが依然機能しますが、新しい機能は得られません。

pytorch
from torchvision.transforms import v2

transform = v2.Compose([
    v2.RandomResizedCrop(224, antialias=True),
    v2.RandomHorizontalFlip(),
    v2.ToDtype(torch.float32, scale=True),   # scale to [0,1]
    v2.Normalize(mean=[0.485, 0.456, 0.406],
                 std=[0.229, 0.224, 0.225]),
])

# v2 works on images, videos, masks, and bounding boxes together
imgs, masks = transform(imgs, masks)
imgs, bboxes, labels = transform(imgs, bboxes, labels)

# supports more ops and JIT scripting
transform = v2.RandomChoice([
    v2.RandomHorizontalFlip(),
    v2.RandomVerticalFlip(),
])

カスタム Transform

テンソル(か PIL 画像)を受け取り 1 つを返す、任意の呼び出し可能オブジェクトであるのが、カスタム transform です。transforms.Compose で構成しましょう。float 上で動くよう、ToTensor の後にノイズを適用しましょう。各呼び出しが新しい決定を得るよう、サンプルごとのランダム性のためには、__call__ の内側で torch.rand を使いましょう。forward をオーバーライドすることで、結合した(image, label)の入力を扱う transform クラスを書けるのが、Transforms v2 です。

pytorch
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/vocab をモデルのチェックポイントと共に保存しましょう。

pytorch
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
16

カスタム Dataset

Dataset クラス

__len__ と __getitem__ だけが必要なのが、Dataset です。何百万のパスを安価にメモリに保持できるよう、__getitem__ の内側でファイルを遅延的に開きましょう。(input, target) のタプルを返し、DataLoader のデフォルトの collate にバッチへスタックさせましょう。worker プロセス上で動くため、__getitem__ は安価で副作用フリーに保ちましょう。共有された状態を書き換えないこと。

pytorch
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]

Image Folder Dataset

クラスごとに 1 サブディレクトリを期待し、フォルダ名からラベルを推論するのが、ImageFolder です。画像分類を始める最も速い方法です。名前を整数ラベルへマッピングするのが、class_to_idx で、train/val/test をまたいで一貫するよう、同じマッピングを再利用しましょう。基礎のデータを共有する Subset を返すのが、random_split です。そのため、メモリは複製されません。

pytorch
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 でパディングしましょう。そうすれば、各バッチが自分の最大長までしかパディングしません。RNN で、パッドの位置をスキップするのが、その後の pack_padded_sequence です。transformer の学習のためには、attention がパッドトークンを無視するよう、attention マスクを返しましょう。

pytorch
from torch.utils.data import Dataset
import torch

class TextDataset(Dataset):
    def __init__(self, texts, labels, vocab, max_len=128):
        self.texts = texts
        self.labels = labels
        self.vocab = vocab
        self.max_len = max_len

    def __len__(self):
        return len(self.texts)

    def __getitem__(self, idx):
        tokens = self.texts[idx].split()[:self.max_len]
        ids = [self.vocab[t] for t in tokens]
        ids += [0] * (self.max_len - len(ids))   # pad
        return torch.tensor(ids), self.labels[idx]

# variable length: use custom collate
def text_collate(batch):
    ids, labels = zip(*batch)
    lens = torch.tensor([len(x) for x in ids])
    padded = torch.nn.utils.rnn.pad_sequence(ids, batch_first=True)
    return padded, lens, torch.tensor(labels)

Iterable Dataset

ランダムアクセスの代わりにデータをストリーミングするのが、IterableDataset です。巨大なかストリーミングのソース(ログ、データベース、S3)には不可欠です。すべての worker が同じデータを読むのを避けるため、worker が明示的にストリームを分割しなければなりません(itertools.islice)。直接サポートされないのが、shuffle です。代わりに、サンプルをバッファし、バッファ内でシャッフルしましょう。長さによりインデックスするには大きすぎる dataset に、これを。

pytorch
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

データが RAM に収まるときの最速の経路が、TensorDataset です。デフォルトの collate がバッチへスタックする、テンソルのタプルを返します。データセットを端から端までチェーンするのが、ConcatDataset です。ラベル付きと疑似ラベル付きデータの組み合わせに有用です。インデックスリスト付きで dataset を包むのが、Subset で、データをコピーせず random_split とカスタムスライシングを可能にします。

pytorch
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])
17

LR スケジューラ

StepLR と MultiStepLR

最も単純なスケジューラが、StepLR と MultiStepLR です。固定のエポックで LR を gamma 倍します。予測可能であり、スクラッチから学習する CNN で良く機能します。バッチループの内側でなく、エポックの学習の後に、必ず scheduler.step() を呼びましょう。ロギングのための現在の LR を示すのが、get_last_lr() です。注意:エポックを数えるのが、step_size であり、ステップではありません。

pytorch
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 を滑らかに減衰させるのが、cosine annealing です。ステップ decay より、しばしば小さな精度の向上が得られます。各サイクルの開始時に、LR をベース値へリセットするのが、ウォーム再開(SGDR)で、モデルがシャープな極小から逃げるのを助け得ます。各サイクルが 2 倍の長さになるのが、T_mult=2 です。画像分類と事前学習のためのモダンなデフォルトが、cosine スケジューラです。

pytorch
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

指標を監視し、改善が止まったとき LR を減らすのが、ReduceLROnPlateau です。正しいスケジュールが事前に分からないときに完璧です。損失には mode='min' を、精度には「max」を。減らす前に、N エポックの改善なしを待つのが、patience=N です。他のスケジューラと違い、step(metric) へ指標を渡さなければなりません。patience が多すぎると過剰適合しやすいため、早期停止と組み合わせましょう。

pytorch
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

ウォームアップし、ピークに達し、その後 anneal するのが、OneCycleLR(super-convergence)です。与えられた精度へモデルを学習する最も速い方法であることがしばしばあります。バッチごとに step するため、total_steps = epochs * batches_per_epoch を設定しましょう。ステップの 30% をウォームアップに使うのが、pct_start=0.3 です。ベースと最大の LR の間で振動するのが、CyclicLR で、良い LR の発見(LR レンジテスト)に有用です。

pytorch
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)

ウォームアップ + Decay

Adam の第 2 モーメントの推定が悪条件であるとき、最初のステップを安定させるのが、ウォームアップです。transformer の学習には不可欠です。任意の decay スケジュールと、ウォームアップをきれいに組み合わせるのが、LinearLR + SequentialLR です。ステップ数の関数経由で完全な制御を与えるのが、LambdaLR で — 最も柔軟なスケジューラです。HuggingFace 風のスケジュールには、transformers.get_cosine_schedule_with_warmup を見ましょう。

pytorch
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)

カスタムスケジューラ

ベースの LR を lambda(step) で掛けるのが、LambdaLR です。カスタムスケジュールを実装する最も柔軟な方法です。グループごとのスケジュールのためには、lambda のリストを(param_group ごとに 1 つ)渡しましょう。例えば、バイアスでなく重みを減衰する、または転移学習でバックボーンとヘッドに異なるスケジュールを使う、です。毎ステップ動くため、lambda は安価でなければなりません。可変状態を取り込む Python クロージャを避け、純粋に保ちましょう。

pytorch
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()
18

転移学習

事前学習済みモデル

WeightsEnum の API を必ず使いましょう(最良の利用可能なものを選ぶのが、DEFAULT)。古い pretrained=True が非推奨です。モデルが学習された正確な前処理を返す .transforms() を、各 weights オブジェクトが公開します。入力が一致するよう、これを使いましょう。ImageNet の 1000 クラスを出力するのが、分類のヘッドです。あなたのタスクのために置き換えましょう。

pytorch
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])

特徴抽出

バックボーンを凍結し新しいヘッドだけを学習するのが、特徴抽出です。最も速い転移学習のベースラインで、小さい dataset 上での数分の学習で、高い精度にしばしば届きます。バックボーンが凍結されているため、特徴を一度事前計算し、その上に安価な分類器を学習でき、莫大な計算が節約されます。ヘッドを学習している間も、BatchNorm が running 統計を使うよう、model.eval() を設定しましょう。

pytorch
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 を使いましょう:早いレイヤー(一般的な特徴)には小さく、ヘッド(タスク固有)には大きくです。より安定なのが、(ヘッドを先に学習し、その後深いレイヤーを unfreeze する)漸進的な unfreeze です。特に小さい dataset 上では、一度にすべてを学習するより、です。

pytorch
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.

レイヤーの凍結と unfreeze

autograd がパラメータの追跡・更新を止めるのが、requires_grad_(False) です。しかし、勾配が、凍結されたレイヤーを通し、下流の学習可能なものへ依然流れます。選択的な凍結のためには、named_parameters() でレイヤー名によりフィルタしましょう。うっかりすべてを凍結しないよう(よくあるサイレントバグ)、学習可能なパラメータ数を必ずログしましょう。unfreeze 後には、新しく学習可能なパラメータを拾うよう、オプティマイザーを再作成しましょう。

pytorch
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

分類器の置き換え

異なる属性に、分類器を持つのが、各アーキテクチャです。.fc を使うのが ResNet で、.classifier[1] を使うのが EfficientNet、.heads.head を使うのが ViT です。requires_grad=True で新しいヘッドを設定すれば、最初はそれだけが学習します。バックボーンを共有する複数の Linear レイヤーで、ヘッドを置き換えるのが、マルチタスク学習です。元のヘッドをきれいに落とすのに便利な no-op モジュールが、nn.Identity() です。

pytorch
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)
19

可視化

TensorBoard のセットアップ

イベントをログディレクトリへストリーミングするのが、SummaryWriter です。閲覧するには、`tensorboard --logdir=runs` で TensorBoard を起動しましょう。ステップ対単一の指標をプロットするのが、add_scalar で、1 つのチャート上に複数の曲線を重ねるのが、add_scalars です。同じ UI で実行を比較するため、実験ごとに(runs/exp1、runs/exp2)別々のサブディレクトリを使いましょう。最後のイベントが書かれるよう、末尾には writer.close() で flush しましょう。

pytorch
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

グラフとヒストグラムのロギング

Graphs のタブでモデルのアーキテクチャを可視化するのが、add_graph です。forward フローのデバッグに有用です。時間をかけた重みか勾配の分布を示すのが、add_histogram です。健康的な学習が、勾配を非ゼロに、重みをおおよそ釣り鐘形に保ちます。勾配ヒストグラムの急なスパイクが、不安定性を示唆します。遅いのが、毎ステップのロギングなので、N ステップごとにサンプリングしましょう。

pytorch
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()

画像のロギング

CHW のテンソルを受け付けるのが、add_image です。表示可能な範囲へスケールするよう、normalize=True 付きで、バッチを 1 つの画像へタイル化するのが、make_grid です。matplotlib の Figure を直接ログするのが、add_figure です。素早い視覚 QA のために、予測を重ねるのが、(torchvision.utils の)draw_segmentation_masks と draw_bounding_boxes です。スカラーの指標だけでなく、定性的な進捗を監視するため、エポックごとにいくつかの検証サンプルをログしましょう。

pytorch
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 のグラフ

単一の forward パスの autograd のグラフを描くのが、torchviz です。形状の不一致、意図しない分岐、切り離されたテンソルのデバッグに最適です。各ノードが op で、テンソルのフローを示すのが、辺です。backward のために保たれた中間テンソルを(メモリ使用量を決めるものです)表示するのも、show_saved=True です。インストールは、`pip install torchviz` とシステム PATH 上の Graphviz です。

pytorch
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 です。

pytorch
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)
20

分散学習

DDP のセットアップ

標準のマルチ GPU 学習のパターンが、DDP(DistributedDataParallel)です。GPU ごとに 1 プロセスで、すべてのレプリカが同期し続けるよう、勾配が all-reduce されます。NVIDIA GPU 上で最も速いバックエンドが、nccl です。あなたのために env 変数(RANK、WORLD_SIZE、LOCAL_RANK)を設定するのが、torchrun です。ジョブがきれいに exit するよう、末尾には必ず dist.destroy_process_group() を呼びましょう。フルのループは、gpu-training のセクションを。

pytorch
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

プロセスをまたいで dataset をシャードするのが、DistributedSampler です。各 GPU が各バッチの一意な部分集合を見るように(実効的なバッチ = batch_size * world_size)、です。毎エポック、sampler.set_epoch(epoch) を MUST で呼ぶこと — なければ、毎エポックが同じシャッフルを使い、モデルが同じ順序を見ます。サンプラーを使うとき、DataLoader へ shuffle=True を渡さないこと。順序を扱うのが、サンプラーです。

pytorch
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
        ...

マルチノードの起動

GPU ごとに 1 プロセスを起動し TCP 経由で結ぶのが、torchrun です。マルチノードでは、同じ master_addr と一意の node_rank で、各ノード上で torchrun を実行しましょう。ノードが互いを見つけ、エラスティックな再起動をサポートするのが、(--rdzv_endpoint の)ランデブーのエンドポイントです。ファイアウォール上で master_port が開いていること、すべてのノードが master_addr に届くことを確認しましょう。良いスケーリングのためには、NCCL が高帯域の相互接続(InfiniBand/NVLink)も必要です。

pytorch
# 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

勾配の同期

backward の計算と勾配の all-reduce をオーバーラップさせるのが、DDP です。よくスケールする理由です。一部のパラメータが毎ステップ勾配を得ないとき(条件分岐など)、必要なのが、find_unused_parameters=True ですが、オーバーヘッドがかかるため、できれば避けましょう。1 ステップの同期をスキップするのが、model.no_sync() です。勾配蓄積と共に有用であり、毎ミニバッチでなく、実効的なバッチごとに一度だけ同期します。

pytorch
# 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 で包む前に、すべてのレプリカが同じ重みから始まるよう、すべての rank 上でチェックポイントをロードしましょう。

pytorch
# 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)

パラメータ、勾配、オプティマイザーの状態を GPU をまたいでシャードするのが、FSDP です。そのため、1 GPU には大きすぎるモデルが、いくつかをまたいで学習できます。DDP(フルのレプリカを保つ)と違い、forward/backward の間、必要に応じて FSDP がシャードを集めます。モデルが 1 GPU のメモリに収まらないとき、これを使いましょう。保存が厄介です:rank 0 がフルモデルをマテリアライズするよう、FULL_STATE_DICT モードで state_dict の収集を包みましょう。非常に大きいモデルを学習させられるのが、混合精度 + FSDP + activation checkpointing です。

pytorch
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')

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.