简介一份基于卷积神经网络的手写数字识别项目以MNIST数据集为训练对象专门解决图像分类场景中的模型构建与评估问题适合深度学习初学者、课程设计者及竞赛选手参考。压缩包内共二十个文件核心包括三个Python脚本分别用于模型训练、数据处理和结果演示另含四组MNIST原始数据压缩包无需额外下载即可直接训练还有十张测试图片、一份说明文档和若干编译缓存文件包体总大小约十一兆。项目运行流程完整执行主脚本即可输出测试集上的识别准确率数据加载脚本负责归一化与样本划分演示脚本可展示单张手写数字的预测效果说明文档则提供环境配置与使用指引。通过该项目可以系统掌握卷积层、池化层、全连接层的工作原理理解数据预处理、批训练、模型评估等关键步骤并可直接改造为自定义图像识别实验的基础框架。目前已有三百一十五人学习使用适合希望以最小成本入门深度学习的开发者。1. 打开 cnn_mnist.zip 之前先看清楚 CNN、MNIST 和 mnist.py 这一套组合到底在解决什么问题新手拿到这类 cnn_mnist.zip 资源包常见动作是解压、双击 mnist.py、然后黑窗口一闪而过或者报一堆导入错误。其实标题里的三块内容正好对应一个最小可落地的深度学习闭环CNN 是网络模型MNIST 是标准的手写数据集mnist.py 是把二者串起来的训练脚本。整个包解决的是手写数字识别这个入门问题给定一张 28x28 的手写数字图片模型输出 0 到 9 中的某个类别。它适合刚接触 PyTorch、还没有完整跑过一次图像分类任务的开发者也适合想快速验证环境是否装好的从业者。半小时能出结果一小时能调明白参数。代价低、反馈快这就是这个资源包最大的价值。2. 拆解 mnist.py 的三层结构从卷积核到分类头的参数流2.1 CNN 的基本结构为什么卷积和池化对手写数字这么有效手写数字识别虽然只是 10 分类但用全连接网络直接吃 784 个像素并不是最省力的方案。一张 28x28 的图片拉平后每个像素之间的空间关系会被打散比如“7”的横笔和竖笔的相对位置完全丢失了。CNN 的基本结构就是通过卷积核在图像上滑动保留局部邻域关系卷积核相当于一组可学习的特征模板训练后它可能自动变成竖线检测器、圆弧检测器。池化层则在保留主要特征的同时把特征图尺寸减半让后面的层覆盖更大的感受野。整个流程就是卷积提取特征、池化压缩特征、最后全连接层把特征映射到 10 个类别概率。传统方案也可以做这件事比如先提取 HOG 特征再喂给 SVMMNIST 上同样能达到 98% 以上的正确率。但 HOG 需要手工设计特征换一种字体、换一种噪声特征就得重新调。CNN 的特征是从训练数据里自动学出来的换到其他手写风格时鲁棒性好得多。这也是为什么这个入门项目选 CNN 而不是 SVM 或普通神经网络。import torch.nn as nn import torch.nn.functional as F class LeNet(nn.Module): def __init__(self): super(LeNet, self).__init__() self.conv1 nn.Conv2d(1, 6, 5, padding2) self.conv2 nn.Conv2d(6, 16, 5) self.fc nn.Linear(16 * 5 * 5, 10) def forward(self, x): x F.max_pool2d(F.relu(self.conv1(x)), 2) x F.max_pool2d(F.relu(self.conv2(x)), 2) x x.view(x.size(0), -1) return self.fc(x)这段代码是 mnist.py 里最常见的模型骨架本质是简化版 LeNet。第一层输入通道必须为 1因为 MNIST 是灰度图最后一层输出必须为 10因为要分 0 到 9 共十个类别。中间的 6、16 是特征图通道数改成 32、64 就是更现代的做法。padding2 的作用是让第一次卷积后特征图仍保持 28x28这样第二次卷积加池化后正好得到 5x5 的特征图FC 层输入维度才是 1655。view 那行把每个样本的特征展平成向量。改网络结构时最容易翻车的就是这一句后面避坑章会再展开。2.2 数据加载与预处理MNIST 数据集如何被喂进 CNNMNIST 数据集由四部分文件组成训练集图像、训练集标签、测试集图像、测试集标签。mnist.py 里通常通过 torchvision 的 datasets.MNIST 接口加载downloadTrue 时它会自动把数据下载到 root 指定目录。注意数据加载不是简单读文件transform 才是真正决定数据质量的一环。from torchvision import datasets, transforms transform transforms.Compose([ transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,)) ]) train_set datasets.MNIST( root./data, trainTrue, downloadTrue, transformtransform ) train_loader torch.utils.data.DataLoader( train_set, batch_size64, shuffleTrue )ToTensor 做的事是把 PIL 图片从 0 到 255 的 uint8 类型变成 0.0 到 1.0 的张量并额外增加一个 channel 维度形状从 28x28 变成 1x28x28。Normalize 用 MNIST 数据集的全局均值和标准差做标准化0.1307 和 0.3081 是官方统计值直接写死即可。DataLoader 里的 shuffleTrue 是必须的它让每个 epoch 重新打乱样本顺序否则模型会学会按类别排列的顺序而不是学习特征本身。batch_size64 表示每次前向传播同时过 64 张图梯度也是在这 64 张图的平均上计算。2.3 损失函数与优化器mnist.py 中训练循环的参数流有了数据和模型还需要损失函数和优化器才能形成训练闭环。PyTorch 的标准做法是 CrossEntropyLoss 搭配 Adam 或 SGD。cross entropy 内部已经做了 softmax所以模型最后一层输出的是未归一化的 logits不需要再手动接 softmax。import torch device torch.device(cuda if torch.cuda.is_available() else cpu) model LeNet().to(device) optimizer torch.optim.Adam(model.parameters(), lr1e-3) criterion nn.CrossEntropyLoss() for epoch in range(10): for images, labels in train_loader: images, labels images.to(device), labels.to(device) optimizer.zero_grad() outputs model(images) loss criterion(outputs, labels) loss.backward() optimizer.step() print(fepoch {epoch1}, loss {loss.item():.4f})这段代码里新手最容易漏掉 optimizer.zero_grad()。如果漏了梯度会在每个 batch 之间累积loss 曲线会呈现诡异的周期性跳动。to(device) 保证模型和输入数据都在同一设备上否则会报 device mismatch。在纯 CPU 环境下跑 10 个 epoch 大约三到五分钟用 GPU 只要几十秒。Adam 默认学习率 1e-3 对 MNIST 来说足够收敛不需要一开始就调复杂的调度器。3. 把 mnist.py 跑起来最小命令、目录要求与四个必调参数3.1 最小运行流程文件结构与你应该在哪个目录下敲命令解压后通常会看到 mnist.py、数据目录或一个 README。常见做法是保持 zip 原有的目录层级不要把 mnist.py 单独拖到别的文件夹因为它内部使用的是相对路径换目录后可能找不到数据。最小三条命令就能把整个流程跑起来unzip cnn_mnist.zip cd cnn_mnist python mnist.py --mode train第一条命令解压第二条进入包目录第三条运行训练脚本。如果脚本没写命令行参数解析直接 python mnist.py 也行默认就是训练模式。运行前最好先验证环境避免把环境问题当成代码问题排查半天python -c import torch, torchvision; print(torch.__version__, torchvision.__version__)如果这行报 ModuleNotFoundError说明当前 Python 环境里没装 PyTorch 或 torchvision。此时先激活虚拟环境再用 pip 安装依赖列表而不是去改代码。环境错误的一大特征是代码本身语法没问题但 import 段就崩这时甚至不需要看后续逻辑。3.2 四个必调参数batch size、学习率、epochs、dropout参数调优是跑通之后最值得花时间的部分。MNIST 数据集很干净模型不大但只要参数不对照样会出现不收敛或过拟合。我一般会先固定一组保守参数再逐项调整观察变化。参数常见默认值影响建议调整范围batch_size64梯度稳定性与显存占用32 到 256lr1e-3Adam收敛速度与最终精度1e-4 到 3e-3epochs10欠拟合与过拟合5 到 30dropout0.5正则化强度0.2 到 0.5batch_size 越大梯度越平滑但会占用更多内存MNIST 单张图很小256 也没有压力。学习率方面Adam 用 1e-3 是稳定起点换成 SGD 则建议 1e-2 并配 momentum0.9。epochs 不必一开始就拉满先跑 10 个看曲线形状loss 还在明显下降就继续加。dropout 只加在全连接层上卷积层通常不加因为卷积层的参数共享本身已有正则化效果。如果 mnist.py 里没有参数解析可以自己补一段 argparse方便每次调整不用改源码import argparse parser argparse.ArgumentParser() parser.add_argument(--epochs, typeint, default10) parser.add_argument(--batch-size, typeint, default64) parser.add_argument(--lr, typefloat, default1e-3) parser.add_argument(--dropout, typefloat, default0.5) args parser.parse_args() print(fConfig: epochs{args.epochs}, batch_size{args.batch_size}, lr{args.lr}, dropout{args.dropout})逻辑说明argparse 从命令行读取参数没传就用 default。这样你可以在不改代码的情况下用 python mnist.py --epochs 20 做对比实验。对初学者来说把参数放在命令行而不是硬编码在代码里能省下大量改文件重跑的时间。3.3 训练日志的读法loss 震荡、下降速度与过拟合线索训练日志是判断模型状态最直接的窗口。一份典型的 log 长这样epoch 1/10 | train loss 0.4412 | acc 0.8613 epoch 2/10 | train loss 0.1217 | acc 0.9637 epoch 3/10 | train loss 0.0784 | acc 0.9782 epoch 5/10 | train loss 0.0401 | acc 0.9879 epoch 10/10 | train loss 0.0213 | acc 0.9931判断标准很简单每个 epoch 的训练 loss 是否在下降。初始 loss 大约在 2.3 附近因为 CrossEntropyLoss 对随机初始化的十分类模型输出结果自然接近 ln(10)。前两三个 epoch 从 2.3 快速掉到 0.1 是正常现象说明梯度在正常工作。如果 loss 在某个 epoch 开始反弹先怀疑学习率过大再看数据是否真的做了归一化。我一般会在每个 epoch 结束后加一个测试集准确率打印这样过拟合何时发生、从哪个 epoch 开始一眼就能看到。4. 解决 torchvision 下载 MNIST 的 404数据源不可达的替代路径4.1 现象与原因MNIST 官方数据源迁移带来的失效现在一个高频问题mnist.py 里明明写了 downloadTrue运行却报 HTTP 404而且没有任何代码层面的错误提示。这个现象的原因不是代码逻辑错误而是 torchvision 的 MNIST 接口内置了下载 URL而官方数据源经历过多次迁移。早期版本的数据源托管在个人服务器上后来迁移到云存储旧版本 torchvision 内置的 URL 自然就失效了。本机缓存里如果没有原始文件downloadTrue 就会触发一个已经失效的地址于是 404。很多人遇到这个报错会不断重试但这不是网络抖动重试没有意义。更可靠的做法是绕过自动下载手动把 MNIST 的四个文件放到本地目录让 datasets.MNIST 在校验文件完整后直接加载。这个方案对任何 torchvision 版本都有效而且不依赖外部网络环境。4.2 手动放置数据四个 gz 文件的目录结构与命名MNIST 原始数据由四个 gz 压缩文件组成文件名是固定的torchvision 内部硬编码了这些名字。正确做法是先把目录结构建好再把文件放进去。mkdir -p ./data/MNIST/raw cd ./data/MNIST/raw touch train-images-idx3-ubyte.gz touch train-labels-idx1-ubyte.gz touch t10k-images-idx3-ubyte.gz touch t10k-labels-idx1-ubyte.gz上面用 touch 只是示意文件名实际使用时应把四个真实文件放到这个目录下。数据放好后把代码里的 download 改为 Falsetrain_set datasets.MNIST( root./data, trainTrue, downloadFalse, transformtransform )downloadFalse 时torchvision 会检查 raw 目录是否存在四个文件如果齐全就直接加载不再访问网络。注意 gz 压缩文件不需要手动解压torchvision 会自动解压处理要是手动解压成 idx3-ubyte 文件放进去反而会被它忽略。文件名一个都不能改改一个字符就会当作文件缺失处理。提示先确认四个文件的大小和 MD5 值匹配官方内容否则 torchvision 校验失败还是会报错。4.3 替换数据源 URL适合源码受控的 torchvision 版本如果不想手动下载文件也可以直接修改 torchvision 内部的数据源地址。这个方案适用于你能够改动项目依赖源码的环境比如自己维护的虚拟环境。常见做法是替换 MNIST.resources 元组中的 URL 和 MD5 校验值from torchvision.datasets import MNIST MNIST.resources [ (https://example-mirror/train-images-idx3-ubyte.gz, f68b3c2dcbeaaa9fbdd348bbdeb94873), (https://example-mirror/train-labels-idx1-ubyte.gz, d53e105ee54ea40749a09fcbcd1e9432), (https://example-mirror/t10k-images-idx3-ubyte.gz, 9fb629c4189551a2d022faa399f2f0d8), (https://example-mirror/t10k-labels-idx1-ubyte.gz, ec29112dd5afa0611ce80d1b7f02629c) ] train_set MNIST(./data, trainTrue, downloadTrue, transformtransform)逻辑说明MNIST.resources 是一个元组列表每个元组包含下载地址和 MD5 校验值。你把它整体替换成可访问的镜像地址后调用 MNIST 时 downloadTrue 就会从新地址拉取数据。后面的 MD5 值是 MNIST 原始文件的标准校验码不要随意改动。这个方案的实际坑在于如果你用的是新版 torchvision内部可能已经改成了别的实现方式此时要优先检查当前版本源码而不是盲目套用。5. CNN 手写识别避坑四个常见问题与排查记录5.1 训练精度高、测试精度低过拟合来得比想象中早现象训练集准确率到 99%测试集却只有 96%而且随着 epoch 增加差距越拉越大。原因模型在后期开始记忆训练集的噪声特征尤其是小网络配大 epoch 时非常明显。解决先加验证集监控然后在全连接层加 dropout最后再考虑数据增强。MNIST 数据集本身很干净随机平移两个像素这类增强有时反而会损伤精度所以优先用正则化手段。如果加了 dropout 后训练集准确率掉到 97%但测试集提升到 97.5%这就是正则化生效的正常表现不要强求训练集 100%。5.2 维度不匹配view 那行报 RuntimeError现象运行到 forward 里的 view 时报 “shape [-1, 400] is invalid for input of size 3600” 之类。原因你在改卷积参数时调整了 kernel_size、padding 或网络深度导致卷积层输出的特征图尺寸不再是 16x5x5而 FC 层的输入维度还停留在旧数值。解决改完结构后先用假数据打印每层输出尺寸x torch.randn(1, 1, 28, 28) model LeNet() print(model.conv1(x).shape) print(model.conv2(F.max_pool2d(F.relu(model.conv1(x)), 2)).shape)把最后一次打印的形状手动算一遍然后更新 self.fc nn.Linear(16 * 5 * 5, 10) 里的 1655。不要靠猜打印出来的数值才是真实的。这个问题在改模型结构时几乎必出现提前打印形状能省下大量调试时间。5.3 像素没归一化loss 下降到一半开始明显震荡现象前几个 epoch 准确率正常上升到中间阶段 loss 开始抖动训练曲线像锯齿一样。原因最常出现在 transform 只用了 ToTensor没有接 Normalize或者自己手动读了原始像素值。原始像素值范围 0 到 255 太大梯度范数在不同 batch 间波动明显。解决确认 transform 里有 Normalize并且均值和标准差用的是 MNIST 的标准值 0.1307 和 0.3081。如果数据是自己读的需要在喂给模型前手动做一步 (x - mean) / std不能省。5.4 模型保存与加载checkpoint 换环境后加载报错现象训练时保存的模型换一台机器或换到 CPU 环境加载时报 key 不匹配或“Attempting to deserialize object on a CUDA device”。原因保存时用了整个模型对象而不是 state_dict或者加载时没有指定 map_location导致在无 GPU 的环境里强行反序列化 CUDA 张量。解决保存时只保存权重加载时明确指定设备。# 保存 torch.save(model.state_dict(), mnist_cnn.pth) # 加载 model LeNet() state torch.load(mnist_cnn.pth, map_locationcpu) model.load_state_dict(state)map_locationcpu 是这里的关键它让原本存在 GPU 上的权重被重映射到 CPU。如果你确实要在 GPU 上继续训练就把 map_location 改为当前设备字符串。我习惯把所有设备信息放在一个配置变量里避免每次推理都去改代码。6. 用混淆矩阵和自绘图验证确认这套 CNN 模型不是运气好训练完模型后最值得做的一件事不是看准确率而是看错在哪。MNIST 里最经典的易混对是 4 和 9、3 和 8、7 和 2用 sklearn 的 confusion_matrix 可以直观看到哪些类别互相干扰。我每次跑完都会输出一张混淆矩阵如果某个数字的错误集中在另一个数字上说明模型学到的是结构性特征而不是随机猜测。另一个验证手段是自绘数字。用 PIL 画一个 28x28 的图片做同样的预处理后喂给模型看输出的类别。这个方法能很快暴露训练脚本里隐藏的预处理差异比如训练时用了 Normalize推理时却忘了做同样的变换。from PIL import Image import torchvision.transforms as transforms def predict_image(model, image_path): transform transforms.Compose([ transforms.Resize((28, 28)), transforms.ToTensor(), transforms.Normalize((0.1307,), (0.3081,)) ]) img Image.open(image_path).convert(L) tensor transform(img).unsqueeze(0) model.eval() with torch.no_grad(): logits model(tensor) pred logits.argmax(dim1).item() return predmodel.eval() 这行不能省它会把 dropout 关闭推理时得到确定性输出。自绘图验证通过后还可以试试把 Adam 换成带 momentum 的 SGD学习率在第 12 个 epoch 时衰减为原来的十分之一通常准确率能从 98.8% 推到 99.2% 附近。这不是玄学小数据集上 SGD 配合学习率衰减收敛终点往往比 Adam 更稳。这个技巧我在多个手写识别项目里反复验证过值得作为固定习惯保留。希望这份完整的落地路径能帮到你愿你第一次跑通 mnist.py 时少走几段弯路。本文还有配套的精品资源点击获取