简介：这是一套基于TensorFlow 2.0的手写数字识别完整项目，面向深度学习初学者，适合作为AI课程设计与毕业设计参考。项目依托经典的MNIST数据集，包含6万张训练图片和1万张测试图片，所有图像均为28×28的灰度手写数字；代码使用Keras高层接口搭建卷积神经网络，依次由卷积层、池化层和全连接层组成，能够自动学习并提取图像中的数字特征，完成0到9共10个类别的准确分类。除数据加载、模型训练、评估外，还实现了模型的保存与加载，并提供了图形化操作界面：用户可以直接输入或绘制手写数字，系统会实时显示识别结果，上手非常友好。资源共20个文件，包括3个Python脚本（分别负责训练、测试与图形界面）、1个已训练好的h5模型文件、1个json配置、1个txt依赖说明，以及多个jpg/png图片素材，压缩包整体仅2.69MB，轻量实用。目前已有593人学习。通过学习此项目，能够理解即时执行、交叉熵损失、Adam优化器、卷积特征提取等核心概念，并掌握将深度学习模型封装为桌面应用的方法，是入门计算机视觉非常值得研究的一个实例。
1. 从MNIST到桌面应用：TensorFlow 2.0手写数字识别源码的完整落地
这个项目不是单纯的训练脚本，它把深度学习里最经典的“Hello World”——MNIST手写数字识别，做成了一条从数据加载、CNN模型训练、H5权重保存，到Tkinter图形界面实时推理的完整链路。源码包里有train.py、mnist_window.py、requirements.txt，以及已训练好的mnist_cnn.h5，解压后只要环境对齐就能直接跑。对于刚接触TensorFlow 2.0的开发者来说，这是一个能同时看清模型训练过程和桌面端推理逻辑的样例；对有经验的工程师而言，关注点则落在模型结构参数、图像预处理对齐和GUI事件循环的线程处理上。本文会按“原理选型→训练实现→界面推理→打包与排错”的顺序拆解这套源码，给出的代码都可以直接对照修改。
2. TensorFlow 2.0 + CNN：手写数字识别的模型选型与结构设计
2.1 为什么是TensorFlow 2.0和Keras
在2025年回看MNIST相关项目，TensorFlow 2.0的意义在于它彻底改变了1.x时代“先构图再Session.run”的写法。默认开启Eager Execution，调试时可以直接打印张量值；tf.keras作为高级API被整合为核心接口，层定义、损失函数、优化器都不需要额外引入。这个项目里的模型构建方式就是典型的Sequential堆叠，没有自定义训练循环，但“能跑通”和“知道为什么这么跑”是两回事。
从工程角度看，选择TensorFlow 2.0而不是PyTorch的原因很实际：部署生态里TensorFlow Serving、TFLite、OpenVINO对H5和SavedModel格式支持比较成熟，mnist_cnn.h5这种单文件权重可以被load_model直接加载，后续无论是转成TFLite还是嵌入Flask服务都很方便。源码里把train.py和mnist_window.py分开，也是为了让训练和推理两个阶段解耦。
2.2 MNIST数据集的关键属性
MNIST包含60000张28×28灰度训练图和10000张测试图，像素值范围是0～255，标签是0～9的整数。这些数字来自美国人口普查局和NIST的样本，虽然年代久远，但作为基准数据集依然适合验证卷积网络的效果。需要特别注意两点：一是图像是单通道，输入shape应为(28, 28, 1)；二是标签不是One-Hot向量，在TensorFlow中配合SparseCategoricalCrossentropy可以直接使用整数标签，不需要手动转换。
源码中大概率会做tf.keras.datasets.mnist.load_data()，这个函数会自动下载到~/.keras/datasets目录。如果网络受限，手动下载四个.gz文件放到对应路径也能被识别。验证数据是否就绪的简单办法是看目录下的mnist.npz文件是否存在。
2.3 CNN模型结构设计
手写数字识别用全连接网络也能达到97%左右，但CNN能把准确率推到99%以上。源码里mnist_cnn.h5对应的结构一般如下：
import tensorflow as tf from tensorflow.keras import layers, models model = models.Sequential([ layers.Reshape((28, 28, 1), input_shape=(28, 28)), layers.Conv2D(32, (3, 3), activation='relu'), layers.MaxPooling2D((2, 2)), layers.Conv2D(64, (3, 3), activation='relu'), layers.MaxPooling2D((2, 2)), layers.Flatten(), layers.Dense(128, activation='relu'), layers.Dropout(0.2), layers.Dense(10, activation='softmax') ]) model.summary()第一层Reshape把(28, 28)的灰度矩阵补成(28, 28, 1)，明确告诉卷积层这是单通道图像。两个卷积层分别用32和64个3×3卷积核，参数量可控，配合ReLU激活函数引入非线性。每层卷积后接MaxPooling2D，把特征图尺寸缩小一半，减少计算量并增强平移不变性。全连接层用128个神经元，Dropout(0.2)在训练时随机失活20%的神经元，防止过拟合。最后一层10个神经元加softmax，输出每个数字类别的概率分布。
| 层名 | 输出shape | 参数量 | 作用 |
|---|---|---|---|
| Reshape | (None, 28, 28, 1) | 0 | 补充通道维度 |
| Conv2D 32×3×3 | (None, 26, 26, 32) | 320 | 提取局部边缘特征 |
| MaxPooling2D | (None, 13, 13, 32) | 0 | 下采样，保留主要特征 |
| Conv2D 64×3×3 | (None, 11, 11, 64) | 18496 | 提取更高层抽象特征 |
| MaxPooling2D | (None, 5, 5, 64) | 0 | 再次缩小特征图 |
| Flatten | (None, 1600) | 0 | 展平为全连接输入 |
| Dense 128 | (None, 128) | 204928 | 特征组合 |
| Dropout | (None, 128) | 0 | 防止过拟合 |
| Dense 10 | (None, 10) | 1290 | 分类输出 |
参数量按卷积层(3×3×输入通道+1)×输出通道计算，第一层是(3×3×1+1)×32=320，第二层是(3×3×32+1)×64=18496。Dense层参数量则是输入维度×输出维度+偏置，128层占用最大。理解这个表格后，改结构时就能预估显存和训练时间的增长。
2.4 损失函数、优化器与评估指标
模型编译时通常选择tf.keras.optimizers.Adam作为优化器，学习率默认0.001。Adam结合了动量和自适应学习率的优点，对MNIST这种小规模数据收敛很快，通常5个epoch就能达到98%以上。损失函数使用SparseCategoricalCrossentropy，因为标签是整数而不是One-Hot编码；如果标签是One-Hot，则必须改用CategoricalCrossentropy，这是初学者最容易踩的错。评估指标用accuracy，训练过程中会自动输出训练集准确率和验证集准确率。
3. 训练脚本train.py：数据流水线与模型保存
3.1 数据加载与归一化
源码中的train.py负责从零训练模型并保存H5权重。训练前需要对原始像素做归一化，把0～255的整数映射到0～1的范围。直接除以255.0即可，但要注意x_train.astype('float32')必须显式转换，否则整数除法会直接清零。
mnist = tf.keras.datasets.mnist (x_train, y_train), (x_test, y_test) = mnist.load_data() x_train = x_train.astype('float32') / 255.0 x_test = x_test.astype('float32') / 255.0 x_train = x_train[..., tf.newaxis] x_test = x_test[..., tf.newaxis] print(f"训练集: {x_train.shape}, 测试集: {x_test.shape}")x_train[..., tf.newaxis]用切片在最后一个维度增加一维，效果等同于reshape(-1, 28, 28, 1)。归一化对CNN至关重要，如果跳过，卷积核的梯度更新会因像素值跨度大而不稳定，导致准确率卡在90%左右上不去。验证时也要做同样处理，否则训练好的模型会把灰度值847这类输入当成噪声。
3.2 训练参数与回调函数
训练过程中，ModelCheckpoint回调是保留最优模型的关键。默认save_best_only=True时，只有验证准确率提升才会覆盖H5文件，这样即使训练后期过拟合，磁盘上的权重仍然是峰值状态。
callbacks = [ tf.keras.callbacks.ModelCheckpoint( filepath='mnist_cnn.h5', monitor='val_accuracy', save_best_only=True, save_weights_only=False, verbose=1 ) ] history = model.fit( x_train, y_train, batch_size=128, epochs=10, validation_data=(x_test, y_test), callbacks=callbacks ) model.save('mnist_cnn.h5')batch_size设为128是一个折中值：太小则梯度更新频繁，震荡大；太大则单个epoch时间长，且内存占用高。epochs=10对MNIST来说足够，继续增加只会把验证准确率推到99.3%左右后陷入平台期。save_weights_only=False表示保存完整模型结构和权重，这样mnist_window.py可以用tf.keras.models.load_model('mnist_cnn.h5')直接加载，不需要再复制一遍网络结构。
3.3 训练后的评估
训练结束后，model.evaluate会在测试集上给出最终的损失和准确率。这里有几个细节值得注意：如果测试集和训练集都在load_data后做过相同归一化，结果才有可比性；如果将模型用于GUI推理，画布上采集的图像也必须先变成28×28单通道浮点数，再除以255.0，否则识别结果会偏移。
test_loss, test_acc = model.evaluate(x_test, y_test, verbose=0) print(f"测试集损失: {test_loss:.4f}, 准确率: {test_acc:.4f}") # 保存为H5后验证加载 loaded_model = tf.keras.models.load_model('mnist_cnn.h5') loaded_loss, loaded_acc = loaded_model.evaluate(x_test, y_test, verbose=0) print(f"H5加载后损失: {loaded_loss:.4f}, 准确率: {loaded_acc:.4f}")第二次evaluate是为了确认H5文件没有损坏，且加载后的模型与训练时状态一致。如果loaded_acc比test_acc低很多，说明保存过程有问题，最常见原因是回调里设置了save_weights_only=True却用load_model加载——此时应该用model.load_weights而不是load_model。
3.4 requirements.txt的环境约束
源码中的requirements.txt通常会锁定tensorflow==2.x和Pillow的版本。安装时建议先创建独立虚拟环境，再用pip install -r requirements.txt。TensorFlow 2.10以上版本自带Keras，不需要单独安装keras包。如果希望在WSL2里训练，无界面环境可以直接跑train.py，但后续运行GUI需要配置WSLg或X Server，这部分放在最后一章说明。
4. 图形化界面推理：mnist_window.py的实现与图像预处理
4.1 Tkinter画布的手写输入设计
mnist_window.py是整套源码里最直观的部分。Tkinter是Python标准库，不需要额外安装，比PyQt更轻量。界面通常包含一个Canvas组件用于鼠标绘制数字，一个“识别”按钮触发预测，以及一个“清空”按钮重置画布。核心难点不是按钮布局，而是把画布上的任意笔画转成模型能接受的28×28张量。
画布绘制一般通过绑定鼠标事件实现：
import tkinter as tk class DigitCanvas: def __init__(self, root): self.canvas = tk.Canvas(root, width=280, height=280, bg='white') self.canvas.pack() self.canvas.bind('<B1-Motion>', self.paint) self.last_x, self.last_y = None, None def paint(self, event): x, y = event.x, event.y if self.last_x is not None: self.canvas.create_line( self.last_x, self.last_y, x, y, width=20, fill='black', capstyle=tk.ROUND, smooth=True ) self.last_x, self.last_y = x, ywidth=20的线条模拟真实手写笔迹的粗细，capstyle=tk.ROUND让笔画端点圆润，避免出现断点。last_x和last_y必须跨事件保留，否则画出的是一条条分离的短线，模型看到的图形不连续。部分源码还会用canvas.coords获取矩形区域，但最简单的方式是直接把整个画布导出为图像。
4.2 画布图像转28×28张量
这是GUI推理中最容易出错的环节。画布是280×280像素，MNIST模型期望28×28输入，直接缩小会让笔画变得模糊。正确处理流程是：先把画布保存为灰度图，取数字实际占用的边界框，裁剪后按比例缩放并居中到28×28区域。如果省略边界框裁剪，空白边距会占据大部分图像，数字主体被压缩到几个像素内，识别结果会频繁出错。
from PIL import Image, ImageOps import io import numpy as np def canvas_to_tensor(canvas): # 保存画布为PNG字节流 canvas.postscript(file='temp.eps') # Tkinter Canvas无直接save，需先转EPS img = Image.open('temp.eps').convert('L') img = ImageOps.invert(img) # 白底黑字 -> 黑底白字？不，MNIST是黑底白字 # 计算非零像素边界框 bbox = img.getbbox() if bbox is None: return np.zeros((28, 28, 1), dtype=np.float32) img = img.crop(bbox) img.thumbnail((20, 20), Image.LANCZOS) # 创建28x28白底画布，将数字居中 canvas_28 = Image.new('L', (28, 28), 0) offset_x = (28 - img.width) // 2 offset_y = (28 - img.height) // 2 canvas_28.paste(img, (offset_x, offset_y)) arr = np.array(canvas_28, dtype=np.float32) / 255.0 return arr.reshape(1, 28, 28, 1)这里有个常见的陷阱：img.getbbox()返回的是非零像素的边界框，但Tkinter画布默认背景是白色，数字是黑色，非零区域就是数字本身，无需再反转。如果使用ImageOps.invert，反而会把背景变成黑色，导致识别结果完全错误。thumbnail((20, 20))保持宽高比缩小到最长边20像素以内，然后再粘贴到28×28画布中央，可以保留笔画的原始比例。
4.3 模型加载与实时预测
识别按钮的回调函数需要加载H5模型并执行推理。源码中更合理的做法是在窗口初始化时加载一次模型，避免每次识别都重新读文件。
class App: def __init__(self, root): self.model = tf.keras.models.load_model('mnist_cnn.h5') self.canvas_widget = DigitCanvas(root) self.result_label = tk.Label(root, text='等待输入...', font=('Arial', 18)) self.result_label.pack() btn_predict = tk.Button(root, text='识别', command=self.predict) btn_predict.pack() def predict(self): tensor = canvas_to_tensor(self.canvas_widget.canvas) pred = self.model.predict(tensor, verbose=0) digit = int(np.argmax(pred[0])) confidence = float(np.max(pred[0])) self.result_label.config(text=f'识别结果: {digit} 置信度: {confidence:.2f}')model.predict返回的是形状为(1, 10)的概率分布，argmax给出最终数字，max给出置信度。在实际使用中，如果置信度低于0.6，更合理的交互是提示用户重写，而不是硬给出一个数字。这个判断逻辑在源码里可以自行添加。
4.4 常见推理错误排查
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 识别结果全是0或1 | 图像反转错误，背景为白色前景为黑色 | 检查是否误用ImageOps.invert |
| 小数字识别正常，大数字识别差 | 边界框裁剪后未缩放到合适尺寸 | thumbnail最大边设20，而不是直接resize到28 |
| 笔画断断续续 | 鼠标事件未绑定<B1-Motion> | 确认绑定的是拖动事件而非<Button-1> |
| GUI点击识别无响应 | 模型加载失败或路径不对 | 用绝对路径加载H5，并在启动时打印模型输入shape |
| 预测结果与手写明显不符 | 测试时图像没有归一化 | 确认像素除以255.0后范围在0～1之间 |
如果model.predict报shape错误，用print(model.input_shape)确认模型输入是(None, 28, 28, 1)还是(None, 28, 28)。源码中模型第一层是Reshape，所以输入可以是后者，但如果自己训练时去掉了Reshape层，GUI这边就必须补齐维度。
5. 进阶：模型评估矩阵、WSL2图形环境与PyInstaller打包
5.1 用混淆矩阵检验模型边界
准确率只能反映整体表现，手写数字识别里“4”和“9”、“3”和“8”是最容易混淆的组合。在train.py的基础上扩展一个评估脚本，可以一次性看清模型的错误模式：
from sklearn.metrics import confusion_matrix import seaborn as sns import matplotlib.pyplot as plt y_pred = np.argmax(model.predict(x_test, verbose=0), axis=1) cm = confusion_matrix(y_test, y_pred) plt.figure(figsize=(8, 6)) sns.heatmap(cm, annot=True, fmt='d', cmap='Blues') plt.xlabel('Predicted') plt.ylabel('True') plt.savefig('confusion_matrix.png', dpi=150)如果cm[4][9]或cm[9][4]数值偏高，说明模型对这两种数字的区分度不够。一个有效技巧是增加训练轮次并配合数据增强，例如给训练图像加入小幅度旋转和位移。另一个思路是把第一个卷积层的卷积核数量从32增加到48，但这会带来约50%的参数量增加，训练时间也会相应延长。
5.2 WSL2中的图形化界面运行
很多开发者的训练环境是WSL2 Ubuntu，但默认没有显示服务器。如果直接执行python mnist_window.py，会报No display name and no $DISPLAY environment variable错误。WSL2更新到较新版本后自带WSLg支持，可以在Windows桌面直接显示Linux GUI程序。
验证方法是运行echo $DISPLAY，如果不为空说明WSLg已启用。若为空，则需要安装x11-apps并启动dbus服务。禁用WSLg的情况下，可以使用export DISPLAY=:0配合VcXsrv，但要注意防火墙放行6000端口。对多数人来说，最省事的方案是把Tkinter代码放到Windows侧的Python环境运行，模型H5文件跨平台通用。
5.3 PyInstaller打包成独立exe
mnist_window.py依赖模型文件，打包时要把mnist_cnn.h5作为数据文件一并加入。PyInstaller默认不会包含非Python文件，需要在spec文件里显式声明：
pyinstaller -F -w --add-data "mnist_cnn.h5;." mnist_window.py-F生成单文件，-w去掉控制台窗口，--add-data路径分隔符在Windows上是分号，Linux/Unix上是冒号。打包后的exe运行时，load_model('mnist_cnn.h5')会失败，因为资源被解压到临时目录。正确写法是用sys._MEIPASS拼接路径：
import sys import os def resource_path(relative_path): base_path = getattr(sys, '_MEIPASS', os.path.abspath('.')) return os.path.join(base_path, relative_path) model = tf.keras.models.load_model(resource_path('mnist_cnn.h5'))这个函数在源码态下返回当前目录，打包态下返回PyInstaller解压临时目录。如果漏掉这一步，exe在别人的电脑上会直接崩溃，且终端窗口不显示错误，排查难度极高。打包完成后，建议用VMWare或另一台机器实测一次，重点验证画布绘制和识别按钮是否正常。
本文还有配套的精品资源，点击获取
