简介这份资源面向计算机、人工智能、自动化等专业的在校学生与教师提供一套基于YOLOv8的工地基坑变形预警完整项目可用于毕业设计、课程设计或大作业。压缩包共8个文件约15.91MB包含3个Python脚本、3个模型权重文件与2个说明文本分别承担可视化界面、模型训练、视频检测推理及部署指引等用途结构清晰简单部署即可运行。项目已通过测试可生成核心指标曲线图、混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果与标签分布图便于答辩展示与结果分析。目前已有28人学习下载。读者可直接获得源码、数据集、可视化页面与部署说明的一站式材料既能快速复现完整流程也能在此基础上修改扩展功能适合作为毕设保底方案或入门进阶的实践参考。1. 工地基坑变形预警为什么值得用 YOLOv8 重做一遍基坑监测这个场景传统做法是在支护结构、周边建筑和地表布设沉降观测点靠全站仪或水准仪定期人工测量。问题在于采样频率低、覆盖点位有限等数据出来往往已经错过了最佳处置窗口。而工地现场其实从来不缺摄像头——塔吊上的球机、围挡边的枪机、出入口的半球这些设备每天都在产生画面只是没人把它们和「变形预警」联系起来。基于 YOLOv8 的工地基坑变形预警核心思路就是把视觉检测能力接到这些已有画面上用目标检测模型识别基坑边缘的位移标志、支护结构的裂缝区域、周边地面的沉降特征再结合简单的时序比对逻辑触发预警。它解决的不是「替代精密测量」而是「在两次人工测量之间提供高频次的视觉巡检」。适合谁做毕设或课程设计的学生、想快速验证视觉方案可行性的现场工程师、以及需要一套能跑起来看到效果再决定要不要深入的人。源码、可视化界面、数据集和部署教程打包在一起意味着你不需要从零标注数据或搭前端部署完就能看到检测框和预警状态。2. 从标注到训练基坑变形数据集怎么处理才不翻车2.1 基坑场景的数据集长什么样、为什么不能直接用公开数据集公开的 COCO、VOC 里没有「基坑变形」这个类别。你能找到的最近似的是裂缝检测数据集或建筑工地安全帽数据集但类别定义和标注粒度都对不上。基坑变形预警需要检测的目标通常包括几类基坑边缘的位移监测标志点、支护墙面的裂缝、周边路面的沉降凹陷区域、以及可能出现的渗水痕迹。这些目标在画面里往往对比度低、边界模糊和 COCO 里那些轮廓清晰的日常物体完全不是一个分布。我一般会建议先用 labelme 做一轮小规模标注大概 200 到 300 张图就能看出类别定义是否合理。标注时有个血泪经验位移标志点如果只标一个点YOLOv8 的检测头处理起来效果很差因为 YOLO 系列本质是框回归。正确做法是给标志点画一个紧贴其外轮廓的小矩形框哪怕这个框只有十几个像素宽。裂缝标注同理不要用多边形描边直接用矩形框把裂缝段包住一段裂缝一个框不要试图用一个框覆盖整条不规则裂缝。# 将 labelme 标注的 json 批量转成 YOLOv8 需要的 txt 格式 import json import os from pathlib import Path def labelme_to_yolo(json_dir, output_dir, class_map): json_dir: labelme json 文件所在目录 output_dir: 输出 txt 标签目录 class_map: 类别名到索引的映射如 {crack: 0, settlement: 1, marker: 2} json_dir Path(json_dir) output_dir Path(output_dir) output_dir.mkdir(parentsTrue, exist_okTrue) for json_file in json_dir.glob(*.json): with open(json_file, r, encodingutf-8) as f: data json.load(f) img_w data[imageWidth] img_h data[imageHeight] lines [] for shape in data[shapes]: label shape[label] if label not in class_map: continue points shape[points] xs [p[0] for p in points] ys [p[1] for p in points] # 计算矩形框的归一化中心点和宽高 x_center (min(xs) max(xs)) / 2.0 / img_w y_center (min(ys) max(ys)) / 2.0 / img_h width (max(xs) - min(xs)) / img_w height (max(ys) - min(ys)) / img_h lines.append(f{class_map[label]} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}) txt_path output_dir / (json_file.stem .txt) with open(txt_path, w) as f: f.write(\n.join(lines)) # 调用示例 labelme_to_yolo( json_dir./raw_annotations, output_dir./labels/train, class_map{crack: 0, settlement: 1, marker: 2} )这段脚本的关键在于归一化计算。YOLOv8 要求标签是相对于图像宽高的归一化值中心点坐标和宽高都在 0 到 1 之间。class_map 的顺序必须和后续 data.yaml 里的 names 列表严格一致否则训练出来的模型会把裂缝识别成沉降。转换完成后建议随机抽 10 张图用可视化脚本把框画回原图上检查一遍这一步能拦住大部分标注错误。2.2 数据增强参数怎么设基坑场景的四个必调项YOLOv8 默认的数据增强对自然场景图像很友好但基坑监控画面有其特殊性。监控摄像头角度固定、光照条件随天气和时间剧烈变化、画面里大量重复的支护结构纹理。直接套默认参数模型很容易过拟合到某一种光照条件。我一般会重点调这四个参数。第一hsv_v 调到 0.5 以上因为工地从早到晚的光照变化极大阴影和逆光场景必须让模型见过。第二degrees 旋转角度不要开太大基坑监控画面基本是水平视角旋转超过 15 度反而引入不真实的样本设成 10 左右即可。第三mosaic 增强建议保持默认的 1.0但如果你发现模型对小目标检测效果差可以关掉 mosaic 最后 10 个 epoch让模型在真实分布上收尾。第四copy_paste 对裂缝这类细长目标有奇效但需要额外做实例分割标注如果只有检测框标注就保持 0。# data.yaml 配置文件放在数据集根目录 path: ./dataset train: images/train val: images/val names: 0: crack 1: settlement 2: marker这个 yaml 文件里 path 指向数据集根目录train 和 val 是相对于 path 的子路径。names 的索引必须和前面转换脚本里的 class_map 完全对应。有个容易忽略的点如果 val 集里某个类别一张图都没有训练时不会报错但验证指标里那个类别会显示为 0容易误判模型没学会。划分数据集时确保每个类别在训练集和验证集里都有足够样本。2.3 用 YOLOv8 命令行训练参数含义与显存不够时的降级方案YOLOv8 的训练入口很简洁但参数背后的取舍需要说清楚。假设你用的是 6GB 显存的卡比如 GTX1660Ti直接上 yolov8m 或 yolov8l 大概率会 OOM。我的建议是从 yolov8n 或 yolov8s 起步先把流程跑通再根据验证集指标决定要不要换大模型。# 从预训练权重开始训练batch 根据显存调整 yolo detect train \ data./dataset/data.yaml \ modelyolov8s.pt \ epochs150 \ imgsz640 \ batch8 \ lr00.01 \ patience30 \ device0 \ project./runs/detect \ namepit_experiment逐项说明imgsz640 是输入分辨率基坑画面里小目标多的话可以提到 1280但显存占用会翻倍不止。batch8 在 6GB 卡上跑 yolov8s 比较稳如果 OOM 就降到 4同时把 lr0 按比例降到 0.005 左右因为 batch 变小后梯度噪声增大。patience30 表示验证指标 30 个 epoch 不提升就早停基坑数据集通常不大这个值设 20 到 50 之间都合理。device0 指定第一块 GPUCPU 训练的话改成 devicecpu但速度会慢到让你怀疑人生。训练过程中重点看两个曲线train/box_loss 和 metrics/mAP50。如果 box_loss 震荡剧烈多半是学习率太大或 batch 太小。如果 mAP50 在某个值附近长期不动检查一下验证集里是不是有标注错误的样本——我遇到过一张图里裂缝框标到了阴影上模型怎么学都学不会最后是逐张检查验证集才发现的。3. 可视化界面怎么接从检测结果到预警状态的完整链路3.1 界面框架选型为什么用 Gradio 而不是 PyQt打包方案里带可视化界面常见做法有两种PyQt 桌面应用和 Gradio 网页应用。PyQt 的优势是本地运行不依赖浏览器但部署到服务器或让别人远程访问时很麻烦。Gradio 几行代码就能起一个网页界面支持图片上传、摄像头实时流、视频文件处理而且和 Python 生态无缝衔接。对于毕设或课程设计场景Gradio 的性价比明显更高。我一般会搭三个功能区单张图片检测、视频文件批量处理、实时摄像头预警。单张图片检测用来快速验证模型效果视频文件处理用来跑历史录像做复盘实时摄像头预警才是真正体现「预警」价值的部分。界面不需要花哨但检测结果上要叠加三样东西检测框和类别标签、置信度分数、以及一个根据连续帧检测结果计算出的预警状态。import gradio as gr import cv2 import numpy as np from ultralytics import YOLO model YOLO(./runs/detect/pit_experiment/weights/best.pt) # 预警状态缓存用于时序判断 alert_buffer [] def detect_image(image, conf_threshold): 单张图片检测返回标注后的图像和统计信息 results model.predict(image, confconf_threshold, imgsz640) annotated results[0].plot() boxes results[0].boxes info f检测到 {len(boxes)} 个目标 if len(boxes) 0: classes boxes.cls.cpu().numpy().astype(int) names [model.names[c] for c in classes] info f类别{, .join(set(names))} return annotated, info def detect_video(video_path, conf_threshold, alert_frames): 视频检测连续 alert_frames 帧检测到目标则触发预警 alert_frames: 触发预警所需的连续帧数 cap cv2.VideoCapture(video_path) fps cap.get(cv2.CAP_PROP_FPS) w int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) h int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) out_path ./output_alert.mp4 writer cv2.VideoWriter(out_path, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) consecutive 0 alert_triggered False while cap.isOpened(): ret, frame cap.read() if not ret: break results model.predict(frame, confconf_threshold, imgsz640, verboseFalse) annotated results[0].plot() num_boxes len(results[0].boxes) if num_boxes 0: consecutive 1 else: consecutive 0 alert_triggered False if consecutive alert_frames and not alert_triggered: alert_triggered True cv2.putText(annotated, ALERT: Deformation Detected, (30, 60), cv2.FONT_HERSHEY_SIMPLEX, 1.2, (0, 0, 255), 3) writer.write(annotated) cap.release() writer.release() return out_path # Gradio 界面搭建 with gr.Blocks(title基坑变形预警系统) as demo: gr.Markdown(## 工地基坑变形预警 - YOLOv8 检测) with gr.Tab(图片检测): img_input gr.Image(typenumpy, label上传图片) conf_slider gr.Slider(0.1, 0.9, value0.35, label置信度阈值) img_output gr.Image(label检测结果) info_output gr.Textbox(label检测信息) img_btn gr.Button(开始检测) img_btn.click(detect_image, [img_input, conf_slider], [img_output, info_output]) with gr.Tab(视频预警): vid_input gr.Video(label上传视频) vid_conf gr.Slider(0.1, 0.9, value0.35, label置信度阈值) alert_frames_slider gr.Slider(1, 30, value5, label连续帧阈值) vid_output gr.Video(label预警结果) vid_btn gr.Button(处理视频) vid_btn.click(detect_video, [vid_input, vid_conf, alert_frames_slider], vid_output) demo.launch(server_name0.0.0.0, server_port7860)这段代码的核心逻辑在 detect_video 函数里。alert_frames 参数控制预警灵敏度设成 5 意味着连续 5 帧检测到目标才触发预警能有效过滤掉单帧误检造成的假警报。实际部署时这个值要根据摄像头帧率和目标出现频率来调25fps 的摄像头设 5 到 10 比较合理。置信度阈值默认 0.35 是基坑场景的经验值因为裂缝和沉降区域的特征本身就不如日常物体那么鲜明阈值设太高会漏检设太低误报多。3.2 预警逻辑的时序判断单帧检测为什么不够单帧检测只能告诉你「这一帧里有裂缝」但基坑变形是一个渐进过程。真正有价值的预警信号是「同一位置的目标在连续多帧中持续出现」或者「目标框的面积在时间序列上呈扩大趋势」。前者用连续帧计数就能实现后者需要给每个检测框分配一个跟踪 ID记录其面积变化。我一般会在预警模块里加一个简单的面积趋势判断对每个跟踪到的目标保存最近 N 帧的框面积如果面积持续增大超过某个比例即使置信度没有明显变化也触发预警。这个逻辑不需要复杂的跟踪算法用 IoU 匹配前后帧的检测框就能做到。代价是代码复杂度上升但对于「变形预警」这个目标来说这个复杂度是值得的——毕竟没人希望系统只在裂缝已经很明显的时候才报警。4. 部署到实际环境CPU 版本、边缘设备和常见翻车点4.1 Ubuntu 20.04 上搭 CPU 版 YOLOv8 环境的最小步骤不是每个人都有 GPU 服务器。很多毕设场景就是一台普通笔记本或者实验室的 CPU 机器。YOLOv8 的 CPU 推理速度虽然比不上 GPU但在 640 分辨率下单帧推理大概 200 到 500 毫秒对于图片检测和低帧率视频处理完全够用。# Ubuntu 20.04 上从零搭建 YOLOv8 CPU 环境 # 第一步确认 Python 版本YOLOv8 要求 3.8 以上 python3 --version # 第二步创建虚拟环境避免污染系统 Python python3 -m venv yolov8_env source yolov8_env/bin/activate # 第三步安装 PyTorch CPU 版本注意不要装成 CUDA 版 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 第四步安装 ultralytics pip install ultralytics # 第五步验证安装 yolo detect predict modelyolov8n.pt sourcehttps://ultralytics.com/images/bus.jpg devicecpu第三步是最容易翻车的地方。如果不指定 index-urlpip 默认会装 CUDA 版本的 PyTorch在无 GPU 机器上虽然能装上但运行时会报各种动态库缺失的错误。指定 cpu 的 index-url 能确保装到纯 CPU 版本。第五步的验证命令会下载一个示例图片跑推理如果能看到检测结果输出说明环境没问题。4.2 边缘设备部署RK3588 和 Hi3516CV610 的模型转换思路如果要把模型推到边缘设备上跑比如 RK3588 或 Hi3516CV610就不能直接用 .pt 权重了。常见做法是先把 YOLOv8 导出成 ONNX再用厂商提供的工具链转成设备支持的格式。RK3588 用 RKNN 工具链Hi3516CV610 用海思的 NNIE 或 SVP 工具链。from ultralytics import YOLO # 导出 ONNX 格式opset 版本根据设备工具链要求调整 model YOLO(./runs/detect/pit_experiment/weights/best.pt) model.export(formatonnx, opset12, imgsz640, simplifyTrue)opset12 是兼容性比较好的选择RKNN 和大多数海思工具链都支持。simplifyTrue 会调用 onnx-simplifier 做图优化去掉冗余算子。导出后建议用 Netron 打开 ONNX 文件看一眼输入输出节点名后面写推理代码时要用到。边缘设备部署的坑主要集中在量化环节INT8 量化能大幅提升推理速度但基坑场景里裂缝这类细长目标对量化误差很敏感量化后 mAP 可能掉 5 到 10 个点。如果精度要求高建议用 FP16 而不是 INT8。5. 避坑与排查基坑变形预警落地时最容易踩的五个坑5.1 模型把阴影识别成裂缝现象验证集上 mAP 看着不错但实际跑视频时支护结构上的阴影区域被大量标成裂缝置信度还不低。原因训练集里阴影样本和裂缝样本在纹理特征上太接近模型没学到真正的裂缝特征而是学到了「暗色细长区域」这个浅层特征。基坑监控画面里阴影是常态模型走了捷径。解决在训练集里专门加入含阴影但不含裂缝的负样本数量至少占裂缝正样本的三分之一。同时把 hsv_v 增强调大让模型见过各种光照下的阴影形态。如果已经训练完了可以用验证集里误检的阴影图做一轮 hard negative mining重新微调。5.2 置信度阈值设太高导致漏检现象图片检测时明明肉眼能看到裂缝模型就是不框把阈值从 0.5 降到 0.25 才出来。原因基坑裂缝的视觉特征本身就不如日常物体那么鲜明模型输出的置信度普遍偏低。用 COCO 预训练模型的经验值 0.5 来卡会漏掉大量真实目标。解决基坑场景的置信度阈值建议从 0.25 到 0.35 起步根据误报率再往上调。同时检查训练时用的 conf 参数——训练阶段的 conf 和推理阶段的 conf 是两回事训练时设 0.001 是为了计算完整的 PR 曲线推理时要根据实际场景重新定。5.3 视频检测结果抖动严重现象同一段视频相邻帧的检测框位置跳来跳去预警状态也跟着闪烁。原因YOLOv8 是逐帧独立检测没有时序平滑。监控画面里的噪声、压缩伪影、光照突变都会导致单帧检测结果波动。解决在检测后加一个简单的跟踪器比如 ByteTrack 或 BoT-SORT用跟踪 ID 来稳定检测框。如果不想引入额外依赖至少做一个基于 IoU 的帧间匹配对匹配上的框做指数移动平均平滑。预警状态也要加滞后逻辑连续 N 帧满足条件才切换状态避免在阈值附近反复横跳。5.4 部署到服务器后 Gradio 界面打不开现象本地跑得好好的 Gradio 界面部署到云服务器后浏览器访问不了。原因Gradio 默认只监听 127.0.0.1云服务器的安全组也没放行对应端口。解决launch 时指定 server_name“0.0.0.0” 让 Gradio 监听所有网卡同时在云服务器安全组里放行 server_port 指定的端口。如果服务器有防火墙还要在系统层面放行。另外注意 Gradio 的 share 参数不要开那个会生成一个临时公网链接不适合正式部署。5.5 数据集划分不合理导致验证指标虚高现象训练完 mAP50 到了 0.9 以上但实际用新视频测试效果很差。原因划分数据集时用了随机划分同一段视频的相邻帧被分到了训练集和验证集。相邻帧画面几乎一样模型在验证集上看到的其实是训练时见过的内容指标虚高。解决按视频源划分同一段视频的所有帧要么全在训练集要么全在验证集。如果数据来自多个摄像头按摄像头划分更稳妥。划分完后检查一下训练集和验证集的类别分布是否一致某个类别在验证集里太少的话指标波动会很大。6. 把预警阈值调准一个可复现的验证方法与我的参数习惯模型训练完、界面搭好之后真正决定这套系统好不好用的是预警阈值。置信度阈值、连续帧阈值、面积增长比例这三个参数组合起来决定了系统是「太敏感天天误报」还是「太迟钝漏掉真变形」。我一般会用一段已知结果的视频来做阈值标定找一段包含真实变形过程的录像或者人工在正常画面上合成一些变形效果然后跑一遍检测统计不同阈值组合下的误报率和漏报率。具体做法是写一个简单的网格搜索脚本把置信度从 0.2 到 0.5 按 0.05 步进连续帧阈值从 3 到 15 按 2 步进对同一段测试视频跑检测记录每种组合下的预警触发次数和触发时间点。然后对照人工标注的「真实变形发生时间」算一个简单的 F1 分数。这个过程不需要 GPUCPU 跑一段几分钟的视频大概十几分钟能出结果。import itertools import pandas as pd # 假设已经有一个函数 run_detection(video_path, conf, alert_frames) # 返回 (是否触发预警, 触发时间点秒数) # ground_truth_time 是人工标注的真实变形发生时间 def grid_search_thresholds(video_path, ground_truth_time, tolerance5.0): 网格搜索最优阈值组合 tolerance: 触发时间与真实时间的允许误差秒 results [] conf_range [0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5] frames_range [3, 5, 7, 9, 11, 13, 15] for conf, frames in itertools.product(conf_range, frames_range): triggered, trigger_time run_detection(video_path, conf, frames) if triggered: time_error abs(trigger_time - ground_truth_time) is_correct time_error tolerance else: time_error float(inf) is_correct False results.append({ conf: conf, alert_frames: frames, triggered: triggered, trigger_time: trigger_time if triggered else None, time_error: time_error, correct: is_correct }) df pd.DataFrame(results) # 优先选正确触发且时间误差最小的组合 correct_df df[df[correct]].sort_values(time_error) if len(correct_df) 0: best correct_df.iloc[0] print(f最优组合conf{best[conf]}, alert_frames{best[alert_frames]}, f时间误差{best[time_error]:.1f}秒) else: print(没有组合能在容差范围内正确触发需要检查模型或调整容差) return df # 调用示例 # df grid_search_thresholds(./test_video.mp4, ground_truth_time45.0, tolerance5.0)这个脚本的输出是一张表格每一行是一种阈值组合的表现。实际用的时候不用追求「最优」而是找一个在你可接受的误报率下漏报最少的组合。我的习惯是置信度阈值定在 0.3 左右连续帧阈值定在 5 到 8 之间面积增长比例如果启用了就设 1.2 到 1.5 倍。这套参数在几个不同工地的测试视频上表现比较均衡误报主要出现在暴雨天气画面噪声大的时候漏报主要出现在裂缝极细且光照不足的场景。最后说一个我踩过的坑不要用训练集里的图片去调预警阈值。训练集上的检测结果天然偏好调出来的阈值放到实际视频上会过于乐观。一定要用完全没参与训练的、最好来自不同摄像头的视频来做阈值标定。这个习惯帮我省掉了至少两次「实验室里好好的、到现场就疯狂误报」的尴尬。希望帮到你。本文还有配套的精品资源点击获取