# 桥梁安全隐患检测 — YOLO 训练数据集指南

本文说明如何在 **检澜 → 模型训练** 中准备符合 [Ultralytics YOLOv8](https://docs.ultralytics.com/datasets/segment/) 规范的分割数据集。

## 一、目录结构

```text
bridge_hazard_demo/          ← ZIP 解压后的根目录（名称可自定）
├── data.yaml                ← 必须存在
├── train/
│   ├── images/              ← 训练图片
│   │   ├── img001.jpg
│   │   └── img002.jpg
│   └── labels/              ← 训练标注（与图片同名 .txt）
│       ├── img001.txt
│       └── img002.txt
└── val/
    ├── images/              ← 验证图片（至少 1 张）
    └── labels/
        └── img003.txt
```

> **注意**：`labels` 与 `images` 文件名一一对应（仅扩展名不同）。

## 二、`data.yaml` 模板

项目内提供可复制模板：

[`training_templates/data.yaml.example`](../training_templates/data.yaml.example)

最小可用示例：

```yaml
path: .
train: train/images
val: val/images

nc: 1
names:
  0: hazard
```

## 三、分割标注格式（`labels/*.txt`）

每一行表示一个隐患实例（多边形）：

```text
<class_id> <x1> <y1> <x2> <y2> ... <xn> <yn>
```

- `class_id`：整数，对应 `data.yaml` 的 `names` 索引（从 0 开始）
- `x1 y1 ...`：多边形顶点，**归一化**到 0~1（除以图像宽高）

示例 — 图像中心约 50% 区域的矩形（类别 0）：

```text
0 0.25 0.25 0.75 0.25 0.75 0.75 0.25 0.75
```

无隐患的图片：对应 **空的** `.txt` 文件或不存在 label 文件（建议空文件）。

## 四、打包 ZIP 上传

1. 在「模型训练」页点击 **选择 ZIP**，选中整个 `bridge_hazard_demo` 文件夹压缩为 `bridge_hazard_demo.zip`
2. 确保解压后 **第一层** 能看到 `data.yaml`（不要多套一层无意义的父目录）
3. 上传后平台会校验 `data.yaml` 并解压到 `data/datasets/<id>/`

## 五、一键生成演示数据集（试跑训练）

若尚无标注数据，可用脚本从项目内示例桥梁照片生成 **占位标注** 的迷你数据集（仅用于验证训练流程，**不能**代替真实标注）：

```powershell
cd BridgeDiseaseBackend-main
python scripts/create_demo_dataset.py
```

生成物：

- 目录：`training_templates/bridge_hazard_demo/`
- ZIP：`training_templates/bridge_hazard_demo.zip`（可直接在 Web 页上传）

## 六、训练参数建议

| 场景 | 基线模型 | epochs | imgsz | batch |
|------|----------|--------|-------|-------|
| 本机 CPU 试跑 | yolov8n-seg.pt | 5~10 | 640 | 2~4 |
| 有 GPU 正式训 | yolov8s-seg.pt | 50~100 | 640 | 8~16 |

## 七、标注工具推荐

- [Labelme](https://github.com/wkentaro/labelme) → 导出后需转换为 YOLO 格式  
- [CVAT](https://www.cvat.ai/)  
- [Roboflow](https://roboflow.com/)（可导出 YOLOv8 分割）

导出时请选择 **YOLOv8 Segmentation** 格式。

## 八、常见问题

| 问题 | 处理 |
|------|------|
| 上传后提示找不到 data.yaml | 检查 ZIP 根目录是否含 `data.yaml`，不要只压缩 `train` 子文件夹 |
| 训练立即失败 | 查看任务「日志」；常见为 labels 缺失、class_id 超出 names 范围 |
| 训练极慢 | CPU 正常；减小 `imgsz`、`batch` 或换 `yolov8n-seg` |
| 检测效果差 | 演示集为占位框，需换真实桥梁隐患标注重新训练 |