# machineLearning-demo

**Repository Path**: sdssaa/machineLearning-demo

## Basic Information

- **Project Name**: machineLearning-demo
- **Description**: 1234567890
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Machine Learning Demo

一个**端到端的全栈机器学习平台**，覆盖数据集管理 → 参数配置 → 模型训练 → 模型管理 → 在线推理的完整工作流，并提供模型溯源（Model → Dataset + Params）能力。

## ✨ 特性

- **数据集管理**：上传 CSV，自动解析列名/行数/类型，预览数据，统计描述
- **训练参数管理**：6 种主流 ML 算法（线性/逻辑回归、随机森林、SVM）的超参数预设
- **模型训练**：基于 SSE 的实时训练进度流（数据加载→预处理→划分→标准化→训练→评估→保存）
- **模型管理**：通过外键关联（`dataset_id` + `params_id`）实现模型溯源时间线
- **模型推理**：加载已保存模型，输入特征即可获得预测值与分类概率分布
- **美观界面**：基于 Element Plus 的现代深色侧边栏 + 浅色内容布局

## 🏗️ 技术栈

| 层 | 技术 |
|---|---|
| 后端 | FastAPI + SQLAlchemy + scikit-learn + joblib + sse-starlette |
| 数据库 | MySQL 8.0（数据库名 `ml_demo`，启动时自动建表） |
| 前端 | Vue 3 (Composition API) + Vite + Element Plus + Pinia + ECharts + axios |
| 包管理 | uv (后端) · npm (前端) |

## 📁 项目结构

```
machineLearning-demo/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI 入口
│   │   ├── database.py      # SQLAlchemy 连接
│   │   ├── models.py        # ORM：Dataset / TrainingParam / Model（含溯源 property）
│   │   ├── schemas.py       # Pydantic Schemas + JSON 字段 validator
│   │   ├── core/config.py  # 设置 + 资源路径
│   │   ├── routers/
│   │   │   ├── datasets.py    # CSV 上传/预览/统计
│   │   │   ├── params.py      # 训练参数 CRUD
│   │   │   ├── training.py    # 训练任务 + SSE 流式进度
│   │   │   ├── models.py      # 模型 CRUD + 溯源查询
│   │   │   └── inference.py   # 模型推理
│   │   └── ml/trainer.py   # 训练引擎 + 推理 + 任务存储
│   ├── data/                # 上传的 CSV 存储位置
│   ├── models_store/        # 训练好的 .joblib 模型
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── api/index.ts         # axios 封装 + 全部 API
│   │   ├── router/index.ts      # 路由
│   │   ├── stores/app.ts        # 全局状态
│   │   ├── layouts/MainLayout.vue  # 主布局
│   │   └── views/
│   │       ├── Dashboard.vue    # 仪表盘
│   │       ├── Datasets.vue     # 数据集管理
│   │       ├── Params.vue       # 训练参数
│   │       ├── Training.vue     # 模型训练（SSE 实时进度）
│   │       ├── Models.vue       # 模型管理 + 溯源
│   │       └── Inference.vue    # 模型推理
│   └── vite.config.ts         # 已配置 /api → 8000 代理
└── README.md
```

## 🚀 启动方式

### 1. 准备数据库

确保 MySQL 已安装并运行。本项目的默认连接配置为：

```
host=localhost  port=3306  user=root  password=qwe147  db=ml_demo
```

如需修改，编辑 `backend/app/core/config.py` 中的 `Settings` 或创建 `backend/.env` 文件覆盖。

创建数据库（首次）：

```bash
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS ml_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

> 表 (`datasets` / `training_params` / `models`) 由 FastAPI 启动时自动创建。

### 2. 启动后端

```bash
cd backend
uv sync                      # 安装依赖（首次）
.venv/Scripts/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

访问：http://127.0.0.1:8000/docs 查看 Swagger UI。

### 3. 启动前端

```bash
cd frontend
npm install                  # 首次
npm run dev
```

访问：http://localhost:5173

> 前端 `vite.config.ts` 中已配置 `/api` 反向代理到后端 8000 端口，无需关心跨域。

## 🧪 完整流程示例

1. **数据集管理** → 上传 `loan_data.csv`（包含 age、income、credit_score、loan_approved 等列），系统自动解析列、行数
2. **训练参数** → 新建「随机森林默认」，算法 `random_forest_classifier`，参数 `{"n_estimators": 100}`
3. **模型训练**：
   - 选择数据集 + 参数集
   - 选择目标列（如 `loan_approved`）
   - 设置测试集比例（默认 20%）
   - 点击「开始训练」→ 实时观察 SSE 进度（数据加载→预处理→训练→评估→保存）
   - 训练完成后查看指标（准确率/精确率/召回率/F1/混淆矩阵）
   - 点击「保存模型」 → 给个名称即可保存到模型库
4. **模型管理** → 查看已保存模型 → 点击「溯源」查看完整血缘时间线（模型 ← 数据集 + 参数集）
5. **模型推理** → 选择已保存模型 → 输入特征值 → 实时获得预测结果与类别概率分布

## 🔌 API 一览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 健康检查 |
| GET/POST/PUT/DELETE | `/api/datasets` | 数据集 CRUD |
| GET | `/api/datasets/{id}/preview` | 数据预览 |
| GET | `/api/datasets/{id}/stats` | 数据统计描述 |
| GET/POST/PUT/DELETE | `/api/params` | 训练参数 CRUD |
| POST | `/api/training/start` | 启动训练（后台任务） |
| GET | `/api/training/stream/{task_id}` | SSE 实时训练流 |
| GET | `/api/training/status/{task_id}` | 训练状态查询 |
| POST | `/api/training/discard/{task_id}` | 放弃并清理训练产物 |
| GET/POST/PUT/DELETE | `/api/models` | 模型 CRUD |
| POST | `/api/models/from-task/{task_id}` | 从训练任务保存模型并建立溯源 |
| GET | `/api/models/{id}/lineage` | 模型溯源（关联数据集+参数集） |
| POST | `/api/inference/predict` | 模型推理 |
| GET | `/api/inference/model/{id}/schema` | 模型输入 schema |