这是一个从 0 到 1 的手写数字识别学习项目。仓库围绕 MNIST 数据集，用 PyTorch 逐步搭建了一个完整的深度学习入门闭环：
- 数据集理解
- 张量与 shape
- 最小模型
- 训练循环
- 完整训练
- 模型评估
- 单张预测
- 外部图片预测 Web Demo
当前默认任务是：
手写数字识别（MNIST, 0~9 分类）
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt训练线性模型：
source .venv/bin/activate
python scripts/train_mnist_classifier.py训练 CNN 模型：
source .venv/bin/activate
python scripts/train_cnn_mnist_classifier.py训练数据增强 CNN 模型：
source .venv/bin/activate
python scripts/train_augmented_cnn_mnist_classifier.pysource .venv/bin/activate
python scripts/evaluate_mnist_classifier.py也可以指定模型：
python scripts/evaluate_mnist_classifier.py --model cnnsource .venv/bin/activate
python scripts/predict_single_image.pysource .venv/bin/activate
streamlit run demo/web_demo.pysource .venv/bin/activate
python scripts/evaluate_external_images.py也可以比较预处理方式：
python scripts/evaluate_external_images.py --preprocessing basic
python scripts/evaluate_external_images.py --preprocessing centered- 当前最小线性模型测试准确率约：
91.83% - 当前最小 CNN 模型测试准确率约：
96.77% - 当前数据增强 CNN 模型测试准确率约：
96.55% - 当前模型权重路径：
artifacts/minimal_mnist_classifier.pth - 当前 CNN 模型权重路径：
artifacts/minimal_cnn_mnist_classifier.pth - 当前数据增强 CNN 模型权重路径：
artifacts/augmented_cnn_mnist_classifier.pth
IMGRecognizer/
├── README.md
├── demo/
├── requirements.txt
├── scripts/
└── docs/
后续我们会把学习过程中的文档逐步放进 docs/ 目录，比如：
- 阶段说明
- 概念笔记
- 数据集说明
- 模型说明
- 训练记录
- 问题排查记录
当前已创建：
- 00 项目总览
- 01 环境准备
- 02 MNIST 数据集
- 03 张量与 shape
- 04 第一个最小模型与输入输出
- 05 训练循环
- 06 batch 和 epoch
- 07 正式训练模型
- 08 评估模型效果
- 09 单张图片预测
- 10 项目整理与复盘
- 11 外部图片预测与 Web Demo
- 12 为什么要升级到 CNN
- 13 最小 CNN 的输入输出 shape
- 14 训练最小 CNN
- 15 选择线性模型或 CNN 模型
- 16 数据增强
- 17 评估外部图片
- 18 改进外部图片预处理
- 19 外部图片失败样本诊断
- 18 改进外部图片预处理
- 从 0 开始理解一个深度学习项目的完整流程
- 亲手训练出一个可运行的手写数字识别模型
- 学会对模型进行测试、预测和分析
- 最终具备扩展到更复杂手写体识别任务的能力
目标：先不急着写代码，先知道整个项目到底在做什么。
- 理解什么是“手写体识别”
- 理解什么是样本、标签、特征
- 理解什么是训练集、测试集
- 理解什么是模型
- 理解什么是损失函数和优化器
- 理解什么是训练、验证、推理
- 理解为什么先从 MNIST 手写数字识别开始
完成标志：
- 能用自己的话解释一个图像分类项目的基本流程
目标：把项目运行环境准备好，并理解每一步为什么要做。
- 检查本机 Python 是否可用
- 创建并激活
.venv - 确认当前终端正在使用项目环境中的 Python
- 创建第一个最小依赖文件
- 安装基础依赖
- 验证依赖安装成功
完成标志：
- 能在当前项目中成功进入虚拟环境并运行 Python
目标：先研究数据，而不是一上来就训练模型。
- 理解 MNIST 数据集是什么
- 了解一张图片对应一个标签是什么意思
- 下载 MNIST 数据集
- 编写脚本读取一条样本
- 打印图片数据类型、形状和标签
- 理解为什么图片大小是
28x28 - 可视化几张样本图片
- 观察不同数字的样子
完成标志：
- 能清楚说出“模型输入的图片数据长什么样”
目标：理解深度学习里最基础的数据表示方式。
- 理解什么是张量（tensor）
- 理解图像数据在代码里的维度含义
- 理解单张图片和一批图片的区别
- 理解 batch 的概念
- 观察一批 MNIST 数据的 shape
- 理解标签张量长什么样
- 理解模型输入 shape 和输出 shape
完成标志：
- 能读懂一条图像分类数据在代码中的 shape
目标：先实现一个最简单、能跑通的模型。
- 理解为什么图像任务常用神经网络
- 初步认识全连接层和卷积层
- 先决定第一版模型结构
- 创建模型文件
- 编写模型类
- 编写
forward方法 - 用假数据测试模型是否能跑通
- 检查模型输出 shape 是否正确
完成标志：
- 模型能接收输入并输出 10 个类别分数
目标：把训练过程拆开，真正理解每一步在做什么。
- 理解一次训练迭代包含哪些步骤
- 理解前向传播
- 理解损失函数如何计算误差
- 理解反向传播的作用
- 理解优化器如何更新参数
- 编写单步训练逻辑
- 理解 epoch 和 batch 的关系
- 打印训练过程中的 loss
完成标志：
- 能自己解释“训练一轮”到底发生了什么
目标：把数据、模型、训练循环串起来，开始真正训练。
- 编写训练入口脚本
- 加载训练集 DataLoader
- 加载测试集 DataLoader
- 初始化模型
- 初始化损失函数
- 初始化优化器
- 跑通第 1 次训练
- 观察每轮训练的 loss 和 accuracy
- 保存模型权重文件
完成标志：
- 成功训练出第一个可用模型
目标：判断模型训练得怎么样，而不是只看它“能不能跑”。
- 在测试集上评估准确率
- 理解准确率的含义
- 查看模型在哪些样本上预测错误
- 分析常见错误类型
- 记录当前模型效果
完成标志：
- 能解释当前模型效果好不好，以及为什么
目标：让训练好的模型识别新的手写图片。
- 编写预测脚本
- 加载训练好的模型
- 读取单张图片
- 对图片做与训练一致的预处理
- 输出预测类别
- 输出预测置信度
- 测试几张图片的预测结果
完成标志：
- 模型能够对单张新图片完成预测
目标：把项目整理成一个清晰、可复用的学习成果。
- 整理目录结构
- 补充项目说明
- 记录训练命令
- 记录预测命令
- 记录当前模型效果
- 复盘整个项目学到了什么
完成标志：
- 项目达到“别人拿到也能看懂并运行”的状态
目标：在第一版闭环完成后，继续往更真实的任务推进。
- 认识数据增强
- 可视化数据增强效果
- 把数据增强接入 CNN 训练
- 理解为什么要升级到 CNN
- 编写最小 CNN shape 演示
- 尝试更强的模型结构并训练
- 支持评估脚本选择模型
- 支持 Web Demo 选择模型
- 支持自定义手写图片数据训练
- 支持外部图片预测
- 开发简单 Web Demo
- 支持英文手写字母识别
- 了解中文手写体识别的难点
- 尝试模型导出或部署
完成标志：
- 具备把入门项目扩展为更真实任务的基础能力
- 阶段 0：建立全局认知
- 阶段 1：环境准备
- 阶段 2：认识数据集
- 阶段 3：认识张量与输入输出
- 阶段 4：第一个最小模型
- 阶段 5：理解训练循环
- 阶段 6：正式训练模型
- 阶段 7：评估模型效果
- 阶段 8：单张图片预测
- 阶段 9：项目整理与复盘
- 阶段 10：能力升级（进行中）
- 当前已完成：检查本机 Python 是否可用
- 当前已完成：阶段 0 建立全局认知
- 当前已完成：阶段 1 环境准备
- 当前已完成：阶段 3 张量与输入输出
- 当前已完成：阶段 5 理解训练循环
- 当前已完成：阶段 6 正式训练模型
- 当前已完成：阶段 7 评估模型效果
- 当前已完成：阶段 8 单张图片预测
- 当前已完成：阶段 9 项目整理与复盘
- 当前所在阶段：阶段 10
- 当前下一步：扩充外部验证集，或让数据增强更接近外部图片风格