# ai02

**Repository Path**: xiak/ai02

## Basic Information

- **Project Name**: ai02
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI

## README

# 🧠 纯前端神经网络：手写数字识别

这是一个**完全使用原生 JavaScript** 实现的手写数字识别项目，不依赖 TensorFlow、PyTorch 或任何第三方神经网络库。

本项目的目标是帮助初学者从零开始理解机器学习的核心原理：微积分、导数、梯度下降和反向传播。所有代码都带有详细的中文注释，并配有 5 篇循序渐进的教程文档。

![项目预览](docs/preview.png)

---

## ✨ 项目亮点

- **纯原生实现**：没有任何机器学习框架，所有矩阵运算、激活函数、反向传播算法均手写。
- **完整训练流程**：支持在浏览器中使用真实 MNIST 数据集进行端到端训练。
- **实时可视化**：
  - 观察信息如何在神经网络中前向流动
  - 实时监测 Loss 下降曲线和测试准确率
  - 查看第一层权重如何演化成"特征探测器"
- **后台训练**：使用 Web Worker 进行训练，页面不会卡死。
- **零基础教程**：附带 5 篇从微积分讲到实战代码的教程文档。

---

## 🚀 快速开始

### 1. 克隆或下载项目

```bash
git clone <仓库地址>
cd ai02
```

### 2. 下载 MNIST 数据集

确保已安装 Python 3，然后运行：

```bash
python prepare_mnist.py
```

脚本会自动下载 MNIST 数据集并转换为浏览器友好的 JSON 格式，生成：
- `data/mnist_train.json`（约 100 MB）
- `data/mnist_test.json`（约 17 MB）

> 如果你不想下载真实数据，直接打开网页也可以运行。此时系统会自动生成**合成数据**供你快速体验流程（但准确率会明显低于真实 MNIST）。

### 3. 启动本地服务器

由于浏览器的安全限制（CORS），不能直接用 `file://` 协议加载本地 JSON。请启动一个本地 HTTP 服务器：

**使用 Python：**
```bash
python -m http.server 8000
```

**使用 Node.js：**
```bash
npx serve .
```

### 4. 打开浏览器

访问 `http://localhost:8000`，按照页面提示开始训练和识别。

---

## 📚 教程文档

建议按顺序阅读：

| 文档 | 内容 |
|------|------|
| [01. 微积分基础](docs/01-微积分基础.md) | 从瞬时速度理解导数 |
| [02. 导数与链式法则](docs/02-导数与链式法则.md) | 复合函数求导，ReLU/Sigmoid 导数 |
| [03. 梯度下降](docs/03-梯度下降.md) | 下山类比，学习率，SGD vs Mini-batch |
| [04. 反向传播](docs/04-反向传播.md) | 深度学习的核心算法完整推导 |
| [05. 实战代码详解](docs/05-从零实现神经网络.md) | 逐行解读 `neural-network.js` |

---

## 🗂️ 项目结构

```
ai02/
├── index.html              # 主页面（UI + Canvas）
├── css/
│   └── style.css           # 暗色科技风样式
├── js/
│   ├── math-utils.js       # 矩阵运算、激活函数、损失函数
│   ├── neural-network.js   # ⭐ 神经网络核心（前向+反向传播）
│   ├── mnist-loader.js     # MNIST 数据加载 / 合成数据生成
│   ├── trainer-worker.js   # Web Worker 训练器
│   ├── visualizer.js       # Canvas 实时可视化
│   └── app.js              # 主逻辑，串联所有模块
├── data/                   # MNIST JSON 数据（由脚本生成）
├── prepare_mnist.py        # Python 数据下载转换脚本
├── docs/                   # 教程文档
└── README.md               # 本文件
```

---

## 🔧 网络架构

本项目使用了一个四层全连接神经网络（两个隐藏层）：

```
输入层 (784) ──→ 隐藏层1 (256, ReLU) ──→ 隐藏层2 (128, ReLU) ──→ 输出层 (10, Softmax)
```

- **输入层**：784 个神经元，对应 MNIST 图片的 28×28 个像素。
- **隐藏层1**：256 个神经元，激活函数为 ReLU，负责提取初级笔画特征（横、竖、斜线）。
- **隐藏层2**：128 个神经元，激活函数为 ReLU，负责组合初级特征形成更复杂的数字模式。
- **输出层**：10 个神经元，激活函数为 Softmax，输出 0-9 的概率分布。

参数总量约为 **235,000** 个（含权重和偏置）。更深的网络带来了更强的表达能力，在 MNIST 上更容易达到 95% 以上的准确率。

---

## 🎮 使用界面说明

### 左侧面板：手写识别
- 在黑色画布上画出 0-9 的任意一个数字。
- 点击"识别"按钮，观察模型预测结果。
- 下方的柱状图显示了模型对 10 个数字的概率分布。

### 中间面板：神经网络结构
- 实时展示前向传播时各层神经元的激活状态。
- 神经元越亮，表示激活值越高。
- 输入层的 28×28 网格直接对应你手写的笔迹。

### 右侧面板：训练控制台
- **损失曲线**：实时绘制训练过程中的 Loss 变化。
- **测试准确率**：每个 epoch 结束后在测试集上评估。
- **权重热力图**：把第一层 128 个神经元的权重画成 28×28 的小图，观察模型学到的特征模式。

---

## 🧪 实验建议

1. **调整学习率**：试试 0.01、0.1 和 0.5，观察 Loss 曲线的震荡和平滑程度。
2. **改变批次大小**：试试 8、32 和 128，感受训练速度和稳定性的权衡。
3. **增加训练轮数**：在真实 MNIST 上，通常 5-10 个 epoch 就能达到 90% 以上准确率。

---

## ⚠️ 已知限制

- **训练速度**：纯 JavaScript 在 CPU 上的训练速度远不如 Python + GPU（CUDA）。在普通电脑上，一个 epoch 可能需要 1-3 分钟。这是用原生前端代码演示深度学习原理所付出的代价。
- **浏览器兼容性**：请使用现代浏览器（Chrome、Edge、Firefox、Safari 最新版）。Internet Explorer 不受支持。

---

## 📖 学习路径建议

如果你是完全的初学者，建议按下面这个顺序学习：

1. **先读文档**：依次阅读 `docs/` 下的 5 篇教程。
2. **再看代码**：重点看 `js/neural-network.js` 和 `js/math-utils.js`。
3. **动手修改**：
   - 改学习率、改 batch size，看效果。
   - 在网络里再加一层（比如 [784, 256, 128, 10]）。
   - 把 ReLU 换成 Leaky ReLU。
4. **尝试扩展**：加入学习率衰减、Momentum、Dropout 等经典技巧。

---

## 📄 许可证

本项目仅用于教育和学习目的。数据来自公开的 [MNIST 数据集](http://yann.lecun.com/exdb/mnist/)。

---

Happy Learning! 🎉