DASE7509 · 零基础逐页精讲

MNIST准备代码 · 122行逐行讲解

左右键翻页;“连续阅读”展开整份;搜索可定位概念。

代码段 1 / 12 · 第1–11行

第1–11行:这份文件做什么,怎样启动

001 | """Download the MNIST archive used by Keras and export PNG images + labels.csv.
002 | 
003 | Install: conda install numpy pillow
004 | Run:     python prepare_mnist.py
005 | Preview: python prepare_mnist.py --limit 20 --output mnist_preview
006 | 
007 | The NPZ archive is the official Keras redistribution, not the original IDX files.
008 | Dataset and hash source:
009 | https://github.com/keras-team/keras/blob/master/keras/src/datasets/mnist.py
010 | """
011 | 

左侧看代码,右侧逐行讲解。

打开源文件

这份程序读取 Keras 使用的 MNIST .npz 归档,把数据变成可打开的 PNG 图片和标签表。课程文件是 prepare_mnist.txt,将内容另存为 prepare_mnist.py 后,从该文件所在目录的终端运行。

  • 第1、7–10行用三引号包住模块说明,内容交代归档来源、以及该 NPZ 是 Keras 的分发版本。Python 将这段文字存为 __doc__,第70行用它生成命令行帮助。
  • 第3–5行列出终端命令。conda install numpy pillow 安装处理数组与图片的工具;python prepare_mnist.py 执行脚本并完整导出;带参数的命令只导出每个子集的前 20 张。

python prepare_mnist.py --limit 20 --output mnist_preview

运行这条命令时,程序仍取得并读取完整归档,随后在 mnist_preview/train/images/ 和 mnist_preview/test/images/ 各写 20 张普通 PNG。每个子集有自己的 labels.csv。根目录还会多出第一张训练图的放大版和像素表。

代码段 2 / 12 · 第12–22行

第12–22行:导入各项工具

012 | from pathlib import Path
013 | from urllib.request import urlopen
014 | import argparse
015 | import csv
016 | import hashlib
017 | import shutil
018 | 
019 | import numpy as np
020 | from PIL import Image
021 | 
022 | 

左侧看代码,右侧逐行讲解。

打开源文件

第12–20行给后续代码准备工具。先看工具在哪里第一次真正做事,再回头读名字。

行号 导入的名字 后面负责的操作
12 Path Path("data") / "images" 拼出 data/images,也能开文件、检查是否存在
13 urlopen 第42行打开归档的下载响应
14 argparse 第70–75行登记并读取 --input、--output、--limit
15 csv 第58–64行创建写入器,写表头和图像标签
16 hashlib 第29–33行计算归档字节的 SHA-256 摘要
17 shutil 第43行把下载响应中的字节复制到磁盘文件
19 numpy as np 第83行用 np.load(...) 读取 NumPy 归档
20 Image 第63行用 Image.fromarray(...) 将像素数组保存为图片

from ... import ... 导入的名字可以直接写,例如 Path(...)、Image.fromarray(...)。import numpy as np 把整个模块取了短名,后续成员要通过 np.名字 引用。PIL 是 Pillow 安装包在代码中的导入名。

代码段 3 / 12 · 第23–27行

第23–27行:下载地址、固定摘要和脚本目录

023 | URL = "https://storage.googleapis.com/tensorflow/tf-keras-datasets/mnist.npz"
024 | SHA256 = "731c5ac602752760c8e48fbffcf8c3b850d9dc2a2aedcf2cc48468fc17b673d1"
025 | BASE = Path(__file__).resolve().parent
026 | 
027 | 

左侧看代码,右侧逐行讲解。

打开源文件

这三行给后续调用提供固定值。全大写是命名惯例。

  • 第23行将 MNIST 归档地址存进 URL。第42行把它传给 urlopen 时才联网。
  • 第24行将期望的 SHA-256 摘要存为 64 个十六进制字符:731c5ac602752760c8e48fbffcf8c3b850d9dc2a2aedcf2cc48468fc17b673d1。第44、47行把实际文件的摘要与它比较。
  • 第25行逐步找到脚本目录:__file__ 给出脚本位置,Path(__file__) 将其变成路径对象,.resolve() 得到绝对路径,.parent 去掉最后的文件名。

