尧图网页设计 
简介这套资源面向计算机视觉方向的学生和开发者提供了基于YOLOv8的教室窗户破损识别完整方案可直接用于毕业设计或课程设计。项目涵盖源码、可视化界面、完整数据集与部署说明支持运行核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线及验证集预测结果等分析流程便于答辩时直观展示模型效果。资源包共8个文件以Python脚本、PyTorch模型权重文件和说明文档为主整体大小约15.91MB结构简洁、便于快速上手。目前已累计41人学习适合具备一定目标检测基础、希望快速完成项目演示或进一步修改扩展的在校学生和开发人员。全部代码经测试可正常运行下载后按README指引即可完成环境配置与使用。1. 教室窗户破损识别系统从毕设需求到YOLOv8落地的完整路径目标检测类毕业设计年年都有人做但九成开源项目堆在人、车、猫狗这些常规类目上。把检测对象换成教室窗户破损问题立刻变得具体且琐碎玻璃裂纹是稀疏的线性弱纹理特征常规通用训练集的经验并不能直接平移。这套基于YOLOv8的教室窗户破损识别系统把源码、可视化界面、完整数据集和部署教程打包在一起数据处理到界面推理的链路全部打通适合时间紧张需要快速交付毕设或课设、以及想在一个真实小数据集上完整跑一遍YOLOv8流程的开发者。它的价值在于让你把精力放在参数调整和排错上这部分恰恰是答辩时最经得起追问的地方。2. YOLOv8的检测原理与系统模块划分为什么v8适合裂纹检测2.1 C2f与Anchor-Freev8相对v5的结构进步与小目标优势YOLOv8是2023年初发布的检测框架相比上一代v5结构上有三处改动值得你先搞清楚因为这些改动直接决定后面调参的方向。第一处改动在检测头。v5用的是Anchor-Based方式训练前需要用聚类算法统计数据集里的锚框尺寸v8改成Anchor-Free让网络直接回归边界框到中心点的两对距离不再依赖锚框预设。窗户破损目标的长宽比波动非常大——有的裂纹是竖直长条有的是放射状圆形如果用聚类锚框很难照顾到所有形态。省掉锚框设计等于排掉一个调参变量。第二处改动在骨干网络。v8用C2f模块替换了v5的C3模块。C2f的底层思路是把输入按通道切分成两部分一部分直传另一部分连续通过多个Bottleneck后再与直传部分拼接。梯度回传路径变多浅层的细小微纹理特征更容易被保留这对玻璃裂纹这种低对比度目标是实打实的收益。代价是参数量和计算量略增换在CPU上推理会慢一些这个后面部署时会再碰上。第三处改动是跨尺度特征融合更密集。v8在Neck部分沿用PAN-FPN但在高层特征下采样到中层时做了额外拼接让深层语义和浅层几何信息结合得更早。实际测试中640x640输入下v8n对只有六七个像素宽的裂纹也能稳定检出同数据集下v5s的漏检明显更多。模型规模上这套项目默认给的是nanoyolov8n.yaml参数量约3M。窗户破损场景类别少、背景单一不需要上s或m。如果你想快速验证流程直接用n如果追求更好的检测效果且显卡显存大于8G可以换成s训练时间大约增加一倍。2.2 系统四模块拆解数据、训练、推理、可视化各管一段解压这套资源后目录职责大致分成四块dataset/原始图像 labelme标注JSON 转换后的YOLO格式TXTmodels/预训练权重和训练产物scripts/格式转换脚本、训练脚本、推理脚本ui/可视化界面代码从数据流的角度看四条链路之间靠一个约定衔接标注JSON转出的txt文件名必须和图片文件名完全一致这是最容易断掉的一环。我建议你不要上来就启动UI而是按下面六步把最小链路打通用labelme打开dataset下的任意JSON检查标注框是否贴合破损区域运行scripts/convert_json_to_txt.py确认生成的txt数量和图片数量一致改dataset/data.yaml确认train/val路径和names正确后台启动训练同时翻一遍ui/代码熟悉界面结构用训练出的best.pt跑推理脚本看效果把best.pt路径填进ui配置文件启动界面这样做的好处是每一步的产物都能在下游被验证出问题时定位范围很小。最常见的翻车点是第2步和第3步之间的格式不匹配后面第5章我会专门展开。2.3 环境准备与版本锁定先跑通推理再开始训练这类毕设资源最常见的问题是环境版本漂移。ultralytics这个包迭代极快8.1和8.2的API就存在差异项目作者写代码时锁定的版本和你本机最新版一旦不一致调用YOLO类的方式直接不兼容。不要自己直接pip install ultralytics最新版先看docs/下的requirements.txt。我一般会这样做conda create -n yolo8 python3.9 -y conda activate yolo8 cd window_detect_project pip install -r requirements.txt装完依赖后不要急着训练先跑一次推理脚本验证环境。如果你的机器没有NVIDIA显卡ultralytics也支持CPU训练和推理只是速度会慢几倍到十几倍。CPU环境下batch要调小、imgsz建议保持640后面第4章会给出具体参数建议。先确认推理脚本能输出检测结果再进入训练环节这个顺序能帮你省掉大量排错时间。3. 数据集准备与格式转换从labelme标注到YOLO txt的完整链路3.1 破损窗户标注规范一个类别还是两个类别数据集质量在这个项目里直接决定模型能不能用。教室窗户破损的视觉表现形式主要有两种一种是玻璃碎裂成放射状裂纹另一种是整块缺失。这两种在标注时应该统一成一个类别broken还是拆成两个类别crack和missing取决于你的毕设题目描述。如果题目是“破损识别”合并成一类就够了如果你想在论文里多做一层分析可以拆成两类但每类至少要有150个以上的标注框否则类别不平衡会让模型偏向样本多的一类。标注规范上我强调整三点。第一边界框要尽量贴合裂纹的外接矩形别把窗框和墙体包进来。第二同一个窗户上有碎片脱落时宁可框住整个破损区域而不是逐块标否则小目标太多会导致正负样本失衡。第三光照反射造成的假裂纹不要标这类样本混进训练集模型会把高光误检成破损答辩现场翻车概率极高。数据量上这套资源自带的数据集规模对毕设是够用的。如果后续你需要扩充可以用手机在不同时段、不同天气下补拍重点是覆盖逆光和侧光两种光照条件破损特征在这两种光照下的视觉差异非常大。3.2 JSON转TXT脚本外接矩形与坐标归一化的两个关键细节labelme标注生成的JSON里保存的是多边形points坐标而YOLO训练需要的是归一化后的中心点坐标和宽高并且类别id从0开始。下面是我在这个项目里实际使用的转换脚本import json from pathlib import Path def convert_json_to_yolo(json_dir: str, txt_dir: str, classes: list): labelme JSON - YOLO txt classes: 类别名列表顺序与data.yaml的names保持一致 json_dir, txt_dir Path(json_dir), Path(txt_dir) txt_dir.mkdir(parentsTrue, exist_okTrue) for json_path in json_dir.glob(*.json): with open(json_path, r, encodingutf-8) as f: data json.load(f) img_w data[imageWidth] img_h data[imageHeight] txt_path txt_dir / (json_path.stem .txt) lines [] for shape in data[shapes]: label shape[label] pts shape[points] # 手绘多边形 points 可能超过两个点必须取外接矩形 xs [p[0] for p in pts] ys [p[1] for p in pts] x_min, x_max min(xs), max(xs) y_min, y_max min(ys), max(ys) x_center (x_min x_max) / 2 / img_w y_center (y_min y_max) / 2 / img_h width (x_max - x_min) / img_w height (y_max - y_min) / img_h cls_id classes.index(label) lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) txt_path.write_text(\n.join(lines), encodingutf-8) print(fdone: {json_path.name} - {len(lines)} boxes)两个关键细节说明一下。第一classes列表的索引顺序要和data.yaml里names的顺序严格一致顺序一旦错位训练出的模型类别全乱。第二坐标系数值要归一化到0~1不需要乘回原图尺寸很多人踩的坑是在这一步多乘了宽高导致检测框全部偏到左上角。还有一个容易被忽略的问题labelme标注的多边形点可能是任意手绘形状脚本里必须用min和max求外接矩形不能直接取points[0]和points[1]否则框会严重偏移。3.3 数据划分按场景隔离别让验证集变成“背题”数据划分这块是毕设项目里最看良心的地方。常见做法是随机按70/20/10切分train/val/test但窗户破损数据集通常样本量不大随机划分很可能让同一个教室同一扇窗户的照片同时出现在训练集和验证集。模型学的其实是“记住这张图”而不是“学会检测破损”验证集的mAP虚高到现场演示时换一个角度立刻露馅。正确的做法是按场景划分同一个机位的照片只允许出现在一个集合里不同日期、不同楼层、不同光照条件的图像尽量打散到三个集合中。如果这套资源附带的划分脚本没做场景隔离你自己手动调整目录分配。划分完成后建议跑一遍下面这个检查脚本统计每张图的标准框数量排查空标注文件from pathlib import Path def check_labels(txt_dir: str): txt_dir Path(txt_dir) empty_files [] total_boxes 0 for txt in txt_dir.glob(*.txt): lines txt.read_text(encodingutf-8).strip().splitlines() if not lines or lines[0] : empty_files.append(txt.name) else: total_boxes len(lines) print(ftotal boxes: {total_boxes}) print(fempty label files: {len(empty_files)}) for name in empty_files[:20]: print( , name) check_labels(dataset/labels/train)如果空标注文件比例超过10%模型会学到大量背景信息影响收敛速度。处理方式是把空标注图片移到ignore目录或者单独归入背景类参与训练。数据划分这件事宁可多花一小时手动核对也不要赌随机分配这是血泪经验。4. 模型训练与参数调优从data.yaml到loss曲线的判读方法4.1 data.yaml配置相对路径、类别顺序与test字段开始训练前先把数据集定义文件搞对。YOLOv8的data.yaml通常长这样# dataset/data.yaml train: dataset/images/train val: dataset/images/val test: dataset/images/test nc: 1 names: [broken]这里最容易翻车的是path字段。如果资源里写的是绝对路径换一台机器后必须手动改。我一般会删掉path字段直接写相对路径前提是执行训练命令的工作目录正好是项目根目录。如果你把项目放在D盘训练命令却在C盘打开相对路径一样会挂。nc是类别数names列表的顺序和转换脚本里的classes顺序必须完全一致。test字段有没有都行训练阶段用不到但最后评估模型时如果要用测试集建议还是配好。如果你改了类别名称记得同步把转换脚本里的classes列表也改掉这一步漏了训练完的模型输出的类别名永远是旧的。4.2 训练命令逐参数拆解imgsz 640、batch 16背后的取舍环境装好、数据划分完毕后就可以开始训练了。下面是一条针对窗户破损场景的完整训练命令yolo detect train \ --model yolov8n.yaml \ --data dataset/data.yaml \ --epochs 120 \ --imgsz 640 \ --batch 16 \ --workers 4 \ --device 0 \ --optimizer AdamW \ --lr0 0.001 \ --patience 15参数逐个说清楚。yolov8n.yaml是模型结构定义从ultralytics官方下载的预训练权重yolov8n.pt会作为初始权重训练时会自动加载COCO预训练的参数做迁移学习这是小数据集能收敛的关键。imgsz用640是速度和精度的平衡点。如果你的破损目标在整张图里占比特别小可以试768但要同时把batch降下来。batch取决于显存大小8G显存建议8~1616G可以到32。workers是数据加载进程数Windows下建议不要超过4太多反而会卡IO。optimizer我选了AdamW。数据集只有几百张时AdamW收敛快不容易因为初始学习率没调好而崩掉如果你的数据集扩充到了几千张SGD的泛化会更好但学习率要相应调到0.01。patience是早停参数15个epoch内验证集指标不再提升就自动停止训练避免浪费时间。4.3 训练输出四张图怎么读从results.png判断过拟合与收敛训练开始后runs/detect/exp/目录下会实时生成results.png和weights/。results.png里包含三条loss曲线box_loss、cls_loss、dfl_loss和四条指标曲线precision、recall、mAP50、mAP50-95。我的判读底线是这样的训练集loss曲线可以下降到不再明显波动但验证集loss不能和训练集loss拉出越来越大的差距。一旦出现这种“剪刀差”说明过拟合了。此时优先做的是降低epochs到早停之前的位置或者减少数据增强强度。ultralytics默认开了Mosaic、HSV扰动等增强对小数据集来说有时增强过度反而难收敛。早停保存的best.pt是验证集mAP最高的权重不是最后一个epoch的权重。部署一律用best.pt不要用last.pt。如果你发现best.pt的验证mAP50不错但单张图推理效果很怪多半是数据划分时的场景泄露问题回到第3.3节检查一下。5. 避坑指南训练与部署中的五个高频故障5.1 CUDA与PyTorch版本不匹配现象训练时直接报RuntimeError: CUDA error: no kernel image is available for execution on the device或者torch.cuda.is_available()返回False。原因PyTorch的CUDA编译版本和显卡驱动支持的CUDA版本不匹配。这个报错在30系、40系显卡上尤其常见老版本torch对Ampere和Ada Lovelace架构支持不完整。解决先运行nvidia-smi看驱动支持的最高CUDA版本再安装对应的torch。40系显卡直接用pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121装CUDA 12.1版本。注意检查pip配置里有没有残留的清华镜像源有时候镜像源会导致下载到CPU版torch。5.2 显存不足OOM现象训练跑到某个epoch时直接CUDA out of memory进程退出前面的进度全部白费。原因batch和imgsz的乘积超过了显存容量。另一个隐蔽原因是ultralytics默认的cache参数可能会把处理后的数据集缓存进显存数据集越大占的显存越多。解决把batch减半这是最快的解法。或者把cache关掉改成cacheFalse。如果batch减到4还不够配合accumulate4效果等于batch16但显存占用只有四分之一。注意accumulate只影响梯度累积的步数不会改变BatchNorm统计使用的batch大小所以别把accumulate当batch用。5.3 labelme标注与训练格式混用现象训练时报warning说某张图片没有对应的txt文件或者检测出来的框全部偏到左上角。原因JSON没有转换或者转换脚本里坐标归一化时用了图像原始尺寸之外的数。还有个隐蔽的坑labelme保存的JSON里imagePath字段经常包含子目录层级如果图片和labels分开放置转换后文件名匹配不上。解决转换后逐对检查txt文件名和图片文件名是否一致不带后缀。统一用json_path.stem作为主键图片改名时同步改JSON里的imagePath或者干脆让训练时只认stem不依赖JSON里的路径字段。5.4 模型不收敛loss曲线水平震荡现象训练50个epoch后box_loss在2附近横盘震荡mAP50始终低于0.1。原因最常见的是学习率不适合当前数据集规模其次是正负样本极端不平衡——比如500张图里只有20个positive框正样本占比过低loss被大量背景框淹没。解决先统计数据跑一遍第3.3节的检查脚本看看每张图的标注框数量。如果大部分是空文件需要删掉空图或做欠采样。然后按4.2节的参数设置lr00.001配合AdamW如果还在横盘把warmup_epochs改大到5让网络先稳定学好分类头再接检测头。还有一个小技巧把close_mosaic从默认10调到0对小数据集能减少Mosaic增强造成的样本分布偏移。5.5 中文路径与文件夹空格现象Windows下训练报错FileNotFoundError但路径肉眼看着完全没问题。原因数据集路径带中文或空格ultralytics底层的cv2.imread对非ASCII路径解析经常失败。这个坑在毕设资源包里非常普遍因为很多同学把项目放在“毕业设计-最终版-v3”这种文件夹。解决把整个项目挪到全英文路径下比如D:/workspace/window_detect/。如果必须保留中文名文件夹在代码入口处加两行编码设置但说实话最省事的方法就是换目录别在这上面浪费时间。6. 可视化界面与推理验证让模型成为可演示的毕设作品6.1 UI核心逻辑与置信度阈值设定这套系统附带的可视化界面一般基于PyQt5实现核心逻辑可以概括为三个按钮、两个区域加载模型、选择图片、开始检测以及结果展示区。界面关键代码长这样from ultralytics import YOLO model YOLO(runs/detect/exp/weights/best.pt) def detect(image_path): results model.predict( sourceimage_path, conf0.35, iou0.45, imgsz640, saveFalse, verboseFalse ) boxes results[0].boxes.xyxy.cpu().numpy() confs results[0].boxes.conf.cpu().numpy() clss results[0].boxes.cls.cpu().numpy() return boxes, confs, clssconf阈值别设太高。窗户破损这类视觉上不明显的目标置信度通常在0.3到0.6之间设到0.5以上很容易把真阳性全滤掉。我一般会先在命令行用十张图横测一遍统计置信度分布再回头定UI里的默认值。iou用0.45是从COCO习惯带下来的不需要动。界面绘制推荐直接用ultralytics自带的plot方法但如果你想在界面里单独控制字体和图例用cv2.rectangle自己画也行唯一要注意的是坐标在推理结果是原图尺寸不要二次归一化。我在实际使用中习惯在界面上加一个“置信度滑条”答辩演示时可以现场调整给老师看效果比固定阈值好很多。6.2 跑一次干净的val验证并导出论文素材演示阶段你大概率被答辩老师问“模型精度多少”这时候不要张口说训练日志里的mAP应该单独把验证集指标完整跑一遍。这既是对项目的总验收也是论文素材的来源。yolo detect val \ --model runs/detect/exp/weights/best.pt \ --data dataset/data.yaml \ --split val \ --img 640 \ --conf 0.001conf设成0.001是为了让所有预测框都参与PR曲线计算不影响mAP结果。跑完后输出会包含precision、recall、mAP50和mAP50-95四项指标。如果mAP50在0.8以上这个项目作为毕设核心成果是能站住脚的。写论文时PR曲线图、混淆矩阵和几张典型检测结果图是必须的。从runs/detect/val目录下找到confusion_matrix.png和PR_curve.png直接作为图表素材。我自己的习惯是每次训练完都强制跑一遍这个val流程然后把results.png和val目录里的图按日期归档写论文时按时间线取图逻辑非常清晰。从那以后我每次换数据集、换机器都强制走一遍这个最小验证流程图片进、JSON出、界面显示确认数据没有泄露、模型确实在学特征、界面加载的是best.pt而不是last.pt。这个习惯帮我避掉了无数个“代码没问题但结果不对”的夜晚也希望帮到你。本文还有配套的精品资源点击获取 YOLOv8教室窗户破损识别系统：从标注到部署的完整实践
简介这套资源面向计算机视觉方向的学生和开发者提供了基于YOLOv8的教室窗户破损识别完整方案可直接用于毕业设计或课程设计。项目涵盖源码、可视化界面、完整数据集与部署说明支持运行核心指标曲线、混淆矩阵、F1分数曲线、精确率-召回率曲线及验证集预测结果等分析流程便于答辩时直观展示模型效果。资源包共8个文件以Python脚本、PyTorch模型权重文件和说明文档为主整体大小约15.91MB结构简洁、便于快速上手。目前已累计41人学习适合具备一定目标检测基础、希望快速完成项目演示或进一步修改扩展的在校学生和开发人员。全部代码经测试可正常运行下载后按README指引即可完成环境配置与使用。1. 教室窗户破损识别系统从毕设需求到YOLOv8落地的完整路径目标检测类毕业设计年年都有人做但九成开源项目堆在人、车、猫狗这些常规类目上。把检测对象换成教室窗户破损问题立刻变得具体且琐碎玻璃裂纹是稀疏的线性弱纹理特征常规通用训练集的经验并不能直接平移。这套基于YOLOv8的教室窗户破损识别系统把源码、可视化界面、完整数据集和部署教程打包在一起数据处理到界面推理的链路全部打通适合时间紧张需要快速交付毕设或课设、以及想在一个真实小数据集上完整跑一遍YOLOv8流程的开发者。它的价值在于让你把精力放在参数调整和排错上这部分恰恰是答辩时最经得起追问的地方。2. YOLOv8的检测原理与系统模块划分为什么v8适合裂纹检测2.1 C2f与Anchor-Freev8相对v5的结构进步与小目标优势YOLOv8是2023年初发布的检测框架相比上一代v5结构上有三处改动值得你先搞清楚因为这些改动直接决定后面调参的方向。第一处改动在检测头。v5用的是Anchor-Based方式训练前需要用聚类算法统计数据集里的锚框尺寸v8改成Anchor-Free让网络直接回归边界框到中心点的两对距离不再依赖锚框预设。窗户破损目标的长宽比波动非常大——有的裂纹是竖直长条有的是放射状圆形如果用聚类锚框很难照顾到所有形态。省掉锚框设计等于排掉一个调参变量。第二处改动在骨干网络。v8用C2f模块替换了v5的C3模块。C2f的底层思路是把输入按通道切分成两部分一部分直传另一部分连续通过多个Bottleneck后再与直传部分拼接。梯度回传路径变多浅层的细小微纹理特征更容易被保留这对玻璃裂纹这种低对比度目标是实打实的收益。代价是参数量和计算量略增换在CPU上推理会慢一些这个后面部署时会再碰上。第三处改动是跨尺度特征融合更密集。v8在Neck部分沿用PAN-FPN但在高层特征下采样到中层时做了额外拼接让深层语义和浅层几何信息结合得更早。实际测试中640x640输入下v8n对只有六七个像素宽的裂纹也能稳定检出同数据集下v5s的漏检明显更多。模型规模上这套项目默认给的是nanoyolov8n.yaml参数量约3M。窗户破损场景类别少、背景单一不需要上s或m。如果你想快速验证流程直接用n如果追求更好的检测效果且显卡显存大于8G可以换成s训练时间大约增加一倍。2.2 系统四模块拆解数据、训练、推理、可视化各管一段解压这套资源后目录职责大致分成四块dataset/原始图像 labelme标注JSON 转换后的YOLO格式TXTmodels/预训练权重和训练产物scripts/格式转换脚本、训练脚本、推理脚本ui/可视化界面代码从数据流的角度看四条链路之间靠一个约定衔接标注JSON转出的txt文件名必须和图片文件名完全一致这是最容易断掉的一环。我建议你不要上来就启动UI而是按下面六步把最小链路打通用labelme打开dataset下的任意JSON检查标注框是否贴合破损区域运行scripts/convert_json_to_txt.py确认生成的txt数量和图片数量一致改dataset/data.yaml确认train/val路径和names正确后台启动训练同时翻一遍ui/代码熟悉界面结构用训练出的best.pt跑推理脚本看效果把best.pt路径填进ui配置文件启动界面这样做的好处是每一步的产物都能在下游被验证出问题时定位范围很小。最常见的翻车点是第2步和第3步之间的格式不匹配后面第5章我会专门展开。2.3 环境准备与版本锁定先跑通推理再开始训练这类毕设资源最常见的问题是环境版本漂移。ultralytics这个包迭代极快8.1和8.2的API就存在差异项目作者写代码时锁定的版本和你本机最新版一旦不一致调用YOLO类的方式直接不兼容。不要自己直接pip install ultralytics最新版先看docs/下的requirements.txt。我一般会这样做conda create -n yolo8 python3.9 -y conda activate yolo8 cd window_detect_project pip install -r requirements.txt装完依赖后不要急着训练先跑一次推理脚本验证环境。如果你的机器没有NVIDIA显卡ultralytics也支持CPU训练和推理只是速度会慢几倍到十几倍。CPU环境下batch要调小、imgsz建议保持640后面第4章会给出具体参数建议。先确认推理脚本能输出检测结果再进入训练环节这个顺序能帮你省掉大量排错时间。3. 数据集准备与格式转换从labelme标注到YOLO txt的完整链路3.1 破损窗户标注规范一个类别还是两个类别数据集质量在这个项目里直接决定模型能不能用。教室窗户破损的视觉表现形式主要有两种一种是玻璃碎裂成放射状裂纹另一种是整块缺失。这两种在标注时应该统一成一个类别broken还是拆成两个类别crack和missing取决于你的毕设题目描述。如果题目是“破损识别”合并成一类就够了如果你想在论文里多做一层分析可以拆成两类但每类至少要有150个以上的标注框否则类别不平衡会让模型偏向样本多的一类。标注规范上我强调整三点。第一边界框要尽量贴合裂纹的外接矩形别把窗框和墙体包进来。第二同一个窗户上有碎片脱落时宁可框住整个破损区域而不是逐块标否则小目标太多会导致正负样本失衡。第三光照反射造成的假裂纹不要标这类样本混进训练集模型会把高光误检成破损答辩现场翻车概率极高。数据量上这套资源自带的数据集规模对毕设是够用的。如果后续你需要扩充可以用手机在不同时段、不同天气下补拍重点是覆盖逆光和侧光两种光照条件破损特征在这两种光照下的视觉差异非常大。3.2 JSON转TXT脚本外接矩形与坐标归一化的两个关键细节labelme标注生成的JSON里保存的是多边形points坐标而YOLO训练需要的是归一化后的中心点坐标和宽高并且类别id从0开始。下面是我在这个项目里实际使用的转换脚本import json from pathlib import Path def convert_json_to_yolo(json_dir: str, txt_dir: str, classes: list): labelme JSON - YOLO txt classes: 类别名列表顺序与data.yaml的names保持一致 json_dir, txt_dir Path(json_dir), Path(txt_dir) txt_dir.mkdir(parentsTrue, exist_okTrue) for json_path in json_dir.glob(*.json): with open(json_path, r, encodingutf-8) as f: data json.load(f) img_w data[imageWidth] img_h data[imageHeight] txt_path txt_dir / (json_path.stem .txt) lines [] for shape in data[shapes]: label shape[label] pts shape[points] # 手绘多边形 points 可能超过两个点必须取外接矩形 xs [p[0] for p in pts] ys [p[1] for p in pts] x_min, x_max min(xs), max(xs) y_min, y_max min(ys), max(ys) x_center (x_min x_max) / 2 / img_w y_center (y_min y_max) / 2 / img_h width (x_max - x_min) / img_w height (y_max - y_min) / img_h cls_id classes.index(label) lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) txt_path.write_text(\n.join(lines), encodingutf-8) print(fdone: {json_path.name} - {len(lines)} boxes)两个关键细节说明一下。第一classes列表的索引顺序要和data.yaml里names的顺序严格一致顺序一旦错位训练出的模型类别全乱。第二坐标系数值要归一化到0~1不需要乘回原图尺寸很多人踩的坑是在这一步多乘了宽高导致检测框全部偏到左上角。还有一个容易被忽略的问题labelme标注的多边形点可能是任意手绘形状脚本里必须用min和max求外接矩形不能直接取points[0]和points[1]否则框会严重偏移。3.3 数据划分按场景隔离别让验证集变成“背题”数据划分这块是毕设项目里最看良心的地方。常见做法是随机按70/20/10切分train/val/test但窗户破损数据集通常样本量不大随机划分很可能让同一个教室同一扇窗户的照片同时出现在训练集和验证集。模型学的其实是“记住这张图”而不是“学会检测破损”验证集的mAP虚高到现场演示时换一个角度立刻露馅。正确的做法是按场景划分同一个机位的照片只允许出现在一个集合里不同日期、不同楼层、不同光照条件的图像尽量打散到三个集合中。如果这套资源附带的划分脚本没做场景隔离你自己手动调整目录分配。划分完成后建议跑一遍下面这个检查脚本统计每张图的标准框数量排查空标注文件from pathlib import Path def check_labels(txt_dir: str): txt_dir Path(txt_dir) empty_files [] total_boxes 0 for txt in txt_dir.glob(*.txt): lines txt.read_text(encodingutf-8).strip().splitlines() if not lines or lines[0] : empty_files.append(txt.name) else: total_boxes len(lines) print(ftotal boxes: {total_boxes}) print(fempty label files: {len(empty_files)}) for name in empty_files[:20]: print( , name) check_labels(dataset/labels/train)如果空标注文件比例超过10%模型会学到大量背景信息影响收敛速度。处理方式是把空标注图片移到ignore目录或者单独归入背景类参与训练。数据划分这件事宁可多花一小时手动核对也不要赌随机分配这是血泪经验。4. 模型训练与参数调优从data.yaml到loss曲线的判读方法4.1 data.yaml配置相对路径、类别顺序与test字段开始训练前先把数据集定义文件搞对。YOLOv8的data.yaml通常长这样# dataset/data.yaml train: dataset/images/train val: dataset/images/val test: dataset/images/test nc: 1 names: [broken]这里最容易翻车的是path字段。如果资源里写的是绝对路径换一台机器后必须手动改。我一般会删掉path字段直接写相对路径前提是执行训练命令的工作目录正好是项目根目录。如果你把项目放在D盘训练命令却在C盘打开相对路径一样会挂。nc是类别数names列表的顺序和转换脚本里的classes顺序必须完全一致。test字段有没有都行训练阶段用不到但最后评估模型时如果要用测试集建议还是配好。如果你改了类别名称记得同步把转换脚本里的classes列表也改掉这一步漏了训练完的模型输出的类别名永远是旧的。4.2 训练命令逐参数拆解imgsz 640、batch 16背后的取舍环境装好、数据划分完毕后就可以开始训练了。下面是一条针对窗户破损场景的完整训练命令yolo detect train \ --model yolov8n.yaml \ --data dataset/data.yaml \ --epochs 120 \ --imgsz 640 \ --batch 16 \ --workers 4 \ --device 0 \ --optimizer AdamW \ --lr0 0.001 \ --patience 15参数逐个说清楚。yolov8n.yaml是模型结构定义从ultralytics官方下载的预训练权重yolov8n.pt会作为初始权重训练时会自动加载COCO预训练的参数做迁移学习这是小数据集能收敛的关键。imgsz用640是速度和精度的平衡点。如果你的破损目标在整张图里占比特别小可以试768但要同时把batch降下来。batch取决于显存大小8G显存建议8~1616G可以到32。workers是数据加载进程数Windows下建议不要超过4太多反而会卡IO。optimizer我选了AdamW。数据集只有几百张时AdamW收敛快不容易因为初始学习率没调好而崩掉如果你的数据集扩充到了几千张SGD的泛化会更好但学习率要相应调到0.01。patience是早停参数15个epoch内验证集指标不再提升就自动停止训练避免浪费时间。4.3 训练输出四张图怎么读从results.png判断过拟合与收敛训练开始后runs/detect/exp/目录下会实时生成results.png和weights/。results.png里包含三条loss曲线box_loss、cls_loss、dfl_loss和四条指标曲线precision、recall、mAP50、mAP50-95。我的判读底线是这样的训练集loss曲线可以下降到不再明显波动但验证集loss不能和训练集loss拉出越来越大的差距。一旦出现这种“剪刀差”说明过拟合了。此时优先做的是降低epochs到早停之前的位置或者减少数据增强强度。ultralytics默认开了Mosaic、HSV扰动等增强对小数据集来说有时增强过度反而难收敛。早停保存的best.pt是验证集mAP最高的权重不是最后一个epoch的权重。部署一律用best.pt不要用last.pt。如果你发现best.pt的验证mAP50不错但单张图推理效果很怪多半是数据划分时的场景泄露问题回到第3.3节检查一下。5. 避坑指南训练与部署中的五个高频故障5.1 CUDA与PyTorch版本不匹配现象训练时直接报RuntimeError: CUDA error: no kernel image is available for execution on the device或者torch.cuda.is_available()返回False。原因PyTorch的CUDA编译版本和显卡驱动支持的CUDA版本不匹配。这个报错在30系、40系显卡上尤其常见老版本torch对Ampere和Ada Lovelace架构支持不完整。解决先运行nvidia-smi看驱动支持的最高CUDA版本再安装对应的torch。40系显卡直接用pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121装CUDA 12.1版本。注意检查pip配置里有没有残留的清华镜像源有时候镜像源会导致下载到CPU版torch。5.2 显存不足OOM现象训练跑到某个epoch时直接CUDA out of memory进程退出前面的进度全部白费。原因batch和imgsz的乘积超过了显存容量。另一个隐蔽原因是ultralytics默认的cache参数可能会把处理后的数据集缓存进显存数据集越大占的显存越多。解决把batch减半这是最快的解法。或者把cache关掉改成cacheFalse。如果batch减到4还不够配合accumulate4效果等于batch16但显存占用只有四分之一。注意accumulate只影响梯度累积的步数不会改变BatchNorm统计使用的batch大小所以别把accumulate当batch用。5.3 labelme标注与训练格式混用现象训练时报warning说某张图片没有对应的txt文件或者检测出来的框全部偏到左上角。原因JSON没有转换或者转换脚本里坐标归一化时用了图像原始尺寸之外的数。还有个隐蔽的坑labelme保存的JSON里imagePath字段经常包含子目录层级如果图片和labels分开放置转换后文件名匹配不上。解决转换后逐对检查txt文件名和图片文件名是否一致不带后缀。统一用json_path.stem作为主键图片改名时同步改JSON里的imagePath或者干脆让训练时只认stem不依赖JSON里的路径字段。5.4 模型不收敛loss曲线水平震荡现象训练50个epoch后box_loss在2附近横盘震荡mAP50始终低于0.1。原因最常见的是学习率不适合当前数据集规模其次是正负样本极端不平衡——比如500张图里只有20个positive框正样本占比过低loss被大量背景框淹没。解决先统计数据跑一遍第3.3节的检查脚本看看每张图的标注框数量。如果大部分是空文件需要删掉空图或做欠采样。然后按4.2节的参数设置lr00.001配合AdamW如果还在横盘把warmup_epochs改大到5让网络先稳定学好分类头再接检测头。还有一个小技巧把close_mosaic从默认10调到0对小数据集能减少Mosaic增强造成的样本分布偏移。5.5 中文路径与文件夹空格现象Windows下训练报错FileNotFoundError但路径肉眼看着完全没问题。原因数据集路径带中文或空格ultralytics底层的cv2.imread对非ASCII路径解析经常失败。这个坑在毕设资源包里非常普遍因为很多同学把项目放在“毕业设计-最终版-v3”这种文件夹。解决把整个项目挪到全英文路径下比如D:/workspace/window_detect/。如果必须保留中文名文件夹在代码入口处加两行编码设置但说实话最省事的方法就是换目录别在这上面浪费时间。6. 可视化界面与推理验证让模型成为可演示的毕设作品6.1 UI核心逻辑与置信度阈值设定这套系统附带的可视化界面一般基于PyQt5实现核心逻辑可以概括为三个按钮、两个区域加载模型、选择图片、开始检测以及结果展示区。界面关键代码长这样from ultralytics import YOLO model YOLO(runs/detect/exp/weights/best.pt) def detect(image_path): results model.predict( sourceimage_path, conf0.35, iou0.45, imgsz640, saveFalse, verboseFalse ) boxes results[0].boxes.xyxy.cpu().numpy() confs results[0].boxes.conf.cpu().numpy() clss results[0].boxes.cls.cpu().numpy() return boxes, confs, clssconf阈值别设太高。窗户破损这类视觉上不明显的目标置信度通常在0.3到0.6之间设到0.5以上很容易把真阳性全滤掉。我一般会先在命令行用十张图横测一遍统计置信度分布再回头定UI里的默认值。iou用0.45是从COCO习惯带下来的不需要动。界面绘制推荐直接用ultralytics自带的plot方法但如果你想在界面里单独控制字体和图例用cv2.rectangle自己画也行唯一要注意的是坐标在推理结果是原图尺寸不要二次归一化。我在实际使用中习惯在界面上加一个“置信度滑条”答辩演示时可以现场调整给老师看效果比固定阈值好很多。6.2 跑一次干净的val验证并导出论文素材演示阶段你大概率被答辩老师问“模型精度多少”这时候不要张口说训练日志里的mAP应该单独把验证集指标完整跑一遍。这既是对项目的总验收也是论文素材的来源。yolo detect val \ --model runs/detect/exp/weights/best.pt \ --data dataset/data.yaml \ --split val \ --img 640 \ --conf 0.001conf设成0.001是为了让所有预测框都参与PR曲线计算不影响mAP结果。跑完后输出会包含precision、recall、mAP50和mAP50-95四项指标。如果mAP50在0.8以上这个项目作为毕设核心成果是能站住脚的。写论文时PR曲线图、混淆矩阵和几张典型检测结果图是必须的。从runs/detect/val目录下找到confusion_matrix.png和PR_curve.png直接作为图表素材。我自己的习惯是每次训练完都强制跑一遍这个val流程然后把results.png和val目录里的图按日期归档写论文时按时间线取图逻辑非常清晰。从那以后我每次换数据集、换机器都强制走一遍这个最小验证流程图片进、JSON出、界面显示确认数据没有泄露、模型确实在学特征、界面加载的是best.pt而不是last.pt。这个习惯帮我避掉了无数个“代码没问题但结果不对”的夜晚也希望帮到你。本文还有配套的精品资源点击获取