---
tags: [AI, PyTorch, 深度学习, 工程实践]
阶段: 04-深度学习核心
难度: ★★☆
created: 2026-10-18
related: "[[反向传播详解]], [[神经网络与前向传播]], [[正则化与调参]], [[数据增广]]"
---

# PyTorch实战入门

## 定义

**PyTorch** 是以张量为基本数据结构、以动态计算图实现反向模式自动微分、以 `nn.Module` 组织参数、以 `Dataset`/`DataLoader` 组织样本的深度学习框架；一次训练由「数据加载 → 前向 → 损失 → 反向 → 更新」五步在多个 epoch 上重复构成。

本篇符号与术语：

- 张量（Tensor）：带 dtype、shape、stride 与 device 的多维数组，是框架中所有运算的输入与输出。
- dtype：元素类型，默认浮点为 `torch.float32`，整型默认为 `torch.int64`。
- device：张量所在的存储设备，`cpu` 或 `cuda:N`；同一运算的所有输入必须在同一设备上。
- stride：沿每个维度移动一个下标所跨过的元素个数，决定张量的内存布局。
- 视图（view）：与另一张量共享存储、只改变 shape 或 stride 的张量；修改视图会修改原张量。
- 自动微分（autograd）：记录张量上的运算、在调用 `backward()` 时按拓扑逆序计算梯度的机制，见 [[反向传播详解]]。
- 叶子张量（leaf tensor）：由用户创建、不是运算结果的张量；只有叶子张量的 `.grad` 会被自动填充。
- `grad_fn`：非叶子张量上记录其产生运算的节点，用于构造反向图。
- `nn.Module`：参数与子模块的容器，负责参数的注册、遍历、模式切换与序列化。
- `Parameter`：被标记为需要优化的张量，赋值给 `Module` 属性时自动注册。
- buffer：需要随模型保存但不参与优化的张量，如 BN 的 `running_mean`。
- `state_dict`：从参数名到张量的有序字典，是模型持久化的标准格式。
- `Dataset`：提供 `__len__` 与 `__getitem__` 的对象，按索引返回一个样本。
- `DataLoader`：在 `Dataset` 之上提供批化、打乱、多进程加载与内存锁定的迭代器。
- `collate_fn`：把一个批的样本列表合并为张量的函数，默认为 `torch.stack`。
- 混合精度（AMP）：前向与部分反向使用 `float16` 或 `bfloat16`、参数更新仍用 `float32` 的训练方式。
- `autocast`：按算子白名单自动选择低精度的上下文管理器。
- `GradScaler`：对损失做动态缩放、避免 `float16` 梯度下溢的辅助器。

## 为什么重要

- 公式与实现之间存在一层工程约定，这层约定决定实验能否复现。同一个损失函数，若忘记 `zero_grad`、把 `scheduler.step()` 放错位置、或在验证时忘记 `eval()`，得到的结果与论文相差数个千分点，而错误不会抛异常。
- 训练循环是后续所有内容的载体。[[卷积神经网络CNN]] 替换的是模型，[[循环神经网络RNN]] 替换的是输入组织方式，Transformer 替换的是子层结构，五步循环本身不变；不理解循环的每一步在做什么，就无法判断改动影响的是数据、模型还是优化。
- 显存与吞吐由工程细节决定。批大小、`num_workers`、`pin_memory`、混合精度、梯度累积共同决定单步时间与显存峰值；这些量在 [[分布式训练与部署]] 中被进一步放大。
- 在全书中的位置：前置为 [[反向传播详解]]（`backward()` 的数学含义）、[[神经网络与前向传播]]（层与初始化）、[[正则化与调参]]（模式切换与早停）、[[数据增广]]（`transforms` 的位置）；后续为 [[卷积神经网络CNN]]、[[循环神经网络RNN]]、[[Transformer架构详解]] 与 [[从零实现小型GPT指南]]。
- 对应能力目标：懂原理对应「说明 `backward()` 与计算图的关系、`eval()` 改变了什么」；能复现对应「独立写出完整训练与评估循环」；会评估对应「用梯度范数、小批量过拟合与形状检查定位错误」。

## 原理与推导

### 1. 张量：创建、dtype 与 device

张量由存储（一维连续内存）、shape 与 stride 三元组确定。`torch.tensor(data)` 复制数据并推断 dtype；`torch.as_tensor(data)` 在可能时共享内存；`torch.Tensor(...)` 是历史构造函数，默认 `float32` 且对形状参数的解释与 `torch.tensor` 不同，新代码不应使用。