假设脚本在 D:/example/prepare_mnist.py,BASE 就是 D:/example。第71、72行据此得到默认输入 D:/example/mnist.npz、默认输出 D:/example/mnist_readable。显式填写 --output mnist_preview 时,这类相对路径用终端当前目录解析,具体见第7节。

代码段 4 / 12 · 第28–35行

第28–35行:分块计算SHA-256,每一步是什么

028 | def sha256(path):
029 |     digest = hashlib.sha256()
030 |     with path.open("rb") as source:
031 |         for block in iter(lambda: source.read(1024 * 1024), b""):
032 |             digest.update(block)
033 |     return digest.hexdigest()
034 | 
035 | 

左侧看代码,右侧逐行讲解。

打开源文件

sha256(path) 接收文件路径,返回该文件的十六进制摘要。每次读一块,所有字节按原顺序进入同一个摘要计算。

  • 第28–29行定义函数,创建一个空的摘要累积器 digest = hashlib.sha256()。
  • 第30行以 "rb" 打开文件,读到的是字节。with 负责离开代码块时关闭文件。
  • 第31–32行把 lambda 理解为每次「读下一块」的操作。iter(这个操作, b"") 反复读,直到结果等于空字节串。每次读到的非空块交给 digest.update(block)。
  • 第33行用 hexdigest() 返回最终摘要字符串。摘要对象在 with 块外仍可访问,文件此时已关闭。

以一个恰好 1 MiB 加 3 字节的文件为例。第一次 read(1024 * 1024) 返回 1,048,576 字节并更新摘要;第二次只返回剩余 3 字节,也更新摘要;第三次返回 b"",循环结束,最后取总摘要。分块和一次把所有字节读入得出的摘要一致,分块所需的临时内存较少。

代码段 5 / 12 · 第36–51行

第36–51行:先用临时文件下载,再校验归档

036 | def get_archive(path):
037 |     if not path.exists():
038 |         path.parent.mkdir(parents=True, exist_ok=True)
039 |         temporary = path.with_suffix(".npz.part")
040 |         print("Downloading the archive used by the official Keras loader...", flush=True)
041 |         print(URL, flush=True)
042 |         with urlopen(URL, timeout=120) as response, temporary.open("wb") as destination:
043 |             shutil.copyfileobj(response, destination)
044 |         if sha256(temporary) != SHA256:
045 |             raise ValueError("Download checksum mismatch. Please download again.")
046 |         temporary.replace(path)
047 |     if sha256(path) != SHA256:
048 |         raise ValueError("This archive does not match the checksum in the Keras source.")
049 |     print("SHA-256 verification passed.", flush=True)
050 | 
051 | 

左侧看代码,右侧逐行讲解。

打开源文件

get_archive(path) 在正式归档缺失时下载,在正式归档存在时直接校验。先看第37行和第47行的缩进:第38–46行只属于「文件缺失」分支,第47–49行两种情况都会执行。

归档初始状态 经过的行 结果
已有 mnist.npz 且摘要一致 37 → 47 → 49 直接打印校验通过
已有 mnist.npz 且摘要不一致 37 → 47 → 48 抛出 ValueError,结束流程
缺少 mnist.npz,下载且校验成功 37 → 38–46 → 47 → 49 先生成临时文件,验证后成为正式归档

下载分支按顺序执行:第38行补建父目录;第39行用 with_suffix(".npz.part") 把 mnist.npz 变成临时路径 mnist.npz.part;第40–41行用 flush=True 及时显示下载信息。第42行打开网络响应和临时文件,其中 timeout=120 是网络操作的超时设置;第43行 copyfileobj 把字节写入以 "wb" 打开的文件。with 结束后关闭两个流,此时磁盘上仍是临时文件。

第44–45行摘要不符就抛异常;通过后第46行用 replace 改为正式路径。下载中断可能留下 .npz.part,未走到第46行便不会出现新正式归档。

