# material-platform

**Repository Path**: strongqiding/material-platform

## Basic Information

- **Project Name**: material-platform
- **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-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物料识别模型平台 (Material Recognition Model Platform)

陕汽门区物料识别的一站式 Web 平台：**推理可视化 + 数据集管理 + 训练管理(含二次训练) + 模型管理导出**。
独立部署在 200 服务器，单端口 5010 同时托管页面与 API，无需登录。

---

## 一、访问地址

```
http://192.168.1.200:5010
```

浏览器直接打开即用（无登录）。左侧菜单四大模块：推理可视化 / 数据集管理 / 训练管理 / 模型管理。

---

## 二、启停管理

部署目录：`/home/dell/docker/material-platform/`

```bash
cd /home/dell/docker/material-platform
./manage.sh start      # 启动 (端口 5010)
./manage.sh stop       # 停止主服务 (不会杀掉后台训练子进程)
./manage.sh restart    # 重启
./manage.sh status     # 查看状态/内存/最近日志
./manage.sh logs       # 实时跟踪日志
```

> **注意**：`stop` 只停 Web 主服务，正在跑的训练任务因 `start_new_session` 已与主服务隔离，**不会被中断**，重启后仍能在任务列表看到其进度（状态从文件系统恢复）。

---

## 三、四大模块使用说明

### 1. 推理可视化 `/infer`
顶部可切换**单图推理 / 多视角投票**两种模式。

**单图推理**：
1. 选择**模型**（下拉显示 mAP50）。
2. 拖动**置信度阈值**滑块（默认 0.40，与现场部署口径一致）。
3. 选择**输入尺寸**：常规 640；**pipe 管端面模型自动切 1280**。
4. **上传本地图片** 或 **选数据集中的图**，点「开始推理」。
5. 右侧展示**带框大图** + **按类计数表** + **置信分级徽标**（HIGH≥0.60 / MEDIUM≥0.40 / N_A）。

**多视角投票**（模拟现场多机位同场景拍照）：
1. 上传**同一场景的多张图（≥2张，不同机位）**。
2. 点「投票合并计数」。
3. 各视角各自计数，取**众数(median)**作为事件级最终物料数，抵消单视角漏检/重复——与 ai-worker/gateway 部署口径一致。
4. 展示**事件级合并计数** + **各视角原始计数**。

### 2. 数据集管理 `/datasets`
- 卡片网格展示全部数据集（train/val 图数）。
- 「上传数据集」：上传 **YOLO 格式 zip**（内含 `images/` `labels/`），解压进 `datasets/`。
- 点卡片看详情：**类别分布柱状图**、每类框数、**校验告警**（无标签/坐标越界等）、**验证集缩略图墙**。
- 「重新划分」：按指定比例重新随机划分 train/val。
- 卡片右上**删除**按钮：二次确认后 `rm -rf datasets/<name>`（不可逆）。

### 3. 训练管理 `/train`
- 左侧表单：
  - **基座模型**分两组：`COCO 预训练`（全新训练）/ `二次训练`（选已有模型 best.pt 继续训）。
  - 数据集 yaml、imgsz、batch（-1 自动）、epochs、输出名称。
- 点「启动训练」。**单 GPU 串行**：已有训练在跑时新任务返回 **409**（GPU 忙）。
- 右侧监控：任务列表（状态/进度条/epoch）、**实时 mAP 曲线**、**训练日志面板**、「停止」按钮。
- 进度判定：轮询 `runs/<name>/results.csv` 行数 ÷ epochs；**DONE 以 best.pt 出现为准**。

### 4. 模型管理 `/models`
- 表格扫描 `runs/`：mAP50 / mAP50-95 / imgsz / **ONNX·RKNN 徽标** / 时间。
- **多选对比**：勾选 ≥2 个模型点「对比」，并列展示 mAP/精度/召回/epochs/基座 + **柱状对比图**。
- 「验证」：**双口径 + mAP**——
  - **mAP50 / mAP50-95**（标准 `model.val()` 口径）
  - **精确口径**（计数完全相等，val.py 原口径）
  - **容差口径**（±容差内命中率 + 平均相对误差）——密集类（如管端面）看容差口径更合理。