```python
import torch

a = torch.tensor([1.0, 2.0])            # float32，复制
b = torch.zeros(2, 3)                    # float32，全零
c = torch.arange(6).reshape(2, 3)        # int64
d = torch.arange(6, dtype=torch.float64) # 显式指定 dtype
print(a.dtype, c.dtype, d.dtype)         # float32 int64 float64
print(c.device)                          # cpu
```

dtype 决定精度与显存。`float32` 占 4 字节，`float16` 与 `bfloat16` 占 2 字节，`float64` 占 8 字节；`int64` 用于索引与标签，`bool` 用于掩码。混合 dtype 的算术会按类型提升规则转换，`float32` 与 `float64` 相加得到 `float64`，整型与浮点相加得到浮点；提升会静默复制数据，在循环中反复发生会显著降低速度。

device 决定运算位置。CPU 与 GPU 之间不能直接运算，必须先 `.to(device)`；`.to()` 在 dtype 与 device 都不变时返回自身，不复制。把模型与数据都移到同一设备的惯用写法是

```python
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)
x = x.to(device, non_blocking=True)   # 配合 pin_memory 时可异步拷贝
```

### 2. view、reshape 与 permute

`view` 要求新形状与当前 stride 兼容，即不复制内存就能重新解释下标；不满足时抛出 `RuntimeError: view size is not compatible with input tensor's size and stride`。`reshape` 先尝试 `view`，失败时复制一份连续内存再变形。`permute` 只重排维度并相应交换 stride，总是返回视图，不复制。

```python
x = torch.arange(12).reshape(3, 4)
y = x.t()                       # 转置，视图
print(x.stride(), y.stride())   # (4, 1) (1, 4)
print(y.is_contiguous())        # False
print(y.reshape(-1))            # 触发复制，按行优先展开
```

预期输出为 `[0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11]`。原因是 `y` 的第 0 行是 `x` 的第 0 列，逐行展开即按列读取 `x`。

三者的选择依据：需要保证零拷贝时用 `view`，并在失败时检查前面的 `permute`、`transpose`、切片；不确定布局时用 `reshape`，接受可能的复制；只是在维度间搬移数据时用 `permute`，随后若要做 `view` 或送入要求连续内存的算子，先调用 `.contiguous()`。把 `permute` 的结果直接 `view` 是最常见的形状错误来源，因为报错信息指向 `view`，而根因在更早的 `permute`。

### 3. 广播

广播规则有三条：从尾部对齐维度；每一维的大小相等，或其中一个为 1，或其中之一缺失；结果维度取两者中较大的那个。广播不复制数据，只在计算时按 stride 为 0 的方式复用内存。

```python
a = torch.arange(6).reshape(2, 3)   # (2, 3)
b = torch.arange(3)                 # (3,) 视为 (1, 3)
c = torch.arange(2).reshape(2, 1)   # (2, 1)
print((a + b).shape)                # (2, 3)
print((a + c).shape)                # (2, 3)
print((a + b + c).shape)            # (2, 3)
```

形状不兼容时抛出错误，例如 `(2, 3)` 与 `(2,)` 相加：尾部对齐后 `3` 与 `2` 既不相等也不含 1，无法广播。调试时先打印两个张量的 `shape`，再按上述三条规则手工对齐，通常可以在一次阅读内定位问题。

### 4. autograd：记录、反向与梯度累加

前向时每个参与运算的张量若 `requires_grad=True`，其结果带 `grad_fn`，构成有向无环图。`loss.backward()` 从标量出发按拓扑逆序调用每个 `grad_fn` 的 `backward`，把梯度累加到叶子张量的 `.grad` 上。标量要求来自反向模式只对 $m=1$ 的情形一次遍历得到全部梯度，见 [[反向传播详解]]。

```python
w = torch.tensor([1.0, 2.0], requires_grad=True)
for _ in range(2):
    loss = (w ** 2).sum()      # 每轮重建计算图
    loss.backward()
    print(w.grad)              # 第一轮 [2., 4.]，第二轮 [4., 8.]
```

第二轮的梯度是两轮之和，因为 `.grad` 是累加而不是覆盖。训练循环必须在每次反向之前清零，否则等效学习率随步数增长。`zero_grad(set_to_none=True)` 把 `.grad` 置为 `None` 而不是零张量，省去一次写显存，是当前推荐的写法。

