AI 视觉训练工具 - 使用手册

# AI 视觉训练工具 - 使用手册

本工具集数据标注、模型训练、模型推理导出于一体，支持目标检测（YOLOX）、旋转目标检测（YOLOv7-OBB）、图像分类（ResNet）三类视觉任务。

## 一、整体流程概览

1. **工程管理**：新建或打开一个工程，工程用于统一管理数据集、标注、模型和训练输出。
2. **数据准备**：在"数据"页面导入原始图片。
3. **数据标注**：在"标注"页面使用矩形框/旋转框/分类标签进行标注。
4. **模型添加**：在"训练"页面的训练列表中添加一个或多个训练模型。
5. **参数配置**：配置训练超参数、数据增强、预训练权重、是否增量训练等。
6. **开始训练**：点击"训练"按钮启动训练进程，实时观察 loss/mAP 曲线。
7. **模型导出**：训练完成后右键导出 ONNX 模型用于部署。

## 二、工程管理

| 功能 | 说明 |
| --- | --- |
| 新建工程 | 菜单 `工程(P) -> 新建工程`，选择一个空文件夹作为工程目录。工程目录结构： · `datasets/` 存放原始图片和标注 · `models/` 存放每个训练模型的workspace（yaml配置、权重、日志） |
| 打开工程 | 启动页自动列出最近工程列表，点击即可打开；也可通过菜单重新选择。 |
| 最近工程 | `工具(T) -> 设置` 可配置最近工程列表保存数量。 |

## 三、数据页面

数据页面用于批量导入训练图片，并划分训练集/验证集。

- **导入图片**：支持单张、多张、整文件夹导入。
- **数据集比例**：训练页面"数据划分比例"参数（默认 0.9，即 90% 训练、10% 验证）在导入时生效。

## 四、标注页面

标注页面提供可视化标注工具。详细操作请参考标注界面提示。

## 五、训练页面 - 参数详解（核心）

在训练页面左侧"训练列表"添加模型后，右侧面板会显示该模型的全部训练参数。

### 5.1 训练列表操作

| 操作 | 说明 |
| --- | --- |
| 添加模型 | 点击"添加模型"按钮，选择模型类型（**YOLOX**：水平框检测 / **YOLOv7-OBB**：旋转框检测 / **ResNet**：图像分类），输入模型名称。 |
| 删除模型 | 选中列表中一个模型后点击"删除模型"。**注意**：删除后该模型的workspace和训练权重会被一并删除，请谨慎操作。 |
| 重命名 | 在训练列表中右键模型 -> 重命名。 |
| 导出ONNX | 训练完成后右键 -> 导出模型，将权重转换为 ONNX 格式用于部署。 |
| 切换模型 | 点击列表中不同模型，右侧参数面板会自动加载该模型的 yaml 配置；切换时**会自动保存当前模型参数**，参数不会丢失。 |

### 5.2 基础参数

| 参数 | 默认值 | 说明与建议 |
| --- | --- | --- |
| 训练/推理设备 | GPU | 选择使用 GPU(CUDA) 还是 CPU 训练。**强烈建议使用 GPU**，CPU训练速度极慢。请确保已正确安装 CUDA 和对应显卡驱动。 |
| 预训练模型 | 关闭 | **开启**：使用对应规模的 ImageNet/COCO 预训练权重初始化 backbone，可大幅加速收敛、提升小数据集精度。 **关闭**：权重随机初始化，需要更多数据和更长训练时间。 **建议**：大多数场景下保持"开启"；只有当你有极强算力和海量数据时才考虑关闭。 |
| 冻结训练 | 关闭 | **开启**：训练前若干 epoch 冻结 backbone 权重，只训练检测头，可在训练初期防止预训练权重被破坏，适合小数据集微调。 冻结轮数 = `min(10, 总Epoch / 3)`，由程序自动计算。 |
| 混合精度(fp16) | 关闭 | 开启后使用半精度浮点训练，可**减少约 40% 显存占用**并提升训练速度，对精度影响极小（支持 Tensor Core 的显卡效果明显，如 RTX 20 系列以上）。 **注意**：若显卡不支持 fp16（如部分老款 GTX 10 系列），开启可能报错；出现 `NaN loss` 时请关闭此选项。 |