- 「导ONNX」：调 `export_onnx.py`，imgsz 跟随模型。
- 「转RKNN」下拉选量化：
  - **FP16**（验证用，快）
  - **INT8**（正式部署，自动用模型训练集图做校准，需 ≥20 张）。
  跨容器调度 `rknn-sim`（docker cp → exec → cp 回），生成 `best.rknn`。
- 「下载」：best.pt / best.onnx / best.rknn。
- **删除**：二次确认后 `rm -rf runs/<name>`（不可逆）。

---

## 四、典型工作流（二次训练为例）

1. `/datasets` 上传补采的新数据集 zip。
2. `/train` 基座选「二次训练 → 已有 pipe 模型 best.pt」，数据集选新集，启动训练。
3. 右侧看 mAP 曲线收敛，DONE 后到 `/models`。
4. `/models` 对新模型「验证」（双口径达标）→「导ONNX」→「转RKNN」→「下载 best.rknn」。
5. 把 best.rknn 部署到 RK3588 网关 ai-worker。

---

## 五、技术架构与目录

- **后端**：FastAPI + uvicorn，系统 `/usr/bin/python3`（与攻关同环境，不建 venv），端口 5010。
- **前端**：Vue3 + Vite + Element Plus + ECharts，`npm run build` 出 `dist/`，由 FastAPI `StaticFiles` 单端口托管。
- **训练长任务**：`subprocess.Popen`（`start_new_session` 脱离主服务）+ pid/日志文件 + **单 GPU 串行锁**。状态即文件系统，**无数据库/队列**。
- **复用**：推理/计数/校验**直接 import** `infer_test.py`/`prepare_dataset.py` 纯函数；训练/val/导出走 **subprocess 调攻关脚本**（6 个脚本零改造）。

```
/home/dell/docker/material-platform/
├── manage.sh                 # 启停脚本
├── backend/app/
│   ├── main.py               # FastAPI 入口 + 托管 dist + 路由
│   ├── config.py             # MODEL_ROOT/PORT/RKNN_CONTAINER
│   ├── reuse.py              # import 攻关纯函数
│   ├── routers/{infer,datasets,train,models}.py
│   └── services/{job_manager,infer_service,rknn_service,scan_service}.py
├── backend/data/{jobs,uploads,infer_out}/   # 任务/上传/画框图
├── frontend/                 # Vue3 工程 + dist/
└── links/model -> /home/dell/model          # 软链, 共用攻关产物
```

> 训练输出仍落 `MODEL_ROOT/runs/`、数据集在 `MODEL_ROOT/datasets/`——**平台与命令行共用同一份产物**。

---

## 六、重新构建前端

改了 `frontend/src/` 后：

```bash
cd /home/dell/docker/material-platform/frontend
npm run build
cd .. && ./manage.sh restart
```

---

## 七、第三方调用 / API 文档

左侧菜单「**API 文档**」打开 FastAPI 自动生成的 **Swagger UI**（`http://192.168.1.200:5010/docs`），可在线查看全部接口定义、参数、试调用。第三方系统按此对接即可。
OpenAPI JSON：`http://192.168.1.200:5010/openapi.json`。

### 关键 API 速查（前缀 /api）

| 模块 | 方法 | 路径 |
|---|---|---|
| 健康 | GET | `/api/health` |
| 推理 | GET/POST | `/api/infer/models`、`/api/infer/predict`、`/api/infer/predict-multi`(多视角投票) |
| 数据集 | GET/POST/DELETE | `/api/datasets`、`/api/datasets/{ds}`、`/api/datasets/upload`、`DELETE /api/datasets/{ds}` |
| 训练 | GET/POST | `/api/train/base-models`、`/api/train/start`、`/api/train/jobs/{id}`、`/api/train/jobs/{id}/stop` |
| 模型 | GET/POST/DELETE | `/api/models`、`/api/models/{n}/validate`(双口径+mAP)、`/api/models/{n}/export-onnx`、`/api/models/{n}/export-rknn`(quant=fp/i8)、`/api/models/{n}/download/{kind}`、`DELETE /api/models/{n}` |