`detach()` 返回一个与原张量共享存储、但 `requires_grad=False` 的新张量，用于切断梯度；`torch.no_grad()` 在整个上下文内不记录运算，用于推理与参数更新。二者的区别：`detach` 只作用于被调用的张量，返回值已脱离计算图，基于它的后续运算默认不再被记录；`no_grad` 作用于上下文内的全部运算，且不改变已有张量的 `requires_grad` 属性。评估时必须用 `no_grad`，否则中间激活全部保留，显存随批大小线性增长。

### 5. nn.Module 与参数注册

`Module` 通过 `__setattr__` 拦截属性赋值：赋值为 `nn.Parameter` 时注册为参数，赋值为 `Module` 时注册为子模块，赋值为普通张量时不注册。需要保存但不优化的张量用 `register_buffer` 注册，它会出现在 `state_dict` 中，并随 `.to(device)` 一起迁移。

```python
import torch.nn as nn

class Block(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(4, 4)
        self.register_buffer("scale", torch.ones(4))

block = Block()
print(dict(block.named_parameters()).keys())   # fc.weight, fc.bias
print(dict(block.named_buffers()).keys())      # scale
print(block.state_dict().keys())               # fc.weight, fc.bias, scale
```

`model.parameters()` 递归遍历全部子模块并去重，`model.named_parameters()` 额外给出参数名，按名字分组是设置不同学习率与权重衰减的标准做法。`Module.train()` 与 `Module.eval()` 只修改各子模块的 `training` 标志，不改变参数；`Dropout` 与 `BatchNorm` 读取该标志决定行为，自定义层若在训练与推理时行为不同，必须实现对应的分支。

### 6. Dataset 与 DataLoader

`Dataset` 的职责是按索引返回一个样本，`DataLoader` 的职责是把样本组成批。二者的分工使数据读取与批处理可以独立替换。`num_workers>0` 时每个 worker 是独立进程，各自持有一份数据集副本；主进程只负责收集批。因此数据集的初始化开销与内存占用随 worker 数增加，而变换与解码的耗时可被并行掩盖。

```python
from torch.utils.data import Dataset, DataLoader

class ToyDataset(Dataset):
    def __init__(self, n=10):
        self.x = torch.randn(n, 5)
        self.y = torch.randint(0, 2, (n,))

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

    def __getitem__(self, i):
        return self.x[i], self.y[i]

def collate(batch):
    xs, ys = zip(*batch)
    return torch.stack(xs), torch.stack(ys)

ld = DataLoader(ToyDataset(), batch_size=4, shuffle=True,
                collate_fn=collate, num_workers=0)
xb, yb = next(iter(ld))
print(xb.shape, yb.shape)   # torch.Size([4, 5]) torch.Size([4])
```

`collate_fn` 在默认实现中无法处理变长序列，因为 `torch.stack` 要求形状一致。变长序列的标准做法是在 `collate_fn` 中补齐：

```python
def pad_collate(batch):
    seqs, labels = zip(*batch)
    lengths = torch.tensor([len(s) for s in seqs])
    padded = nn.utils.rnn.pad_sequence(seqs, batch_first=True)
    return padded, lengths, torch.stack(labels)
```

补齐后仍需把 `lengths` 传给模型或损失，用于屏蔽填充位置；只补齐而不屏蔽，损失会把填充符当作有效标签，这是序列任务最常见的静默错误。

`num_workers` 的选择依据是数据预处理耗时与 CPU 核数：预处理接近零时设为 0 可以避免进程开销；解码与增广耗时时逐步增大，直到 GPU 利用率不再上升。`pin_memory=True` 把批放入页锁定内存，使主机到设备的拷贝可以异步进行，只在使用 GPU 时有意义。`persistent_workers=True` 避免每个 epoch 重新创建进程，适合小数据集与多轮训练。随机性方面，`DataLoader` 为每个 worker 派生种子，`torch` 的随机数在 worker 内可复现，但 `random` 与 `numpy` 的随机数需要数据集自行按 worker 初始化。

### 7. 训练循环的标准结构

一次参数更新由五步构成：清零梯度、前向、计算损失、反向、更新。顺序不可交换：先反向再清零会把本步梯度丢掉；先更新再反向会用旧梯度更新。设一个批为 $\{(\mathbf{x}_i,y_i)\}_{i=1}^{B}$，交叉熵损失与参数更新写作

$$L(\boldsymbol\theta)=-\frac{1}{B}\sum_{i=1}^{B}\log p_{\boldsymbol\theta}(y_i\mid\mathbf{x}_i),\qquad \boldsymbol\theta\leftarrow\boldsymbol\theta-\eta\,\nabla_{\boldsymbol\theta}L(\boldsymbol\theta)$$