代码段 6 / 12 · 第52–68行

第52–68行:一张张保存PNG,同时写标签表

052 | def export_split(images, labels, split, output, limit):
053 |     folder = output / split
054 |     image_folder = folder / "images"
055 |     image_folder.mkdir(parents=True)
056 |     count = len(images) if limit is None else min(limit, len(images))
057 |     with (folder / "labels.csv").open("w", newline="", encoding="utf-8-sig") as file:
058 |         writer = csv.writer(file)
059 |         writer.writerow(["filename", "label"])
060 |         for index in range(count):
061 |             filename = f"image_{index:05d}.png"
062 |             # uint8 (28, 28) arrays become grayscale PNGs, with unchanged pixels.
063 |             Image.fromarray(images[index]).save(image_folder / filename)
064 |             writer.writerow([filename, int(labels[index])])
065 |             if (index + 1) % 5000 == 0 or index + 1 == count:
066 |                 print(f"{split}: {index + 1:,} / {count:,} images exported", flush=True)
067 | 
068 | 

左侧看代码,右侧逐行讲解。

打开源文件

export_split(images, labels, split, output, limit) 将一套数组导出为图片和标签表。以 split="train"、output=mnist_preview、limit=20 为例说明。

  • 第52–55行分别拼出 mnist_preview/train 与其中的 images,并创建目录。parents=True 补建缺失的父目录。由于未给 exist_ok=True,图片目录已经存在时会报错。
  • 第56行不限制时取 len(images),给了 limit 时取两者中较小值。本例图像共 60000 张,count=min(20,60000)=20。
  • 第57–59行以写入模式打开 train/labels.csv,用 newline="" 让 CSV 写入器控制行尾,用 utf-8-sig 保存字符编码,随后写下表头 filename,label。
  • 第60–64行range(count) 给出 0 至 19。{index:05d} 用 0 补到至少五位;Image.fromarray(images[index]).save(...) 按原像素写 PNG;再用相同索引取 int(labels[index]),写文件名与标签。
  • 第65–66行用 index+1 算已完成张数,每满 5000 张或完成最后一张就报告进度。本例 index=19 时打印 train: 20 / 20 images exported;较大的数字用逗号分隔千位。

用本地归档的前三条训练记录核对。由索引 0 读出的第一张是数字 5,下一轮同时读索引 1 的图片与标签,防止拿错对应关系。

index 读取的像素数组 写入 train/labels.csv 的一行
0 images[0] image_00000.png,5
1 images[1] image_00001.png,0
2 images[2] image_00002.png,4

常规 PNG 大小为 28×28,像素值保持不变。标签表有一行表头和 20 行记录,limit 只约束这次循环。

代码段 7 / 12 · 第69–81行

第69–81行:解析命令行,并拒绝覆盖已有输出

069 | def main():
070 |     parser = argparse.ArgumentParser(description=__doc__)
071 |     parser.add_argument("--input", type=Path, default=BASE / "mnist.npz")
072 |     parser.add_argument("--output", type=Path, default=BASE / "mnist_readable")
073 |     parser.add_argument("--limit", type=int, default=None,
074 |                         help="Export only the first N images in EACH split; default: all.")
075 |     args = parser.parse_args()
076 |     if args.limit is not None and args.limit < 1:
077 |         parser.error("--limit must be a positive integer.")
078 |     output = args.output.resolve()
079 |     if output.exists():
080 |         raise FileExistsError(f"Output already exists: {output}\nUse --output with a new folder name.")
081 | 

左侧看代码,右侧逐行讲解。

打开源文件

main() 先读取命令行,决定从哪读、写多少、写到哪。第70行的 description=__doc__ 把开头说明带进帮助文字。第71–74行先登记参数,第75行 parse_args() 再读本次命令。

属性 没写这个选项时 输入 --limit 20 --output mnist_preview 时
args.input BASE / "mnist.npz" 同左
args.output BASE / "mnist_readable" 路径 mnist_preview
args.limit None,两个子集全部导出 整数 20,各子集取前 20 张

