# AutoMLPlatform

**Repository Path**: hqr77/auto-mlplatform

## Basic Information

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YOLO26 AutoML Platform 🚀

企业级自动化目标检测训练平台 — 集成训练、导出、校准、Benchmark、诊断、报告与打包的一体化流水线。

---

## 目录

- [系统架构](#系统架构)
- [功能盘点](#功能盘点)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [一键启动平台](#一键启动平台)
- [使用方法](#使用方法)
- [AutoML 逻辑详解](#automl-逻辑详解)
- [输出说明](#输出说明)
- [API 参考](#api-参考)
- [高级配置](#高级配置)
- [故障排查](#故障排查)

---

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                          入口层                                  │
│  start_platform.bat   run_automl.bat   FastAPI Server   WebUI   │
└────────────────┬──────────────┬──────────────────────────────────┘
                 │              │
                 ▼              ▼
┌────────────────────────────────────────────────────────────────┐
│                    core / automl_task.py                        │
│                  （8 步流水线编排入口）                          │
│                                                                  │
│  automl_config ──► train_core ──► export_automl                 │
│       │                │               │                        │
│       │           analysis_automl   int8_calib                  │
│       │                │                                        │
│       └──────► automl_task ◄────────────────────────────────┐  │
│                        │                                     │  │
│              benchmark ─┤─ report ─┤─ package ─┤─ log_analyzer │
└────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────────────┐
│                        输出层                                    │
│   runs/detect/<n>/   weights/   report.html   deploy_package/   │
└────────────────────────────────────────────────────────────────┘
```

### 核心设计原则

| 原则 | 实现方式 |
|------|----------|
| **数据驱动配置** | 所有超参（batch、lr、epochs、增强）由数据集统计量和 GPU 显存自动推算 |
| **流水线可裁剪** | `run_automl_task()` 每步均有 `do_*` 开关，按需启用 |
| **状态可持久化** | API 任务写入 `tasks_data/*.json`，服务重启后自动恢复 |
| **并发安全** | `asyncio.Semaphore` 控制最大并发训练数，超出的任务显示 `queued` |
| **诊断闭环** | 训练后自动分析曲线和日志，给出参数建议，可进入 AutoML Loop 自动迭代 |

---

## 功能盘点

### AutoML 自适应能力

| 功能 | 实现细节 |
|------|----------|
| **GPU / 显存检测** | 读取空闲显存（非总量），更准确地反映可用资源 |
| **模型规模自选** | 空闲显存 < 4G→nano，4-6G→small，7-11G→medium，12-17G→large，≥18G→xlarge |
| **batch size 精细计算** | `空闲显存×0.75 / 模型系数 / (imgsz/640)²`，对齐到2的倍数 |
| **学习率线性缩放** | `lr0 = 0.0005 × (batch/16)`，batch 和 lr 联动 |
| **epochs 6 档细分** | <100张→200，<500→150，<2000→120，<5000→100，<10000→80，≥10000→50 |
| **图像尺寸自适应** | 平均目标面积 < 5%→1280，< 10%→960，其余→640 |
| **增强策略 4 档** | small/medium/large/xlarge 按数据集规模差异化配置，防小数据集 mAP 崩盘 |
| **类别名称智能读取** | 优先级：`names.txt` → `classes.txt` → `data.yaml` → 占位名兜底 |
| **data.yaml 自动生成** | 数据集目录无 yaml 时自动生成，含真实类别名 |

### 训练优化参数

| 参数 | 值 | 作用 |
|------|----|------|
| `optimizer` | AdamW | 比 SGD 更稳定，防过拟合 |
| `cos_lr` | True | 余弦学习率衰减，平滑收敛 |
| `warmup_epochs` | 5 | 延长预热期，保护预训练权重 |
| `warmup_momentum` | 0.5 | 预热阶段降低动量，更温和更新 |
| `patience` | 30 | 早停耐心值，防止无效训练 |
| `close_mosaic` | 10 | 最后 10 轮关闭 mosaic，提升精度 |
| `amp` | True | 混合精度训练，速度提升约 2× |
| `cache` | disk | 磁盘缓存，稳定性优于内存缓存 |
| `rect` | True | 矩形训练，减少填充，加速数据加载 |

### 训练后流水线（8 步）

| 步骤 | 模块 | 说明 |
|------|------|------|
| 1 数据集验证 | `dataset_utils` | 路径检查 + 自动生成 data.yaml + 类别名读取 |
| 2 参数生成 | `automl_config` | GPU 显存 → 模型/batch/lr/imgsz/增强策略 |
| 3 训练 | `train_automl_core` | AdamW + cos_lr + AMP + 早停 + 矩形训练 |
| 4 导出 | `export_automl` | ONNX (opset=17) + TRT FP16 + TRT INT8 |
| 5 Benchmark | `benchmark_automl` | 多格式延迟/FPS/模型大小对比 |
| 6 部署打包 | `package_automl` | ZIP 含模型 + 推理示例 + 元数据 |
| 7 曲线诊断 | `analysis_automl` | 6 种问题自动检测，给出参数建议 |
| 8 报告生成 | `report_automl` | Chart.js 交互曲线 + 诊断区块 HTML 报告 |

### 自动诊断能力

| 诊断状态 | 触发条件 | 典型建议 |
|---------|----------|----------|
| `stable` | 无异常 | — |
| `early_instability` | 前 10 轮 loss 变异系数 > 0.3 | 降低 lr0，增加 warmup |
| `overfit` | train loss 降但 val mAP 停滞 | 减少 epochs，增加 mixup/erasing |
| `underfit` | 最终 mAP < 0.3 | 增加 epochs，换更大模型 |
| `lr_too_high` | loss 爆炸或前 5 轮 loss 上升 | 大幅降低 lr0 |
| `augment_too_strong` | 前 20 轮 mAP < 0.1 且波动大 | 降低 mosaic，关闭 mixup/erasing |
| `slow_convergence` | 最后 20 轮 mAP 仍明显提升 | 增加 epochs |

### Web 平台功能

| 功能 | 说明 |
|------|------|
| REST API | FastAPI + Swagger UI 文档 (`/docs`) |
| 任务状态 4 态 | `pending → queued → running → completed/failed` |
| 任务持久化 | `tasks_data/*.json`，重启后自动恢复 |
| 并发控制 | `asyncio.Semaphore`，默认最大 2 个并发任务 |
| CORS 安全 | 通过环境变量 `AUTOML_ALLOWED_ORIGINS` 精确配置 |
| API Key 验证 | 可选启用，环境变量 `AUTOML_API_KEY` |
| Web UI | Flask+SocketIO，实时日志推送，可视化监控 |
| AutoML Loop | 训练→分析→调参→再训练自动闭环迭代 |

---

## 项目结构

```
AutoMLPlatform/
│
├── start_platform.bat         # 🚀 一键启动平台（API + WebUI + 自动开浏览器）
├── stop_platform.bat          # 🛑 一键停止平台（释放端口 8000 / 5000）
├── start_api.bat              # 单独启动 API 服务
├── start_webui.bat            # 单独启动 Web UI
├── run_automl.bat             # 命令行一键训练
├── run_automl_loop.bat        # AutoML Loop 自动迭代训练
├── run_export.bat             # 仅执行模型导出
├── kill_gpu_users.bat         # 强制释放 GPU 占用进程
│
├── requirements.txt           # Python 依赖列表
│
├── core/                      # 核心业务逻辑
│   ├── automl_types.py        # 数据结构定义（DatasetInfo/GPUInfo/AutoMLConfig/AutoMLResult）
│   ├── automl_config.py       # 自适应参数生成（batch/lr/epochs/imgsz/增强策略）
│   ├── automl_task.py         # 8步流水线编排（唯一对外入口）
│   ├── automl_loop.py         # AutoML 自动迭代优化（训练→分析→调参→循环）
│   ├── train_automl_core.py   # YOLO 训练封装（含完整优化参数）
│   ├── export_automl.py       # ONNX / TensorRT FP16 / INT8 导出
│   ├── int8_calib.py          # TensorRT INT8 校准数据集准备
│   ├── benchmark_automl.py    # 多格式推理性能对比
│   ├── report_automl.py       # HTML 报告生成（Chart.js 曲线 + 诊断区块）
│   ├── analysis_automl.py     # 训练曲线自动诊断（6 种问题检测）
│   ├── log_analyzer.py        # 训练日志异常扫描（OOM/NaN/DataLoader）
│   ├── package_automl.py      # 部署包 ZIP 打包
│   └── utils/
│       ├── gpu_utils.py       # GPU 检测 + select_model_for_gpu()
│       ├── dataset_utils.py   # 数据集分析 + 类别名称智能读取
│       └── file_utils.py      # 文件操作 + 任务 ID 生成
│
├── api/
│   └── server.py              # FastAPI REST API（任务队列 + 持久化 + CORS 安全）
│
├── webui/
│   ├── webui_automl.py        # Flask+SocketIO Web UI（实时日志推送）
│   └── templates/             # Jinja2 模板
│
├── scripts/
│   ├── run_automl.py          # CLI 一键训练脚本
│   ├── run_automl_loop.py     # CLI AutoML Loop 脚本
│   ├── run_export.py          # CLI 仅导出脚本
│   └── run_benchmark.py       # CLI 批量 Benchmark 脚本
│
├── configs/
│   ├── yolo26_config.yaml     # 默认训练配置（opset=17, AdamW, cos_lr, patience=30…）
│   └── augment_profiles.yaml  # 4 档增强策略（small/medium/large/xlarge）
│
├── models/
│   ├── yolo26n.pt             # 预训练权重（nano）
│   └── yolo26s.pt             # 预训练权重（small）
│
├── tasks_data/                # 任务持久化目录（自动生成）
│   └── task_*.json
│
├── datasets/                  # 数据集目录
│   └── <your_dataset>/
│       ├── images/train/
│       ├── images/val/
│       ├── labels/train/
│       ├── labels/val/
│       ├── names.txt          # 可选：每行一个类别名
│       └── data.yaml          # 自动生成
│
└── runs/                      # 训练输出（自动生成）
    └── detect/
        └── <dataset>_<timestamp>/
            ├── weights/
            │   ├── best.pt
            │   ├── best.onnx          # opset=17, dynamic batch
            │   ├── best_fp16.engine   # TensorRT FP16
            │   └── best_int8.engine   # TensorRT INT8
            ├── results.csv
            ├── report.html            # 交互式训练报告
            ├── analysis.json          # 训练曲线诊断结果
            ├── train.log              # 完整训练日志
            ├── benchmark.json         # 推理性能数据
            ├── automl_result.json     # 任务完整结果
            └── deploy_package/        # 部署包
```

---

## 快速开始

### 1. 安装依赖

```bash
conda create -n yolo26 python=3.10
conda activate yolo26

# PyTorch（CUDA 12.x）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 平台依赖
pip install -r requirements.txt

# TensorRT（可选，推理加速）
pip install nvidia-pyindex tensorrt-cu12
```

### 2. 准备数据集

```
your_dataset/
  images/
    train/   *.jpg / *.png
    val/     *.jpg / *.png
  labels/
    train/   *.txt  （YOLO 格式：class_id cx cy w h，均归一化）
    val/     *.txt
  names.txt          ← 可选，每行一个类别名，行号对应 class_id
```

### 3. 一键训练

```bat
run_automl.bat datasets\your_dataset
```

或 Python：

```bash
python scripts/run_automl.py --dataset datasets/your_dataset
```

---

## 一键启动平台

项目目录下提供两个脚本，双击即可启动或关闭整个平台。

### 启动

```bat
start_platform.bat
```

脚本依次执行：

```
[1/5] 检查 conda 并激活 yolo26 环境
[2/5] 自动检测并补装缺失依赖（ultralytics / fastapi / flask-socketio / pandas）
[3/5] 检测端口 8000 / 5000 是否被占用，冲突时询问是否继续
[4/5] 交互式安全配置（API Key、最大并发数，直接回车跳过使用默认值）
[5/5] 在独立控制台窗口启动 API 和 Web UI，等待就绪后自动打开浏览器
```

启动成功后显示：

```
╔══════════════════════════════════════════════════════════╗
║   平台已启动！                                           ║
║                                                          ║
║   🖥  Web UI      http://localhost:5000                  ║
║   ⚡  API 服务    http://localhost:8000                  ║
║   📄  API 文档    http://localhost:8000/docs             ║
╚══════════════════════════════════════════════════════════╝
```

> 关闭启动窗口**不会**停止服务，API 和 Web UI 在各自独立的控制台窗口中运行。

### 停止

```bat
stop_platform.bat
```

通过 `netstat` 定位占用 8000 / 5000 端口的进程并终止，验证端口释放后打印确认。

### 安全参数（可选）

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `AUTOML_API_KEY` | REST API Key（空=不启用验证） | 不启用 |
| `AUTOML_ALLOWED_ORIGINS` | 允许的跨域来源，逗号分隔 | localhost 系列 |
| `AUTOML_MAX_CONCURRENT` | 最大并发训练任务数 | 2 |

预设环境变量后直接启动可跳过交互提示：

```bat
set AUTOML_API_KEY=my-secret-key
set AUTOML_MAX_CONCURRENT=3
start_platform.bat
```

---

## 使用方法

### 命令行训练

```bash
# 基础训练（全自动）
python scripts/run_automl.py --dataset datasets/coco128

# 指定模型和 GPU
python scripts/run_automl.py --dataset datasets/coco128 --model yolo26l --device 1

# 自定义训练参数
python scripts/run_automl.py --dataset datasets/coco128 --epochs 300 --batch 8 --imgsz 1280

# 跳过导出和 Benchmark（仅训练）
python scripts/run_automl.py --dataset datasets/coco128 --no-export --no-benchmark

# 包含 TensorRT INT8 导出
python scripts/run_automl.py --dataset datasets/coco128 --int8
```

### AutoML Loop（自动迭代优化）

```bat
run_automl_loop.bat datasets\coco128
run_automl_loop.bat datasets\coco128 --iterations 5 --convergence 0.005
```

```bash
python scripts/run_automl_loop.py --dataset datasets/coco128 --iterations 3
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--iterations` | 最大迭代次数 | 5 |
| `--convergence` | 收敛阈值（mAP 提升小于此值停止） | 0.01 |

### Python API

```python
from core import run_automl_task, run_automl_loop

# 基础训练
result = run_automl_task("datasets/coco128")
print(f"报告: {result.report_html}")

# 自定义配置
result = run_automl_task(
    dataset_path="datasets/my_dataset",
    model="yolo26m",
    device=0,
    custom_config={
        'epochs': 200,
        'imgsz': 1280,
        'lr0': 0.0003,
    },
    do_export_trt_int8=True,
)

# AutoML Loop 自动优化
loop_result = run_automl_loop(
    dataset_path="datasets/coco128",
    max_iterations=5,
    convergence_threshold=0.01,
)

# 手动分析已有训练结果
from core.analysis_automl import TrainingAnalyzer
analyzer = TrainingAnalyzer("runs/detect/coco128_20260322_153000")
analysis = analyzer.analyze()
print(f"状态: {analysis.status}")
print(f"建议: {analysis.suggestions}")
```

---

## AutoML 逻辑详解

### 模型选型（按空闲显存）

| 空闲显存 | 模型 | batch | workers | 适用 GPU |
|---------|------|-------|---------|---------|
| < 4 GB | yolo26n | 16 | 4 | 低端 GPU |
| 4–6 GB | yolo26s | 24 | 6 | GTX 1060 / RTX 3060 |
| 7–11 GB | yolo26m | 28 | 10 | GTX 1080 Ti / RTX 3080 10G |
| 12–17 GB | yolo26l | 48 | 8 | RTX 3090 |
| ≥ 18 GB | yolo26x | 64 | 8 | A100 / H100 |

### 超参计算公式

| 超参 | 计算逻辑 |
|------|----------|
| `batch_size` | `空闲显存(MB) × 0.75 / 模型系数 / (imgsz/640)²`，取2的倍数 |
| `lr0` | `0.0005 × (batch/16)`，范围 [0.0001, 0.002] |
| `imgsz` | avg_object_size < 5% → 1280，< 10% → 960，其余 → 640 |
| `epochs` | 按训练集图像数量分 6 档，最多 200，最少 50 |

### 增强策略分档（`configs/augment_profiles.yaml`）

| 档位 | 规模 | mosaic | mixup | erasing | 说明 |
|------|------|--------|-------|---------|------|
| small | < 500 张 | 0.5 | 0.0 | 0.0 | 防早期 mAP 崩盘 |
| medium | 500–2000 张 | 0.8 | 0.0 | 0.1 | 适度增强 |
| large | 2000–10000 张 | 1.0 | 0.1 | 0.2 | 标准增强 |
| xlarge | > 10000 张 | 1.0 | 0.1 | 0.2 | 标准 + copy-paste |

### 类别名称解析优先级

```
1. datasets/<n>/names.txt    （每行一个类别名，推荐）
2. datasets/<n>/classes.txt  （darknet 格式）
3. datasets/<n>/data.yaml    （现有 yaml 中的 names 字段）
4. 占位名 class_0, class_1...  （兜底，同时打印提示）
```

---

## 输出说明

每次训练在 `runs/detect/<dataset>_<timestamp>/` 下生成：

| 文件 | 来源 | 说明 |
|------|------|------|
| `weights/best.pt` | Ultralytics | 验证集 mAP 最高的权重 |
| `weights/best.onnx` | export_automl | opset=17，dynamic batch |
| `weights/best_fp16.engine` | export_automl | TensorRT FP16 |
| `weights/best_int8.engine` | export_automl | TensorRT INT8 |
| `results.csv` | Ultralytics | 每 epoch 训练指标 |
| `results.png` | Ultralytics | 训练曲线图 |
| `confusion_matrix.png` | Ultralytics | 混淆矩阵 |
| `report.html` | report_automl | Chart.js 交互报告 + 诊断区块 |
| `analysis.json` | analysis_automl | 训练曲线诊断结果 |
| `train.log` | log_analyzer | 完整训练日志 |
| `benchmark.json` | benchmark_automl | 多格式推理性能数据 |
| `automl_result.json` | automl_task | 任务完整结果（可序列化） |
| `deploy_package/` | package_automl | 部署包（模型 + 推理示例 + 元数据） |

---

## API 参考

### 创建训练任务

```http
POST /api/tasks
Content-Type: application/json
X-API-Key: your-key  （如已配置）

{
  "dataset_path": "datasets/your_dataset",
  "model": "yolo26n",
  "device": 0,
  "do_export_onnx": true,
  "do_export_trt_fp16": true,
  "do_export_trt_int8": false,
  "do_benchmark": true
}
```

### 查询任务

```http
GET /api/tasks/{task_id}
GET /api/tasks/{task_id}/report
GET /api/tasks/{task_id}/benchmarks
DELETE /api/tasks/{task_id}
```

### 任务状态流转

```
pending → queued → running → completed
                           ↘ failed
```

### 健康检查

```http
GET /health
→ {"status": "healthy", "running_tasks": 1, "queued_tasks": 0}
```

完整文档：`http://localhost:8000/docs`

---

## 高级配置

### 自定义增强策略（`configs/augment_profiles.yaml`）

```yaml
small:         # <500 张
  mosaic: 0.5
  mixup: 0.0
  erasing: 0.0

large:         # 2000-10000 张
  mosaic: 1.0
  mixup: 0.1
  erasing: 0.2
```

### 自定义训练默认值（`configs/yolo26_config.yaml`）

```yaml
optimizer:
  name: AdamW
  lr0: 0.0005
  warmup_epochs: 5.0
  warmup_momentum: 0.5
  patience: 30
  cos_lr: true
  close_mosaic: 10

export:
  onnx:
    opset: 17        # 统一 opset=17
    dynamic: true
    simplify: true
```

---

## 故障排查

**训练 loss 为 NaN**  
降低学习率：`custom_config={'lr0': 0.0001}`，关闭强增强：`{'mosaic': 0, 'mixup': 0}`，检查标签坐标是否在 0-1 范围内。

**CUDA out of memory**  
减小 batch：`--batch 8`，或降低分辨率：`--imgsz 640`。report.html 和 analysis.json 中会有具体提示。

**mAP 始终为 0**  
检查类别数是否正确，标签格式是否为 YOLO 格式（归一化坐标），训练集/验证集是否正确分离。

**TensorRT 导出失败**  
未安装 TensorRT 时自动跳过，不影响 `.pt` 和 `.onnx`。安装：`pip install tensorrt-cu12`。

**API 重启后任务消失**  
任务持久化在 `tasks_data/*.json`，重启后自动加载。重启期间 running/queued 任务标记为 failed，训练产物（权重、报告）不受影响。

**WebUI 报错 `No module named flask_socketio`**  
运行 `pip install flask flask-socketio eventlet`，或直接运行 `start_platform.bat` 会自动补装。

---

## 参考资料

- [Ultralytics YOLO 文档](https://docs.ultralytics.com/)
- [PyTorch 安装指南](https://pytorch.org/get-started/locally/)
- [TensorRT 安装指南](https://docs.nvidia.com/deeplearning/tensorrt/install-guide/)
- [FastAPI 文档](https://fastapi.tiangolo.com/)

---

**YOLO26 AutoML Platform** — 让目标检测训练可重复、可分析、可自动化 🚀