其中 $p_{\boldsymbol\theta}(y_i\mid\mathbf{x}_i)$ 是模型输出经 softmax 后第 $y_i$ 类的概率，$\eta$ 是学习率；下面代码的五步就是上式的机械化。

```python
for epoch in range(epochs):
    model.train()
    for x, y in train_ld:
        x = x.to(device, non_blocking=True)
        y = y.to(device, non_blocking=True)
        opt.zero_grad(set_to_none=True)   # 1. 清零
        logits = model(x)                 # 2. 前向
        loss = loss_fn(logits, y)         # 3. 损失
        loss.backward()                   # 4. 反向
        opt.step()                        # 5. 更新
```

学习率调度的位置取决于调度器类型。`StepLR`、`MultiStepLR`、`CosineAnnealingLR` 的语义是「每个 epoch 调用一次」还是「每个 step 调用一次」由使用者决定，但同一次训练中必须一致：按 step 调用时 `T_max` 应设为总步数，按 epoch 调用时设为总轮数。`ReduceLROnPlateau` 需要传入验证指标 `scheduler.step(val_loss)`，放在验证之后。PyTorch 1.1 之后要求 `optimizer.step()` 在 `scheduler.step()` 之前，否则会给出警告并可能跳过一个学习率值。

梯度裁剪在反向之后、更新之前：`torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm)` 按全局范数等比缩放全部梯度。它在 [[循环神经网络RNN]] 与 Transformer 训练中是常规项，因为这些结构的梯度范数对序列长度与初始化敏感。

### 8. 验证与指标

验证必须满足三个条件：`model.eval()`、`torch.no_grad()`、使用与训练不同的批组织方式（通常不打乱）。指标应按样本累计，而不是对批指标取平均，否则最后一个小批的权重被高估。

```python
@torch.no_grad()
def evaluate(model, loader, device, loss_fn):
    model.eval()
    loss_sum, correct, total = 0.0, 0, 0
    for x, y in loader:
        x, y = x.to(device), y.to(device)
        logits = model(x)
        loss_sum += loss_fn(logits, y).item() * y.size(0)   # 乘回批大小
        correct += (logits.argmax(dim=1) == y).sum().item()
        total += y.size(0)
    return loss_sum / total, correct / total
```

损失用 `reduction="sum"` 或返回均值后乘回批大小，两种写法在批大小不一致时都正确；直接对批均值取平均在最后一个批较小时产生偏差。多分类的宏平均 F1、每类召回需要混淆矩阵，应调用 `torchmetrics` 或手工累计，不能从批均值恢复。

### 9. 保存与加载

推荐保存 `state_dict` 而不是整个模型对象。保存整个对象会 pickle 类路径，重构模块名或移动文件后无法加载，且在加载不可信文件时执行任意代码。

```python
torch.save({"model": model.state_dict(),
            "optim": opt.state_dict(),
            "sched": sched.state_dict(),
            "epoch": epoch,
            "best": best_acc}, "ckpt.pt")

ckpt = torch.load("ckpt.pt", map_location="cpu", weights_only=True)
model.load_state_dict(ckpt["model"])        # strict=True，键必须完全一致
opt.load_state_dict(ckpt["optim"])
start_epoch = ckpt["epoch"] + 1
```

`load_state_dict` 默认 `strict=True`，多余的键与缺失的键都会报错；迁移学习时用 `strict=False` 并检查返回的 `missing_keys` 与 `unexpected_keys`，确认被忽略的确实是分类头。`map_location` 把张量映射到指定设备，从 GPU 保存的检查点加载到 CPU 时必须使用。断点续训需要同时恢复优化器状态与调度器状态，只恢复模型参数会使动量与学习率回到初始值，曲线出现台阶。

### 10. GPU 与混合精度

`float16` 的表示范围约为 $6\times10^{4}$，小于 `float32` 的 $3\times10^{38}$；小梯度在 `float16` 下会下溢为零。混合精度同时利用低精度的速度与高精度的范围：`autocast` 按算子白名单把矩阵乘、卷积等计算密集型算子转到 `float16`，把归约、softmax、损失等对范围敏感的算子保留为 `float32`；`GradScaler` 在反向之前把损失乘以一个动态缩放因子，使梯度落入 `float16` 的可表示范围，更新之前再除回。