第76–77行先检查 args.limit is not None,再判断是不是小于 1。由于 and 从左向右算,省略 limit 时不会对 None 做数值比较;给了 0 或负数则由 parser.error 结束。

第78行调用 .resolve() 得到绝对输出路径。给相对路径时基于终端当前目录,默认路径则基于脚本所在目录。第79–80行发现目标路径已存在便报 FileExistsError。这发生在第82行读取归档之前,所以重复运行同一输出目录时,会停在路径检查。

代码段 8 / 12 · 第82–86行

第82–86行:取得归档,再读取四个数组

082 |     get_archive(args.input)
083 |     with np.load(args.input, allow_pickle=False) as archive:
084 |         x_train, y_train = archive["x_train"], archive["y_train"]
085 |         x_test, y_test = archive["x_test"], archive["y_test"]
086 | 

左侧看代码,右侧逐行讲解。

打开源文件

第82行先调用 get_archive(args.input),校验完成才进入第83行。np.load(..., allow_pickle=False) 打开归档,并禁用通过 pickle 加载对象数组;with 结束后关闭归档资源。第84–85行以归档里的键名取出四个数组,分别留在内存中的变量里:

归档键与接收变量 用途 索引 0 的类型和内容
x_train 训练图片 28×28 像素矩阵,对应一张 5
y_train 训练标签 整数 5
x_test 测试图片 28×28 像素矩阵,对应一张 7
y_test 测试标签 整数 7

赋值 x_train, y_train = archive["x_train"], archive["y_train"] 可顺序读:右边先按两个键各取一个数组,左边名字再一一接收。图片和标签用同一索引配对。训练集和测试集都从各自的索引 0 开始。

代码段 9 / 12 · 第87–95行

第87–95行:验证形状、类型,并打印基本信息

087 |     expected = [(x_train, (60000, 28, 28)), (y_train, (60000,)),
088 |                 (x_test, (10000, 28, 28)), (y_test, (10000,))]
089 |     for array, shape in expected:
090 |         if array.shape != shape or array.dtype != np.uint8:
091 |             raise ValueError("Unexpected MNIST array shape or data type.")
092 |     print("Training images:", x_train.shape, "Labels:", y_train.shape)
093 |     print("Test images:    ", x_test.shape, "Labels:", y_test.shape)
094 |     print("First training image label:", int(y_train[0]))
095 | 

左侧看代码,右侧逐行讲解。

打开源文件

第87–88行用 expected 把每个数组与它应有的形状写在一对括号里。第89行循环逐对拆开,array 是当前数组,shape 是它的预期形状。

数组 预期形状 每个轴表示什么
x_train (60000, 28, 28) 训练张数、高、宽
y_train (60000,) 每张训练图一个标签
x_test (10000, 28, 28) 测试张数、高、宽
y_test (10000,) 每张测试图一个标签

(60000,) 的尾逗号表示单元素元组;(60000) 仍是整数。第90–91行分别检查形状与 dtype。若误把图像转成 float32,即使形状完全相符,array.shape != shape 为假、array.dtype != np.uint8 为真,假 or 真 仍然触发 ValueError。uint8 每个元素占 1 字节,所以 60000×28×28=47,040,000 个训练像素约占 47 MB。

通过以后,第92–93行输出形状,第94行打印 int(y_train[0])。本地归档给出的第一条标签为 5,这里只是从数组读标签。

代码段 10 / 12 · 第96–104行

第96–104行:导出两个子集,再做第一张图预览

096 |     export_split(x_train, y_train, "train", output, args.limit)
097 |     export_split(x_test, y_test, "test", output, args.limit)
098 | 
099 |     # These two extra files make the first image easy to inspect.
100 |     Image.fromarray(x_train[0]).resize(
101 |         (280, 280), Image.Resampling.NEAREST
102 |     ).save(output / "first_train_large.png")
103 |     np.savetxt(output / "first_train_pixels.csv", x_train[0], fmt="%d", delimiter=",")
104 | 

左侧看代码,右侧逐行讲解。

打开源文件

第96、97行用同一个 export_split 分别处理训练和测试数组。以 --limit 20 为例,根目录里会出现:

mnist_preview/
  train/images/              20 张 28×28 灰度 PNG
  train/labels.csv            从 image_00000.png,5 开始
  test/images/               20 张 28×28 灰度 PNG
  test/labels.csv             从 image_00000.png,7 开始
  first_train_large.png      第一张训练图,280×280
  first_train_pixels.csv     第一张训练图,28 行×28 列

第100–102行从 x_train[0] 创建图像,再用最近邻算法放大,最后保存。宽高各变成 10 倍,所以原图上每个像素显示成 10×10 的同值方块。以本地归档为例,第一张的 x_train[0,6,10] 为 94,放大图中第 60–69 行、第 100–109 列的整块也是 94。括号里的三行是一条链式调用。

第103行将同一张原始二维数组写成 CSV,fmt="%d" 指每个值以整数输出,delimiter="," 指列之间用逗号。数组下标从 0 开始,所以 94 对应像素表的第 7 行、第 11 列。常规导出的 28×28 图用于模型输入,放大图用于看细节。

代码段 11 / 12 · 第105–119行

第105–119行:写入数据来源说明

105 |     (output / "DATA_SOURCE.txt").write_text(
106 |         "MNIST handwritten digit dataset\n"
107 |         "Copyright: Yann LeCun and Corinna Cortes, per Keras documentation.\n"
108 |         "License: https://creativecommons.org/licenses/by-sa/3.0/\n"
109 |         "Documentation: https://keras.io/api/datasets/mnist/\n"
110 |         "Loader: https://github.com/keras-team/keras/blob/master/keras/src/datasets/mnist.py\n"
111 |         f"Archive: {URL}\nSHA-256: {SHA256}\n"
112 |         "Export: original 28x28 grayscale pixels preserved as PNG.\n"
113 |         "first_train_large.png is enlarged only for viewing, not for model input.\n"
114 |         "The published MNIST test set and its labels are public.\n"
115 |         f"Export limit per split: {args.limit if args.limit is not None else 'all'}\n",
116 |         encoding="utf-8",
117 |     )
118 |     print("\nFinished. Open this folder:", output)
119 | 

左侧看代码,右侧逐行讲解。

打开源文件

第105–117行向 DATA_SOURCE.txt 写入一份数据说明。路径由 output / "DATA_SOURCE.txt" 得到。第106–115行括号内相邻的字符串会拼成一段文字,每个 \n 另起一行,末尾的 encoding="utf-8" 指定写入编码。

  • 第106–110行写数据集名称、代码记录的版权与许可证,以及文档和加载器地址。
  • 第111行用 f 字符串把常量 URL 和 SHA256 填到 Archive 和 SHA-256 两行。
  • 第112–114行说明普通 PNG 保留原始 28×28 像素,放大版供预览,公开测试集有标签。
  • 第115行如果 args.limit 有值就插入该值,否则插入 all。给 --limit 20 时写 Export limit per split: 20;实际张数仍由第56行对每个子集取较小值来决定。
  • 第118行在文件写完后打印 Finished. Open this folder: 以及绝对输出路径。
代码段 12 / 12 · 第120–122行

第120–122行:入口开关,以及整份流程怎样串起来

120 | 
121 | if __name__ == "__main__":
122 |     main()

左侧看代码,右侧逐行讲解。

打开源文件

第121–122行决定何时调用 main()。__name__ 是 Python 给当前模块的名字,== 在这里比较字符串。

使用方式 本文件中的 __name__ 会调用 main() 吗
python prepare_mnist.py --limit 20 --output mnist_preview __main__ 会
import prepare_mnist prepare_mnist 不会,可显式调用其中的函数

启动主程序后,执行依次经过第75行读参数,第78–80行检查输出位置,第82–85行取得归档和数组,第87–94行校验尺寸及类型,第96–97行调用两次导出函数,第100–103行写预览图片和像素表,最后第105–118行保存来源说明并提示完成。Python 读到 def 时只建立函数;例如 export_split 要等第96行传入训练数据才开始保存图片。

返回总目录