### 5.3 模型规模

| 规模 | YOLOX | YOLOv7-OBB | ResNet | 适用场景 |
| --- | --- | --- | --- | --- |
| 边缘 | yolox_nano | yolov8p-obb | mobilenet_v2 | 嵌入式/边缘端部署，速度极快 |
| 轻量型 | yolox_tiny | yolov8q-obb | mobilenetv3_small | 移动端/低算力设备 |
| 小型 | yolox_s | yolov8n-obb | mobilenetv3_large | **通用推荐起点**，速度与精度平衡 |
| 中等 | yolox_m | yolov8s-obb | resnet34 | 服务器部署，精度较好 |
| 大型 | yolox_l | yolov8m-obb | resnet50 | 高精度场景，需要较强GPU |
| 最大 | yolox_x | yolov8l-obb | resnet101 | 追求极致精度，显存需求高 |
| 超大 | yolox_x | yolov8x-obb | resnet101 | 竞赛/科研用途 |

> **规模选择原则**：先从小型(s)开始跑通流程验证数据质量，再根据部署硬件和精度需求调整规模。

### 5.4 训练超参数

| 参数 | 默认值 | 说明与调参建议 |
| --- | --- | --- |
| 随机种子(Seed) | 11 | 控制随机初始化、数据 shuffle 的种子。固定种子可让实验结果可复现；需要多次独立实验对比时可改变种子。 |
| 训练轮数(Epoch) | 100 | 完整遍历数据集的次数。 · 数据集小（&lt;1000张）：50~100 epoch 通常足够 · 数据集中等（1000~5000张）：100~200 epoch · 数据集大（&gt;5000张）：200~300 epoch **建议**：观察 loss 曲线，若后期验证 loss 不再下降甚至上升（过拟合），可提前停止。 |
| 批次大小(BatchSize) | 3 | 每次迭代送入网络的图片数。**显存占用与BatchSize线性相关**。 · 4GB 显存：batch=1~2 · 6~8GB 显存：batch=2~4 · 11~12GB 显存：batch=4~8 · 24GB 以上：batch=8~32 出现 `CUDA out of memory` 时调小此值。 |
| 线程数(Workers) | 0 | 数据加载的子线程数。`0` 表示在主线程加载（Windows下推荐0，避免多进程问题）。若CPU核心多且I/O快，可设为2~4加速数据读取。 |
| 输入尺寸 | 512 | 图片送入网络前被 resize 的边长（32 的倍数）。 · 小目标多：增大至 640 或 800（显存占用随尺寸²增长） · 大目标/简单场景：416 即可，速度更快 显示"Image Size:[N,N]"，N = `缩放系数 × 32`。 |
| 最大学习率(Init_lr) | 1e-2 | 训练初期的学习率上限。**学习率过大**会导致 loss 震荡甚至发散（出现 NaN），**过小**会收敛极慢。 · 带预训练权重微调：1e-3 ~ 1e-2 · 从头训练：1e-2 ~ 1e-1（需配合warmup） · BatchSize 增大时可适当增大学习率（线性缩放规则） |
| 最小学习率(Min_lr) | 1e-4 | 学习率衰减的下限，通常设为最大学习率的 1%~10%。训练后期用小学习率精细调整权重。 |
| 数据集划分比例 | 0.9 | 训练集占全部数据的比例，剩余部分作为验证集。推荐 0.8~0.9。验证集用于监控过拟合、计算 mAP。 |

### 5.5 增量训练

> **什么是增量训练？** 勾选"增量训练"后，训练将从该模型上次保存的 `last_epoch_weights.pth` 继续训练，而**不是从预训练权重重新开始**。适用于：
> - 上次训练被中断，需要继续训练
> - 已有训练好的模型，新增了数据继续微调

| 场景 | 行为 |
| --- | --- |
| 首次训练（无历史权重） | 若勾选增量训练但 weights 目录下无 `last_epoch_weights.pth` 和 `best_epoch_weights.pth`，程序会自动回退到预训练权重，并在日志中输出警告信息。 |
| 正常续训 | 优先加载 `last_epoch_weights.pth`；若不存在则尝试 `best_epoch_weights.pth`。 |
| 切换模型列表 | 切换时不会覆盖增量训练路径，参数保持不变。 |

