# mnist-web-base

**Repository Path**: Mather/mnist-web-base

## Basic Information

- **Project Name**: mnist-web-base
- **Description**: 一个支持离线训练和 Web 预测的 MNIST MLP 模型项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MNIST-Web

<p align="center">
  <img src="screenshot.jpg" alt="项目界面预览" width="500" />
</p>

这是一个从零构建、支持离线模型训练与在线 Web 预测的端到端 AI 项目。

项目基于现代 Python 工程化标准构建，使用 `scikit-learn` 训练多层感知机（MLP）模型，
并通过 Flask 提供标准的 RESTful API 与开箱即用的前端交互页面。

## 📁 项目结构

本项目采用了标准的 Python `src` 目录布局，实现了训练逻辑与推理逻辑的彻底解耦：

```text
.
├── mnist/                  # 原始数据集
│   ├── dataset.npy
│   └── class.npy
├── model/                  # 训练产出的模型与预处理文件
│   ├── mlp_model5000.pkl
│   └── scaler.pkl
├── img/                    # 手写数字图片
├── src/
│   └── mnist_model/        # mnist_model 程序源码
│       ├── __init__.py     
│       ├── train.py        # 模型训练程序
│       ├── app.py          # 启动 Web 服务程序
│       └── templates/
│           └── index.html  # 前端交互界面
├── pyproject.toml          # 项目配置文件
└── README.md               # 项目说明文档
```

## 📋 软件环境

在安装和运行本项目之前，请确保您的设备满足以下软件环境：

- 语言环境 Python: `== 3.8.*`
- 包管理工具: `uv`

## 🛠️ 环境配置与安装

本项目使用 uv 工具管理项目和依赖

1. 创建并激活虚拟环境：

```bash
    # 创建虚拟环境并自动根据 pyproject.toml 安装依赖
    uv venv
    
    # Windows 系统中使用下面的命令激活环境 
    .\.venv\Scripts\activate
    
    # Linux/macOS 系统中使用下面的命令激活环境
    source .venv/bin/activate
```

2. 安装项目依赖：
确保环境激活后，一键安装项目所需的第三方库（如 Flask, scikit-learn 等）：

```bash
    uv sync
```

## 📥 数据准备

由于 MNIST 数据集体积较大，Git 仓库内未包含原始数据集。在运行项目前，必须执行以下数据准备脚本
```bash
    uv run python download_data.py
```

该脚本会自动从 OpenML 镜像站下载原始数据，并在项目根目录下创建 mnist/ 文件夹，生成项目所需的 dataset.npy 和 class.npy 文件。

## 🤖 训练模型

由于本地仓库没有内置现成的模型，你需要亲自运行训练脚本，来生产用于推理的 AI 模型：

```bash
  uv run train-mnist
```

根目录下会自动创建 model/ 文件夹，并生成 `mlp_model5000.pkl`模型文件和 `scaler.pkl`数据预处理文件。

如果你想使用更多的数据进行更长时间的训练，可以尝试携带参数运行`uv run train-mnist --samples 10000`

## 🚀 启动 Web 服务

当完成了上述的 环境安装、数据下载、模型训练 后，准备工作就彻底完成了，现在可以启动网页端进行手写数字识别的交互了：

```bash
  uv run serve-mnist
```

启动后，直接在浏览器中访问 http://127.0.0.1:5000 ，在前端页面上直接手写数字，或者上传一张手写数字图片，点击预测，网页将实时调用你刚刚亲手训练出来的模型并返回识别结果

## 🔌 Web API 接口文档

如果你需要在其他前端项目（如 Vue.js / React 应用）中调用此模型，可以直接对接以下接口。本项目已预埋 flask-cors 支持，本地开发无跨域烦恼。

### 手写数字识别预测接口

- 接口路径: `/predict`
- 请求方法: `POST`
- 请求头: `Content-Type: multipart/form-data`

#### 请求参数 (Body)
请使用表单数据（FormData）格式提交以下参数：

| 参数名 | 类型 | 是否必填 | 示例 |  描述说明 |
| :--- | :--- | :--- | :--- | :--- |
| `image` | `File` (文件) | **是** | `digit.png` | 手写数字的图片文件（建议为**黑底白字**的 PNG/JPG，尺寸不限，后台会自动调整为 28x28 像素）。 |

#### 响应示例

成功响应 `200 OK`:
```json
{
  "message": "识别成功",
  "predicted_digit": 5,
  "confidence": 0.9842
}
```

失败响应 `400 Bad Request`:

未上传图片或字段名错误

```json
{
  "message": "错误：请求中未捕获到名为 'image' 的图片文件"
}
```