简介：面向深度学习入门者与图像识别初学者的 TensorFlow 手写文字识别案例包，围绕卷积神经网络与 Softmax 回归两条实现路径，串联数据预处理、模型搭建、训练验证、保存与预测等完整流程，帮助读者理解手写字符识别的工程落地方式。压缩包共 6 个文件，以 4 个 Python 源码为核心，另配 1 份 PDF 说明和 1 个 zip 压缩包，整体约 2.32MB，体积轻便，便于按模块阅读与本地运行。该资源已有 1584 人学习，具备一定参考热度。源码案例覆盖输入数据读取、网络模型定义、训练与识别脚本等环节，PDF 可辅助梳理整体思路；读者可据此对照 CNN 中卷积层、池化层与全连接层的组织方式，理解损失函数、优化器选择、训练轮次与过拟合验证等关键点，也能比较 Softmax 回归与卷积模型在特征学习上的差异，适合作为课程实验、毕业设计前期练手或深度学习项目入门模板，便于后续迁移到更复杂的图像分类任务。

1. 先明确需求：手写文字识别这套源码要交付什么

答辩前一晚，A同学把训练脚本跑出 99.2% 的测试准确率，第二天评委递来一张自己手写的数字照片，模型认错了。这类失败在手写文字识别项目里太常见：数据集上的分数好看，一碰真实笔迹就失效。这份基于 tensorflow框架 的 手写文字识别 python 源码案例，要解决的核心问题，是把数据管线、模型结构、训练回调、单图推理四段串成一条能交付的链路——分数可复现、输入能对上、错例能解释。它适合正在做图像识别方向毕设或课设的学生，也适合需要快速搭一个字符识别原型、再往上叠加业务逻辑的开发者。下面按需求、设计、实现、验收的顺序拆开讲，代码和参数可以直接搬。

2. 总体架构与技术选型：四层数据流与六个模块的职责边界

这套方案的整体结构可以概括成一条单向数据流：原始图片 → 预处理管线 → 卷积网络 → 概率输出 → 业务层。四个环节之间只用「张量形状」和「文件路径」两种约定通信，任何一环被替换，其余环节都不需要改动。之所以强调这种解耦，是因为手写识别项目最常见的失控方式，就是预处理写在训练脚本里、推理时又写一遍，两遍逻辑不一致，最后谁也说不清错在哪。

2.1 为什么用 CNN 而不是全连接网络或传统特征

28×28 的灰度图拉平是 784 维向量。如果直接接一个 512 维全连接层，仅这一层就有 401408 个参数，而它拿到的是一串被打乱的空间顺序——像素 (0,0) 和 (27,27) 在向量里是邻居，但在图上毫无关系。卷积层靠局部感受野和权值共享解决这个问题：一个 3×3 的卷积核在整张图上滑动，参数只有 3×3×通道数，却能捕捉笔画端点、交叉、弧线这类局部模式；再叠加池化做下采样，感受野逐层扩大，高层就能组合出「闭合环」「竖折」这样的结构。

传统方案 HOG + SVM 也能跑到 98% 左右，但它依赖人工设计的梯度方向直方图，对笔画粗细、倾斜角度、书写速度带来的形变很敏感，换一批笔迹就要重新调特征参数。CNN 把特征提取交给数据自己学，代价是需要足够样本和算力——MNIST 的 6 万张训练图在普通笔记本 CPU 上十几分钟就能跑完一轮，这个代价完全可以接受。

选型上还有两个现实考虑。一是框架生态：TensorFlow 的tf.keras把层定义、训练循环、模型保存、部署导出都收在同一套 API 下，做课设时不用东拼西凑。二是可解释性：卷积层的特征图可以直接可视化出来，答辩时把第一层 32 个卷积核的响应图一贴，「模型在看什么」这个问题就有答案了。

2.2 目录结构与模块职责

源码目录按职责切分，不按文件类型切分。很多人习惯把所有脚本平铺在根目录，训练、推理、界面全混在一起，改一个参数要翻三个文件。合理的划分大致是这样：