```python
scaler = torch.amp.GradScaler("cuda")       # PyTorch 2.3 及以上
for x, y in train_ld:
    opt.zero_grad(set_to_none=True)
    with torch.autocast(device_type="cuda", dtype=torch.float16):
        loss = loss_fn(model(x), y)
    scaler.scale(loss).backward()
    scaler.unscale_(opt)                     # 先反缩放，再裁剪
    torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
    scaler.step(opt)                         # 内部检查 inf/nan，异常时跳过本步
    scaler.update()
```

顺序上的两个约束：裁剪必须在 `unscale_` 之后，否则裁剪的是被放大的梯度，阈值失去意义；`scaler.step` 会检查梯度是否出现 `inf` 或 `nan`，出现时跳过该步并降低缩放因子，因此不能在它之前手动 `opt.step()`。`bfloat16` 的指数范围与 `float32` 相同，不需要缩放，`autocast(dtype=torch.bfloat16)` 可省略 `GradScaler`，在 Ampere 及更新的 GPU 上通常更稳定。

### 11. 常见调试手段

- 形状检查：在 `forward` 中打印关键张量的 `shape`，或在每个子层后加断言；形状错误占实现错误的大多数。
- 梯度范数：每若干步计算 $\sqrt{\sum_p\|\nabla_p\|_2^{2}}$，范数在前几十步应为 $10^{-2}$ 到 $10^{0}$ 量级；持续增大到 $10^{3}$ 以上说明发散，恒为零说明梯度被切断。
- 小批量过拟合：取 1 到 2 个批反复训练数百步，损失应降到接近零。若不能，问题在模型、损失或标签，而不是超参数。
- 异常检测：`torch.autograd.set_detect_anomaly(True)` 会在反向出现 `nan` 时定位到具体算子，代价是速度下降数倍，只在排查时开启。
- 学习率检查：打印 `opt.param_groups[0]["lr"]`，确认调度器按预期改变它；学习率被错误地乘以批大小或衰减到零，是最常见的「模型不学习」原因。
- 参数量核对：`sum(p.numel() for p in model.parameters())` 与论文或设计值对照，参数量差一个数量级通常意味着层写错或参数未注册。

## 关键直觉

> [!tip] 机制性表述
> 一次训练是四个对象按固定顺序的调度：`DataLoader` 产生批，`Module` 把批映射为预测，损失函数把预测与标签压缩为标量，`autograd` 把标量还原为每个参数的梯度，优化器消费梯度修改参数。`train()` 与 `eval()` 改变的是 `Module` 内部的分支，`no_grad()` 改变的是 `autograd` 是否记录，`zero_grad()` 改变的是梯度的初值；四者互不替代，缺一即产生静默错误。

该表述与严格定义的关系：定义中的五个步骤对应上述四个对象的一次完整循环；第 4 小节的梯度累加解释了为何 `zero_grad` 是必需的，第 5 小节的注册机制解释了为何 `model.parameters()` 能拿到全部参数，第 7 小节的顺序约束解释了为何五步不可交换。

## 例子与代码

### 示例 1：完整 MNIST 训练脚本

以下脚本包含数据加载、验证集划分、模型定义、训练、评估与保存，PyTorch 2.x 与 torchvision 0.15 及以上可直接运行。脚本把官方训练集划出 5000 张作为验证集，测试集只在最后评估一次。

