本篇文档记录了 HVAC工程图纸中关键设备检测器的完整训练流程与经验教训。怎么说呢，目标是让后续接手人员能快速复现、排查常见问题并在此基础上迭代。

痛点概览

• 数据量极少仅 30 张 PNG。单类样本不足 10 张，导致 mAP 低于可用门槛。
• GPU 不可用当前环境只能 CPU 训练，耗时大幅增加。
• Claude CLI 超时不稳定同一张图多次跑时耗时差异大，需要手动 retry 或剔除。
• Valve 类别缺失autolabel 默认跳过阀门，导致该类 mAP 为 0。
• 标签质量不一致自动标注框位置偏移、漏标，需要人工修订才能效果更好。
• 训练参数不当导致收敛慢或未收敛imgsz 缩小过度、epochs 太少、early‑stop 触发过快。
• 文件同步/方法错误易导致 “背景图” 或 “无 .txt” 的污染
• 代码与配置文件耦合度高**。更改单一参数需全程检查**

一、项目背景 & 数据集概况

1.1 项目目标

A. 在暖通空调工程图纸中识别水路程序关键设备，输出设备类型与边界框。B. 拓扑关系由 LLM在 prompt 阶段拼接。C. 检测器只负责设备类型 + 边界框,后端调用时再做 LLM 联合推理。

1.2 数据集结构 & 标签信息

# dataset/yolo.yaml
至于nc，6
从names来看。- chiller
- pump
- cooling_tower
- heat_exchanger
- valve
- terminal_load

*注意*：class_id 必须保持不变，否则历史标签失效。所有 .txt 文件必须位于 dataset/labels/ 并与 PNG 同名。

1.3 原始数据来源 & 标注流程概述

• - DWG 源文件已通过 DWG‑to‑PNG 转换放入 dataset/rendered/ .
• - 使用 Claude CLI + Label Studio 实现预标注 + 人工修订.
• - 自动标注脚本 scripts/autolabel_v2.py 将结果保存为 YOLO .txt 与原始 JSON.
• - 手动将 .txt 拷贝到 dataset/labels/ 并核对 splits.
`

二、通用训练流程

至于步骤1，环境准备

uv sync --extra training
uv run python -c "import torch,ultralytics;print)"

步骤2这方面。使用 Claude CLI 自动预标注 
bash
uv run python scripts/autolabel_v2.py B_10.png # smoke‑test 单张图片

： 


a) 在 config.toml 的 `` 部分将 `timeout` 延长，例如 `timeout = 600` 秒；

b) 调整脚本中的 `max_side`，降低缩放后宽高。例如 `scripts/autolabel_v2.py`: `max_side = 2048` → `1024`。

bash
uv run python scripts/autolabel_v2.py $

若仍有超时图，请 retry 或从 splits 剔除。

步骤3这方面。拷贝标签到正式位置并核对一致性 
bash
python - <'EOF'
from pathlib import Path
src = Path
dst = Path
dst.mkdir
for txt in src.glob:
    if not txt.stem.endswith:
        dst.joinpath.write_bytes)
print))} files to {dst}")
EOF

# 核对 splits 与 labels 是否匹配：
bash
python - <'EOF'
from pathlib import Path
splits = set
for n in :
    with open as f:
        splits.update).stem for line in f if line.strip])
labels = {Path.stem for p in Path.glob}
print} labels={len}")
print}")
print}")
EOF
*若有缺失或多余，请及时修正，以免训练过程中把背景图片当成有效样本*。

说到步骤4，配置训练超参 
toml
epochs = 30 # 或根据 GPU 性能自行增减
batch = 16 # CPU 上建议较小；GPU 可加大
imgsz = 640 # 分辨率越高，小目标越能识别；CPU 限制下建议>=512
device = "cpu" # GPU 时改为显卡 ID，如 `"0"` 或 `"cuda"`
patience = 30 # early‑stop 容忍度，可根据验证集波动调整


再看步骤5，启动训练并备份前一次结果 
bash
# 若已有 best.pt。请先备份防止覆盖
cp -r runs/detect/train runs/detect/train_$_backup
uv run python -m training.pipeline.train \
--epochs ${training.epochs} \
--batch ${training.batch} \
--imgsz ${training.imgsz} \
--device ${training.device}

# 检查启动日志是否正常：


`train这方面，` 行数应与 train.txt 匹配；backgrounds、corrupt 等均为 0；

`Overriding model.yaml nc=` 与实际类别数一致。

`box_loss`,`cls_loss`。`dfl_loss` 均应随 epoch 降至合理区间。




步骤6这方面，评估 & 查看结果图像 
bash
uv run python -m training.pipeline.evaluate # 默认使用 best.pt
# 如需指定权重：
uv run python -m training.pipeline.evaluate runs/detect/train/weights/best.pt

# 查看输出：


文件名
用途
说明列举



weights/best.pt
最佳权重，用于部署


results.png
损失曲线+ mAP 曲线，可判断收敛情况


val_batch0_pred.jpg
验证集预测，可直观看模型预测框是否合理


val_batch0_labels.jpg
验证集真值，对比预测框是否覆盖真实物体


confusion_matrix.png
混淆矩阵，查看类别混淆程度


results.csv
每个 epoch 指标汇总。可继续分析趋势














# 判断是否成功：


M50 范围
Status



✅ 基础可用但仍需调整*





   {}
*若 mAP50 < 0.70，则需要从数据或标签入手，而非单纯调参。  
常见陷阱



症状
排查方向
对策




train:N images ... backgrounds!
= 0
检查 splits 是否指向不存在的 PNG 或缺 .txt
修正 splits / 删除无效行


Corrupt...
查看对应 .txt 是否为空或坐标越界
手动修复或重新 autolabel


CUDA out of memory
减小 batch_size / imgsz
或切换至 CPU


loss 不下降且 mAP 长期低
调整 learning rate 、扩充样本数或修订标签位置
对小目标提高 imgsz





三、本项目特定踩坑 & 决策依据 

A．起点状况与预测差距分析

''
**主要结论**
* 数据量极少。单类样本不足 ~10 张，导致模型几乎无法学习任何类别；* CPU 环境下 imgsz 缩小到 ~512 导致细节丢失，小目标无法被检测；* early‑stop patience 设置太低，验证集波动大造成过早终止。

B．自动预标注阶段遇到的超时 & 挣扎过程 


Tried single image smoke‑test → ClaudeCLIError 超时。- 调整 config.toml `.timeout = 600`;- 缩减 max_side → 从2048降至1024。• 成功率提高至 90%。• 超大图 CH_20 无法 retry → 从 splits 剔除。**坑提示**
① **网络延迟极不稳定** – 同一张 B_10 在第一次跑秒级，在全量跑可能分钟级。② **超时时间需留出足够余量** – 不要设为「正常」值，而要考虑 worst-case 延迟。


C．标签质量与 Valve 类别缺失问题 


`autolabel_v2.py` 默认跳过 valve，因为阀门太小框不准。话说回来，→ 此类在 train&val 中完全缺失 ⇒ mAP 为 0。`
• 建议方案 A : **人工补充 Valve**。• 建议方案 B : **保留 autolabel 框作为参考进行微调**。


