企业官网建设流程全解析

简介：面向深度学习入门者与课程实验需求的手写数字识别实战包，围绕MNIST数据集完成前馈神经网络训练与推理，适合希望跳过环境搭建与重复训练、直接获得可运行代码和可用模型的读者。压缩包共5个文件、约1.39MB，包含3个Python脚本与2个HDF5模型文件：脚本对应训练、评估和预测等环节，HDF5文件分别提供模型参数与完整模型，便于按需加载或继续微调。已有6131人学习，说明其在入门教学与实验复现中具有一定参考价值。读者可据此理解MNIST数据预处理、网络结构定义、模型训练与保存加载的完整链路，也能将现成模型用于手写数字识别演示、作业提交或二次开发，减少从零调试的时间成本。

1. MNIST 手写数字识别：为什么照抄教程的代码只能跑到 92% 的准确率

很多人第一次用 MNIST 数据集训练手写数字识别模型，会撞上一个很怪的现象：教程里清一色写 99% 准确率，自己把代码原样跑一遍，验证集却卡在 92% 上下，换网络、加层数、调学习率都试了，数字就是不动。问题大概率不在模型结构，而在几个不会报错的环节——Normalize 的均值方差填错、训练和推理没有切换 eval 模式、模型保存时只存了权重却忘了结构。这些细节不会让代码崩，只会让结果悄悄变差，属于典型的“能跑但不对”。下面按数据加载、网络定义、训练循环、排错、部署这条线，把能稳定复现 99% 的流程和训练好的模型文件用法一次讲清，适合刚接触手写数字识别、想直接拿到可用模型的人跟着做。

2. 从 IDX 文件到 DataLoader：MNIST 数据加载的五个必调参数

MNIST 数据加载看起来是最没技术含量的一步，但准确率从 92% 拉到 99% 的差距，一半以上出在这一步。原始数据是四个 IDX 格式的文件，训练集 60000 张、测试集 10000 张，每张 28×28 灰度图，像素值 0 到 255。常见做法是用 torchvision 直接读，不自己解析二进制，因为 IDX 格式的魔数和维度偏移量写错一个字节，读出来的就是乱码图片，而且不会报错，只会让 loss 曲线变成一条水平线。

2.1 MNIST 的 IDX 格式与官方切分：为什么不能自己乱切

IDX 文件的开头是魔数，图像文件是 2051，标签文件是 2049，接着是维度信息和像素数据。torchvision 的datasets.MNIST已经把这层封装好了，传train=True拿 60000 张训练集，传train=False拿 10000 张测试集。这里有一个容易被忽略的点：官方切分是固定的，训练集和测试集之间没有重叠，测试集的 10000 张在训练阶段完全不可见。我见过不少做法是从训练集里再切 20% 当测试集，然后把官方测试集晾在一边，这样得到的准确率和公开结果不可比，换一台机器、换一个随机种子，数字就会漂移。

如果需要验证集做早停，正确做法是从 60000 张训练集里固定随机种子留出 5000 张，剩下 55000 张用于训练，官方测试集始终保留到最后评估。切分代码不要用random.shuffle之后再切片，因为每次运行种子不同，验证集分布会变，早停的阈值也跟着变，复现性会很差。常见做法是用torch.utils.data.random_split配合固定种子，或者直接按索引切一段固定区间，后者更稳，因为每次运行拿到的验证集完全一样。

另一个细节是数据增强。MNIST 是灰度手写数字，水平翻转要慎用，因为 6 翻转后接近 9，会把标签搞乱。可以用的增强是RandomRotation(10)和RandomAffine(translate=(0.1, 0.1))，模拟书写时的小角度倾斜和位置偏移，训练集上做、验证集和测试集不做。增强太猛反而掉点，旋转超过 15 度时数字 1 可能被转成斜线，模型学不到稳定特征。

2.2 transforms 里 ToTensor 与 Normalize 的两个数字怎么定

ToTensor()做两件事：把 PIL 图片或 numpy 数组转成 FloatTensor，同时把像素值从 0 到 255 缩放到 0 到 1，形状从 H×W 转成 C×H×W。这一步不做的话，输入值域是 0 到 255，第一层卷积的权重更新会被大数值主导，学习率要调到很小才不炸，训练时间直接翻倍。