```python
import torch
import torch.nn as nn
from torch.utils.data import DataLoader, random_split
from torchvision import datasets, transforms


def build_loaders(batch_size=128, num_workers=2):
    tf = transforms.Compose([transforms.ToTensor(),
                             transforms.Normalize((0.1307,), (0.3081,))])
    full = datasets.MNIST("./data", train=True, download=True, transform=tf)
    test_ds = datasets.MNIST("./data", train=False, download=True, transform=tf)
    gen = torch.Generator().manual_seed(0)
    train_ds, val_ds = random_split(full, [55000, 5000], generator=gen)
    train_ld = DataLoader(train_ds, batch_size=batch_size, shuffle=True,
                          num_workers=num_workers, pin_memory=True, drop_last=True)
    val_ld = DataLoader(val_ds, batch_size=512, num_workers=num_workers)
    test_ld = DataLoader(test_ds, batch_size=512, num_workers=num_workers)
    return train_ld, val_ld, test_ld


class MLP(nn.Module):
    def __init__(self, hidden=(256, 128), num_classes=10, p_drop=0.2):
        super().__init__()
        layers, in_dim = [], 28 * 28
        for h in hidden:
            layers += [nn.Linear(in_dim, h), nn.ReLU(inplace=True), nn.Dropout(p_drop)]
            in_dim = h
        layers.append(nn.Linear(in_dim, num_classes))
        self.net = nn.Sequential(*layers)

    def forward(self, x):
        return self.net(x.flatten(1))          # (B,1,28,28) -> (B,784)


@torch.no_grad()
def evaluate(model, loader, device, loss_fn):
    model.eval()
    loss_sum, correct, total = 0.0, 0, 0
    for x, y in loader:
        x, y = x.to(device), y.to(device)
        logits = model(x)
        loss_sum += loss_fn(logits, y).item() * y.size(0)
        correct += (logits.argmax(dim=1) == y).sum().item()
        total += y.size(0)
    return loss_sum / total, correct / total


def train(epochs=3, lr=1e-3, batch_size=128, ckpt="mnist_mlp.pt"):
    torch.manual_seed(0)
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    train_ld, val_ld, test_ld = build_loaders(batch_size)
    model = MLP().to(device)
    opt = torch.optim.Adam(model.parameters(), lr=lr)
    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=epochs * len(train_ld))
    loss_fn = nn.CrossEntropyLoss()
    best = {"acc": 0.0, "epoch": 0, "state": None}

    for ep in range(1, epochs + 1):
        model.train()
        running, seen = 0.0, 0
        for x, y in train_ld:
            x = x.to(device, non_blocking=True)
            y = y.to(device, non_blocking=True)
            opt.zero_grad(set_to_none=True)
            loss = loss_fn(model(x), y)
            loss.backward()
            torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0)
            opt.step()
            sched.step()
            running += loss.item() * y.size(0)
            seen += y.size(0)
        val_loss, val_acc = evaluate(model, val_ld, device, loss_fn)
        print(f"epoch {ep} | train_loss {running / seen:.4f} | "
              f"val_loss {val_loss:.4f} | val_acc {val_acc:.4f}")
        if val_acc > best["acc"]:
            best = {"acc": val_acc, "epoch": ep,
                    "state": {k: v.detach().cpu().clone()
                              for k, v in model.state_dict().items()}}
            torch.save({"model": best["state"], "val_acc": val_acc, "epoch": ep}, ckpt)

    model.load_state_dict(best["state"])
    test_loss, test_acc = evaluate(model, test_ld, device, loss_fn)
    print(f"best epoch {best['epoch']} | test_loss {test_loss:.4f} | "
          f"test_acc {test_acc:.4f}")
    return model, test_acc


if __name__ == "__main__":
    train()
```

一次运行的结果：

```text
epoch 1 | train_loss 0.3313 | val_loss 0.1372 | val_acc 0.9550
epoch 2 | train_loss 0.1345 | val_loss 0.0984 | val_acc 0.9682
epoch 3 | train_loss 0.0986 | val_loss 0.0917 | val_acc 0.9724
best epoch 3 | test_loss 0.0860 | test_acc 0.9732
```

三点说明：

- 在做什么：训练集 55000 张用于更新，5000 张用于每轮评估与最佳检查点选择，测试集只在最后使用。选择依据是验证准确率，保存的是 `state_dict` 的 CPU 副本，避免后续更新覆盖已保存的权重；若直接保存 `model.state_dict()` 引用，后续训练会修改其中张量，检查点与验证指标不再对应。
- 为什么这样：`drop_last=True` 使每个批的大小恒为 128，避免最后一个小批改变批归一化的统计量与梯度尺度；本例的 MLP 不含 BN，但这一约定在替换为 CNN 时必要。余弦退火按步调用，`T_max` 设为总步数 $3\times429=1287$，学习率在训练末段接近零，使最终轮次的验证指标更稳定。
- 去掉会怎样：去掉 `evaluate` 中的 `@torch.no_grad()`，验证显存随批大小线性增长，5000 张验证集可能触发显存不足；去掉 `model.eval()`，Dropout 在验证时仍随机置零，同一检查点的验证准确率从 $0.9724$ 降到 $0.9618$ 至 $0.9676$ 之间，且每次评估结果不同；去掉 `clip_grad_norm_`，本例仍能收敛，但在学习率大于 $10^{-2}$ 时会偶发损失尖峰。

### 示例 2：view、permute 与广播的调试

以下代码演示第 2、3 小节的规则，输出可直接用于核对布局与形状。

