简介基于YOLOv8的实时人体检测项目面向深度学习初学者和计算机视觉工程师聚焦视频流与图像中的人体目标识别可广泛用于安防监控、人流统计等实时场景YOLOv8在检测速度与精度之间做了较好平衡这套资源正好提供了一套可运行的代码骨架。压缩包共18个文件以7个Python脚本为主体覆盖模型推理、主程序入口和数据预处理另含示例图片、训练曲线、混淆矩阵等可视化文件以及YAML配置与说明文档整体仅2.73MB结构紧凑且便于本地复现。目前已有44人学习虽然规模不大但作为轻量级入门项目仍有参考价值。具体而言包内包含可直接加载权重进行检测的推理脚本、应用启动入口、依赖版本清单、数据集配置说明和权重目录配合PR曲线与预测样例图能够帮助开发者快速理解YOLOv8的完整使用流程减少了从零搭建环境的成本。适合用来做课程设计、算法对比或生产前的可行性验证。1. 基于YOLOv8的实时人体检测一个zip解压后的完整落地路径拿到一个名为“基于YOLOv8的实时人体检测.zip”的压缩包第一反应应该是看里面有没有训练好的权重、推理脚本和数据集目录。这类压缩包在工程上通常把“模型训练—权重导出—视频流推理”三件事打包在一起目标很直接让你在本地把人体检测跑起来再换成自己的场景数据做微调。YOLOv8是Ultralytics维护的目标检测框架COCO预训练权重里已经包含了person这个类别class id 0所以实时人体检测并不一定非要从头训练它更多是直接调用预训练权重、或者在人流密集的特定场景里做二次微调。这篇文章不假设你已经看过那个zip包里的源码而是按这类项目最常见的内部分工把每一步“怎么做、参数怎么设、坑在哪”讲清楚让手上拿到类似工程包的人能独立跑通而不是只停留在看README的阶段。2. 先把工程跑通环境配置、模型选择与第一帧person框2.1 环境配置GTX 1660 Ti这类中端卡要装什么版本打开压缩包如果看到requirements.txt先别急着无脑pip install -r。里面很可能锁了torch版本而torch版本和你机器上的CUDA驱动未必匹配。我一般先把Python固定到3.9或3.103.11以上有些老代码里的扩展编译会失败然后用nvidia-smi确认驱动再单独安装PyTorch最后才装ultralytics。GTX 1660 Ti是一块6GB显存的图灵架构显卡跑YOLOv8s及以下模型完全够用但注意torch对图灵架构的CUDA要求是10.2以上。这里有个最稳妥的顺序# 先确认驱动版本再决定torch版本 nvidia-smi # CUDA Version显示11.x / 12.x都没问题 python -m venv venv source venv/bin/activate # 手动装torch避免pip自动拉取不匹配的版本 pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics8.2.0逻辑说明先装torch再装ultralytics是有原因的。ultralytics在pip安装时会自动拉取torch但拉到的往往是当前默认版本可能和驱动不匹配。手动装torch能保证CUDA可用。如果你发现torch装完import时直接报“libcudnn.so.8: cannot open shared object file”说明驱动里的CUDA runtime版本和torch编译时用的不一致这时候升级显卡驱动而不是降torch版本能省掉后面一堆麻烦。有一个非常玄学的地方老代码里常见的组合是torch1.13.0 torchvision0.14.0如果你把ultralytics升到8.2以上API会变化很多训练脚本会崩。打开zip里的train.py先看import语句是from ultralytics import YOLO还是from models.experimental import attempt_load。前者是新版API后者是旧工程风格两者的安装依赖完全不同。旧工程如果硬装新ultralytics会在加载权重时直接报错。2.2 用预训练权重跑通第一帧person检测不管zip里的代码组织成什么样推理部分最终都能简化成下面这段from ultralytics import YOLO # 优先加载zip里自带的权重文件没有就用官方预训练 model YOLO(yolov8n.pt) # source可以传图片、视频文件或摄像头ID results model.predict( sourcetest.jpg, conf_thres0.25, iou_thres0.45, classes[0], # 只保留person类别 saveTrue, imgsz640, verboseFalse ) for r in results: for box in r.boxes: cls_id int(box.cls[0].item()) conf float(box.conf[0].item()) xyxy box.xyxy[0].tolist() print(fclass{cls_id}, conf{conf:.2f}, box{xyxy})逻辑说明classes[0]是把COCO 80类里index0的person过滤出来这是实时人体检测最常用的类别过滤方式。如果不传这个参数模型会在人的同时把车、猫、狗一起画框输出里混着大量无关类别你还要再手动筛一遍多此一举。conf_thres是置信度阈值监控场景里0.25在密集人流下容易误检建议提到0.35以上iou_thres是NMS的IoU阈值0.45在行人重叠多的场景里容易把两个人合并成一个框改成0.3会更保守但漏检率会上升。参数说明imgsz640是输入分辨率。YOLOv8默认训练分辨率是640推理也建议用640。如果你把imgsz提到1280远处的小目标行人能多召回一些但GPU推理耗时几乎翻倍。GTX 1660 Ti上跑yolov8n的640推理大约8到12毫秒一帧1280大约要20到25毫秒实时性从30fps掉到15fps以下。另一个容易被忽略的坑是权重文件路径和图片路径里不要有中文ultralytics在Windows下对中文路径处理一直有历史遗留问题运行时代码会报奇怪的编码错误。2.3 模型选型yolov8n到yolov8x怎么选表格对比很多压缩包默认用yolov8n因为参数最少3.2M但人体检测任务如果遮挡多、分辨率低n模型容易漏检。下面这个表格是按“人体检测任务”的使用经验给的选型参考不是万能标准模型参数量(M)1660Ti推理耗时(ms, 640)人体密集场景评价yolov8n3.28~12漏检较多适合单人或稀疏场景yolov8s11.212~16性价比高室内监控推荐yolov8m25.920~28遮挡多时更稳但显存吃紧yolov8l43.730~45精度高但实时性差不推荐中端卡yolov8x68.250以上只适合离线离线批量任务为什么实时人体检测在1660Ti上推荐s而不是n因为人体检测和通用物体检测不太一样人形姿态变化大、衣服颜色杂、多个人重叠时NMS压力很大n模型的C2f模块深度不够特征表达能力偏弱。实际测下来同一段监控视频里yolov8n在人流量大的入口能漏掉三到四成行人yolov8s只漏一到两成。很多人在搜“gtx1660ti跑yolov8”时只看帧率忽略了漏检率这是本项目里最容易踩坑的地方。3. 训练自己的实时人体检测模型数据集格式、训练命令与关键参数3.1 数据集准备把标注数据整理成YOLO格式如果压缩包自带数据集训练前先确认标注格式。YOLOv8训练时吃的是txt标注文件每行一个目标格式是class x_center y_center width height坐标值需要归一化到0~1之间。如果你手上是VOC的XML或者COCO的JSON需要先转成这个格式。常见做法是写一个转换脚本核心逻辑如下import os import cv2 def convert_coco_bbox_to_yolo(img_w, img_h, bbox): # coco的bbox是[x, y, width, height]左上角坐标 x, y, w, h bbox center_x (x w / 2) / img_w center_y (y h / 2) / img_h norm_w w / img_w norm_h h / img_h return center_x, center_y, norm_w, norm_h # 假设你在处理一张图片的标注 img cv2.imread(frame_001.jpg) img_h, img_w img.shape[:2] # 一个person标注x100, y150, w80, h200 coco_bbox [100, 150, 80, 200] cx, cy, nw, nh convert_coco_bbox_to_yolo(img_w, img_h, coco_bbox) # 写成YOLO格式的一行class_id cx cy nw nh with open(frame_001.txt, a) as f: f.write(f0 {cx:.6f} {cy:.6f} {nw:.6f} {nh:.6f}\n)逻辑说明CONVERT的要点是把COCO的“左上坐标宽高”换算成“中心点坐标宽高”并除以图像尺寸做归一化。很多人在这一步直接把COCO的x和y当成了中心点导致训练出来的模型预测框位置全部偏移你会在验证集上看到框比实际人大一圈且明显偏左下。另一个常见错误是忘了把类别id映射到自己的类别列表COCO里人的类别是1YOLO里从0开始编号如果直接拿COCO的原始id写入txt训练时类别对不上模型会把人体当成其他物体。3.2 训练命令与5个关键参数数据集准备好之后目录结构建议按这样组织dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yamldata.yaml内容大概是# 数据集的YAML配置文件 path: ./dataset train: images/train val: images/val names: 0: person然后执行训练yolo train \ modelyolov8s.pt \ datadataset/data.yaml \ epochs100 \ imgsz640 \ batch16 \ device0 \ workers4 \ patience15 \ projectruns/train参数说明modelyolov8s.pt这里用的是预训练权重做初始化不写的话模型会从随机权重开始训收敛速度慢很多上半身和下半身比例这类基础形状要重新学。batch16在1660Ti的6GB显存上基本是yolov8s的上限如果报CUDA out of memory就降成8同时workers降到2否则数据加载线程会抢占显存。patience15是说验证集指标连续15轮不提升就提前停止我一般保留这个默认值省时间。一个细节训练日志里有个box_loss和cls_loss很多初学者看到loss值大了就开始担心。其实YOLOv8的loss是多个任务加权后的结果box_loss在0.5到2之间波动很正常关键看val曲线是否下降。如果你用的是老代码可能还会看到giou_loss这个叫法它和box_loss是一回事只是算损失的函数版本不同不用纠结名字。3.3 训练后验证与模型导出训练完成后runs/train/exp/weights/目录下会有best.pt和last.pt。best是验证集指标最优的权重last是最后一轮权重推荐用best做推理和导出。验证命令yolo val modelruns/train/exp/weights/best.pt datadataset/data.yaml验证完看两个指标mAP50和mAP50-95。人体检测单类别场景mAP50在0.85以上基本可用mAP50-95能到0.6就算合格。如果mAP50高但mAP50-95低说明框的位置精度不够通常是标注框本身不贴合人体边缘或者训练分辨率不够。如果两个都低优先检查训练集的标注txt格式和原始图像是否文件名对不上。导出ONNX或TensorRT引擎可以用一条命令yolo export modelruns/train/exp/weights/best.pt formatonnx dynamicTruedynamicTrue会导出动态尺寸的ONNX方便后续在RK3588这类边缘设备上调整输入分辨率。注意导出的onnx如果直接用opencv的dnn模块加载输出解析方式和yolo原生模型不同你需要额外处理输出层三个头的拼接这个坑在边缘部署时非常常见。4. 实时推理落地视频流处理、性能调优与RK3588部署路径4.1 摄像头/视频流推理的最小框架训练好的模型最终要接到视频流里才叫实时检测。最简单的做法是用OpenCV读帧逐帧送入模型推理import cv2 from ultralytics import YOLO model YOLO(runs/train/exp/weights/best.pt) cap cv2.VideoCapture(0) # 0表示usb摄像头 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720) while True: ret, frame cap.read() if not ret: break results model.predict( sourceframe, conf_thres0.35, imgsz640, classes[0], verboseFalse ) # 在原始帧上画框 for r in results: boxes r.boxes for box in boxes: x1, y1, x2, y2 map(int, box.xyxy[0].tolist()) cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.imshow(person detection, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()逻辑说明这个框架里最容易翻车的地方是摄像头分辨率和推理分辨率的加减乘除搞混。摄像头采集是1280x720推理imgsz640模型输出的box坐标是相对640x640输入坐标系的但YOLOv8的predict接口在传入numpy数组时已经把坐标还原到了原始帧的坐标系所以可以直接用xyxy画框不需要手动缩放。如果你走的是自己写的预处理流程resize letterbox就一定要在画框前把坐标映射回去否则框全是偏的。性能瓶颈通常不在模型本身而在“读帧→推理→画框”这套串行流程。OpenCV的VideoCapture读取usb摄像头默认是拉流同步的如果算法耗时20ms帧率就只有不到30fps。想要更高吞吐常见做法是加一个队列让采集线程和推理线程解耦。这里不展开多线程代码先记住一个原则把cap.read()放在一个单独的线程里推理线程只管处理队列里的最新一帧这样即使推理偶尔卡顿画面也不会越堆越卡。4.2 性能调优你能动的几个参数在不换硬件的前提下实时帧率可以从这几方面去抠。第一是conf_thres从0.25提到0.4能过滤掉大量低置信度的误检框NMS处理的候选框数量减少推理耗时能下降10%到15%。第二是imgsz如果你监控的是固定机位视角范围基本不变可以把640降到480只损失一点远处小目标的召回帧率提升立竿见影。第三是推理时关闭增强相关的参数predict接口里的augmentTrue会做多尺度测试速度慢好几倍默认是False别手滑改成True。还有两个不那么直观的优化手段。batch推理适用于视频流里同时处理多路摄像头把多帧拼成一个batch送进模型GPU利用率可以提高yolov8s在batch4时单帧耗时能降两到三成。另一种是半精度推理在支持FP16的图灵架构上直接把模型转成fp16权重yolo predict modelyolov8s.pt sourcetest.jpg halfTrueFP16推理在1660Ti上大约能快10%到20%但精度会略降密集人群时可能出现框位置抖动的现象。如果你的场景对框的稳定性要求高border建议别开FP16用TensorRT引擎效果更好——不过TensorRT在1660Ti上的收益主要是显存占用降低速度提升没有高端卡那么夸张。4.3 RK3588部署yolov8从PyTorch到NPU要走完的几步很多人在搜“yolov8部署到rk3588”是因为RK3588这颗芯片自带6TOPS的NPU适合在边缘设备上跑轻量级人体检测。部署路径大概是PyTorch训练 → 导出ONNX → RKNN转换工具转成rknn格式 → 在RK3588上用瑞芯微的runtime API推理。这个链路里最麻烦的是ONNX导出和RKNN适配。导出ONNX时建议用固定输入尺寸RK35188对动态尺寸的ONNX支持不稳定yolo export modelruns/train/exp/weights/best.pt formatonnx opset12 imgsz640转换rknn时注意权重文件里如果包含部分不支持的算子比如某些自定义上采样模块需要用瑞芯微的RKNN-Toolkit2逐个排查。常见做法是先用rknn的quantizeTrue做INT8量化人体检测的精度损失一般能控制在mAP50下降3个百分点以内。如果你的模型是人多的密集场景INT8量化后漏检会明显增加这时候建议保留FP16推理但NPU的FP16效率不如INT8帧率会掉一半。后端runtime的集成流程虽然很工程化但核心点在于RDK瑞芯微开发套件上的rknn_run输入要求是NHWC格式的numpy数组和PyTorch的NCHW不一样需要在喂数据前做转置或者用字母盒预处理把图像padding到640x640。这个坑几乎每个RK3588部署新手都会踩一次。5. 避坑与常见问题人体检测项目最容易翻车的5个点5.1 现象训练时loss正常但预测结果全是空的原因推理时忘记了类别过滤。如果你在训练时只用了person一个类但推理时没传classes[0]模型会把COCO里80个类别的判断全部跑一遍输出结果里person类别的置信度被其他类别的NMS压低了有些低置信度目标被过滤看起来像是空的。还有一个原因是权重路径加载错误——加载了last.pt但训练没有收敛到最好状态。解决推理时显式加classes[0]并优先使用best.pt。如果你自己标注的数据集只有person一类训练时data.yaml里names就只写person推理时没必要再去过滤COCO的类别id直接传classes[0]即可。5.2 现象摄像头实时检测的帧率上不去只有十几fps原因测速时把画框、显示窗口、打印日志都算进去了。cv2.imshow本身就要占据一部分帧时间verboseTrue会每帧打印一次检测结果这些IO操作在Windows下特别明显。另一个原因是模型选型过重有人一次性拿yolov8x跑640实时检测那帧率自然惨不忍睹。解决先用results model.predict(sourceframe, verboseFalse)做纯推理测速把画框注释掉看这一段的耗时。yolov8s在1660Ti上如果纯推理超过20ms检查是否开了FP16、imgsz是否被意外设到了1280。如果纯推理只有15ms但整体帧率低问题就出在显示和读取环节用双线程或者把显示窗口的刷新率降到30fps画面流畅度体感会好很多。5.3 现象密集人流场景里两个人重叠时只出一个框原因iou_thres0.45时NMS会把重叠度高的两个候选框合并成一个。人体检测和车辆检测不同人挨着人站非常常见IoU超过0.5的候选框不少。第二个原因和锚框有关YOLOv8虽然是anchor-free的但在小目标人形上预测的多个候选框重叠度过高NMS合并后只保留了一个。解决把iou_thres降到0.3并适当降低conf_thres到0.3左右让重叠候选框保留更多。如果还没改善在训练时把imgsz提到768或896小目标的可分性会明显提升。实测下来人流密集的地铁闸机场景imgsz从640提到768时漏检率能降四分之一。5.4 现象运行环境报错——torch版本和CUDA不匹配import时报错原因很多人拿到zip后直接pip install -r requirements.txt然后train.py一跑就报错。最常见的是torch是CPU版本或者torch的CUDA编译版本比自己驱动低了一个大版本。GPU和torch之间这种兼容性问题是深度学习环境里最玄学的一环也是让人浪费时间最多的地方。解决先看nvidia-smi的输出再对照PyTorch官方给出的whl包版本。如果驱动显示CUDA 12.2你可以直接装pip install torch --index-url https://download.pytorch.org/whl/cu121不用管驱动版本比torch编译版本新向下兼容没问题。如果驱动显示CUDA 10.2以下就别挣扎了先升级驱动要不然后面TensorRT和ONNX Runtime都会各种报错。5.5 现象想画损失函数曲线图和热力图看模型行为但代码不工作原因YOLOv8训练时默认只输出终端日志和results.png如果你想画单独的损失函数曲线图或者生成特征热力图需要手动在回调里收集指标。很多zip里的可视化脚本是给老版本写的YOLOv8的trainer API在8.0以后改过接口旧回调函数里用的事件名称对不上新版本所以脚本一执行就报找不到属性。解决新版YOLOv8可以用下面的方式拿到训练过程中的loss指标from ultralytics import YOLO model YOLO(yolov8s.pt) def show_metrics(trainer): metrics trainer.metrics print(box_loss:, metrics.get(val/box_loss)) model.train( datadataset/data.yaml, epochs10, callbacks{on_train_epoch_end: show_metrics} )训练完成后在runs/train/exp/目录下的results.png里已经包含了box_loss、cls_loss、dfl_loss和mAP曲线多数情况下不需要自己重画。如果你是想看特征层热力图YOLOv8本身不提供直接API常见做法是用grad-CAM类工具或者用model.model.model[-1]取到检测头之前的特征层做钩子这个改动比较深新手可以先从results.png入手别一上来就啃热力图代码。6. 验证模型做对没有损失曲线、热力图与部署前的最后一次摸底训练跑完不是结束部署前我通常会做三件验证的事。第一是看损失曲线打开runs/train/exp/results.png重点看val/box_loss那一栏如果曲线尾部还在一路向下没走平说明epochs不够直接加训会比换个模型更快提升精度如果训练集loss下降但验证集loss回升就是过拟合了需要加数据增强或增加训练数据而不是继续加epochs——这是很多人第一次训练自己数据集时会搞反的地方。第二是抽样跑一批从来没见过的测试图片不要只看mAP指标把检测结果可视化出来。我习惯随机选100张图统计三类问题漏检的人、误检的背景、框偏移过大的目标。这三类问题的比例决定了你的模型适合什么样的部署场景。如果误检多调conf_thres看能不能压下去压不下去就回训练集检查是否有标注质量太差的样本比如框画得过大或漏标了几个人这种情况往往是标注数据的问题不是你调参能掩盖的。第三是部署前的环境摸底尤其是准备上RK3588这类边缘设备时。先在PC上用onnxruntime跑一遍导出的onnx模型确认输出尺寸和解析逻辑正确再上RKNN转换。不要跳步直接从PyTorch转RKNN中间隔了太多层转换出了错根本分不清是ONNX的问题还是RKNN量化的问题。我习惯把PC端onnx的推理结果和PyTorch原模型的推理结果做对比同一张图上所有检测框的类别、置信度、位置都基本一致再继续往下走。最后说一个我自己的习惯无论zip包里自带了多少代码我拿到之后一定会自己写一个最精简的复现脚本把从加载权重到输出检测框的完整流程重新写一遍大致就是第2.2节里那个model.predict的调用。这个过程能逼着我把这个工程的每个环节都过一遍而不是依赖某个人写好的封装脚本。做完这一步再回到自己的业务场景里你就能判断这个方向值不值得继续投入时间了。希望这些踩坑经验能帮你把YOLOv8实时人体检测真正落地。本文还有配套的精品资源点击获取