Normalize((0.1307,), (0.3081,))是 MNIST 训练集的全局均值和标准差，这两个数字不是拍脑袋写的。MNIST 背景像素占多数，整体分布偏向 0，均值 0.1307 说明大部分像素接近黑色，标准差 0.3081 说明有效笔画像素的离散程度。用真实统计值做标准化后，输入分布接近零均值、单位方差，卷积核的梯度尺度更均匀，收敛更快。如果图省事填(0.5, 0.5)，模型也能跑，但第一轮 loss 会偏高，到 99% 需要的 epoch 数会多两到三个。

下面这段代码把数据加载、标准化和 DataLoader 配置一次写全，可以直接抄：

import torch from torch.utils.data import DataLoader, random_split from torchvision import datasets, transforms # MNIST 训练集统计出来的均值和标准差，不要改成 0.5 transform_train = transforms.Compose([ transforms.RandomRotation(10), # 小角度旋转，模拟书写倾斜 transforms.RandomAffine(degrees=0, translate=(0.1, 0.1)), # 小幅平移 transforms.ToTensor(), # PIL -> FloatTensor，像素缩到 [0,1] transforms.Normalize((0.1307,), (0.3081,)) # 按全局均值方差标准化 ]) transform_eval = transforms.Compose([ transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,)) # 验证/测试只做标准化，不做增强 ]) # 官方训练集 60000 张，测试集 10000 张 full_train = datasets.MNIST(root="./data", train=True, download=True, transform=transform_train) test_set = datasets.MNIST(root="./data", train=False, download=True, transform=transform_eval) # 从训练集固定切 5000 张做验证，种子写死保证每次一致 val_size = 5000 train_size = len(full_train) - val_size train_set, val_set = random_split( full_train, [train_size, val_size], generator=torch.Generator().manual_seed(42) ) train_loader = DataLoader( train_set, batch_size=128, # 每批 128 张，显存不够降到 64 shuffle=True, # 训练集每轮打乱，避免固定顺序影响梯度 num_workers=4, # Linux 开 4 个子进程；Windows 改成 0 pin_memory=True, # 有 GPU 时锁页内存，拷贝更快 drop_last=True # 丢掉最后不满一批的样本，避免 BatchNorm 遇到 batch=1 ) val_loader = DataLoader( val_set, batch_size=256, shuffle=False, num_workers=4, pin_memory=True ) test_loader = DataLoader( test_set, batch_size=256, shuffle=False, num_workers=4, pin_memory=True ) # 抽查一个 batch，确认形状和数值范围 images, labels = next(iter(train_loader)) print(images.shape, images.dtype, labels.shape) print(images.min().item(), images.max().item()) # 归一化后约 -0.42 到 2.82

这段代码里drop_last=True容易被忽略。训练集 55000 张除以 128 除不尽，最后一批可能只剩几十张甚至一张。如果网络里用了 BatchNorm，batch 大小为 1 时方差估计会出问题，轻则 loss 抖动，重则直接报错。丢掉最后不满一批的样本损失不到 128 张，对 55000 张的训练集影响可以忽略。

2.3 DataLoader 的 batch_size、shuffle、num_workers 与 pin_memory

batch_size从 128 起步是 MNIST 上的经验值。64 到 256 之间都合理，batch 太小梯度噪声大，loss 曲线像心电图；batch 太大泛化可能变差，而且 60000 张的数据集没必要上 1024。显存 4GB 以下的机器用 64，8GB 以上用 128 或 256 都行。

shuffle=True只对训练集开。验证集和测试集必须False，否则每次评估的样本顺序不同，预测结果和图片对不上，后面做错误样本复盘时找不到对应原图。

num_workers在 Linux 上设 4 基本够用，设太高反而因为进程切换拖慢速度。Windows 上直接设 0，因为 PyTorch 的多进程 DataLoader 在 Windows 下会把整个脚本重新 import 一遍，没有if __name__ == "__main__":保护时直接卡死或报递归错误。这个坑后面第 5 章还会展开。

pin_memory=True只在有 GPU 时开。它把数据锁在页锁定内存里，从 CPU 拷贝到 GPU 时走 DMA，比普通内存快一截。纯 CPU 训练时开这个没有收益，反而占内存。