handwriting-recognition/ ├── config.py # 超参、路径、随机种子集中管理 ├── data/ │ ├── loader.py # 数据集加载、划分、标签编码 │ └── preprocess.py # 归一化、居中、反相（训练与推理共用） ├── models/ │ ├── cnn.py # 网络结构定义，只返回 model 对象 │ └── best.keras # 训练产物，由回调自动写入 ├── train.py # 训练入口，读 config，调 loader + cnn ├── predict.py # 单图/批量推理入口 ├── app.py # 界面层，只调 predict 暴露的函数 └── requirements.txt # 锁定依赖版本

关键点在于data/preprocess.py必须是训练和推理的唯一入口。训练时它接收 ndarray，推理时它接收图片路径读出来的 ndarray，内部逻辑完全一样。这条规则看起来朴素，却能挡掉后面八成以上的「训练好、实战差」问题。

config.py单独存在也有必要。学习率、batch size、epoch 数、模型保存路径、随机种子这些散落在各处的常量，集中之后做对比实验只要改一个文件，答辩时也能直接说清「我用了什么配置」。

2.3 张量形状与接口约定

四层数据流之间的契约必须写死，写死在代码注释里也行：

单张推理时把 (28,28,1) 扩一维成 (1,28,28,1)，因为 Keras 模型永远按批次处理输入。这个细节漏掉会直接报形状不匹配，但错误信息往往指向网络内部，新手容易在卷积层上找半天。

提示：把上面这张表直接写进preprocess.py的模块 docstring，后面任何人接手都不用猜。

3. 数据管线与预处理：从 28×28 像素到可训练张量

数据和特征决定了模型上限，网络结构和调参只是在逼近这个上限。手写识别看起来是「干净数据集上的简单任务」，但预处理里每一个偷懒的地方，都会在推理阶段加倍还回来。

3.1 数据集加载、划分与标签编码

Keras 内置了 MNIST 的下载接口，第一次运行会自动拉取并缓存到本地。加载后得到四个数组：60000 张训练图、10000 张测试图，标签是 0–9 的整数。

import tensorflow as tf def load_dataset(val_ratio=0.1, seed=42): """返回 (x_train, y_train), (x_val, y_val), (x_test, y_test)""" (x_train, y_train), (x_test, y_test) = tf.keras.datasets.mnist.load_data() # 从训练集切出验证集，测试集全程不参与调参 n = x_train.shape[0] split = int(n * (1 - val_ratio)) x_val, y_val = x_train[split:], y_train[split:] x_train, y_train = x_train[:split], y_train[:split] return (x_train, y_train), (x_val, y_val), (x_test, y_test)

这里有个容易被忽略的点：验证集必须从训练集里切，测试集在整个调参周期内不能碰。有人图省事用测试集当验证集，通过validation_data=(x_test, y_test)训练，最后报出来的准确率是「被模型看过一万遍的数据上的准确率」，这个数字在答辩现场经不起追问。切 10% 出来做验证，训练集还剩 54000 张，对 MNIST 这个规模完全够用。

标签编码要看损失函数怎么选。用categorical_crossentropy就得把整数标签转成 one-hot：

NUM_CLASSES = 10 y_train = tf.keras.utils.to_categorical(y_train, NUM_CLASSES) y_val = tf.keras.utils.to_categorical(y_val, NUM_CLASSES) y_test = tf.keras.utils.to_categorical(y_test, NUM_CLASSES)

如果不想转，就用sparse_categorical_crossentropy配整数标签，两者不能混。混用的典型症状是 loss 一直降不下去、准确率卡在 10% 左右——模型输出 10 维概率，标签却是形状 (N,1) 的整数，广播之后算出来的梯度毫无意义。

3.2 归一化与通道扩维

原始像素是 0–255 的整数，直接喂进网络会让梯度尺度失衡，学习率稍微设大一点就发散。除以 255 是最省事的归一化，把输入压到 [0,1]：

def normalize(x): x = x.astype("float32") / 255.0 return x[..., tf.newaxis] # (N,28,28) -> (N,28,28,1) x_train, x_val, x_test = normalize(x_train), normalize(x_val), normalize(x_test)

