基于PyTorch的轻量级手写数字识别模型设计与实现

使用 torchvision.datasets.MNIST 自动下载 MNIST 数据集到本地 ./data 目录，加载训练集（60000 张）和测试集（10000 张），下载失败时给出明确错误提示并支持手动指定本地路径。

将 MNIST 图像（28×28 灰度）转换为 PyTorch Tensor 并归一化到 [0,1] 或标准化到 mean=0.1307, std=0.3081；支持可配置的 resize 操作以适应不同模型输入尺寸要求。

对训练集应用随机数据增强：随机旋转（±10°）、随机平移（最多 2 像素）、随机缩放（0.9~1.1 倍）、随机擦除（RandomErasing, p=0.25），增强操作通过 torchvision.transforms 组合实现，每种增强的开关和参数均可通过配置单独控制。

构建训练集和测试集的 DataLoader，支持可配置的 batch_size（默认 64）、shuffle（训练集开启、测试集关闭）、num_workers（默认 2），确保数据加载不成为训练瓶颈。

提供数据集基本信息打印：训练/测试集样本数、类别分布统计、单批次图像 shape；支持随机抽样展示 16 张样本图片及其标签，用于数据质量人工检查。

从 MNIST 训练集（60000 张）中按可配置比例（默认 9:1）随机划分出训练子集（54000 张）和验证集（6000 张），使用 torch.utils.data.random_split 实现；划分时固定随机种子（默认 42）保证可复现；验证集不参与训练、不应用数据增强，仅用于每个 epoch 的中间评估。

定义轻量级 CNN 网络类，包含 2~3 个卷积层（Conv2d + ReLU + MaxPool2d）和 1~2 个全连接层，控制总参数量在 100K~500K 范围；支持通过 __init__ 参数调整通道数、卷积核大小等超参数。

在网络中添加 Dropout 层（可配置 dropout 概率，默认 0.25）和 BatchNorm2d 层以防止过拟合并加速收敛；Dropout 训练时启用、评估时自动关闭。

实现 forward 方法完成网络前向传播：输入 [N,1,28,28] 图像张量，依次经过卷积层、池化层、展平、全连接层，输出 [N,10] 的 logits 张量；支持打印模型结构摘要（各层名称、输出形状、参数量）。

在模型类上增加 compute_params() 方法，返回模型总参数量、可训练参数量和理论计算量（FLOPs），用于量化"轻量级"优势；提供与 LeNet-5 和 3 层全连接网络的参数量对比输出。

额外实现两个对比网络：LeNet-5（经典 5 层 CNN）和 3 层全连接网络（MLP，隐藏层 256→128 神经元），保持输入输出接口一致，用于实验对比。

在基础轻量CNN之外，额外实现一个深度可分离卷积（Depthwise Separable Conv）变体：将标准Conv2d替换为torch.nn.Conv2d(depthwise=True)或自定义DepthwiseSeparableConv模块，对比标准卷积与深度可分离卷积在参数量、FLOPs和准确率上的差异，作为论文中"模型结构改进"的核心创新点。

定义模型注册/工厂机制，通过配置参数 model_variant 统一切换不同模型变体：cnn_light（标准轻量 CNN）、cnn_depthwise（深度可分离卷积变体）、cnn_no_bn（无 BatchNorm）、cnn_no_dropout（无 Dropout）、cnn_channel_reduced（通道缩减）、lenet5（LeNet-5）、mlp（全连接网络）；各变体共享相同输入输出接口（[N,1,28,28]→[N,10]），便于消融实验和对比实验自动遍历所有变体。

使用 CrossEntropyLoss 作为多分类损失函数；优化器可选 SGD（momentum=0.9）或 Adam（lr=0.001），学习率、weight_decay 等超参数通过配置文件或命令行参数可调。

实现单 epoch 训练循环：遍历 DataLoader 每个 batch，前向传播 → 计算 loss → 反向传播 → 优化器步进；记录每个 batch 的 loss 和 accuracy，打印 epoch 结束时训练集平均 loss 与准确率。

