NumPy手写前馈神经网络：MNIST训练推理完整闭环

简介面向深度学习入门者与课程实验需求这份资料围绕MNIST手写数字识别任务提供可直接运行的前馈神经网络训练与测试代码以及已经训练好的模型权重和完整模型文件省去从环境搭建到反复调参的等待适合课堂演示、作业复现与初次接触机器学习项目时对照学习。压缩包共5个文件以3个Python脚本和2个H5模型文件为主脚本承担数据加载、网络构建、训练与预测流程H5文件便于直接加载验证或继续微调整体约1.39MB体积轻便。已有6131人学习下载可见其在入门实践中具有参考价值。读者可据此理解MNIST数据预处理、全连接网络结构、损失函数与优化器配置、训练轮次控制及模型保存加载等环节也能借助现成权重快速完成识别效果验证并在此基础上修改网络层数、批量大小或学习率形成实验记录与排错思路。1. 从一份 loss 变 nan 的脚本说起上周有位同学拿着一份手写数字识别的训练脚本过来说 loss 跑到第三个 epoch 就开始乱飘最后直接 nan。打开一看问题不在网络结构出在标签 one-hot 和 log 里那个 0。类似的事在 MNIST 上太常见了——数据简单到让人以为它不会出问题真正翻车的地方全在细节。这份资源给的是完整的一条路基于 MNIST 数据集训练手写数字识别的脚本、前馈神经网络的逐行实现、训练好的模型文件以及加载权重就能出预测的推理脚本。它适合两类人刚学完反向传播想找最小可跑闭环的和想把深度学习那套训练—评估—保存—推理流程真正落进自己项目的。不用 GPU普通笔记本十几分钟就能跑到 97% 以上。2. 工程结构与技术选型不装深度框架也能跑起来的原因拿到一份带“完整代码 训练好的模型”的资源最怕的是不知道从哪个文件开始看。这套工程我按“数据进、梯度出、权重存”的顺序拆成了七个文件每个文件只干一件事改的时候不用满仓库找。2.1 目录结构与文件职责解压后是这样一棵树没有多余的东西mnist-mlp/ ├── data/ # 原始 idx 文件脚本启动时自查 │ ├── train-images-idx3-ubyte │ ├── train-labels-idx1-ubyte │ ├── t10k-images-idx3-ubyte │ └── t10k-labels-idx1-ubyte ├── mnist_io.py # idx 解析、归一化、one-hot、batch 迭代 ├── model.py # 参数初始化、前向、反向、softmax ├── train.py # 训练循环、验证、早停、保存 npz ├── predict.py # 加载 npz做单张或整批预测 ├── reference_torch.py # PyTorch 对照实现用来校准准确率 ├── artifacts/ │ ├── mnist_mlp.npz # 训练好的权重约 900KB │ └── history.json # 每轮 loss / val_acc 记录 └── requirements.txtmnist_io.py是第一站负责把四个二进制文件读成float32矩阵并把标签转成 one-hot所有跟“脏活”有关的代码都集中在这里。model.py只有纯数学不碰文件也不碰命令行参数参数用字典存前后向函数都是无状态的这样单测好写。train.py把两者串起来管超参、管日志、管权重落盘。predict.py是交付给别人的入口。reference_torch.py不是必需项它的作用是当你发现自己手写的版本只有 92% 而框架版有 98% 时用同一份数据跑一遍框架版快速判断是数据管线的问题还是梯度计算的问题。artifacts/目录里那两个文件是这份资源最值钱的部分之一。mnist_mlp.npz是训练好的权重别人拿到后不训练、直接跑predict.py就能出结果history.json记录每轮的训练损失和验证准确率调参时拿它跟新实验对比比凭感觉靠谱得多。2.2 技术选型NumPy 手写与框架对照核心实现只用 NumPy不引入任何深度学习框架。这不是为了炫技而是这类前馈网络在 784–256–128–10 这个规模下矩阵乘法本身就够快一轮 epoch 在普通 CPU 上两三秒加框架反而是给自己加一层黑匣子。手写的收益很直接梯度的每个形状、每个转置都摆在眼前出问题时能在backward里逐层打印dZ.mean()定位而不只是盯着一个 loss 数字猜。框架版的定位是“裁判”。当准确率对不上预期或者想加卷积改进时reference_torch.py提供同结构同超参的基线两边差值超过 0.5 个百分点就说明手写实现有 bug。维度NumPy 手写版PyTorch 对照版依赖仅 numpytorch约 2GB单轮训练耗时CPU23 秒35 秒可调试性每层梯度可见需 hook 或断点适合场景理解原理、教学、轻量部署快速试结构、上 GPU2.3 环境准备与三步跑通Python 版本建议 3.10 以上numpy用 1.26 系列比较稳2.x 在部分老系统上跟其他库有冲突。虚拟环境走一遍# 创建并激活环境 python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -r requirements.txt # numpy / matplotlib / pillow对照版另装 torch接着是训练参数全走命令行不用改代码python train.py \ --data-dir ./data \ --epochs 20 \ --batch-size 128 \ --hidden 256 128 \ --lr 1e-3 \ --out artifacts/mnist_mlp.npz几个参数值得说清楚改错了最容易白跑参数默认值说明--epochs20实际 1215 轮就收敛早停会提前结束--batch-size128小于 32 梯度噪声大大于 512 收敛变慢--hidden256 128每层宽度可传多个值换层数--lr1e-3Adam 的初始学习率超过 5e-3 容易发散--seed42固定初始化与打乱顺序保证可复现跑完再用训练好的权重做推理不用重新训练# 整批评估测试集 python predict.py --weights artifacts/mnist_mlp.npz --split test # 单张图片需要 pillow会先转成 28x28 灰度再反色 python predict.py --weights artifacts/mnist_mlp.npz --image ./samples/7.png提示data/目录下四个文件名必须和上面完全一致脚本靠文件名判断读哪一份改名后会直接报“找不到 idx 文件”。3. 数据管线拆解从 idx 二进制到 mini-batch 的完整链路MNIST 的原始文件不是图片而是两个自定义二进制格式很多人第一步就栽在这——用open().read()读出来当文本处理结果是满屏乱码。这一层必须老老实实按字节解析。3.1 idx 文件的二进制结构文件名里的idx3和idx1就是维度数。图像文件是三维样本数、行、列标签文件是一维样本数。文件开头是固定长度的头部用大端序存储四个 32 位无符号整数文件类型魔数头部长度头部内容图像 idx3205116 字节魔数、样本数、行数、列数标签 idx120498 字节魔数、样本数魔数是格式的自校验位读到不等于 2051 或 2049 就说明文件下错了或者被改动过。这一点在实际排查里特别有用有人把解压后的文件重命名成.jpg再改回来字节流已经变了魔数校验会第一时间拦住。大端序意味着不能用 Python 默认的小端去解struct.unpack的格式串前面那个就是干这个的。3.2 从字节到张量解析、归一化与 one-hot读取函数写成下面这样两个函数加起来不到二十行是整个管线里最不该出错也最容易出错的地方import struct import numpy as np def read_idx_images(path): 读取 idx3 图像文件返回 (N, 784) 的 float32取值范围 0~1 with open(path, rb) as f: magic, num, rows, cols struct.unpack(IIII, f.read(16)) if magic ! 2051: raise ValueError(f{path} 魔数异常: {magic}期望 2051) buf f.read(num * rows * cols) if len(buf) ! num * rows * cols: raise ValueError(f{path} 数据长度不符可能文件被截断) data np.frombuffer(buf, dtypenp.uint8).reshape(num, rows * cols) # 除以 255 把像素压到 0~1前向传播时数值更稳 return data.astype(np.float32) / 255.0 def read_idx_labels(path): 读取 idx1 标签文件返回 (N,) 的 int64 with open(path, rb) as f: magic, num struct.unpack(II, f.read(8)) if magic ! 2049: raise ValueError(f{path} 魔数异常: {magic}期望 2049) return np.frombuffer(f.read(num), dtypenp.uint8).astype(np.int64)reshape(num, rows * cols)这一步把每张 28×28 的图拉平成 784 维向量正好对上前馈网络的输入层。除以 255 不是可有可无的装饰像素值原本是 0255直接送进第一层加权求和输出动辄上千ReLU 之后梯度爆炸训练几轮就 nan——开头那位同学遇到的正是这个问题。归一化到 01 后第一层输出的量级跟权重初始化匹配学习率 1e-3 才能正常工作。标签要转 one-hot 才能跟 softmax 输出做交叉熵def one_hot(y, num_classes10): 整数标签转 one-hot必须是 float32否则跟 logits 相乘会类型提升 out np.zeros((y.shape[0], num_classes), dtypenp.float32) out[np.arange(y.shape[0]), y] 1.0 return out这里有个细节out的 dtype 必须是float32。如果写成默认的float64跟网络输出的float32矩阵做减法时会静默升精度一路传到梯度里内存翻倍不说某些 BLAS 后端在混合精度下还会给出莫名其妙的值。3.3 mini-batch 迭代器与训练/验证切分数据全部读进内存后约 47MB60000×784×4 字节完全放得下不需要写生成器。迭代器只负责打乱和切片def iterate_minibatches(X, y, batch_size, rng, shuffleTrue): 按 batch 产出 (X_batch, y_batch_onehot)每个 epoch 重新打乱 n X.shape[0] idx rng.permutation(n) if shuffle else np.arange(n) for start in range(0, n, batch_size): sel idx[start:start batch_size] # 最后一批可能不足 batch_size直接产出不做补齐 yield X[sel], one_hot(y[sel])打乱用的是传入的np.random.default_rng(seed)实例不是一个全局随机状态。全局随机状态的问题在于只要中间有任何一处调用了np.random.rand()后续所有 batch 的顺序都会变实验就没法复现。固定一个 rng 实例并显式往下传是这套代码能保证“同样的 seed 出同样的准确率”的关键。验证集从训练集里切而不是拿测试集当验证集def split_train_val(X, y, val_size10000, seed42): rng np.random.default_rng(seed) idx rng.permutation(X.shape[0]) X, y X[idx], y[idx] return X[:-val_size], y[:-val_size], X[-val_size:], y[-val_size:]切分前先整体打乱很重要。MNIST 训练集原始顺序是按标注者排列的前几千张的类别分布很不均匀直接取最后 10000 条当验证集验证准确率会系统性偏低早停就会误判。测试集的 10000 张只在最后评估时用一次不参与任何调参决策否则报出来的数字就是虚的。4. 前馈网络核心实现初始化、前向、反向与参数更新到这一章才是真正的网络。结构很朴素784 输入两层隐藏层各 256 和 128 个 ReLU 单元输出 10 类 softmax。参数量约 784×256 256×128 128×10 ≈ 235K模型文件不到 1MB但足够把 MNIST 做到 98% 上下。4.1 参数初始化与 He 初始化初始化用 He 方案方差取2 / fan_in专为 ReLU 设计def init_params(layer_sizes, seed42): layer_sizes 例[784, 256, 128, 10]返回 W1/b1/W2/b2/W3/b3 rng np.random.default_rng(seed) params {} for i in range(1, len(layer_sizes)): fan_in, fan_out layer_sizes[i - 1], layer_sizes[i] # He 初始化std sqrt(2/fan_in)适配 ReLU 把负半轴砍掉一半的特性 params[fW{i}] (rng.standard_normal((fan_in, fan_out)) * np.sqrt(2.0 / fan_in)).astype(np.float32) params[fb{i}] np.zeros(fan_out, dtypenp.float32) return params为什么不用全零或者小常数全零初始化下同一层的所有神经元梯度完全相同训练完还是同一个值等于白搭一层。为什么不用0.01 * randn第一层 fan_in 是 784输出方差只有 0.078信号传到第三层几乎衰减没了梯度同样消失。He 初始化让每层输出的方差大致保持为 120 层以内都不会明显衰减这里虽然只有 3 层但养成习惯没坏处。偏置初始化为 0 是安全的因为它不参与方差传递。4.2 前向传播784 → 256 → 128 → 10前向同时缓存中间结果反向要用def softmax(Z): 减行最大值再取指数防止 exp 溢出 Z Z - Z.max(axis1, keepdimsTrue) e np.exp(Z) return e / e.sum(axis1, keepdimsTrue) def forward(params, X): 返回 (概率矩阵, 缓存)缓存里存每层的 Z 和 A L len(params) // 2 cache {A0: X} A X for i in range(1, L 1): Z A params[fW{i}] params[fb{i}] if i L: A np.maximum(Z, 0.0) # 隐藏层 ReLU cache[fZ{i}] Z # 反向要用来算 ReLU 掩码 else: A softmax(Z) # 输出层转概率 cache[fA{i}] A return A, cache维度对一遍就清楚了X是(128, 784)W1是(784, 256)乘完是(128, 256)加偏置b1时 NumPy 自动沿第 0 维广播不需要手动复制。softmax里减去行最大值是数值稳定的标准做法不减的话exp(800)直接溢出成 inf除出来全是 nan——这个坑在没归一化输入时尤其容易踩。4.3 反向传播梯度形状对齐与链式求导softmax 加交叉熵的梯度有个很漂亮的化简对 logits 的导数就是预测概率 - one-hot 标签省掉一大串雅可比矩阵def backward(params, cache, y_onehot): 返回与 params 同 key 的梯度字典 L len(params) // 2 m y_onehot.shape[0] # batch 大小 grads {} # softmax 交叉熵合并求导除以 m 是对 batch 求平均 dZ (cache[fA{L}] - y_onehot) / m for i in range(L, 0, -1): grads[fW{i}] cache[fA{i-1}].T dZ # (fan_in, batch) (batch, fan_out) grads[fb{i}] dZ.sum(axis0) # 沿 batch 维求和 if i 1: dA dZ params[fW{i}].T # 传回上一层 dZ dA * (cache[fZ{i-1}] 0) # ReLU 掩码负值处梯度为 0 return grads三行梯度计算公式每一行的形状都要能对上。grads[W1]应该是(784, 256)等于A0.T (784, 128) dZ (128, 256)对得上。dZ.sum(axis0)把 batch 维消掉剩下(256,)跟b1一致。如果哪一步形状不对NumPy 会对某些组合静默广播训练不报错但结果全错——这是最阴的一类 bug后面避坑章会专门讲。ReLU 的掩码用cache[fZ{i-1}] 0不是A 0。两者在隐藏层其实等价A 就是 max(Z,0)但用 Z 语义更清晰它表示“这个神经元当时有没有被激活”。4.4 优化器与完整训练循环优化器用 Adam收敛快、对学习率不敏感适合这种小网络class Adam: def __init__(self, params, lr1e-3, beta10.9, beta20.999, eps1e-8): self.lr, self.b1, self.b2, self.eps lr, beta1, beta2, eps # 一阶矩和二阶矩跟参数同形状 self.m {k: np.zeros_like(v) for k, v in params.items()} self.v {k: np.zeros_like(v) for k, v in params.items()} self.t 0 def step(self, params, grads): self.t 1 for k in params: self.m[k] self.b1 * self.m[k] (1 - self.b1) * grads[k] self.v[k] self.b2 * self.v[k] (1 - self.b2) * (grads[k] ** 2) # 偏差修正前几步的矩估计偏小不修会走得很慢 m_hat self.m[k] / (1 - self.b1 ** self.t) v_hat self.v[k] / (1 - self.b2 ** self.t) params[k] - self.lr * m_hat / (np.sqrt(v_hat) self.eps)偏差修正那两行容易被忽略。t1时m只有真实梯度的 0.1 倍不修正的话第一步的更新量只有应有值的十分之一训练初期会显得“启动慢”。训练主体把前面几块拼起来def train(data_dir, epochs20, batch_size128, hidden(256, 128), lr1e-3, outartifacts/mnist_mlp.npz, seed42, patience5): X_tr, y_tr load_training_set(data_dir) X_tr, y_tr, X_val, y_val split_train_val(X_tr, y_tr, 10000, seed) layer_sizes [784, *hidden, 10] params init_params(layer_sizes, seed) opt Adam(params, lrlr) rng np.random.default_rng(seed) best_acc, wait, history 0.0, 0, [] for epoch in range(1, epochs 1): total_loss, seen 0.0, 0 for Xb, yb in iterate_minibatches(X_tr, y_tr, batch_size, rng): probs, cache forward(params, Xb) # 交叉熵损失加 1e-9 防止 log(0) loss -np.mean(np.sum(yb * np.log(probs 1e-9), axis1)) grads backward(params, cache, yb) opt.step(params, grads) total_loss loss * Xb.shape[0] seen Xb.shape[0] val_acc accuracy(params, X_val, y_val) history.append({epoch: epoch, loss: total_loss / seen, val_acc: val_acc}) print(fepoch {epoch:02d} loss {total_loss/seen:.4f} val_acc {val_acc:.4f}) if val_acc best_acc: best_acc, wait val_acc, 0 np.savez_compressed(out, **params) # 只保存最好的那一版 else: wait 1 if wait patience: print(f验证集 {patience} 轮没提升提前停止) break json.dump(history, open(artifacts/history.json, w), indent2) return best_acc关键点是“只保存验证集最好的那一版”。如果按最后一轮保存模型可能已经在训练集上过拟合测试准确率反而低一两个点。patience5是经验值这套网络通常在第 1014 轮达到峰值。4.5 权重序列化与推理脚本保存用np.savez_compressed每个参数一个 key加载时直接还原def load_model(path): 从 npz 还原参数字典key 顺序无关 state np.load(path) return {k: state[k] for k in state.files} def accuracy(params, X, y, batch_size1000): 分批推理避免一次算 10000 条占内存 correct 0 for start in range(0, X.shape[0], batch_size): probs, _ forward(params, X[start:start batch_size]) correct (probs.argmax(axis1) y[start:start batch_size]).sum() return correct / X.shape[0]npz本质上是个 zipstate.files返回按字典序排的 key 列表所以不能用位置索引去取参数必须按 key 取。这一点在手动检查文件内容时要注意W10会排在W2前面。推理脚本里的单张图片处理需要额外说明程序给的样本图一般是黑字白底而 MNIST 是白字黑底必须反色否则准确率断崖式下跌到 10% 左右——模型看到的是它从没见过的输入分布。5. 避坑与排查五个把我按在凌晨两点的失败模式这套代码跑通不难难的是跑出 98%。下面五条都是真实踩过的每条按现象、原因、解决的顺序写。5.1 排查顺序先怀疑数据再怀疑梯度在开始逐条之前先讲排查的优先级。我的习惯是准确率不对时先打印一个 batch 的输入统计量X.mean()应在 0.13 左右X.max()是 1.0再看y的类别分布是否均匀最后才去看反向传播。原因是数据层的问题表现为全局性的“怎么调都上不去”而梯度层的 bug 通常表现为 loss 直接 nan 或者不降。按这个顺序走八成问题在第一步就能定位比对着 loss 曲线反复调学习率高效得多。5.2 五条血泪踩坑记录第一条loss 稳定在 2.302 附近不动。现象是每轮打印出的 loss 几乎一模一样准确率停在 10%。原因是标签没有转 one-hot直接把整数标签传进了交叉熵y * np.log(p)里的y是标量整个损失失去了区分度梯度恒为零。解决是检查y_onehot.shape必须是(batch, 10)而且dtype是float32。这个 bug 的隐蔽之处在于它不报错只是静静地不学习。第二条前几轮正常第三轮突然 nan。现象是 loss 先降到 0.5 然后跳到 nan之后全是 nan。原因是输入没归一化像素值还是 0255Z X W1算出上千的量级exp溢出。解决是确认X.max() 1.0并且在softmax里保留减最大值那一步。顺带一提np.log(probs)里如果probs有精确的 0也会得到-inf所以损失函数里要加1e-9。第三条验证准确率 97%测试准确率只有 88%。现象是训练日志很好看一上测试集就崩。原因是切验证集之前没有整体打乱取的是原始顺序的尾部 10000 条类别分布跟前 50000 条差异明显早停选出来的模型是“专门讨好那一段数据”的。解决是split_train_val里先rng.permutation再切并且验证集和测试集严格分开测试集只在最后用一次。第四条改了隐藏层宽度训练直接报形状不匹配。现象是matmul抛出维度错误。原因是--hidden 512 256传进来后被当成一个字符串int()转换只做了第一个。解决是命令行参数用nargs配typeint并在train()入口处断言len(hidden) 1。这类问题在加层时最容易出现因为layer_sizes的构造是[784, *hidden, 10]少一个元素后面的 key 全错位。第五条用训练好的 npz 做单张图片预测结果每次都很离谱。现象是明明是个 7模型输出 2 的概率最高。原因是图片预处理只做了缩放没有反色也没有对齐到 28×28 居中。MNIST 的数字是经过居中裁剪的四周留白约 4 像素直接拿手机拍的照片去预测分布完全对不上。解决是用predict.py里的预处理函数转灰度、按最大边缩放、把数字块贴到 28×28 画布中心、反色。这套流程对二次开发很重要后面还会提到。注意改任何超参之前先固定 seed 跑一轮基线把history.json存下来。没有基线的调参就是玄学改完不知道是变好了还是随机波动。6. 二次开发把这套骨架挪到自己的任务上这套代码最实用的地方不是 MNIST 本身而是它把“数据解析—前向—反向—优化—存取”这条链完整暴露出来了换成别的任务只需要动两三个文件。我一般按三个方向改。方向一是换数据。把mnist_io.py里的两个read_idx_*换成你自己的加载函数输出保持(N, D)的float32和(N,)的int64train.py一行都不用改。如果是自采的表格数据把D改成特征数layer_sizes的输入维跟着改就行。这里要改的只有layer_sizes [784, *hidden, 10]里的 784 和 10。方向二是加结构。想试试卷积不用重写反向直接把model.py的forward里第一层换成im2col 矩阵乘反向对应改成col2im其余层照旧。更省事的做法是在reference_torch.py里验证结构有没有效果有效果再往手写版移植# reference_torch.py 里加一层卷积做对照 import torch.nn as nn class ConvNet(nn.Module): def __init__(self): super().__init__() self.features nn.Sequential( nn.Conv2d(1, 16, 3, padding1), nn.ReLU(), nn.MaxPool2d(2), nn.Conv2d(16, 32, 3, padding1), nn.ReLU(), nn.MaxPool2d(2), ) self.head nn.Sequential(nn.Flatten(), nn.Linear(32 * 7 * 7, 10)) def forward(self, x): # 注意输入要 reshape 回 (B, 1, 28, 28)FLATTEN 之后的向量喂不进去 return self.head(self.features(x.view(-1, 1, 28, 28)))方向三是部署。npz里的权重可以导成任何形式最省事的是导成 C 数组塞进嵌入式设备# export_c.py把第一层权重导成 C 头文件适合资源受限的场景 import numpy as np state np.load(artifacts/mnist_mlp.npz) W1, b1 state[W1], state[b1] with open(model_params.h, w) as f: f.write(f#define IN_DIM {W1.shape[0]}\n#define HID_DIM {W1.shape[1]}\n) f.write(fstatic const float W1[{W1.size}] {{) f.write(,.join(f{v:.6f}f for v in W1.ravel())) f.write(};\n)导出后用float32存的权重在 MCU 上跑一次前向只要几毫秒比带 Python 运行时靠谱得多。如果目标是更大的设备直接转 ONNX 也行torch.onnx.export对这套结构支持很好。至于验证改造成不成功我只有一个标准拿固定的 seed 跑三轮看验证准确率的方差是否在 0.3 个百分点以内再对比测试集。方差大说明改动引入了随机性这时候看的是稳定性而不是峰值。从那以后我每次改网络结构都强制先跑一遍基线并保存history.json再动第二个文件。没有基线对比的“感觉变好了”十次里有八次是自欺欺人。希望帮到你。本文还有配套的精品资源点击获取