3. 用 CNN 复现 99% 准确率：LeNet 改造与每层输出尺寸验算

MNIST 上拿到 99% 不需要 ResNet 或 Transformer，一个改过的 LeNet 足够。关键不在网络多深，而在感受野和通道数是否匹配 28×28 的输入。全连接网络在 MNIST 上通常到 97% 左右就上不去了，因为把 28×28 拉成 784 维向量后，相邻像素的空间关系丢了，模型只能靠像素位置的权重组合去记模式，泛化能力有限。卷积核滑过图像时保留局部连接和权重共享，对笔画这种局部特征更友好。

3.1 为什么全连接网络在 MNIST 上到 97% 就上不去了

一个典型的全连接基线是 784→512→256→10，参数量大约 67 万，训练到 97% 不难。但再往上走会卡住，原因有三个。第一，手写数字的判别信息在笔画边缘和拐角处，全连接层把每个像素独立对待，学不到“相邻像素组成线段”这种结构。第二，全连接层参数量集中在第一层，784×512 就是 40 万个权重，容易记住训练集的噪声。第三，没有平移不变性，同一个数字写在图片左上角和右下角，对全连接网络来说是两组完全不同的输入。

卷积网络用 3×3 或 5×5 的核在整张图上滑动，同一个核检测同一种笔画模式，不管它出现在哪个位置。池化层进一步压缩空间尺寸，让后面的层看到更大的感受野。MNIST 的 28×28 输入，两层卷积加两次池化后降到 7×7，再接全连接分类，参数量比纯全连接少一个量级，准确率反而更高。

3.2 LeNet-5 的两处现代改法：ReLU 与 BatchNorm

原始 LeNet-5 用 tanh 激活和平均池化，放在今天收敛偏慢。我一般改两处：把 tanh 换成 ReLU，把池化换成最大池化，再在卷积后加 BatchNorm。ReLU 在正区间梯度恒为 1，不会像 tanh 那样在饱和区把梯度压没；最大池化保留纹理最强的响应，对笔画边缘更敏感；BatchNorm 把每层输入拉回零均值单位方差，学习率可以设大一点，收敛更稳。

网络结构可以这样排：第一层卷积 1→32，3×3 核，padding=1，输出 28×28，接 BatchNorm 和 ReLU，再 2×2 最大池化降到 14×14；第二层卷积 32→64，3×3 核，padding=1，输出 14×14，接 BatchNorm 和 ReLU，再池化降到 7×7；然后展平成 64×7×7=3136 维，接一个 128 维全连接，最后输出 10 类。参数量大约 42 万，比全连接基线少，准确率能到 99.2% 左右。

3.3 网络定义代码与每层输出尺寸验算

下面这段网络定义可以直接用，每一层的输出尺寸我都标在注释里，改结构时照着算一遍，能避开大部分维度不匹配的报错：

import torch import torch.nn as nn import torch.nn.functional as F class MnistCNN(nn.Module): def __init__(self, num_classes=10): super().__init__() # 输入 [B, 1, 28, 28] self.conv1 = nn.Conv2d(1, 32, kernel_size=3, padding=1) # -> [B, 32, 28, 28] self.bn1 = nn.BatchNorm2d(32) self.conv2 = nn.Conv2d(32, 64, kernel_size=3, padding=1) # -> [B, 64, 14, 14] self.bn2 = nn.BatchNorm2d(64) self.pool = nn.MaxPool2d(2, 2) # 空间尺寸减半 self.fc1 = nn.Linear(64 * 7 * 7, 128) # 3136 -> 128 self.dropout = nn.Dropout(0.3) self.fc2 = nn.Linear(128, num_classes) # 128 -> 10 def forward(self, x): x = self.pool(F.relu(self.bn1(self.conv1(x)))) # [B, 32, 14, 14] x = self.pool(F.relu(self.bn2(self.conv2(x)))) # [B, 64, 7, 7] x = torch.flatten(x, 1) # [B, 3136] x = F.relu(self.fc1(x)) x = self.dropout(x) x = self.fc2(x) # [B, 10]，输出 logits return x model = MnistCNN() print(sum(p.numel() for p in model.parameters())) # 约 42 万