每个训练 epoch 结束后，在验证集（从训练集划分 10%，约 6000 张）上执行 model.eval() 模式进行完整评估：计算验证 loss、top-1 准确率；不计算梯度（torch.no_grad），打印验证集结果。根据验证集准确率保存 best_model.pth，测试集仅用于最终评估。

集成学习率调度策略（如 StepLR 每 5 epoch 衰减 0.1 倍 或 ReduceLROnPlateau 按验证 loss 自适应降低），记录每次学习率变化并打印到日志。

每 epoch 保存模型权重（state_dict）和优化器状态到 .pth 文件；保留验证准确率最高的 best_model.pth；支持从 checkpoint 断点恢复训练，继续未完成的 epoch。

通过 YAML/JSON 配置文件或命令行 argparse 统一管理训练超参数：epochs、batch_size、lr、optimizer、dropout、weight_decay、resume（是否从 checkpoint 恢复）、checkpoint_path（恢复路径）、是否启用数据增强等，训练开始时打印完整配置。

使用 logging 模块记录训练过程：每个 epoch 的训练 loss/acc、验证 loss/acc、学习率变化、耗时统计；日志同时输出到控制台和文件（train.log），支持可配置的日志级别。

训练启动时自动检测可用设备：优先 CUDA（torch.cuda.is_available()），其次 MPS（torch.backends.mps.is_available()），最后 CPU；将模型和每批次数据自动移动到所选设备；设备信息打印到训练日志首行，确保代码在有无 GPU 的环境下均可运行。

在训练循环中监控验证 loss：若连续 patience 个 epoch（默认 5）验证 loss 未创新低，则自动停止训练；停止时自动加载 patience 个 epoch 前保存的最佳模型权重；早停是否启用、patience 值、最小改善阈值（min_delta）均通过配置文件可调。

在完整测试集上评估模型，计算并输出 top-1 准确率、平均 loss、推理总耗时和平均每张耗时；支持模型自动选择 best_model.pth 进行评估。

使用 sklearn.metrics 计算精确率（Precision）、召回率（Recall）、F1-score（macro 平均）、混淆矩阵；输出每个数字类别（0-9）的各自指标，便于分析模型对不同数字的识别能力差异。

在相同的训练/测试流程下，分别训练轻量 CNN、LeNet-5 和全连接网络（MLP）三个模型，记录各模型的参数量、训练耗时（每 epoch）、测试准确率，以表格形式输出对比结果。

对轻量 CNN 进行消融实验：分别去除数据增强、去除 BatchNorm、去除 Dropout、减少通道数、替换标准卷积为深度可分离卷积等变体，记录每次变体的参数量变化和测试准确率，量化各组件贡献。

收集测试集中预测错误的样本（图片+真实标签+预测标签+置信度），按置信度降序排列，输出错误样本总数和占比，便于后续分析模型薄弱环节。

将对比实验（轻量CNN/LeNet-5/MLP）、消融实验（各变体）及量化模型（int8量化后）的所有指标汇总为一张 Markdown 表格或 CSV 文件，保存到 outputs/ 目录；表格包含模型/变体名称、参数量、每 epoch 平均耗时、最终测试准确率、F1-score、模型文件大小（.pth体积）六列，便于论文直接引用。

使用 matplotlib 绘制训练过程曲线：双轴图 — 左轴为 loss 曲线（训练 loss + 验证 loss），右轴为准确率曲线（训练 acc + 验证 acc）；x 轴为 epoch 数，保存为 PNG 图片。

使用 sklearn.metrics.ConfusionMatrixDisplay 或 seaborn.heatmap 绘制 10×10 混淆矩阵热力图，标注每个格子的样本数，显示每个数字被误分类为其他数字的分布情况。

选取 1~2 张测试样本，提取第一层卷积层的输出特征图（多通道），以子图网格形式展示各通道激活的可视化结果，配合原始输入图像，分析模型学习到的边缘/形状特征。