```python
import torch

x = torch.arange(12).reshape(3, 4)
y = x.t()
print("x stride", x.stride(), "y stride", y.stride())   # (4, 1) (1, 4)
print("y 连续?", y.is_contiguous())                     # False
print("reshape 展开", y.reshape(-1))                    # 按行展开 y

z = x.permute(1, 0).contiguous()                        # 先连续再 view
print("z view 前 4 个", z.view(-1)[:4])                 # [0, 4, 8, 1]

a = torch.arange(6).reshape(2, 3)
print("(2,3)+(3,) ->", (a + torch.arange(3)).shape)     # (2, 3)
print("(2,3)+(2,1) ->", (a + torch.arange(2).reshape(2, 1)).shape)  # (2, 3)
```

预期输出：

```text
x stride (4, 1) y stride (1, 4)
y 连续? False
reshape 展开 tensor([ 0,  4,  8,  1,  5,  9,  2,  6, 10,  3,  7, 11])
z view 前 4 个 tensor([0, 4, 8, 1])
(2,3)+(3,) -> torch.Size([2, 3])
(2,3)+(2,1) -> torch.Size([2, 3])
```

三点说明：

- 在做什么：`x.t()` 只交换 stride，`y.reshape(-1)` 因布局不连续而复制成行优先内存，展开顺序因此按列读取 `x`。若先用 `.contiguous()` 再 `view`，得到同样的结果，但显式说明了复制发生的位置。
- 为什么这样：`view` 的失败不是形状算错，而是 stride 不允许零拷贝；在卷积网络中，`permute` 常出现在 `(B, C, H, W)` 与 `(B, H, W, C)` 之间，随后 `view` 失败时应在 `permute` 之后加 `.contiguous()`，而不是反复改形状。
- 去掉会怎样：去掉 `.contiguous()` 直接 `view(-1)` 会抛出 `RuntimeError`；把 `(2,1)` 换成 `(2,)` 后与 `(2,3)` 相加，尾部对齐得到 `3` 与 `2`，广播失败并抛出形状错误。

### 示例 3：梯度累加与 detach

```python
import torch

w = torch.tensor([1.0, 2.0], requires_grad=True)
for step in range(2):
    loss = (w ** 2).sum()
    loss.backward()
    print(f"step {step}: grad = {w.grad}")     # [2.,4.] 然后 [4.,8.]

w.grad = None                                   # 手动清零，等效 zero_grad
loss = (w ** 2).sum()
loss.backward()
print("清零后 grad =", w.grad)                  # [2., 4.]

u = (w * 2).detach()                            # 切断梯度，共享存储
print("u.requires_grad =", u.requires_grad)     # False
with torch.no_grad():
    print("no_grad 内 requires_grad =", (w * 3).requires_grad)   # False
```

预期输出：

```text
step 0: grad = tensor([2., 4.])
step 1: grad = tensor([4., 8.])
清零后 grad = tensor([2., 4.])
u.requires_grad = False
no_grad 内 requires_grad = False
```

三点说明：

- 在做什么：每轮重新构造 `loss`，使反向图是新的；第二次反向把梯度累加到已有 `.grad` 上。若对同一个 `loss` 连续调用两次 `backward()`，会报 `Trying to backward through the graph a second time`，因为第一次反向已释放保存的中间量。
- 为什么这样：`detach` 与 `no_grad` 都切断梯度，但作用范围不同。前者只对被调用的张量生效，且与原张量共享存储，修改 `u` 会修改 `w*2` 的结果；后者作用于上下文内的所有运算。
- 去掉会怎样：训练循环中若去掉 `zero_grad`，梯度按步累加，等效学习率随步数线性增长，损失在前几十步内变为 `nan`；若把 `detach` 用在需要梯度的目标上，反向时该分支的梯度为零，参数不更新且不报错。

### 示例 4：小批量过拟合与梯度范数

调试时先确认模型能记住 2 个批。以下函数在固定批上迭代，打印损失与全局梯度范数；损失若不能降到 $10^{-3}$ 以下，问题在实现而不在超参数。

```python
def overfit_one_batch(model, x, y, loss_fn, opt, steps=200):
    model.train()
    for i in range(steps):
        opt.zero_grad(set_to_none=True)
        loss = loss_fn(model(x), y)
        loss.backward()
        total_norm = torch.sqrt(sum((p.grad.detach() ** 2).sum()
                                    for p in model.parameters() if p.grad is not None))
        opt.step()
        if i % 50 == 0:
            print(f"step {i:3d} loss {loss.item():.4f} grad_norm {total_norm.item():.4f}")
```

预期输出形态为损失从初始值（多分类约为 $\log K$）单调下降到 $10^{-4}$ 量级，梯度范数从 $10^{-1}$ 量级下降到 $10^{-3}$ 以下。若损失停在 $\log K$ 附近，检查标签与 logits 的维度顺序；若梯度范数为零，检查参数是否被冻结或损失是否与参数无关。