padding=1是为了让 3×3 卷积后空间尺寸不变，28 进 28 出、14 进 14 出，池化层再统一减半。如果不加 padding，第一层卷积后变成 26×26，第二次池化后是 6×6，全连接层的输入维度就要改成 64×6×6，改漏一处就报mat1 and mat2 shapes cannot be multiplied。

Dropout(0.3)放在全连接层之间，训练时随机丢 30% 的神经元，抑制过拟合。MNIST 数据量不大，不加 Dropout 时训练集准确率能到 99.9%，验证集可能停在 98.8%，加了这个之后两条曲线贴得更近。

不同结构的参数量和预期准确率对比如下，方便选型时心里有数：

加深到 4 层卷积只多 0.1 个百分点，训练时间翻倍，MNIST 上不划算。42 万参数这个版本是准确率和成本的平衡点。

4. 训练循环里的四个开关：优化器、学习率、batch size 与早停

同样的网络，训练循环写错两个地方，准确率能差 3 个百分点。最常见的错误是忘了在验证前调model.eval()，BatchNorm 继续用当前 batch 的均值方差，Dropout 还在随机丢神经元，验证结果每次都不一样，早停的判据跟着乱跳。另一个是只存了state_dict却用torch.save(model)的方式加载，结构对不上直接报错。

4.1 优化器选 Adam 还是 SGD：MNIST 上的实测差异

Adam 默认学习率 1e-3，MNIST 上 3 个 epoch 就能到 98.5%，5 个 epoch 到 99%。SGD 需要手动调学习率和动量，常见配置是 lr=0.01、momentum=0.9，收敛慢一些，但最终准确率有时比 Adam 高 0.1 到 0.2 个百分点，因为 Adam 的自适应学习率在训练后期容易在最优解附近震荡。

我的习惯是先用 Adam 跑一个基线，确认数据和网络没问题，再换 SGD 微调。如果只想拿一个能用的模型文件，Adam 加StepLR每 5 个 epoch 乘 0.5，10 个 epoch 内稳定到 99%。如果追求最后一两个千分点，SGD 加 cosine 退火更稳，但调参时间要多花一两个小时。

不管选哪个，权重衰减都建议加上，weight_decay=1e-4对 MNIST 足够。不加正则时，训练集和验证集的准确率曲线会在第 6 个 epoch 后明显分叉。

4.2 学习率与 batch size 的联动：线性缩放规则靠不靠得住

有一条经验规则是 batch size 翻倍、学习率也翻倍，这条规则在大数据集和大模型上比较成立，MNIST 这种小数据集上不用太教条。batch size 从 64 改到 128，学习率从 1e-3 改到 2e-3 可以试，但 2e-3 在 Adam 上有时会让 loss 在第一个 epoch 抖一下。更稳的做法是保持 1e-3，用学习率调度器在后期降下来。

学习率设太大最直接的表现是 loss 变成 NaN 或者剧烈震荡，设太小则是 loss 降得很慢，10 个 epoch 还在 0.3 以上。判断方法很简单：看第一个 epoch 的平均 loss，MNIST 上合理范围是 0.2 到 0.5，低于 0.1 说明学习率偏大或者数据泄漏，高于 0.8 说明学习率偏小。

4.3 早停该看验证集 loss 还是准确率

验证集 loss 和准确率不一定同步。有时候 loss 还在缓慢下降，准确率已经连续 3 个 epoch 不动，这时候继续训练只会让模型对训练集过拟合。我一般两个都看：准确率连续 3 个 epoch 没有提升就停，同时记录最好的那一轮权重，而不是最后一轮的权重。最后一轮的权重可能已经过拟合，验证准确率比最好轮低 0.3 到 0.5 个百分点。

保存 best model 的逻辑不要写在 epoch 循环外面，要写在验证之后、判断准确率是否创新高之后。下面这段训练循环把优化器、调度器、验证和保存都串起来了：