[..., tf.newaxis]等价于np.expand_dims(x, -1)，作用是在最后补一个通道维。Conv2D 要求输入是 4 维(batch, height, width, channels)，灰度图通道数为 1。少了这一步，Keras 会把 (28,28) 当成 (28,28) 的二维输入，报错信息是「expected 4D but got 3D」，位置指向模型第一层，实际病根在数据。

归一化还有一个隐性收益：它让「反相」这个操作变得简单。MNIST 的约定是黑底白字，笔画像素值高、背景接近 0。如果用户拍的是白纸黑字，走一遍255 - x就能对齐，而这个操作只在 [0,255] 区间内有明确物理意义，所以反相要在除以 255 之前做。

3.3 用 tf.data 搭一条不会卡住 GPU 的输入流水线

小数据集上model.fit(x_train, y_train)直接传数组也能跑，但一旦打开数据增强、或者换到更大的字符集，瓶颈就会从 GPU 转移到数据供给上。tf.data的作用是把加载、打乱、批处理、预取拆成流水线的各个阶段，让 CPU 预处理和 GPU 计算重叠起来。

AUTOTUNE = tf.data.AUTOTUNE def make_dataset(x, y, batch_size=128, training=False): ds = tf.data.Dataset.from_tensor_slices((x, y)) if training: ds = ds.shuffle(buffer_size=10000, seed=42, reshuffle_each_iteration=True) ds = ds.map(augment, num_parallel_calls=AUTOTUNE) return ds.batch(batch_size).prefetch(AUTOTUNE)

shuffle的buffer_size取 10000 是个经验值，太小打乱不充分，太大会吃掉内存；reshuffle_each_iteration=True保证每个 epoch 的批次顺序都不同，否则模型会学到批次的排列规律。prefetch(AUTOTUNE)让下一批数据在当前批计算的同时准备好，这一步对整体吞吐的提升往往比调网络结构更明显。

数据增强要克制。手写数字不能用水平翻转——6 翻转之后不再是合法数字，模型会被教坏。合理的增强是轻微旋转、平移、缩放：