D．参数调优对性能的影响 


*v1 * ： epochs 100 ➜ early stop 未触发 ➜ mAP50 ≈ 0.


*v2 * ： epochs 30 ➜ early stop at epoch X ➜ mAP50 ≈ 0.仍低于可用门槛

成因拆解



因素
v1 问题
v2 改进




epochs
too many
合理设置但 still insufficient


imgsz
too low -> 小目标不可见
↑ 到640 提高检测精度


batch_size
CPU 上过大 -> OOM or slow 吞噬内存
↓ 至16 保持稳定


patience
too low -> premature early-stop
↑ 至30 保持更长收敛窗口





小结

即使参数已最优，但由于：


数据量不足；

标签偏移和漏标；

大部分类别严重失衡；


单纯调参难以突破可部署门槛。说到接下来主要是，

1️⃣ 人工修订 autolabel 框位置 + 补充 Valve 类别。其实，

✅ 按此方式可以在几小时内将整体 mAP 提高一个数量级。话说回来，


四、下一次接手建议



优先级
动作
收益








P1 • 检视 results.png 和 val_batch0_pred.jpg —— 快速定位模型学到了什么。P2 • 用 Label Studio 把 autolabel 框上传为 predictions，接下来人工补完 valve —— 能跃升一个数量级。P3 • 扩充 dataset 至至少200张，并保持每类≥10张 —— 稳定提高整体 AP。P4 • 等待 GPU 环境后重训，将 imgsz 设置为1280。batch 调至32 —— 推理速度提高数十倍。P5 • 针对 CH_20 等超大图做切片或压缩处理，再加入 splits —— 防止未来
报错。

P₂ 是性价比最高的一步，其成本仅数小时却能最大幅度提高 AP. 


五、故障排查 FAQ

Autolabel 阶段



ClaudeCLIError 超时: 请检查 config.toml .timeout;若仍然超时则执行 retry 或剔除对应图片。不过，
`


…

六、命令速查清单

# 安装依赖
uv sync --extra training


uv run python scripts/autolabel_v2.py $

python scripts/copylabelsto_dataset.py

uv run python scripts/preflight_train.py

uv run python -m training.pipeline.train \
--epochs $EPOCHS \
--batch $BATCH \
--imgsz $IMG_SZ \
--device cpu

uv run python -m training.pipeline.evaluate runs/detect/train/weights/best.pt

$env这方面，LABELSTUDIOLOCALFILESSERVINGENABLED=true;\
再看$env，LABELSTUDIOLOCALFILESDOCUMENTROOT=C:\your\path\to\dataset;\
uv run label-studio start

uv run python -m training.pipeline.labelstudio export


This document was auto-generated from original raw notes and structured to aid rapid onboarding and issue resolution.)