import torch import torch.nn as nn from torch.optim import Adam from torch.optim.lr_scheduler import StepLR device = torch.device("cuda" if torch.cuda.is_available() else "cpu") model = MnistCNN().to(device) criterion = nn.CrossEntropyLoss() optimizer = Adam(model.parameters(), lr=1e-3, weight_decay=1e-4) scheduler = StepLR(optimizer, step_size=5, gamma=0.5) # 每 5 轮学习率减半 best_acc = 0.0 patience = 3 # 连续 3 轮不提升就停 no_improve = 0 for epoch in range(15): model.train() # 开启 Dropout 和 BatchNorm 的训练模式 running_loss = 0.0 for images, labels in train_loader: images, labels = images.to(device), labels.to(device) optimizer.zero_grad() logits = model(images) loss = criterion(logits, labels) loss.backward() optimizer.step() running_loss += loss.item() * images.size(0) # 验证阶段必须切 eval，否则 BatchNorm 用当前 batch 统计量 model.eval() correct, total = 0, 0 with torch.no_grad(): for images, labels in val_loader: images, labels = images.to(device), labels.to(device) logits = model(images) pred = logits.argmax(dim=1) correct += (pred == labels).sum().item() total += labels.size(0) val_acc = correct / total print(f"epoch {epoch+1}, loss {running_loss/len(train_set):.4f}, val_acc {val_acc:.4f}") if val_acc > best_acc: best_acc = val_acc no_improve = 0 torch.save(model.state_dict(), "mnist_cnn_best.pth") # 只存权重 else: no_improve += 1 if no_improve >= patience: print(f"early stop at epoch {epoch+1}, best acc {best_acc:.4f}") break scheduler.step()

model.train()和model.eval()的切换是整段代码里最不能省的两行。训练时 BatchNorm 用当前 batch 的均值和方差，验证时用训练阶段累计的滑动平均值；Dropout 训练时按概率丢弃，验证时全部保留。漏掉model.eval()时，验证准确率通常比真实值低 1 到 2 个百分点，而且每次运行结果都不同，早停会在错误的轮次触发。

torch.save(model.state_dict(), ...)只存权重，不存网络结构。优点是文件小，42 万参数约 1.6MB，加载时先实例化MnistCNN()再load_state_dict，结构改了也能对得上。如果用torch.save(model, ...)存整个模型，文件会大一些，而且加载时依赖定义类的源码路径，换一个目录就可能报ModuleNotFoundError。

5. 手写数字识别模型的五个翻车现场：从维度不匹配到 CPU/GPU 状态不一致

MNIST 代码短，报错信息也短，但短报错背后往往是几个固定位置的配置错了。下面五条是我在复现和帮人排查时遇到频率最高的，按“现象 → 原因 → 解决”写，照着对一遍能省掉大半天。

5.1 训练 loss 一直降，验证准确率却卡在 10%

现象：训练集 loss 从 2.3 降到 0.1，验证集准确率始终在 10% 左右，等于随机猜。

原因：验证时没有调model.eval()，BatchNorm 继续用验证 batch 的统计量，而验证 batch 和训练 batch 的分布不一致，导致输出全挤到某一类。另一种可能是标签和输出维度对错了，比如把CrossEntropyLoss用在已经过 softmax 的输出上，梯度被压平。

解决：验证循环开头加model.eval()，外面套torch.no_grad()。检查网络最后一层输出维度是不是 10，CrossEntropyLoss内部自带 softmax，网络最后不要再接F.softmax。

5.2 加载模型后推理结果全是同一个数字

现象：训练时验证准确率 99%，保存模型后用load_state_dict加载，随便拿几张测试图推理，输出全是 3 或者全是 7。

原因：加载权重前没有先实例化模型，或者实例化时改了结构但没改全连接层维度，load_state_dict默认strict=True会报错，有人改成strict=False把错误吞了，结果一半权重没加载上。另一种可能是推理时忘了把图片标准化，输入值域是 0 到 255，网络看到的分布和训练时完全不同。

解决：先model = MnistCNN()，再model.load_state_dict(torch.load("mnist_cnn_best.pth"))，最后model.eval()。推理输入必须走和验证集一样的transform_eval，包括ToTensor和Normalize。

5.3 RuntimeError: mat1 and mat2 shapes cannot be multiplied

现象：前向传播到全连接层时报维度不匹配，提示类似mat1 and mat2 shapes cannot be multiplied (128x3136 and 4096x128)。