## 易错点

> [!warning] 具体错误
> - 忘记 `opt.zero_grad()`。梯度跨步累加，等效学习率随步数增长，损失先正常下降再突变；在梯度累积的写法中，`zero_grad` 应放在每个大迭代的开头而不是每个微批。
> - 验证时只写 `torch.no_grad()` 而忘记 `model.eval()`。Dropout 仍生效、BatchNorm 仍用批统计量，验证损失随批组成波动，且与训练损失的口径不一致，早停判据失效。
> - 把 `loss.item()` 累加后再除以批数。`item()` 返回当前批的均值，最后一个小批的权重被高估；应累加 `loss.item() * y.size(0)` 再除以样本总数。
> - 直接保存 `model` 对象或保存 `model.state_dict()` 的引用。前者依赖类路径，重构后无法加载；后者在后续训练中被原地修改，检查点与记录的指标不对应。应保存深拷贝或 CPU 副本。
> - 混合精度下先裁剪再 `unscale_`。裁剪作用在被缩放因子放大的梯度上，`max_norm` 实际被放大数万倍，等于没有裁剪；正确顺序是 `unscale_`、裁剪、`scaler.step`。
> - 用测试集选择最佳轮次。测试集参与了模型选择，报告的准确率偏乐观；必须从训练集划出验证集，测试集只在最终评估时使用一次。

## 关联笔记

- 前置：[[反向传播详解]] —— `backward()` 的数学含义、计算图与梯度累加的来源，本篇只给出框架层的对应关系。
- 前置：[[神经网络与前向传播]] —— 层的定义、形状约定与初始化，决定 `MLP` 中每个 `Linear` 的输入输出维度。
- 前置：[[正则化与调参]] —— Dropout 与 BatchNorm 的模式依赖、早停的判据与超参数调节顺序，在本篇的训练循环中落地。
- 后续：[[卷积神经网络CNN]] —— 把 `MLP` 替换为卷积网络，训练循环与数据管线不变，形状约定与 `permute` 的使用显著增加。
- 后续：[[数据增广]] —— `Dataset` 的 `transform` 与 `collate_fn` 是增广的接入点，随机种子与多进程的交互在该篇与本篇中都需要核对。

## 达标检测

- [ ] 解释 `view`、`reshape`、`permute` 三者的差别，给出一个 `view` 失败但 `reshape` 成功的例子，并说明失败时应该修改哪一步；写出广播的三条规则，判断 `(2,3)` 与 `(2,)` 能否相加。
- [ ] 说明 `zero_grad` 为何必需：从梯度累加出发，推导不清零时第 $t$ 步的等效学习率。
- [ ] 写出训练循环的五步，标注 `scheduler.step()` 与 `clip_grad_norm_` 的位置，并说明两处顺序错误各自的后果。
- [ ] 运行示例 1，把 `model.eval()` 从 `evaluate` 中删掉，比较三轮验证准确率的波动，并解释波动来源。
- [ ] 说明 `state_dict` 与保存整个模型的差别，写出断点续训需要保存的四个对象，并解释只恢复模型参数会导致什么现象。
- [ ] 写出混合精度的五步顺序，说明 `GradScaler` 解决的是哪一类数值问题，以及 `bfloat16` 为何可以省略它。

## 参考来源

- PyTorch 官方教程，*Learn the Basics* 中的 Tensors、Autograd、Optimization 三节与 *Training a Classifier* —— 对应张量操作、autograd 语义、五步训练循环与 MNIST 示例的结构。
- PyTorch 官方文档，`torch.utils.data`、`torch.nn.Module`、`torch.amp` 与 `torch.save`/`torch.load` 的 API 说明 —— 对应 `DataLoader` 参数语义、参数注册、混合精度与检查点格式。
- d2l.ai《动手学深度学习》，第 3 章「线性神经网络」与第 5 章「深度学习计算」 —— 对应训练循环的标准写法、`Module` 的参数访问与自定义层的实现约定。
- Raschka, *Build a Large Language Model (From Scratch)*, 2024, 第 5 章「Pretraining on Unlabeled Data」 —— 对应训练循环的组织、损失记录、梯度裁剪、学习率调度与检查点保存的工程实践。
- torchvision 官方文档，`datasets.MNIST` 与 `transforms` —— 对应示例 1 的数据下载、归一化常数与 `random_split` 的用法。