augment = tf.keras.Sequential([ tf.keras.layers.RandomRotation(0.05), # ±18° tf.keras.layers.RandomTranslation(0.08, 0.08), # 上下左右各 8% tf.keras.layers.RandomZoom(0.08), # ±8% 缩放 ], name="augment")

这三个层只在训练时激活，推理时自动关闭，不需要额外写分支。幅度参数别贪大，0.05 的旋转已经是 ±18 度，再大就会出现「横着的 1」这种在真实场景里几乎不存在的样本。

如果内存宽裕，可以在shuffle之前插一句.cache()，把解码后的张量缓存在内存里。5.4 万张 28×28 的 float32 图大约 170MB，普通机器完全扛得住，换来的是每个 epoch 省掉一次全量数据转换。

4. 模型构建与训练闭环：卷积层堆叠、回调与持久化

4.1 网络逐层设计与参数量核算

结构不用追求深。手写数字的判别信息集中在笔画形状上，两层卷积加两层池化就足以把感受野撑到覆盖整张图。下面这个结构在 MNIST 上稳定跑到 99% 以上，参数量约 42 万，模型文件不到 5MB，CPU 单张推理在几十毫秒量级。

import tensorflow as tf def build_cnn(num_classes=10): return tf.keras.Sequential([ tf.keras.layers.Input(shape=(28, 28, 1)), # 第一组：32 个 3x3 卷积核，捕捉笔画端点与短弧 tf.keras.layers.Conv2D(32, 3, padding="same", activation="relu"), tf.keras.layers.BatchNormalization(), tf.keras.layers.MaxPooling2D(2), # 28x28 -> 14x14 # 第二组：64 个卷积核，组合出闭合环、交叉等结构 tf.keras.layers.Conv2D(64, 3, padding="same", activation="relu"), tf.keras.layers.BatchNormalization(), tf.keras.layers.MaxPooling2D(2), # 14x14 -> 7x7 tf.keras.layers.Flatten(), # 7x7x64 = 3136 tf.keras.layers.Dense(128, activation="relu"), tf.keras.layers.Dropout(0.5), # 抑制全连接层过拟合 tf.keras.layers.Dense(num_classes, activation="softmax"), ], name="digit_cnn")

逐层算一下参数量，答辩时被问到能直接答：

参数量的分布很说明问题：卷积层只占 4.5%，剩下的九成集中在全连接层。这也是为什么 Dropout 要放在 Dense-128 之后——过拟合的风险主要来自那里，卷积层反而因为权值共享天然带有正则效果。

padding="same"保证卷积后尺寸不变，尺寸变化全部交给池化层，这样每层的输入输出形状一眼可推。BatchNormalization放在激活之后、池化之前，作用是稳定各层输入分布，让较大的学习率也能收敛；代价是训练时多了一点计算，推理时可以折叠进卷积核，不影响速度。

4.2 编译配置：损失函数与优化器的搭配

model = build_cnn() model.compile( optimizer=tf.keras.optimizers.Adam(learning_rate=1e-3), loss="categorical_crossentropy", # 标签已 one-hot；整数标签改用 sparse_ metrics=["accuracy"], ) model.summary()

损失函数选交叉熵而不是 MSE，因为输出层是 softmax，交叉熵配 softmax 的梯度形式是p - y，预测错得越离谱梯度越大，收敛快；MSE 配 softmax 会出现梯度饱和，训练前期几乎不动。

优化器用 Adam，学习率 1e-3 是这个规模下的稳妥起点。想再挤一点精度可以换AdamW加权重衰减，但对课设级别的任务，收益不明显，反而多一个要解释的超参。评估指标只留 accuracy 就够了，top-3 准确率在 10 分类任务上没有展示价值。

4.3 训练循环与三个关键回调

训练本身只有一行fit，真正决定成败的是回调。三个回调各管一件事：留最好的模型、及时停、动态降学习率。

callbacks = [ # 只保存验证集上表现最好的那一版权重 tf.keras.callbacks.ModelCheckpoint( filepath="models/best.keras", monitor="val_accuracy", save_best_only=True, verbose=1, ), # 验证集 3 轮不涨就停，并回滚到最佳权重 tf.keras.callbacks.EarlyStopping( monitor="val_accuracy", patience=3, restore_best_weights=True, ), # 验证损失 2 轮不降，学习率减半 tf.keras.callbacks.ReduceLROnPlateau( monitor="val_loss", factor=0.5, patience=2, min_lr=1e-6, ), ] history = model.fit( train_ds, validation_data=val_ds, epochs=15, callbacks=callbacks, )

ModelCheckpoint的monitor必须和EarlyStopping保持一致，都用val_accuracy。如果一边盯 accuracy 一边盯 val_loss，可能出现「早停说有更优权重，检查点却没保存」的错位，最后加载的是最后一轮而非最佳轮，白训。

restore_best_weights=True是个容易被省掉的参数。不加的话，fit结束时模型停在最后一轮的权重上，而最后一轮往往已经过拟合，验证准确率比峰值低零点几个百分点。加上之后，训练结束时的模型状态就是峰值状态。

训练完把曲线画出来存成图片，history.history里有loss、accuracy、val_loss、val_accuracy四条线。答辩时这张图比任何口头描述都有说服力：训练损失持续下降、验证损失在某个点后抬头，就是过拟合的教科书图像，你能指出这个点，说明你知道模型在干什么。

4.4 保存、加载与单图推理

模型保存格式建议统一用.keras。.h5是旧版格式，对自定义层和子类化模型支持不完整；SavedModel 目录形式适合部署但不利于单文件分发。.keras是官方推荐格式，单文件、带结构、带优化器状态。

推理侧的核心不是调predict，而是让输入分布和训练时一致。真实手写照片的问题通常有三个：白底黑字（和 MNIST 反相）、笔画没居中（MNIST 的数字都做过质心对齐）、笔画粗细和图内占比不同。所以推理前的预处理不能只是resize：

import numpy as np from PIL import Image def preprocess_image(path, canvas=28, box=20): """把任意手写照片对齐成 MNIST 风格的 (28,28) float32""" arr = np.array(Image.open(path).convert("L"), dtype=np.float32) # 1) 白底黑字 -> 黑底白字 if arr.mean() > 127: arr = 255.0 - arr # 2) 按非零像素裁出笔画外接框 ys, xs = np.where(arr > 30) if len(xs) == 0: return None # 空图直接拒绝，别让模型瞎猜 arr = arr[ys.min():ys.max() + 1, xs.min():xs.max() + 1] # 3) 等比缩放到 20x20，保留长宽比，避免数字被拉扁 h, w = arr.shape scale = box / max(h, w) arr = np.array(Image.fromarray(arr.astype(np.uint8)) .resize((max(1, int(w * scale)), max(1, int(h * scale))))) # 4) 贴到 28x28 黑底画布中央 out = np.zeros((canvas, canvas), dtype=np.float32) oy, ox = (canvas - arr.shape[0]) // 2, (canvas - arr.shape[1]) // 2 out[oy:oy + arr.shape[0], ox:ox + arr.shape[1]] = arr return (out / 255.0)[..., np.newaxis]

四个步骤对应四类失败原因：不做反相，模型看到的是「背景亮、笔画暗」，相当于把输入取反；不裁外接框，一张 1080p 照片里数字只占一小块，缩到 28×28 后笔画糊成几个像素；不等比缩放，写瘦长的 1 会被拉成方块；不居中，MNIST 训练时数字的质心基本在图像中心，偏移过大直接掉点。

推理入口：

def predict_digit(path, model_path="models/best.keras"): model = tf.keras.models.load_model(model_path) x = preprocess_image(path) if x is None: return {"label": None, "confidence": 0.0, "reason": "空白图片"} prob = model.predict(x[np.newaxis, ...], verbose=0)[0] # (10,) idx = int(np.argmax(prob)) return { "label": idx, "confidence": float(prob[idx]), "top3": [(int(i), float(prob[i])) for i in np.argsort(prob)[-3:][::-1]], }

返回confidence和top3是为了让结果可解释。置信度低于 0.6 时，界面层可以提示「识别不确定，请重写」，而不是硬给一个错答案。这个设计在演示环节非常加分——评委看到模型会说「我不确定」，反而更相信它的确定判断。

界面层（无论是 Tkinter 画板还是网页上传框）只负责拿到图片路径、调predict_digit、渲染返回值，不碰任何 TensorFlow API。这样换界面不用改模型，换模型不用改界面。

5. 避坑与常见问题排查：五类最容易出问题的地方

5.1 训练集 99%，自己写的字全错

现象：evaluate报出 99.2% 的测试准确率，用画板写一个 8，模型输出 3，置信度还挺高。

原因：训练数据和推理数据的分布对不上。MNIST 是黑底白字、质心居中、笔画经过标准化处理；手机拍的照片是白底黑字、数字偏在角落、笔画粗细随笔尖变化。模型没学过这种输入，输出的是「在训练分布下最像的类别」，本质上是在外推。

解决：把 4.4 的预处理四步做全，特别是反相和外接框裁剪。做完还掉点，就自己写 50 张数字，按 8:2 分微调集和验证集，用 1e-4 的学习率只训最后两层 Dense，冻结卷积部分。这个做法十几分钟就能跑完，通常能把自建样本准确率从六成拉到九成以上。

5.2 加载模型报错，昨天还能跑

现象：load_model抛出ValueError: Unknown layer或者KeyError，同一份代码换台机器就挂。

原因：保存格式和加载方式不匹配，或者依赖版本变了。.h5对子类化模型、自定义层的序列化支持不完整；TensorFlow 2.x 各小版本之间 Keras 的默认保存行为也有差异。另外，如果代码里用了 lambda 层或自定义回调，加载时必须通过custom_objects显式注册。

解决：统一用.keras格式；把依赖写进requirements.txt并锁定小版本，例如tensorflow==2.15.*；自定义层实现get_config()方法，加载时传custom_objects={"MyLayer": MyLayer}。这三条做完，跨机器复现基本不会失败。

5.3 loss 不降，准确率长期停在 10%

现象：训练十几轮，loss 在 2.3 附近波动，accuracy 一直在 0.1 上下——正好是 10 分类的随机水平。

原因：九成是标签格式和损失函数不匹配。用categorical_crossentropy却传了整数标签，或者反过来用sparse_categorical_crossentropy却传了 one-hot。剩下的一成是数据被打乱后标签没跟着打乱，或者归一化漏做导致输入尺度异常。

解决：先打印一个批次的标签形状和取值，y_batch.shape是(128, 10)就用 categorical，是(128,)就用 sparse，改一行即可。再确认shuffle是对(x, y)整体做的——from_tensor_slices((x, y))会按第一维同步打乱，但如果先分别 shuffle 两个数组再用zip拼，对应关系就断了。

5.4 训练慢、内存一路涨到报警

现象：第一个 epoch 就要十几分钟，任务管理器里内存曲线稳步爬升，跑到中途被系统杀掉。

原因：把整份数据一次性转成 one-hot 之外又复制了好几份；数据增强写在 Python 循环里逐张处理，没有并行；prefetch和cache用错位置，把增强后的随机样本缓存下来，等于每个 epoch 都看同一批增强结果。

解决：cache()放在map(augment)之前，缓存原始张量而不是增强结果；map加num_parallel_calls=AUTOTUNE；batch size 从 128 起调，显存不够就减半而不是加。另外检查是不是在fit里同时传了x和validation_data的完整数组，这两份数组会常驻内存。

5.5 每次运行结果都不一样，答辩数字对不上

现象：同一份代码跑两次，一次 99.1%，一次 98.6%；演示时想复现报告里的数字，怎么都跑不出来。

原因：权重初始化、Dropout、数据打乱都带随机性，没有固定种子。

解决：在训练入口最顶部统一设种子，并且注意tf.data的 shuffle 有自己的 seed 参数，要单独传。

import os, random, numpy as np, tensorflow as tf def set_seed(seed=42): os.environ["PYTHONHASHSEED"] = str(seed) random.seed(seed) np.random.seed(seed) tf.random.set_seed(seed) tf.keras.utils.set_random_seed(seed) # 覆盖 Keras 内部初始化

设完之后同一台机器上结果可复现。跨机器仍可能有微小差异，因为不同 CPU 的浮点累加顺序不同，这一点在报告里注明即可，不丢分。

6. 验收与答辩：用三张图和一张表证明方案真的能用

6.1 验收指标表

验收不能只看测试集准确率一个数，那个数字太容易被质疑。我一般按下面这张表来验，每一项都能现场演示：

最后一项最容易被忽略，但它是「交付」和「在自己电脑上能跑」的分界线。答辩前一定要在干净环境里从零装一遍依赖，把报错提前暴露出来。

6.2 现场演示的三张图策略

演示环节时间通常只有三五分钟，讲代码讲不完，讲准确率又太空。我的做法是准备三张图，按顺序放：

第一张是 MNIST 测试集里的样本，配一行「标准输入，置信度 0.998」。这一张建立基线，说明模型在它该擅长的分布上是可靠的。第二张是自己用画板现写的数字，最好故意写得歪一点、粗一点，置信度会掉到 0.9 附近但仍然正确。这一张说明预处理链路真的起了作用。第三张是关键——放一张故意写得很潦草的 5，或者一张带网格线的纸拍的照片，让模型给出低置信度或错误答案，然后你主动解释为什么：外接框裁到了网格线、笔画宽度和训练分布差太多、置信度 0.4 说明模型自己也在犹豫。

第三张图是整套演示里最能建立信任的部分。主动暴露边界，比宣称「准确率 99%」有说服力得多，因为它证明你知道模型在哪里会失效，也知道失效的原因。评委追问时，你可以顺着这个点讲域偏移、讲数据增强的局限、讲如果要继续做该怎么补样本，话题自然就往你熟悉的方向走了。

还有一个小技巧：把predict_digit的返回值打在一个简单的表格里，标签、置信度、top3 候选、处理耗时四列。演示时不用口头报数字，评委自己看，你专心讲逻辑。

从那以后我每次带这类识别项目，都会在答辩前一天强制走一遍「干净环境重装 + 三张图演练 + 空图测试」，不管前几天跑得多顺。踩过的坑多了就知道，能复现的 98% 比不可复现的 99.2% 值钱得多。希望帮到你。

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