原因：卷积层或池化层的输出尺寸算错了。28×28 输入经过两次 2×2 池化后是 7×7，通道数是 64，展平后是 3136。如果某一层忘了加 padding，或者池化核写成 3×3，输出会变成 6×6 或 5×5，全连接层的输入维度就对不上。

解决：在forward里打印x.shape，逐层核对。或者用torchsummary之类的方式把每层输出尺寸列出来。改结构时先算一遍：输出尺寸 = (输入尺寸 + 2×padding - 卷积核) / 步长 + 1，池化层同理。

5.4 训练集 99%，部署后掉到 85%

现象：本地验证集准确率 99.2%，把模型文件交给别人用真实手写图片测试，准确率掉到 85% 左右。

原因：MNIST 的测试集和训练集同分布，都是居中、黑底白字、28×28 的规范图。真实场景里手机拍的手写数字往往有背景、有光照、笔画偏细或偏粗，直接缩放到 28×28 后分布偏移很大。另一个原因是训练时用了RandomRotation但推理时没做对应的预处理，模型见到的输入和训练时不一致。

解决：部署前先用真实图片跑一遍，看看预处理后的图长什么样。常见做法是先把图片转灰度、二值化、裁掉空白边缘、居中缩放，再做和训练一致的标准化。如果真实数据量够，拿几百张真实图微调最后两层，准确率能拉回 95% 以上。

5.5 Windows 上 DataLoader 多进程直接卡死

现象：Linux 上num_workers=4跑得好好的，Windows 上同样的代码一运行就卡住，或者报RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase。

原因：Windows 创建子进程用的是 spawn 而不是 fork，子进程会重新 import 主脚本。如果 DataLoader 的初始化写在模块顶层，没有if __name__ == "__main__":保护，子进程会无限递归地创建新进程。

解决：把训练入口包进if __name__ == "__main__":，同时把num_workers设为 0 先跑通，确认没问题再逐步调到 2 或 4。Windows 上num_workers超过 0 时，数据加载的每个 batch 都要经过进程间拷贝，速度不一定比 0 快，小数据集上直接设 0 更省心。

6. 把训练好的模型文件用起来：state_dict 保存、ONNX 导出与单张图片推理

训练完拿到mnist_cnn_best.pth只是第一步，真正要用起来还得解决加载和跨环境推理。我一般只存state_dict，不存整个模型，因为权重文件小、加载路径干净，换一台机器只要类定义在就能恢复。加载时先实例化MnistCNN()，再load_state_dict，最后eval()，三步缺一不可。

import torch model = MnistCNN() model.load_state_dict(torch.load("mnist_cnn_best.pth", map_location="cpu")) model.eval() # 推理前必须切 eval，否则 Dropout 和 BatchNorm 行为不对

如果要把模型交给不装 PyTorch 的环境，导出 ONNX 更通用。固定输入形状[1, 1, 28, 28]，用torch.onnx.export导出一个几十 MB 的文件，再用 onnxruntime 推理，不依赖训练框架：

import torch dummy = torch.randn(1, 1, 28, 28) torch.onnx.export( model, dummy, "mnist_cnn.onnx", input_names=["input"], output_names=["logits"], opset_version=12 # 常见稳定版本，兼容多数推理引擎 ) import onnxruntime as ort import numpy as np sess = ort.InferenceSession("mnist_cnn.onnx") img = np.random.randn(1, 1, 28, 28).astype(np.float32) logits = sess.run(None, {"input": img})[0] print(logits.argmax(axis=1)) # 输出预测类别

ONNX 推理时最容易翻车的是预处理没对齐。训练时用了Normalize((0.1307,), (0.3081,))，推理时如果只做ToTensor不做标准化，输入分布偏到 0 到 1 之间，预测会明显变差。我的习惯是把预处理写成一个函数，训练和推理共用同一份代码，不靠记忆去对齐参数。

最后留一个我自己的教训：每次改完网络结构，先把state_dict的 key 打出来和旧模型对一遍，再决定是重新训练还是只加载部分层。这个习惯帮我省掉了很多次“加载成功但结果全错”的排查时间。希望帮到你。

本文还有配套的精品资源，点击获取