不用专门铺垫直接进入正题。这篇文章要聊的是一个非常典型的视觉项目基于深度学习YOLOv8的车辆行人检测系统。给那些正在入门目标检测、或者打算拿来做课程设计、毕业设计、甚至工作里快速搭一个检测Demo的朋友。这个项目最有价值的地方不在于“能检测车辆和行人”这个结果而在于它把“数据集准备 → 模型训练 → 推理优化 → 界面封装”这一整条链路跑通了。很多人卡在单点技术上比如会调模型但不会做界面或者会写界面但不知道怎么把模型接进去。这个项目就是把这些环节串起来打开代码你就能看到完整的工程结构而不是孤零零的几个py文件。我会结合自己实测踩坑的经验从数据集怎么整理、训练参数怎么调、界面怎么设计到最终打包部署把关键环节逐个拆开讲清楚。文章尽量写得直接、可操作你照着做基本能复现出一个能跑通的系统。1. 项目整体思路与方案选型1.1 为什么是YOLOv8而不是其它检测模型选型是这个项目第一步也是最容易纠结的一步。市面上目标检测方案不少从老牌的Faster R-CNN、SSD到YOLO系列的v5、v7、v8还有近两年热度很高的DETR系列各有各的适用场景。我在这个项目里坚持选择YOLOv8主要有几个很实际的原因。首先是速度和精度的平衡。车辆和行人检测往往是实时视频流处理比如道路监控、出入口统计、辅助驾驶预警这些场景对延迟非常敏感。Faster R-CNN精度确实不错但两阶段检测器在同等硬件条件下推理速度通常只有YOLOv8的三分之一甚至更低直接跑视频会很吃力。YOLOv8属于单阶段检测器一次前向推理同时输出类别和位置在GPU上处理1080P视频能做到肉眼无感知延迟。其次是部署友好程度。YOLOv8官方仓库提供了非常完整的生态链训练完模型可以直接导出为ONNX、OpenVINO、TensorRT格式还能直接转成TorchScript这对后面封装界面、做桌面应用甚至嵌入式部署都省了很多事。不用自己写一堆转换脚本也不用到处找第三方工具链。第三是代码结构清晰适合学习和二次开发。YOLOv8的检测头设计、损失函数计算、数据增强流程都写得比较规整源码阅读门槛比之前几个版本低很多。对于初学者来说打开源码能看懂每个模块在干什么这本身就是很重要的学习价值。如果是做商用项目团队成员接手也快。第四点也是很多人忽略的YOLOv8的默认超参设置很合理。我之前用YOLOv5的时候需要手动调整不少参数才能达到比较好的效果比如anchor的设置、mosaic增强的开关策略。YOLOv8把很多经验性的东西内置进去了对新手特别友好即使你不太懂调参默认配置跑出来的效果也不会太差。1.2 项目功能拆解与目录结构设计这个项目的完整名字已经透露了核心构成模型训练、检测推理、UI界面。我建议你拿到项目后不要急着运行先搞清楚目录结构理清楚各个模块之间的关系。合理设计的工程结构应该是下面这样的vehicle_pedestrian_detection/ ├── app.py # 主程序入口启动UI界面 ├── detect.py # 独立检测脚本可用于命令行测试 ├── train.py # 模型训练脚本 ├── ui/ │ ├── main_window.py # 主界面逻辑 │ ├── camera_thread.py # 视频流采集线程 │ └── style.qss # 界面样式表 ├── utils/ │ ├── detector.py # YOLOv8模型封装类 │ ├── draw.py # 结果可视化 │ └── config.py # 全局配置 ├── weights/ │ ├── best.pt # 训练好的模型权重 │ └── last.pt ├── datasets/ │ ├── images/ │ ├── labels/ │ ├── train.txt │ ├── val.txt │ └── data.yaml └── requirements.txt这个结构看起来简单但每个目录都有讲究。detector.py把模型推理逻辑单独封装目的是让UI层和算法层解耦。UI只负责展示画面和接收用户操作检测逻辑全部在detector里处理。这样后期如果要替换模型只需要改detector内部实现UI几乎不用动。camera_thread.py的存在也很关键。UI主线程绝对不能用来跑视频采集和模型推理否则界面一卡一卡的根本没法用。把视频流的读取和推理放到独立线程通过信号机制把检测结果回传到主线程刷新画面这是桌面端视觉应用的基本玩法。还有一点值得注意训练脚本和数据管理是分开的。数据集的标注文件、图片列表都是独立维护训练脚本通过data.yaml读取数据集配置。这样做的好处是换数据集的时候不用改代码只改配置文件即可后面如果想把系统扩展到检测其他目标比如检测摩托车、公交车只需要重新标注和修改yaml训练和推理代码基本不用动。1.3 技术栈选型的取舍选择技术栈的时候我在“Web方案”和“桌面方案”之间犹豫了一段时间。Web方案比如用Flask或FastAPI做后端前端用HTMLJavaScript显示视频流优点是部署方便浏览器打开就能用缺点是视频流传输延迟控制比较复杂而且处理实时摄像头数据时要考虑多路并发入门门槛反而更高。最终我选择了**Python PySide6Qt的Python绑定**做桌面应用。原因很简单PySide6的QPainter可以稳定地把检测框绘制到视频帧上延迟低且稳定QThread和信号槽机制天然适合处理视频线程与UI线程的通信打包成exe后可以离线运行不依赖服务端环境对用户来说双击运行一个桌面程序比配置浏览器环境更直观尤其是给非技术人员演示的时候。模型部分自然选择ultralytics YOLOv8这是目前用得最顺手的版本。这里说一句ultralytics包自带的数据加载、训练封装、导出工具实际上把很多底层细节处理好了但我在项目里仍然保留了自己训练脚本的写法方便修改loss权重和自定义数据增强策略这一点后面会细说。2. 数据集准备与标注细节2.1 数据从哪来公开数据集与自建数据的配合车辆和行人检测的数据集最常用的包括COCO、Pascal VOC还有一些专门的自动驾驶数据集。我在这个项目里采用的方式是以COCO数据集中vehicle和person类别的子集为基础补充一部分自采集数据。COCO数据集的person类标注质量很高而且覆盖各种姿态、遮挡情况、远近尺度用来做baseline是非常合适的。车辆类别需要稍微处理一下COCO里car、truck、bus是分开的类别如果业务需求只检测“车辆”可以在数据处理阶段把这三个类别合并。合并类别的操作在标注层面有讲究不能只是把标注文件里类别id改一下还要考虑边界框合并如果一个目标同时被标注成多个类别这种标注在COCO里比较少见但也存在需要去重处理。自采集数据这部分我建议不要偷懒。实际场景中你会发现公开数据集虽然质量高但跟你最终部署的环境往往有差异。比如监控摄像头是俯视角度的而COCO大部分图片是平视角度。我在项目里补充了大约500张不同光照条件下的道路图片用标注工具自己框选目标这500张数据对最终模型在特定场景下的表现提升非常明显。2.2 标注格式与label文件解析YOLO系列使用的标注格式是归一化的中心点坐标 宽高每行对应一个目标class_id x_center y_center width height注意这里的x_center、y_center是相对图片宽高的比例取值范围0到1width和height同理。例如一张1280x720的图片某个行人的边界框左上角坐标是(320, 180)右下角坐标是(640, 540)那么对应标注就是0 0.375 0.5 0.25 0.5因为宽高分别是320/12800.25和360/7200.5中心点x(320640)/2/12800.375y(180540)/2/7200.5。这个换算逻辑看起来简单但很多人写数据转换脚本的时候容易出错尤其是整数除法和浮点数精度的问题在Python里直接用/是浮点除法没问题但如果用//就会出大问题。标注文件的命名要和图片文件完全一致只是扩展名从.jpg/.png变为.txt。图片放在images目录下标注放在labels目录下在data.yaml里指定路径即可。目录结构千万不能乱因为ultralytics框架默认按这个约定寻找标注文件。我之前遇到过一个问题某几张图片的标注文件为空对应txt文件是0字节。训练时却报错“labels not found”或者训练loss出现异常。排查后发现是数据转换脚本在图片没有目标时没有生成空txt文件。YOLO系列的约定是如果图片没有目标也必须有一个空txt文件占位。这是一个很隐蔽的坑切记。2.3 数据增强策略与样本均衡数据增强直接影响模型的泛化能力。YOLOv8训练时默认会做一些增强比如随机翻转、缩放、色彩抖动、mosaic拼接这些都是内置的。但是内置策略不一定适合所有场景我建议针对车辆行人检测做两个调整。第一个是小目标增强。车辆和行人在监控画面里常常是小目标只有几十个像素甚至更小。Mosaic增强确实对小目标有帮助但也可以考虑把图片随机裁剪后resize放大再送入网络训练也就是“copy-paste”类的增强方法可以增强模型对小目标的敏感度。ultralytics里可以通过配置scale和fliplr等参数来实现部分效果。第二个是类别均衡。车辆和行人两个类别在自然图片中的分布很不均匀。我统计过训练数据里车辆目标数量大约是行人的3倍这会导致模型偏向车辆而漏检行人。处理方式是给loss加上类别权重或者在数据处理时对行人样本做过采样。在ultralytics的配置里可以设置loss_gs或者直接在数据层面控制。我在项目中选择了计算两个类别的目标数量占比动态调整样本权重的方法训练后的模型对行人的召回率明显提升。2.4 数据划分与验证集构建数据划分要特别注意不要随机划分。车辆和行人的图片很多是连续视频帧抽取的相邻帧之间场景非常相似如果随机划分训练集和验证集会导致验证集和训练集高度重叠验证结果虚高。正确的做法是按视频片段或场景目录划分确保同一个场景的图片不会同时出现在训练集和验证集里。我按8:1:1的比例划分为训练集、验证集和测试集。其中测试集严格保持隔离整个训练过程中不接触测试集只在最终评估时使用一次。这样得到的精度数据才可信。划分完成后还会检查一下每个集合中两个类别的数量比例避免出现验证集里行人很多、训练集里行人很少这种极端情况。如果分布差异过大需要重新调整划分策略或者补充数据。3. 模型训练与超参调优3.1 环境搭建与GPU配置训练环境方面我这边用的是CUDA 11.8 PyTorch 2.0 torchvision 0.15的组合显卡是单张8GB显存的消费级GPU。这个配置训练YOLOv8s以640x640输入分辨率大约需要4到6个小时完全在可接受范围内。安装依赖的最稳方式是用ultralytics官方文档推荐的pip命令pip install ultralytics但要注意ultralytics会自动安装匹配的PyTorch版本如果你的CUDA版本和它自动安装的版本不匹配训练时就会提示CUDA不可用。建议先手动安装好CUDA版本的PyTorch再安装ultralytics这样能避免版本冲突。还有一个容易踩的坑是NumPy版本冲突。ultralytics会对NumPy版本有要求有时候会和OpenCV依赖的NumPy版本冲突。建议在requirements.txt里固定版本号numpy1.24.3 opencv-python4.8.1 ultralytics8.0.221 PySide66.5.2我实测这个组合是很稳定的组合。3.2 训练参数解析与选择策略训练脚本的核心参数配置需要实际调试。放一份我项目里的关键参数作为参考from ultralytics import YOLO model YOLO(yolov8s.pt) model.train( datadatasets/data.yaml, epochs150, imgsz640, batch16, lr00.01, lrf0.01, optimizerSGD, momentum0.937, weight_decay0.0005, warmup_epochs3, warmup_momentum0.8, box7.5, cls0.5, dfl1.5, patience30, seed42, workers4, device0, )这里重点说几个参数的选择逻辑。lr0初始学习率设为0.01是SGD优化器的常用配置。batch size设为16是因为8GB显存限制下的上限如果batch太小而学习率太大训练会不稳定。batch size和learning rate之间存在对应关系如果你把batch size提升到32建议学习率也适当翻倍否则收敛速度会变慢。box、cls、dfl是三种loss的权重。box控制边界框回归的力度cls控制分类的力度dfl控制分布焦点损失。如果检测目标遮挡严重、边界模糊可以适当调高box权重。如果类别区分度不够可以调高cls。我在项目中采用默认值的基础上小幅调整因为车辆和行人的形态差异较大box权重适当高一点有助于框得更准。patience30是早停机制的等待轮数意思是如果30个epoch内验证集的mAP不再提升训练就会提前终止。这个参数能显著节省时间但不要设太小否则模型还在收敛过程中就被误停了。整个训练过程的监控非常重要。不要只盯着loss曲线看训练loss下降不代表效果就好。真正要关注的是验证集上的mAP曲线和PR曲线。如果训练loss下降而验证集mAP停滞说明发生了过拟合应该早停或者增加数据增强。3.3 预训练权重与模型规模选择YOLOv8有几种不同规模的版本n、s、m、l、x。它们的区别主要是网络宽度和深度。我在项目里用的是YOLOv8s全称是yolov8s.pt。为什么不用nn确实更快但对小目标的检测效果偏差尤其是画面里远处的行人容易漏检。为什么不用m或l因为显存不够而且推理速度会明显变慢。s是一个比较折中的选择在消费级GPU上能以超过100FPS的速度推理精度也比n高不少。这里要特别提醒一件事迁移学习很关键。如果用yolov8s.pt作为初始权重训练时加载的是COCO预训练模型的特征提取能力模型一开始就具备基础视觉特征收敛快而且精度高。我之前做过对比随机初始化权重训练同一个数据集150个epoch后mAP比使用预训练权重低了约15个百分点而且训练时间还更长。所以除非有特殊需求否则一定用预训练权重做fine-tune。3.4 训练过程监控与结果评估训练过程中ultralytics会输出每个epoch的loss、精度、召回率和mAP指标。我建议关注这几个指标的组合不要只盯单个指标。比如精度(precision)高不代表模型好如果召回率(recall)很低说明大量目标根本没检测出来。对于车辆行人检测这种安全相关的场景召回率比精度更重要漏检的代价远高于误检。我自己在项目中就是优先保证召回率再调整阈值来提升精度。训练完成后runs/detect/train目录下会生成很多文件包括权重文件、混淆矩阵、PR曲线、训练曲线等。混淆矩阵能直观看到哪些类别容易被误判比如行人被误判成车辆这个信息对后续优化非常有价值。best.pt和last.pt的区分很简单best是验证集表现最好的权重last是最后一个epoch的权重。正常情况下应该选择best.pt做推理部署。4. 检测推理与性能优化4.1 模型推理源码解析模型训练完接下来就是把它用起来。detect.py脚本里封装了YOLOv8的推理接口核心代码非常简洁from ultralytics import YOLO model YOLO(weights/best.pt) results model.predict(sourcetest.jpg, conf0.4, iou0.5, imgsz640, verboseFalse) boxes results[0].boxes for box in boxes: x1, y1, x2, y2 box.xyxy[0].tolist() conf float(box.conf[0]) cls int(box.cls[0])这段代码虽然简单但有几个参数需要根据实际场景调。conf是置信度阈值只有得分超过这个值的检测结果才会保留。阈值设低了误检多设高了漏检多。我实测下来车辆行人检测场景里0.35到0.45是比较合理的区间。如果是严苛的安全场景可以把阈值调低到0.25宁可多框几个错误的也不能漏掉真实目标后续再通过跟踪算法或逻辑判断来过滤误检。iou是NMS的非极大值抑制阈值用于去除重叠的检测框。默认0.5问题不大但如果目标遮挡严重可以适当提高到0.6让重叠的框更容易被合并。反过来如果场景中目标比较分散0.5就够了。还要注意imgsz输入尺寸对推理速度和精度的影响。640x640是默认值速度与精度的平衡点。如果希望提速可以降到480或320但小目标漏检会明显增加。如果希望提升小目标检测效果可以提升到768或960但推理时间会相应增加。这个参数没有最优值只能根据你的实际硬件和场景去测试。4.2 模型导出与推理加速部署阶段.pt权重文件直接用是可以的但如果要追求更快的推理速度建议转为ONNX格式再推理。转换操作在ultralytics里极其简单model.export(formatonnx, opset12, dynamicFalse, simplifyTrue)转成ONNX之后有几点好处ONNX Runtime的推理速度通常比PyTorch原生推理快10%到20%ONNX模型可以在没有PyTorch环境的情况下运行ONNX是跨平台的后续如果要移植到其他语言环境也能用。在GPU环境下还可以进一步导出为TensorRT格式速度能再上一个台阶。我之前测试过TensorRT FP16精度下推理速度比PyTorch原生快约3倍。不过TensorRT的缺点是构建环境复杂而且不同显卡型号需要重新构建engine文件部署灵活性不如ONNX。项目源码里我保留了两种推理模式默认使用PyTorch原生推理方便调试和理解如果设置了use_onnxTrue则切换为ONNX Runtime推理。实测在1080P视频流上ONNX模式能将单帧推理时间从约15毫秒降到约11毫秒。4.3 推理结果后处理技巧后处理是很多人忽略的环节。模型输出的是原始检测框、类别和置信度但直接画到画面上不经处理的话视觉效果很差。我总结几个比较实用的后处理操作。第一个是类别过滤。系统的需求可能只关心“车辆”和“行人”两个类别模型在COCO预训练时还能识别其他类别推理时需要根据类别ID进行过滤只保留目标类别。这个操作务必在画框之前做这样还可以减少绘制开销。第二个是检测框平滑。视频流中相邻帧的检测框容易出现轻微抖动因为模型对每一帧独立推理目标位置微小的变化都会被捕获。我写了一个简单的EMA平滑算法对连续帧中同一个目标的检测框做加权平均权重偏向最新帧。这能让检测框移动更自然观感好很多。实现时的关键是目标关联也就是判断哪一帧的框和上一帧的框属于同一个目标我用的是IoU匹配IoU大于0.5就认为是同一目标。第三个是置信度阈值动态调整。白天和晚上的检测效果差异明显如果固定使用同一个阈值夜晚场景会要么漏检很多要么误检很多。我实现了一个简单的自适应策略统计一段时间内的平均置信度如果整体置信度偏低就适当降低阈值如果整体置信度高就把阈值调高。这种做法不是最优解但实现简单效果却立竿见影。4.4 多线程推理与视频流处理视频流处理时必须使用多线程这一点在开头提过。实际项目里标准的做法是开两个线程采集线程负责读取视频帧并送入模型推理UI线程负责接收结果并绘制画面。采集线程的伪代码如下class CameraThread(QThread): frame_ready Signal(QImage, list) def run(self): cap cv2.VideoCapture(source) while self.running: ret, frame cap.read() if not ret: break boxes, classes, scores detector.infer(frame) annotated_frame detector.draw(frame, boxes, classes, scores) self.frame_ready.emit(annotated_frame, boxes)关键点是frame_ready信号传递的是绘制好的图片帧和检测结果列表。UI线程收到信号后直接刷新画面显示不要做额外处理。这里有一个容易踩的坑QImage要和QPixmap之间做转换转换操作如果放在UI线程做倒还好如果放在采集线程做注意QImage的生命周期避免出现图片数据被提前释放导致的画面撕裂问题。另一个坑是视频读取速度与模型推理速度不匹配。如果摄像头是30FPS而模型推理只有20FPS采集线程会不断堆积视频帧导致延迟越来越大。解决方式是在采集线程中做帧丢弃策略如果队列中有待处理帧直接丢弃新帧保证处理的是最新画面。对于实时监控来说处理最新帧比处理历史帧更重要。5. UI界面设计与系统集成5.1 界面功能设计与用户体验这个项目的UI设计核心需求在于直观和易用。我给系统设计了几个主要功能模块视频源选择支持本地图片、视频文件、摄像头实时画面三种输入方式检测参数调节置信度阈值滑动条、IOU阈值滑动条画面显示区实时显示检测结果检测框附带类别标签和置信度数字统计信息面板当前帧车辆数、行人数、总目标数、实时推理FPS操作按钮开始检测、暂停检测、截图保存、停止检测。界面布局用的是PySide6的布局管理器左侧是控制面板右侧是视频显示区域底部是统计信息栏。控制面板固定宽度300像素左右折叠起来也不难。整体颜色以深色调为主因为视频画面亮度较高深色界面有助于提升视觉聚焦。还有一点容易被忽视就是界面操作的即时反馈。比如点击“开始检测”按钮后按钮本身要变成“停止检测”同时视频画面开始流动点击“暂停检测”后画面定格在最后一帧且显示暂停标志。这些细节直接决定使用体验。我在UI线程中通过信号机制更新按钮文字和状态调用间隔控制在20毫秒以内不会有卡顿感。5.2 PySide6界面与模型集成的关键代码UI与模型的集成核心在于线程通信。我把模型封装在Detector类里面UI层完全不直接调用模型方法代之以线程信号。这样做的好处是后续如果要替换模型后端UI层代码一行也不用改。主窗口的部分核心代码如下class MainWindow(QMainWindow): def __init__(self): super().__init__() self.detector Detector(model_pathweights/best.pt, conf_thres0.4, iou_thres0.5) self.camera_thread CameraThread(source0, detectorself.detector) self.camera_thread.frame_ready.connect(self.update_frame) self.camera_thread.fps_updated.connect(self.update_fps) def start_detection(self): self.camera_thread.start() self.btn_start.setEnabled(False) self.btn_stop.setEnabled(True) def update_frame(self, image: QImage, results: list): self.video_label.setPixmap(QPixmap.fromImage(image)) self.video_label.setScaledContents(True) self.update_statistics(results)整体的信号槽机制运行得很稳定但UI线程和推理线程之间的数据传递需要小心。QImage是值类型传递副本没问题但检测结果列表如果包含numpy数组最好拷贝一份再传递否则可能出现一帧结果被下一帧覆盖的问题。截图保存功能我直接把当前显示的画面保存为JPEG文件并且把检测结果同步保存到一个CSV文件里每行包含时间戳、目标类别、置信度、坐标信息。这个功能对后续做数据分析和算法评估非常有用。5.3 UI界面的常见性能瓶颈与优化桌面应用最容易出现的问题是“界面卡顿”和“内存泄漏”。我在开发过程中遇到并且解决的几个问题值得拿出来说一下。问题一视频标签控件高分辨率显示卡顿。视频帧分辨率可能达到1920x1080QImage转QPixmap再显示到QLabel上每帧都需要一次缩放操作。如果QLabel大小只有800x600那么一帧就要做一次大比例缩放这个缩放操作很耗时。优化方式是先在数据层把帧缩放为QLabel的实际尺寸再转为QImage。缩放到显示尺寸的图片可以大幅减少draw开销视觉上几乎没有损失因为显示分辨率就这么大。问题二内存持续增长。视频流处理时如果不断创建新的QImage和QPixmapPython的垃圾回收机制可能来不及释放导致内存慢慢上涨。解决方式是复用QImage对象每次用fill方法清空后再绘制。实测优化后内存占用稳定在200MB以内长时间运行没有问题。问题三FPS统计不准确。我最初在UI线程中统计FPS用刷新帧数除以时间结果发现数值波动非常大因为UI刷新和推理是异步的。后来改为在推理线程中统计计算两次推理完成之间的时间差再取倒数这样统计到的才是真实的“处理FPS”而不是“显示FPS”。这个指标对性能评估更有意义。5.4 不同输入源的处理逻辑系统需要同时支持图片、视频文件和摄像头输入三种输入的处理逻辑有细微差别。图片输入最简单读取单帧推理显示结束。不需要线程直接在UI里同步处理即可。视频文件处理需要注意边界情况比如视频播放完了要自动停止并复位按钮状态拖拽进度条时如何同步刷新。我实现的方式是拖拽进度条时暂停推理解析释放资源等松手后再从新位置开始继续。摄像头输入是最复杂的因为摄像头设备有可能被占用、突然断开、驱动异常。代码里需要处理摄像头打开失败的异常情况我在界面里弹出错误提示并自动重置所有控件状态。还有一个很实用的细节摄像头预览分辨率可以设置比如640x480、1280x720、1920x1080。分辨率太高模型推理时间变长分辨率太低画面不清楚。我默认用1280x720平衡清晰度和性能。6. 常见问题与排查技巧实录6.1 训练过程常见问题速查表我在复现和调优这个项目的过程中最常遇到的问题集中在训练环节直接影响能否正常出模型。整理成一张速查表方便对照排查。问题现象原因分析排查思路与解决方案训练时提示CUDA out of memorybatch_size过大或输入分辨率太高调小batch_size或imgsz开启梯度累积选用更小的模型版本训练速度极慢GPU利用率低CPU成为瓶颈数据加载太慢调大workers数量确认数据存在SSD上检查NumPy/OpenCV是否使用了正确版本loss下降但mAP不涨过拟合或数据分布有问题增加数据增强检查训练集验证集是否重叠降低训练轮数验证集mAP正常但实测效果差测试场景与训练场景分布不一致补充目标场景数据做微调尝试提高输入分辨率使用更鲁棒的数据增强显存充足但训练OOM训练时开了混合精度但显存碎片化关闭amp减小batch_size清掉后台占显存的进程labels not found错误标注文件缺失或目录结构错误检查图片和标注文件名是否一一对应检查data.yaml路径是否正确训练正常但导出ONNX失败模型版本与onnx版本不兼容升级ultralytics和onnx指定opset版本使用simplify参数简化模型其中想展开说第一条。OOM问题最简单粗暴的做法是降低batch size但还有一个角度检查输入分辨率。如果imgsz从640提升到960显存占用大约会翻倍很多OOM是输入分辨率设太高导致的。我的建议是显存只有8GB的情况下imgsz尽量不超过640。如果想提升小目标检测效果优先考虑优化数据增强和anchor配置而不是盲目加大输入图尺寸。6.2 推理性能异常与排查实录推理环节我遇到过几个比较有意思的问题分享出来供参考。第一个是GPU推理反而比CPU慢的问题。排查后发现原因是使用ONNX Runtime时没有安装GPU版本默认调用了CPU执行。那时候GPU利用率一直是0%但CPU却接近100%。解决方法是安装onnxruntime-gpu并且在初始化时显式指定使用GPUimport onnxruntime as ort providers [CUDAExecutionProvider, CPUExecutionProvider] session ort.InferenceSession(model.onnx, providersproviders)另一个问题是图像颜色异常。摄像头读取的画面是BGR格式而模型训练时使用RGB格式。YOLOv8内部会自动做格式转换但我在UI中绘制检测结果时如果直接用OpenCV的imshow或者QImage的Format_RGB888颜色会偏蓝偏红。解决方式是明确转换OpenCV读入BGR后先转为RGB再送入模型绘制时如果直接用OpenCV画框就画在BGR图上最后转QImage时用Format_BGR888。这个颜色问题的坑非常隐蔽很多人调试半天发现模型精度没问题其实是显示环节的颜色通道搞错了。第三个是多路视频输入时的资源竞争。如果系统扩展为同时处理多路摄像头每个线程都加载一个模型实例会显存溢出。正确方案是多个线程共享同一个Detector实例通过加锁机制控制推理过程串行执行。实测下来共享实例配合排队推理是资源占用和维护复杂度之间的最佳平衡。如果确实需要并行推理那么要按比例计算显存占用比如1个模型实例占用2GB显存8GB显卡最多同时跑3路。6.3 模型精度优化的实际调试经验模型训练到一定阶段后mAP可能停留在某个水平不再提升这是非常常见的瓶颈期。我在这个项目中调优精度时遵循了一个有效路径按优先级排序如下。检查数据质量问题。标签错标、漏标、边界框画得不准这些是影响精度的最大因素而且模型训练阶段无法自动修正。我抽查了训练数据中10%的标注发现大约3%的边框有明显偏差修正这些标注后mAP提升了约2个百分点。数据质量对模型上限的决定作用怎么强调都不为过。调整输入分辨率。imgsz从640提升到768时小目标的召回率有明显改善但推理速度下降约30%。实际操作中要综合判断如果场景中行人较小优先保证分辨率。针对难样本做特殊处理。车辆行人检测中夜间低光照图片、部分遮挡场景、小尺度目标是最主要的漏检来源。我额外从数据集中提取出这些难样本单独训练了一个微调模型。测试发现对难样本的检测率提升了接近15%而正常场景几乎不受影响。调整置信度阈值。这是成本最低的调优手段。对于严格禁止漏检的场景把阈值从0.45降到0.3召回率能提升约8个百分点代价是误检增加。这种牺牲精度换召回的做法在安防场景中往往是正确的选择。6.4 部署阶段的跨平台打包经验项目最终要交给用户使用时需要打包成独立可执行的程序。我在打包过程中积累了一些经验。PySide6程序打包推荐使用PyInstaller。关键坑是模型文件和UI资源文件要一起打包进去但路径处理非常容易出错。如果用相对路径读取模型打包后程序的当前工作目录可能和源码目录完全不同导致找不到模型文件。我用的是sys._MEIPASS机制来处理import sys import os def resource_path(relative_path): if hasattr(sys, _MEIPASS): return os.path.join(sys._MEIPASS, relative_path) return os.path.join(os.path.abspath(.), relative_path)打包时把模型文件和UI资源文件添加到datas中pyinstaller --onefile --windowed --add-data weights/best.pt;weights --add-data ui/style.qss;ui app.py打包出来的exe体积比较大因为PySide6的依赖库体积就不小加模型文件后通常会有200MB以上。这个体积在桌面应用里可以接受但如果你很在意体积可以先转为ONNX模型用onnxruntime推理能省掉相当一部分PyTorch的动态库体积。还有一个问题是杀毒软件误报。PyInstaller打包的程序经常被Windows Defender或其他杀毒软件误判为病毒这个没有完美的解决办法只能尝试加白名单或者对exe做数字签名。好在个人项目或小型团队内部使用没有太大影响商用分发时需要注意。7. 项目扩展与后续优化方向7.1 从检测到跟踪引入目标追踪算法当前的系统只做单帧检测帧与帧之间没有关联信息。如果要做车辆计数的业务需求比如统计某个路口五分钟内经过的车辆数单靠检测是不行的因为同一辆车在连续帧中会被重复计数。解决方案是加入目标跟踪算法。常用方案是ByteTrack或DeepSORT前者基于运动关联效果好且速度快在YOLOv8的检测结果上直接接入即可。跟踪模块的核心输出是每个目标的track_id有了ID就能做去重计数、轨迹绘制、区域闯入判断等功能。我在扩展版本中加入了ByteTrack车辆计数功能在测试场景下准确率接近95%。引入跟踪之后还有一个附带的好处可以用跟踪结果反过来修正检测结果。比如某帧检测器漏检了一个目标但跟踪器预测了它的位置可以用预测框补充显示。这种检测加跟踪的相互补充极大提升了视频流的使用体验。7.2 夜间与恶劣天气场景增强车辆行人检测部署中最常遇到的实际挑战是夜间和雨天场景。模型在正常光照下表现很好但在暗光环境下精度曲线断崖式下跌。有几种处理思路。一是在数据层面补充夜间数据集这是最直接有效的方法。二是做图像增强预处理比如自动白平衡、直方图均衡化、暗光增强算法。我在项目中集成了简单的直方图均衡化作为预处理选项实测夜间检测的召回率提升约5个百分点。另一种思路是使用红外或热成像摄像头。热成像在夜间对行人检测有天然优势因为行人身体温度与周围环境差异明显但这类摄像头成本较高而且需要重新训练模型适配图像特征。这个方向更适合有预算的商用场景。7.3 边缘设备部署的轻量化尝试如果想把系统部署到嵌入式设备比如Jetson Nano或树莓派模型需要极度轻量化。YOLOv8n配合TensorRT优化在Jetson Nano上可以达到实时推理代价是精度下降明显。轻量化部署还有一个思路是蒸馏用大模型YOLOv8l在目标数据集上生成软标签然后用这些软标签训练小模型YOLOv8n。这样小模型能学到比单独训练更高的精度水平。我尝试过一个简化版本的蒸馏在夜间场景下小模型mAP提升约3个百分点比直接训练小模型效果好。如果你做的是快速原型验证不必一步到位上边缘设备先在本机上用YOLOv8s跑通全流程确认算法效果之后再做轻量化这是更稳妥的技术路线。项目做到这个程度核心链路已经完整从数据准备、模型训练、精度调优、推理优化到界面封装、打包部署每一步都有可验证的产出。配置文件和脚本整理好后换一个数据集、换一类检测目标整个流程照跑一遍就行。后面要继续深挖的方向也不少加入跟踪做统计、引入注意力机制提升精度、接边缘设备做低延迟部署每个方向都够单独做一轮迭代。这条路上值得折腾的事情还多着呢。