随机选取 16~25 张测试样本，以 4×4 或 5×5 网格展示每张图片，上方标注真实标签和预测标签（预测正确标绿色、错误标红色），输出单张汇总图。

绘制轻量 CNN、LeNet-5、MLP 三种模型的参数量（Params）和准确率（Accuracy）的双柱对比图或散点图，直观展示"轻量级"在参数量缩减与准确率保持之间的权衡。

使用PyTorch的hook机制提取最后一层卷积层的梯度，计算类别激活热力图（Grad-CAM），将热力图叠加到原始输入图像上生成叠加图；选取正确和错误预测样本各2~3张，展示模型决策时关注的图像区域，增强论文中可解释性分析的深度。

实现 predict(image_path) 函数：加载任意尺寸的手写数字图片 → 灰度转换 → resize 到 28×28 → 归一化 → 模型推理 → 返回预测类别（0-9）和置信度（softmax 概率）；支持批量图片预测。

支持将训练好的模型导出为 TorchScript（torch.jit.trace）或 ONNX 格式，导出后验证导出的模型与原模型在相同输入下输出一致（误差 < 1e-5），便于跨平台部署。

对单张推理结果，输出原图 + 预测类别 + 置信度柱状图（10 个类别的 softmax 概率分布），保存为结果图片，便于直观展示推理效果。

对单张图片推理和批量推理分别使用 time.perf_counter() 统计预处理耗时 + 模型前向耗时 + 后处理耗时，分项输出到日志；批量推理时额外统计吞吐量（images/sec）；为轻量化论证提供延迟与吞吐数据支撑。

推理接口在加载图片时进行鲁棒性校验：自动将 RGBA/RGB 图片转为灰度图；对非正方形图片居中裁剪后 resize 到 28×28；对格式不支持的文件给出明确错误提示（如「不支持的图片格式: .bmp」）；对全黑/全白等极端输入正常推理不崩溃。

基于Gradio库搭建Web推理演示界面：提供图片上传组件（支持拖拽和点击上传），上传后自动调用模型推理，显示预测数字类别、置信度百分比和10个类别的概率分布柱状图；界面作为main.py的额外子命令（gradio）启动，便于答辩现场实时演示。

项目必须基于 Python 3.13 和 PyTorch（CPU 版本即可，GPU 可选），依赖通过 pip/uv 管理，requirements.txt 或 pyproject.toml 列出所有依赖及版本范围。

项目目录结构：data/（数据集）、models/（模型定义 .py）、train/（训练脚本）、eval/（评估脚本）、visualize/（可视化脚本）、utils/（工具函数）、configs/（配置文件）、checkpoints/（模型权重）、logs/（日志）、outputs/（输出图片）。

核心依赖：torch、torchvision、matplotlib、numpy、scikit-learn、seaborn、pyyaml、pillow、gradio（推理演示界面）、thop（FLOPs 统计）；可选依赖：onnx、onnxruntime。所有依赖通过 uv pip install 一键安装。

固定 Python random、numpy、PyTorch（CPU/CUDA）的随机种子为可配置值（默认 42）；若 GPU 可用则设置 torch.backends.cudnn.deterministic=True、torch.backends.cudnn.benchmark=False 确保卷积操作确定性；种子值记录到训练日志首行，保证每次运行结果完全可复现。

提供 main.py 作为统一 CLI 入口，通过 argparse 子命令选择运行模式：train（训练+验证，支持 --resume 指定 checkpoint 路径恢复训练）、eval（测试集评估）、infer（单张/批量推理）、viz（生成所有可视化图表）、all（依次执行训练→评估→推理demo→可视化）、gradio（启动交互式推理演示界面）；每个子命令通过 --help 显示独立参数说明；支持 --config 指定 YAML 配置文件路径覆盖默认超参数。

使用torch.quantization对训练好的轻量CNN进行静态后训练量化（Post-Training Static Quantization），将模型权重和激活量化为int8；对比量化前后模型文件大小（.pth体积）、推理延迟（CPU单张耗时）和准确率变化，输出量化报告表格，验证"轻量级"在移动端/边缘端部署中的实际价值。