> **注意**：增量训练时**不要更换模型规模**（如把小型改为大型），否则权重结构不匹配会加载失败。

### 5.6 数据增强（"数据增强"按钮）

点击"数据增强"按钮打开数据增强配置面板，合理的数据增强可以显著提升模型泛化能力，防止过拟合。

| 增强方式 | 说明 |
| --- | --- |
| Mosaic | 将4张图片随机拼接成一张，增加小目标、密集场景的鲁棒性。 |
| MixUp | 将两张图片按透明度混合，提升抗干扰能力。 |
| 旋转 | 随机旋转图片（仅 OBB 模型建议开启，水平框模型不建议大角度旋转）。 |
| 水平翻转 | 随机水平镜像，对大多数检测/分类任务都推荐开启。 |
| 垂直翻转 | 随机垂直镜像，适用于无方向性的场景（如工业缺陷检测），自然场景慎用。 |
| 亮度/色彩抖动 | 随机调整亮度、对比度、饱和度，应对不同光照环境。 |

> **建议**：新手可保持默认配置；小数据集可适当增大增强概率，大数据集/高精度场景下弱增强即可。

### 5.7 高级参数

点击"高级参数"展开更多配置项，包含优化器选择、权重衰减、学习率策略、mosaic关闭epoch、损失函数权重等，适合有调参经验的用户。

### 5.8 训练控制按钮

| 按钮 | 说明 |
| --- | --- |
| **训练** | 保存当前 yaml 配置并启动训练进程。启动时若检测到正在运行的训练进程会先终止旧进程。 |
| **结束** | 终止当前训练进程。**注意**：权重会保存到最后一个 epoch 完成的状态，直接终止可能丢失最后几个迭代。 |
| **推理** | 使用当前模型权重对图片/视频进行推理测试（需训练完成）。 |
| `<>` | 展开/收起高级参数面板。 |

## 六、训练监控

- **Loss 曲线**：实时显示训练 loss、验证 loss 变化趋势。train loss 应稳定下降，val loss 若持续上升说明过拟合。
- **mAP 曲线**：验证集平均精度（mean Average Precision），目标检测最核心的评价指标，越高越好。
- **进度条**：显示当前 epoch / 总 epoch。
- **日志区**：输出训练过程的详细信息，遇到错误请查看日志末尾的错误提示。

## 七、常见问题（FAQ）

### Q1: 启动训练报错 `CUDA out of memory` 怎么办？

- 减小 **BatchSize**（最有效）
- 减小 **输入尺寸**（如 640 -> 416）
- 关闭 **混合精度** 后如果仍不够，换更小的模型规模
- 关闭其他占用显存的程序

### Q2: 训练时 loss 变成 NaN 了？

- 学习率过大，调小 **最大学习率**（如 1e-2 -> 1e-3）
- 关闭**混合精度(fp16)**再试
- 检查标注数据中是否有错误的标注（如空框、坐标越界）

### Q3: 切换训练列表时参数会变化吗？

**不会。** 切换模型时会自动保存当前模型所有参数到 yaml，再加载目标模型的配置，参数不会丢失或被篡改。

### Q4: 增量训练从哪里加载权重？

优先加载 `workspace/weights/last_epoch_weights.pth`，若不存在则尝试 `best_epoch_weights.pth`，两者都不存在则回退到预训练权重并警告。

### Q5: 训练好的模型在哪里？

每个模型的权重保存在 `<工程目录>/models/<模型名>/workspace/weights/` 下：

- `last_epoch_weights.pth`：最后一个 epoch 的权重（用于续训）
- `best_epoch_weights.pth`：验证集 mAP 最高的权重（**推荐用于部署**）

### Q6: 如何多模型并行训练？

在训练列表中添加多个模型，分别配置参数后，当前版本同一时间只支持一个训练进程运行（点击训练会先终止旧进程）。如需并行训练请打开多个软件实例。

## 八、版本信息

版本：**v1.0.0**

支持模型：YOLOX（目标检测）、YOLOv7-OBB（旋转目标检测）、ResNet（图像分类）

> **提示**：本文档会随软件更新持续完善。如发现 bug 或有功能建议，请联系开发团队。