# ai01

**Repository Path**: xiak/ai01

## Basic Information

- **Project Name**: ai01
- **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-02
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI

## README

# MNIST 手写数字识别 —— 传统工程师入门 AI 第一课

> 一个专为传统软件工程师（PHP/Java/JavaScript/Go 等）设计的零基础 AI 入门项目
> 
> **目标**：用最简单的方式，让传统工程师理解深度学习，并跑通第一个 AI 项目

---

## 项目简介

本项目使用 **Python + PyTorch + uv** 构建，实现了手写数字的自动识别（准确率 98%+）。

### 核心特性

- ✅ **零基础友好** - 逐行中文注释，每行代码都有详细解释
- ✅ **完整闭环** - 训练 → 预测 → 评估 → 可视化，真实工程流程
- ✅ **现代工具链** - 使用 uv 管理依赖，比 pip 快 10-100 倍
- ✅ **丰富教程** - 7 篇文档，从 AI 历史到未来学习路线
- ✅ **一键运行** - 提供 Makefile 和 Windows 批处理脚本

---

## 📋 目录

- [5 分钟快速开始](#5分钟快速开始)
- [项目结构](#项目结构)
- [依赖说明](#依赖说明)
- [部署与启动](#部署与启动)
- [使用指南](#使用指南)
- [文档教程](#文档教程)
- [常见问题](#常见问题)
- [学习路线](#学习路线)

---

## 5 分钟快速开始

### 方式一：使用 Make（推荐 Mac/Linux）

```bash
# 1. 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 进入项目
cd mnist-beginner

# 3. 一键初始化（安装 Python、依赖、创建环境）
make setup

# 4. 训练模型
make train

# 5. 查看结果
make predict
make evaluate
make visualize
```

### 方式二：Windows 批处理脚本（推荐 Windows 用户）

```powershell
# 1. 安装 uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 进入项目
cd mnist-beginner

# 3. 运行初始化脚本
scripts\setup.bat

# 4. 运行各个功能
scripts\train.bat      # 训练
scripts\predict.bat    # 预测
scripts\evaluate.bat   # 评估
scripts\visualize.bat  # 可视化
scripts\run_all.bat    # 一键运行全部
```

### 方式三：手动命令（通用）

```bash
# 1. 安装 uv（见上方）

# 2. 进入项目
cd mnist-beginner

# 3. 安装 Python 3.12
uv python install 3.12

# 4. 创建虚拟环境
uv venv

# 5. 安装依赖
uv sync

# 6. 运行训练
uv run python src/train.py
```

> 💡 **提示**：第一次运行会下载 MNIST 数据集（约 10MB），请确保网络畅通。

---

## 项目结构

```
mnist-beginner/
├── README.md                 # 本文件（项目说明）
├── QUICKSTART.md             # 5 分钟快速开始指南
├── Makefile                  # Mac/Linux 快捷命令
├── pyproject.toml            # 项目依赖配置（uv 使用）
├── .python-version           # Python 版本锁定
├── .gitignore                # Git 忽略文件
│
├── scripts/                  # Windows 批处理脚本
│   ├── setup.bat             # 环境初始化
│   ├── train.bat             # 训练模型
│   ├── predict.bat           # 运行预测
│   ├── evaluate.bat          # 评估模型
│   ├── visualize.bat         # 生成可视化
│   └── run_all.bat           # 一键运行全部
│
├── src/                      # 源代码（逐行中文注释）
│   ├── __init__.py
│   ├── train.py              # 模型训练（主程序）
│   ├── predict.py            # 单张图片预测
│   ├── evaluate.py           # 评估：混淆矩阵、F1 分数等
│   └── visualize.py          # 可视化：样本、权重、预测结果
│
├── docs/                     # 完整教程文档（必读！）
│   ├── images/               # 可视化图片输出目录
│   ├── 00-what-is-uv.md      # uv 包管理器完全入门
│   ├── 01-ai-history.md      # 第一课：AI 的起源与发展
│   ├── 02-what-is-mnist.md   # 第二课：MNIST 数据集背景
│   ├── 03-neural-network-basics.md  # 第三课：神经网络原理
│   ├── 04-environment.md     # 第四课：环境准备
│   ├── 05-project-guide.md   # 第五课：代码详解
│   ├── 06-hands-on.md        # 第六课：动手实践
│   └── 07-future-roadmap.md  # 第七课：未来学习路线
│
├── data/                     # MNIST 数据集（自动下载）
│   └── .gitkeep
│
├── models/                   # 训练好的模型保存位置
│   └── .gitkeep
│
└── notebooks/                # Jupyter Notebook（可选扩展）
```

---

## 依赖说明

### 生产依赖

| 包名 | 版本 | 用途 |
|------|------|------|
| **torch** | ≥2.0.0 | PyTorch 深度学习框架 |
| **torchvision** | ≥0.15.0 | 计算机视觉工具包，包含 MNIST 数据集 |
| **matplotlib** | ≥3.7.0 | 数据可视化，绘制图表 |
| **tqdm** | ≥4.65.0 | 进度条显示 |

### 开发依赖（可选）

| 包名 | 版本 | 用途 |
|------|------|------|
| **jupyter** | ≥1.0.0 | Jupyter Notebook 交互式开发 |
| **ipython** | ≥8.14.0 | 增强版 Python 交互式 shell |

### Python 版本要求

- **Python 3.10+**（推荐 3.12）

---

## 部署与启动

### 环境要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | Windows 10 / macOS 10.15 / Linux | 任意 |
| 内存 | 4GB | 8GB+ |
| 磁盘空间 | 2GB 空闲 | 5GB+ |
| Python | 3.10 | 3.12 |
| GPU | 不需要 | NVIDIA GPU（可选）|

### 详细部署步骤

#### 步骤 1：安装 uv

uv 是本项目的包管理工具，需要先安装它。

**Windows**（PowerShell）：
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS**：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Linux**：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

验证安装：
```bash
uv --version
# 输出类似：uv 0.5.x
```

> 📖 想了解更多 uv 的用法？阅读 [`docs/00-what-is-uv.md`](docs/00-what-is-uv.md)

#### 步骤 2：初始化项目

```bash
# 进入项目目录
cd mnist-beginner

# 运行初始化（自动安装 Python、创建环境、安装依赖）
make setup
# Windows 用户：scripts\setup.bat
```

这个过程会自动：
1. 安装 Python 3.12（如果本地没有）
2. 创建虚拟环境（`.venv/` 文件夹）
3. 安装 PyTorch 等依赖

⏱️ 耗时：3-5 分钟（主要取决于网络下载速度）

#### 步骤 3：启动训练

```bash
# 方式一：使用 Make
make train

# 方式二：使用 Windows 脚本
scripts\train.bat

# 方式三：直接运行
uv run python src/train.py
```

训练过程会显示：
- 当前 epoch / 总 epoch
- 训练进度条
- 训练集和测试集的准确率
- 最佳模型自动保存提示

⏱️ 耗时：CPU 约 2-5 分钟，GPU 约 30 秒

#### 步骤 4：使用模型

```bash
# 单张预测
make predict          # 或 scripts\predict.bat

# 全面评估
make evaluate         # 或 scripts\evaluate.bat

# 生成可视化图片
make visualize        # 或 scripts\visualize.bat

# 一键完成所有
make all              # 或 scripts\run_all.bat
```

---

## 使用指南

### 常用命令速查表

| 命令 | 作用 | Windows 替代 |
|------|------|-------------|
| `make help` | 查看所有命令 | - |
| `make setup` | 初始化环境 | `scripts\setup.bat` |
| `make train` | 训练模型 | `scripts\train.bat` |
| `make predict` | 运行预测 | `scripts\predict.bat` |
| `make evaluate` | 评估模型 | `scripts\evaluate.bat` |
| `make visualize` | 生成可视化 | `scripts\visualize.bat` |
| `make all` | 一键完成全部 | `scripts\run_all.bat` |
| `make clean` | 清理生成文件 | - |

### 文件说明

| 文件 | 用途 | 何时运行 |
|------|------|----------|
| `src/train.py` | 训练神经网络 | 首次使用或修改模型后 |
| `src/predict.py` | 对单张图片进行预测 | 想看模型效果时 |
| `src/evaluate.py` | 生成混淆矩阵和各项指标 | 想深度分析模型时 |
| `src/visualize.py` | 生成可视化图片 | 想直观理解模型时 |

---

## 文档教程

按顺序阅读，建立完整知识体系：

| 序号 | 文档 | 内容 | 阅读时间 |
|------|------|------|----------|
| 00 | [`00-what-is-uv.md`](docs/00-what-is-uv.md) | uv 包管理器完全入门 | 10 分钟 |
| 01 | [`01-ai-history.md`](docs/01-ai-history.md) | AI 的起源与发展 | 15 分钟 |
| 02 | [`02-what-is-mnist.md`](docs/02-what-is-mnist.md) | MNIST 数据集背景 | 10 分钟 |
| 03 | [`03-neural-network-basics.md`](docs/03-neural-network-basics.md) | 神经网络原理 | 20 分钟 |
| 04 | [`04-environment.md`](docs/04-environment.md) | 环境准备 | 5 分钟 |
| 05 | [`05-project-guide.md`](docs/05-project-guide.md) | 代码详解 | 30 分钟 |
| 06 | [`06-hands-on.md`](docs/06-hands-on.md) | 动手实践 | 40 分钟 |
| 07 | [`07-future-roadmap.md`](docs/07-future-roadmap.md) | 未来学习路线 | 15 分钟 |
| 08 | [`08-libraries-reference.md`](docs/08-libraries-reference.md) | 核心库详解 | 25 分钟 |

**建议学习路径**：
1. **想先跑起来**：直接看 [QUICKSTART.md](QUICKSTART.md)
2. **零基础系统学**：按 00 → 01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 顺序阅读
3. **有基础想实战**：直接跳到 06，边做实验边查 03、05 和 08
4. **想深入理解库**：重点阅读 00（uv）和 08（PyTorch/torchvision 等库详解）

---

## 常见问题

### Q1: uv 是什么？为什么不用 pip？

uv 是现代化的 Python 包管理器，比 pip 快 10-100 倍，且自动锁定依赖版本。

简单说：pip 是 "手动挡"，uv 是 "自动挡"。

详情阅读：[docs/00-what-is-uv.md](docs/00-what-is-uv.md)

### Q2: Windows 没有 make 命令怎么办？

有三种方案：

**方案 A**：使用项目提供的批处理脚本
```powershell
scripts\train.bat
scripts\predict.bat
```

**方案 B**：安装 Git for Windows，使用 Git Bash
Git Bash 自带 make 命令。

**方案 C**：直接运行 Python 命令
```bash
uv run python src/train.py
```

### Q3: 安装依赖很慢 / 下载失败？

PyTorch 较大（约 200MB），国内用户可能下载慢。

**解决方案**：
```bash
# 使用清华镜像安装 PyTorch
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# 然后安装其他依赖
uv sync
```

### Q4: 训练时报 "CUDA 不可用"？

这是正常的。本项目默认使用 CPU 版本 PyTorch，MNIST 数据量小，CPU 训练完全够用。

如果你想用 GPU，需要：
1. NVIDIA 显卡
2. 安装 CUDA Toolkit
3. 安装 GPU 版 PyTorch

对初学者来说，建议先用 CPU 版本熟悉流程。

### Q5: 如何重新开始训练？

```bash
# 删除已训练的模型
rm models/mnist_best.pt        # Mac/Linux
del models\mnist_best.pt       # Windows

# 重新训练
make train
```

### Q6: 预测自己的手写数字？

可以！按照以下步骤：

1. 用画图工具画一个 28×28 像素的灰度图（白底黑字）
2. 保存为 `my_digit.png`
3. 修改 `src/predict.py`，加载你的图片进行预测

具体代码示例见：[docs/06-hands-on.md](docs/06-hands-on.md)

---

## 学习路线

完成本项目后，你可以继续深入：

```
MNIST 入门（本项目）
    │
    ├─→ 计算机视觉路线
    │       ├─ Fashion-MNIST / CIFAR-10（换数据集练习）
    │       ├─ CNN 卷积神经网络
    │       ├─ ResNet、YOLO 等经典网络
    │       └─ Diffusion Model、Stable Diffusion
    │
    ├─→ 自然语言处理路线
    │       ├─ 文本分类
    │       ├─ RNN / LSTM
    │       ├─ Transformer / BERT
    │       └─ GPT / 大语言模型
    │
    └─→ 大模型应用开发（最热门）
            ├─ Prompt Engineering
            ├─ RAG（检索增强生成）
            ├─ Fine-tuning（微调）
            └─ AI Agent（智能体）
```

详细路线规划：[docs/07-future-roadmap.md](docs/07-future-roadmap.md)

---

## 技术栈

- **Python 3.12** - 编程语言
- **PyTorch 2.x** - 深度学习框架
- **torchvision** - 计算机视觉库
- **uv** - 包管理器
- **matplotlib** - 可视化

---

## 贡献与反馈

如果你发现：
- 文档有错误或不清晰的地方
- 代码在特定环境下无法运行
- 有更好的教学方式建议

欢迎提出反馈，帮助改进这个入门项目！

---

## 许可证

MIT License - 自由学习、自由修改、自由分享。

---

## 最后的话

> "AI 不是未来，AI 就是现在。传统工程师最好的转型时机，一个是十年前，一个是今天。"

这个项目很小，但它是一扇大门。你现在已经跨过了这扇门，门后是一片广阔的天地。

**祝你学习愉快，早日成为 AI 时代的全栈工程师！** 🚀

---

**快速导航**：
[5 分钟开始](#5分钟快速开始) • 
[文档教程](#文档教程) • 
[常见问题](#常见问题) • 
[学习路线](#学习路线)