简介面向有深度学习基础的行人检测开发者这套YOLOv8行人检测工程包整合了标注数据集、训练权重与图形界面三个核心部分基于YOLOv8算法在数千张街道和交通场景图像上训练平均精度均值达90%以上可直接用于行人识别省去从零采集与标注数据的时间。压缩包内共2000个文件以文本标注或配置文件为主另含四个说明文档、三个环境配置与运行教程、两个程序源码模块整体约456.56MB。除权重与数据集外还提供训练曲线图、标注工具使用说明、图形界面代码与运行步骤数据集图片为jpg格式类别统一为person可直接适配YOLO系列模型继续微调代码模块划分清晰注释和目录结构便于修改维护可快速搭建检测演示系统或进行二次开发资源涵盖了环境配置、模型训练到界面部署的完整链条初学者可以按图索骥。目前已有817人学习下载配套完整能够帮助学习者避开数据准备与界面开发的重复工作把精力集中在模型改进与业务落地之上对目标检测方向的研究者与工程师都有实用价值。1. 别只跑通YOLOv8一个能交付的行人检测项目差在数据集和界面有个很反直觉的现象很多人跑通了 YOLOv8 的官方 demo换到自己手上的行人检测项目却漏洞百出一半时间耗在数据集上另一半耗在“界面怎么不卡死”上。标题里的三件事——YOLOv8行人检测、数据集、PyQt界面本质是一条链模型提供检测能力数据集决定检测上限界面决定能不能交付使用。这篇笔记面向正在做毕设、演示系统或接单交付的工程师按模型选型、数据集整理、模型训练、PyQt界面集成一条线讲透每个环节给能直接复制的命令和脚本并把最容易翻车的点提前标出来。2. 为什么选YOLOv8做行人检测模型、数据与界面的选型逻辑在动手之前先把“为什么”说清楚不然参数全靠抄出问题就是玄学。行人检测是把目标检测难点占全的场景目标小、互相遮挡、密集排列、尺度变化大。选型直接决定后面每一步的工作量也决定最后能不能在本地 CPU 机器上顺利跑起来。2.1 YOLOv8 vs Faster R-CNN / SSD / YOLOv5行人场景的取舍我一般用三个标准来卡选型单机演示必须实时、换数据集后调参量可控、社区资料多到能解决疑难问题。Faster R-CNN 两阶段精度高但对 CPU 完全谈不上实时在 PyQt 里演示基本不可用SSD 小目标检测弱行人这种远距离小目标漏检严重YOLOv5 成熟但 anchor-based 机制要求换数据集后重算 anchor处理密集行人时 NMS 参数也得反复试。YOLOv8 的改动正好踩在行人检测的需求上。它去掉了 anchor把 head 拆成分类和回归两个独立分支还引入 C2f 结构小目标特征提取能力比 YOLOv5 的 C3 强一些。对做界面的人来说最友好的地方是官方把训练、验证、导出封装成了 yolo 命令不需要自己写训练循环。有人问我 yolov8网络结构图有没有必要看其实你只要知道 backbone 负责提特征、neck 的 PAN-FPN 负责融合不同尺度、head 输出三组特征图就够了其余细节交给官方实现。方案CPU推理小目标换数据集调参界面集成Faster R-CNN慢较好中重SSD快差中中YOLOv5中中anchor需重算中YOLOv8中较好低低这个对比表是我选型时常用的判断方式。行人检测项目通常不是只有训练这一环后面还要做界面、演示、交付越靠后的环节越需要省心YOLOv8 的生态优势在这里体现得很明显。2.2 行人数据集的三大难点尺度、遮挡、难例数据集不是“越多越好”而是“难例越全越好”。行人检测项目里最常见的现象是模型在训练集上 mAP 很高一换场景就疯狂误检。原因多半是数据里只有近距离大目标没有远距离小目标、遮挡行人和负样本。常见做法是先用公开行人数据集做预训练比如 COCO 里的 person 类别、CityPersons、CrowdHuman 这类再用自己场景的图片增量标注。这里的坑是公开数据集标注质量参差不齐很多标签只框了可见部分遮挡严重的行人是缺失的。如果直接拿来当训练标准模型会对遮挡行人不敏感现场一遇到拥挤路段就开始丢框。另一个被忽略的是负样本。行人检测的误检往往来自背景中像人的物体比如树干、路灯杆、广告牌上的人形图案。所以我在数据集里会专门放一批不包含行人的图片让模型学会“这里没有行人”。这批负样本可以是一整个目录标签为空 txt 文件训练时会正常读取只是正样本数量为零。数据集里加入负样本后误检率通常能降一半以上。2.3 PyQt 在项目里的定位UI 线程只负责显示推理必须单独开线程PyQt 在这个项目里不是“画个窗口把检测框贴上去”那么简单。行人检测的推理耗时通常在几十到几百毫秒如果直接在按钮的回调里跑推理点击“开始检测”之后界面会立刻无响应这就是常说的“ui界面卡顿”。我见过太多人把模型推理写在主循环里最后只能靠 sleep 缓解结果画面掉帧更严重。正确结构是主线程负责窗口和 QTimer 定时刷新画面检测工作放在 QThread 子线程里子线程读帧、推理、绘制然后用 signal 把处理好的 QImage 发回主线程。子线程内部用循环控制帧率而不是每次收到 UI 信号才跑一次。这样摄像头的帧率不会拖垮界面界面操作也不会打断推理。另外读取摄像头建议用 OpenCV 而不是 PyQt 自带的多媒体框架。OpenCV 的 VideoCapture 在 ubuntu20.04 上对 USB 摄像头和网络流兼容性更好而且它的帧格式是 BGRYOLOv8 输入要的是 RGB中间记得用 cvtColor 转换。这个细节看起来小但正是检测框错位和颜色异常的常见原因。界面上的控件不需要多复杂文件选择按钮、摄像头切换、置信度滑块、FPS 显示就够用。置信度滑块我强烈建议留出来因为不同场景下行人检测的 conf 阈值差距很大室内 0.3 能出效果室外强光下可能要 0.5把 conf 做成滑块实时传给推理线程比每次改代码重跑快得多。3. 数据集整理一站式脚本把VOC/Labelme标注转成YOLO格式并切分数据集模型训练前数据集必须变成 YOLO 格式。很多人栽在格式上标签路径对不上、坐标没归一化、图片和标签不在同名目录导致训练时 mAP 一直为 0。这一章给你能直接跑的脚本顺便把容易忽略的检查逻辑写进去。3.1 目录结构与检查先保证每个图片标签能对上YOLO 格式的目录结构有约定俗成的规范单类别行人检测的标准布局如下datasets/pedestrian/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 训练标签 │ └── val/ # 验证标签 └── data.yaml # 训练配置图片和标签必须同名只是后缀不同比如0001.jpg对应0001.txt。标签文件每一行是class_id x_center y_center width height这里的坐标是相对图片宽高的归一化值范围在 0 到 1 之间。最容易犯的错是把像素坐标直接写进去训练时 loss 会乱飘。拿到数据集后先跑一遍检查脚本看看有多少图片缺标签、有多少标签文件是空的。空标签对训练本身没影响但如果你没有专门建负样本目录空标签往往意味着漏标这部分图片会让模型学到“有行人但不框”。# check_labels.py核对图片与标签是否一一对应 from pathlib import Path for split in [train, val]: img_dir Path(fdatasets/pedestrian/images/{split}) label_dir Path(fdatasets/pedestrian/labels/{split}) imgs sorted(img_dir.glob(*.*)) missing 0 empty 0 for img in imgs: label label_dir / (img.stem .txt) if not label.exists(): missing 1 print(fmissing label: {label}) elif label.stat().st_size 0: empty 1 print(fempty label: {label}) print(f{split}: {len(imgs)} images, {missing} missing, {empty} empty)这个脚本的逻辑很简单遍历图片目录按 stem 找同名 txt。如果 missing 超过 1%先补标注再训练不要指望模型自己纠正错误标签。empty 数量如果超过 5%确认一下是负样本还是漏标。负样本我会单独放在images/train/negative/子目录里管理方便后续替换。3.2 转换脚本把VOC XML转成YOLO txt处理坐标和类别映射常见的数据来源是 VOC 格式的 XML每张图一个 xml 文件框的坐标是像素级的左上右下。转换脚本核心逻辑如下class_names 的顺序决定了标签编号必须和后续训练配置严格一致。# voc_to_yolo.py将VOC XML标注转成YOLO txt import xml.etree.ElementTree as ET from pathlib import Path class_names [person] # 类别清单顺序决定标签编号 def voc_to_yolo(xml_path: Path) - list: tree ET.parse(xml_path) root tree.getroot() img_w int(root.findtext(size/width)) img_h int(root.findtext(size/height)) lines [] for obj in root.findall(object): name obj.findtext(name) if name not in class_names: continue if obj.findtext(difficult) 1: continue # 跳过difficult目标避免干扰训练 cls_id class_names.index(name) box obj.find(bndbox) xmin int(float(box.findtext(xmin))) ymin int(float(box.findtext(ymin))) xmax int(float(box.findtext(xmax))) ymax int(float(box.findtext(ymax))) # 处理翻转坐标和越界 xmin, xmax min(xmin, xmax), max(xmin, xmax) ymin, ymax min(ymin, ymax), max(ymin, ymax) xmin max(0, xmin) ymin max(0, ymin) xmax min(img_w, xmax) ymax min(img_h, ymax) if xmax - xmin 2 or ymax - ymin 2: continue # 过滤小于2像素的碎片框 x_center (xmin xmax) / 2.0 / img_w y_center (ymin ymax) / 2.0 / img_h bw (xmax - xmin) / img_w bh (ymax - ymin) / img_h lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {bw:.6f} {bh:.6f}) return lines for xml_path in Path(xml_all).rglob(*.xml): lines voc_to_yolo(xml_path) if not lines: continue out_path Path(labels_all) / (xml_path.stem .txt) out_path.write_text(\n.join(lines) \n, encodingutf-8)逻辑说明VOC 的 bndbox 标签是左上右下像素坐标YOLO 需要中心点和宽高的归一化值。转换时我做了两件容易被忽略的事——过滤 difficult 目标和小于 2 像素的碎片框。difficult 是 VOC 里表示“难以辨认”的标记留下它会让训练信号变弱碎片框通常是标注软件误操作产生的留着会让模型对噪声敏感。如果用的是 labelme标注用于yolov8json 文件里存的是多边形点坐标不是矩形框。转换逻辑是先取所有点的 x 最小值、y 最小值、x 最大值、y 最大值得到 bbox再做同一套归一化。注意 labelme 的 imageWidth/imageHeight 字段必须和真实图片一致否则转换后坐标整体偏移训练时 loss 能降但推理框会歪。3.3 切分训练/验证集并生成data.yaml数据转换完成后按比例切分数据集。这里有一个人人都会踩的坑只随机切分图片忘了把同名标签一起移动训练时报“label not found”或者隐式跳过。下面这个脚本把图片和标签一起复制并且保留原始素材切分不满意可以重新来。# split_dataset.py按比例切分train/val图片和标签一起复制 import random import shutil from pathlib import Path random.seed(42) # 固定随机种子保证可复现 val_ratio 0.2 img_all [p for p in Path(images_all).iterdir() if p.suffix.lower() in (.jpg, .jpeg, .png)] img_all.sort() random.shuffle(img_all) val_num int(len(img_all) * val_ratio) for split, imgs in [(train, img_all[val_num:]), (val, img_all[:val_num])]: img_out Path(fdatasets/pedestrian/images/{split}) label_out Path(fdatasets/pedestrian/labels/{split}) img_out.mkdir(parentsTrue, exist_okTrue) label_out.mkdir(parentsTrue, exist_okTrue) for img in imgs: label Path(labels_all) / (img.stem .txt) if not label.exists(): print(fskip {img.name}: label not found) continue shutil.copy2(img, img_out / img.name) shutil.copy2(label, label_out / label.name) print(f{split}: {len(imgs)} images)这里用 shutil.copy2 而不是 os.rename是因为复制不破坏原始目录跑完检查发现划分不理想删掉输出目录重新执行就行这就是后悔药。val_ratio 设成 0.2如果你的素材总量很大可以降到 0.1但验证集图片太少会导致 mAP 波动大不建议低于 50 张。切分完成后在 datasets/pedestrian 下创建 data.yaml# data.yaml path: datasets/pedestrian # 相对路径从运行yolo命令的工作目录解析 train: images/train val: images/val nc: 1 names: [person]注意 path 用相对路径而不是绝对路径绝对路径在当前机器能跑换台电脑或者打包给别人就会全部失效。names 的顺序必须和转换脚本里的 class_names 一致这里只有 person 一个类别顺序影响不大但多类别时顺序错了就是灾难。4. 用ultralytics训练YOLOv8行人检测环境配置、训练参数与结果验证数据准备好了接下来进入训练环节。这一步要同时解决环境、参数和验证三个问题。先搭一个干净的虚拟环境再跑训练命令最后用验证集把模型表现量化出来方便后面调阈值。4.1 ubuntu20.04搭建yolov8环境cpu版本最小可跑环境我常用虚拟环境把项目隔离避免和系统 Python 打架。CPU 版本训练行人检测是可行的慢是慢一点但小数据集完全能撑住。python3 -m venv yolov8_env source yolov8_env/bin/activate pip install --upgrade pip pip install ultralytics opencv-python说明CPU 环境不需要手动装 CUDA 版 torchpip 会自动匹配当前机器安装 CPU 版本。装完后先跑一次官方权重验证环境yolo predict modelyolov8s.pt sourcetest.jpg saveTrue第一次运行会自动下载 yolov8s.pt 权重网络慢的时候会卡在下载阶段。常见做法是先下载好权重文件放到用户目录的~/.cache/ultralytics/下下次启动就直接读缓存。这一步和模型本身关系不大但很多人以为环境坏了实际上是权重没下完。4.2 训练命令与关键参数yolov8模型训练参数含义训练行人检测模型的命令如下我按 CPU 训练的场景给了保守参数yolo detect train \ modelyolov8s.pt \ datadatasets/pedestrian/data.yaml \ epochs120 \ batch8 \ imgsz640 \ lr00.01 \ patience20 \ seed42 \ workers4 \ devicecpu每个参数在行人检测场景下的含义参数推荐值说明modelyolov8s.pt用s而不是nn快但漏检多s在CPU上也能跑epochs120配合patience早停不必纠结具体轮数batch8CPU内存有限太大容易OOMimgsz640小目标多时提高到768或896lr00.01ultralytics默认值除非loss震荡否则不动patience20验证指标连续20轮不涨就停seed42固定随机种子实验可复现devicecpuubuntu20.04 CPU环境直接写cpuimgsz 是行人检测里最值得调整的参数。行人尺度变化大640 输入下远处行人可能只有十几个像素特征根本提不出来。我的习惯是先用 640 跑通流程确认数据没问题后再把 imgsz 提到 768 重新训练通常 mAP50 能涨 3 到 6 个点。代价是训练时间变长CPU 上会更明显。密集行人场景还有一个容易翻车的点ultralytics 默认开启 mosaic 数据增强把四张图拼在一起训练对常规目标有效但对密集行人会让目标互相重叠变成一团马赛克。我在拥挤场景会把 mosaic 调小到 0.5 甚至关闭。可以在训练命令里直接加mosaic0.5或者用 Python 接口设置from ultralytics import YOLO model YOLO(yolov8s.pt) model.train( datadatasets/pedestrian/data.yaml, epochs120, imgsz768, batch8, devicecpu, patience20, seed42, mosaic0.5, cacheFalse, )cache 参数我特意写成了 False。CPU 训练时如果把图片缓存到内存几十 G 的数据会直接把内存打爆虽然能加快读取速度但得不偿失。4.3 验证结果用best.pt在图片上推理并看指标训练结束后runs/detect/train 目录下会有 best.pt 和 last.pt。best.pt 是验证集上表现最好的权重后续界面接入用这个。先跑一次验证集评估拿到量化指标yolo detect val \ modelruns/detect/train/weights/best.pt \ datadatasets/pedestrian/data.yaml输出里主要看 mAP50 和 mAP50-95。行人检测这种单类别任务mAP50 达到 0.8 以上可以进界面联调mAP50-95 受小目标影响大不要因为它低就疯狂调参。再看 Precision 和 Recall如果 Recall 明显低说明漏检严重优先提高 imgsz 或降低 conf 阈值。再用单张图片实测一下顺便验证推理链路from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) results model.predict(test.jpg, conf0.35, iou0.45, imgsz640) for r in results: print(boxes:, r.boxes.xyxy) print(conf:, r.boxes.conf) print(cls:, r.boxes.cls) r.show()conf 和 iou 是两个需要在界面调试中反复调的值。conf 是置信度阈值默认 0.25 对行人检测偏低误检框会很多我一般从 0.35 起步。iou 是 NMS 阈值默认 0.7密集人群场景建议调到 0.4 到 0.45否则重叠的行人会被合并成一个框。5. 落地避坑行人检测从训练到PyQt界面的5个翻车点这一章汇总我实际踩过的坑每一条都按现象、原因、解决三个层面写清楚。项目做多了你会发现模型训练本身很少卡人反而是这些看起来不起眼的细节最耗时间。5.1 训练了100个epochmAP50还是0现象训练日志里 loss 在降验证集 mAP50 永远是 0或者打印出来的类别全是错的。原因三个常见问题——标签类别索引和 data.yaml 对不上、标签坐标是绝对像素没归一化、图片和标签文件名不一致导致模型只学了空标注。解决在训练前画一批带标注框的图片肉眼看一遍。画框脚本如下import cv2 from pathlib import Path img_path Path(datasets/pedestrian/images/train/00001.jpg) label_path Path(datasets/pedestrian/labels/train/00001.txt) img cv2.imread(str(img_path)) h, w img.shape[:2] for line in label_path.read_text().strip().splitlines(): cls, cx, cy, bw, bh map(float, line.split()) x1 int((cx - bw / 2) * w) y1 int((cy - bh / 2) * h) x2 int((cx bw / 2) * w) y2 int((cy bh / 2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.imwrite(check.jpg, img)框位置偏了问题在转换脚本全是几像素的小点说明坐标没有归一化或者读错了宽高框完全画不出来说明标签文件是空的。这一步跑通再训练能省下一整天的调试时间。5.2 PyQt界面一点“开始检测”就卡死现象点击按钮后窗口无响应操作系统提示程序未响应画面冻结。原因模型推理直接写在按钮回调里阻塞了 PyQt 主线程的事件循环。摄像头读取也可能阻塞在视频流的 read() 上尤其是网络摄像头。解决推理放进 QThread 子线程只通过信号回传 QImage。核心结构如下class DetectThread(QThread): frame_ready pyqtSignal(QImage) def run(self): cap cv2.VideoCapture(0) while self.running: ok, frame cap.read() if not ok: continue results model.predict(frame, confself.conf, imgsz640) annotated results[0].plot() rgb cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB) h, w, ch rgb.shape qimg QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) self.frame_ready.emit(qimg)注意 QImage 构造时的 bytesPerLine 参数要用ch * w如果写默认值画面会显示成错位的条纹。模型对象要在子线程里初始化不要在信号回调里反复加载否则每帧都会重新读权重。5.3 远距离小目标漏检密集人群乱成一团现象近处的行人框得很准远处行人漏掉人群里多个框重合。原因输入分辨率太低模型用的是 yolov8n 这种轻量级结构NMS 的 iou 阈值太高导致重叠框被错误合并。解决分三步走。第一步训练时把 imgsz 从 640 提高到 768 或 896第二步模型从 n 换成 s 或 ms 在 CPU 上还能接受m 就比较吃力第三步推理时把 iou 降到 0.4。如果数据集里小目标占比本身低还需要专门补充远距离行人图片模型对小目标不敏感数据层面不给案例是调不出来的。5.4 界面里检测框画在错误位置检测结果对不上画面现象框出现在目标的左边或右边人明明在画面左侧框却标到右侧。原因OpenCV 读进来是 BGRYOLO 输入要 RGB模型内部做了 letterbox 缩放推理出的坐标是缩放后的坐标系没有映射回原图摄像头画面开了镜像但没有对 X 坐标做翻转。解决用 results 自带的 plot() 方法画框不会出错手动画框时一定要做坐标还原。letterbox 的还原公式是固定的ratio min(new_w / orig_w, new_h / orig_h) pad_x (new_w - orig_w * ratio) / 2 pad_y (new_h - orig_h * ratio) / 2 # 推理框x1从模型坐标还原到原图坐标 x1_orig int((x1 - pad_x) / ratio)如果开了镜像记得再执行x1_orig orig_w - x1_orig。这个坑在接入外部摄像头时特别常见因为许多监控摄像头的画面本身就是镜像的。5.5 验证指标虚高实拍却一塌糊涂现象val 集 mAP50 高达 0.85拿到现场一测漏检严重感觉训练了个寂寞。原因数据划分时同一段视频的连续帧被随机拆进了 train 和 val造成数据泄漏。模型在 validation 阶段见过高度相似的帧指标自然虚高。解决划分数据集时按视频段而不是按帧切分。我的做法是先按视频来源给图片打标签比如 surveillance_cam01_frame0001.jpg然后以视频名为单位做切分保证同一段视频的所有帧都在同一集合里。另外现场测试一定要换一个完全没有参与训练的场景哪怕只是隔着一条街拍的片段都比 val 集上的数字有参考价值。6. 进阶把best.pt导出ONNX并接入PyQt用视频离线验证效率高很多训练出 best.pt 并且界面能跑起来之后下一步通常是提速和稳定。我常用的做法是把模型导出成 ONNX再用 onnxruntime 跑推理。这样做有两个好处一是导出后推理逻辑不再依赖 ultralytics 这个大包打包给客户时体积小很多二是 onnxruntime 的 CPU 线程利用率更好配合多线程能让推理速度接近实时。导出命令很简单yolo export modelruns/detect/train/weights/best.pt formatonnx opset12 imgsz640opset 别追求最新客户端装的是 onnxruntime 1.x 时opset 过高会报不兼容。导出后在 PyQt 里加载import onnxruntime as ort sess ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) outs sess.run(None, {sess.get_inputs()[0].name: input_blob})这里 input_blob 是 letterbox 预处理后的归一化张量shape 是 (1, 3, 640, 640)。输出解析要看模型输出的 shape通常是 (1, 84, 8400) 这种形式需要转置后按行过滤置信度。解析逻辑建议画一张坐标变换图存在项目里不然一周后回来看代码就是黑匣子。离线验证是我最推荐的一条工作习惯把现场录一段视频存成 mp4先让脚本读取视频、跑推理、把每帧的 FPS 和漏检情况打印出来确定没问题再接摄像头。在摄像头前反复测试既浪费时间又难复现问题。有一次我直接在摄像头前调参漏检情况无法定位后来把录屏逐帧分析才发现是现场逆光导致行人对比度低加一个光照预处理就解决了。这个教训让我后来坚持先录视频再动手。模型、数据、界面三部分分开测试再串起来整体调试是这个项目里最值得投入的习惯。希望这些内容能帮你少走一段弯路。本文还有配套的精品资源点击获取