MiniTorch 自动微分与 MNIST 训练项目

这是一个用于学习和实验自动微分、张量计算和简单神经网络训练的 MiniTorch 项目。项目实现了基础 Tensor、自动求导、模块系统、优化器、卷积/池化/线性层等组件，并提供了一个基于 MNIST 手写数字数据集的卷积神经网络训练示例。

项目功能

• 自动微分：支持计算图构建、反向传播和梯度累积。
• 张量计算：实现了广播、map、zip、reduce、矩阵乘法等基础操作。
• 神经网络模块：包含 Linear、Conv2d、ReLU、MaxPool2d、Flatten、Sequential 和 CrossEntropyLoss。
• 优化器：提供 SGD 优化器。
• MNIST 数据读取：自动下载并解析 MNIST gzip 数据文件。
• 训练示例：使用一个小型卷积网络训练 MNIST，并生成训练 Loss / Accuracy 曲线图。
• CUDA 后端实验支持：包含基于 ctypes 调用 CUDA 动态库的后端代码；如果未编译动态库，会自动提示 combine.so 不存在。

目录结构

.
├── data/                         # MNIST 数据文件
├── minitorch/                    # MiniTorch 核心实现
│   ├── autodiff.py               # 自动微分与计算图
│   ├── tensor.py                 # Tensor 对象
│   ├── tensor_data.py            # 底层存储、shape、stride 与索引逻辑
│   ├── tensor_functions.py       # Tensor 函数与反向传播规则
│   ├── tensor_ops.py             # CPU 张量算子后端
│   ├── cuda_kernel_ops.py        # CUDA 后端接口
│   ├── module.py                 # Module / Parameter
│   ├── nn.py                     # 神经网络层与损失函数
│   ├── optim.py                  # SGD 优化器
│   └── MNISTIterator.py          # MNIST 下载、读取与 mini-batch 迭代器
├── project/
│   ├── model.py                  # MNISTConvNet 模型定义
│   └── train.py                  # MNIST 训练入口
├── requirements.txt              # Python 依赖
├── training_curves.png           # 训练曲线输出示例
└── README.md

环境准备

建议使用 Python 虚拟环境。

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Linux / macOS:

source .venv/bin/activate

安装依赖：

pip install -r requirements.txt

注意：project/train.py 当前导入了 tqdm。如果运行时报 ModuleNotFoundError: No module named 'tqdm'，可以额外安装：

pip install tqdm

运行训练

在项目根目录执行：

python -m project.train

训练脚本会执行以下流程：

1. 从 data/ 目录读取 MNIST 数据；如果数据不存在，会尝试自动下载。
2. 将图像 reshape 为 (N, 1, 28, 28)，并归一化到 [0, 1]。
3. 使用 one-hot 标签训练 MNISTConvNet。
4. 训练结束后在项目根目录生成 training_curves.png。

当前训练脚本为了缩短运行时间，只使用前 100 个训练样本，并将 batch size 设置为 20：

train_images = train_images[:100]
train_labels = train_labels[:100]
BATCH_SIZE = 20

如果希望使用完整训练集，可以修改 project/train.py 中这几行。

模型结构

MNIST 示例模型定义在 project/model.py：

输入: (N, 1, 28, 28)
Conv2d(1 -> 8, 3x3)
ReLU
MaxPool2d(2x2)
Conv2d(8 -> 16, 3x3)
ReLU
Flatten
Linear(1936 -> 10)
输出: 10 类 logits

损失函数使用 CrossEntropyLoss，优化器使用 SGD。

测试

项目依赖中包含 pytest 和 hypothesis。如果后续添加了测试文件，可以在根目录运行：

pytest

当前仓库主要包含框架代码和训练示例，未看到独立的测试文件。

CUDA 后端说明

minitorch/cuda_kernel_ops.py 会尝试加载：

minitorch/cuda_kernels/combine.so

如果该动态库不存在，程序会打印类似提示：

cuda kernels not implemented: combine.so not found

这不影响默认 CPU 后端的阅读和实验。若要启用 CUDA 后端，需要补齐并编译对应 CUDA kernel 动态库。

常见问题

1. 运行时自动下载 MNIST 失败

可以手动把下面 4 个文件放到 data/ 目录：

train-images-idx3-ubyte.gz
train-labels-idx1-ubyte.gz
t10k-images-idx3-ubyte.gz
t10k-labels-idx1-ubyte.gz

2. 训练很慢

当前 CPU 后端中的卷积和矩阵乘法主要用于教学和验证逻辑，不是高性能实现。建议先使用小样本训练；如果要完整训练 MNIST，需要考虑优化后端或启用 CUDA 实现。

3. 控制台出现乱码

部分源码注释和旧 README 内容存在编码问题。核心代码逻辑不受影响；建议后续统一把源码文件保存为 UTF-8 编码。

开发建议

• 修改底层张量逻辑后，优先验证 tensor_data.py、tensor_ops.py、tensor_functions.py 中的广播、索引和反向传播行为。
• 修改神经网络层后，建议用小输入张量先检查 forward shape，再检查 backward 梯度。
• 训练 MNIST 前，先用小样本配置确认流程能跑通，再扩大数据规模。