简介这份资源是基于YOLOV8的进出口人流量统计识别Python项目源码包面向计算机视觉方向的在校学生与深度学习初学者可直接用于毕业设计、期末大作业或课程设计。项目围绕进出口场景下的行人检测与双向计数展开涵盖模型推理、目标跟踪与流量统计等核心环节代码注释完整新手也能读懂并快速部署运行。压缩包共72个文件约2.13MB其中21个py文件承载检测、跟踪与统计主逻辑26个yaml文件用于模型与数据集配置另有pyc缓存、png与jpg示例图、md说明及docx手册结构清晰、便于按模块查阅。目前已有128人学习关注。项目经过严格调试附带文档说明与示例素材读者可据此掌握YOLOV8在真实场景中的落地流程理解进出口人流统计的实现思路与调参方法并在此基础上完成功能扩展或论文撰写具备较高的参考与复用价值。1. 进出口人流量统计为什么总在闸机口翻车做过园区、口岸、商超进出口统计的人多半有过这种体验模型在测试集上 mAP 挺好看一搬到真实闸机口人数就开始飘。进出口这个场景有几个天然难点——人流密集、目标互相遮挡、逆光和顶光交替、行人走走停停甚至原地折返。用普通的目标检测模型直接数框很容易把同一个人数成两次或者把并排走的两个人算成一个。基于 YOLOV8 的进出口人流量统计识别方案核心思路是用 YOLOV8 做行人检测再叠加一个轻量的跟踪与越线计数逻辑把「检测框」变成「有身份的人」最后按方向累加进出数量。这套东西适合谁适合手里有 Python 基础、想快速搭一套可跑通的人流统计原型的开发者也适合需要把统计结果接到大屏或后台的工程同学。它不追求论文级精度追求的是能在普通 CPU 或一张消费级显卡上稳定跑起来源码结构清晰、文档能照着复现。下面我按自己落地时的顺序把选型、环境、检测、计数、避坑和调优一层层拆开讲。2. YOLOV8 做人流统计的选型账为什么不是 YOLOv5 或 Faster R-CNN2.1 检测器选型精度、速度、部署成本三笔账进出口统计对检测器的要求其实很具体召回率要高宁可多检几个框也别漏人单帧推理要快因为要连续跟踪模型体积不能太大很多现场只有边缘盒子或者老显卡。YOLOV8 在这三点上比较均衡。相比 YOLOv5YOLOV8 换了 C2f 模块和解耦头在相近参数量下小目标召回通常更好一些这对远处刚进画面的行人很关键。相比 Faster R-CNN 这类两阶段检测器YOLOV8 单阶段推理快得多虽然理论上密集遮挡场景精度略吃亏但进出口统计靠的是连续帧跟踪补偿单帧漏一两个框影响没那么致命。我一般会先跑 YOLOV8n 或 YOLOV8s。n 版本在 CPU 上勉强能到实时s 版本在 GTX1660Ti 这种级别的卡上很轻松。如果现场人流特别密再考虑 YOLOV8m。选型时别一上来就上 x进出口场景的瓶颈往往在跟踪和计数逻辑不在检测器本身。模型参数量级别适用场景备注YOLOv8n最小CPU 边缘设备、低功耗盒子精度够用速度优先YOLOv8s小单张消费级显卡进出口统计的甜点选择YOLOv8m中人流密集、遮挡严重需要更好召回时上YOLOv8l/x大服务器端离线分析实时场景一般不选2.2 计数方案选型检测跟踪越线而不是纯检测很多人第一反应是「检测到人就在画面上画个框框数就是人数」。这在进出口场景基本不可用因为同一个人会在连续帧里被反复检测帧率越高重复计数越严重。常见做法是引入跟踪给每个检测框分配一个 ID再用越线判断这个人是否真的跨过了进出口的分界线。跟踪器我一般用 ByteTrack它和 YOLOV8 配合成熟对遮挡和短暂丢失比较鲁棒。计数逻辑是在画面里画一条虚拟线进出口的门线当某个 ID 的轨迹从线的一侧移动到另一侧时计一次数并记录方向。这样同一个人来回走也只会在真正越线时计数。这套组合比纯检测稳得多也比训练一个端到端的计数网络省事。提示虚拟线的位置要放在人流必经且不容易被遮挡的地方别贴着画面边缘否则目标刚出现就被计数。3. 从零搭环境Ubuntu 20.04 和 Windows 下跑通 YOLOV8 的最小步骤3.1 Python 环境与依赖安装环境这块踩坑最多的是 Python 版本和 CUDA 版本对不上。YOLOV8 官方要求 Python 3.8 以上我一般用 3.9 或 3.10。如果你只有 CPU也能跑只是帧率低适合先验证逻辑。下面是在 Ubuntu 20.04 上从零搭一套 CPU 版本环境的命令Windows 下把 apt 换成对应安装方式即可。# 创建独立虚拟环境避免污染系统 Python python3 -m venv yolov8_env source yolov8_env/bin/activate # 升级 pip老版本 pip 装 ultralytics 容易卡在依赖解析 pip install --upgrade pip # 安装 PyTorch CPU 版本注意去官网核对当前推荐命令 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 安装 ultralyticsYOLOV8 的训练和推理都靠它 pip install ultralytics # 验证安装 yolo checksyolo checks会打印环境信息重点看 Python 版本、PyTorch 版本和是否有可用的 GPU。如果这里报错后面所有步骤都别往下走。参数上--index-url指向 CPU 版 wheel如果你有 NVIDIA 显卡换成对应 CUDA 版本的索引装完用torch.cuda.is_available()确认。3.2 用预训练权重先跑通一张图环境好了别急着训练先用官方预训练权重跑一张图确认推理链路通。这一步能帮你排除掉大部分环境问题。from ultralytics import YOLO # 加载 YOLOV8n 预训练权重首次运行会自动下载 model YOLO(yolov8n.pt) # 对单张图片推理classes[0] 只保留 person 类 results model.predict( sourcetest_gate.jpg, classes[0], # COCO 里 person 的类别 id 是 0 conf0.35, # 置信度阈值进出口场景别设太高 iou0.5, # NMS 的 IoU 阈值 saveTrue # 保存带框结果图 ) # 打印检测到的框数量 print(len(results[0].boxes))classes[0]是关键进出口统计只关心人把其他类过滤掉能减少误检。conf我一般从 0.3 到 0.4 之间试设太高远处的人会漏设太低背景杂物会被当成行人。iou控制重叠框合并人流密集时可以适当调低到 0.45 左右避免并排的人被合并成一个框。跑完看runs/detect/下的结果图如果框的位置和数量肉眼看着合理说明检测这步没问题。4. 检测到计数ByteTrack 跟踪与越线逻辑的完整实现4.1 把检测结果接上跟踪器YOLOV8 的model.track()已经内置了 ByteTrack不用自己单独装跟踪库。下面这段是进出口统计的核心循环读视频、逐帧跟踪、拿到每个目标的 ID 和框。import cv2 from ultralytics import YOLO model YOLO(yolov8s.pt) cap cv2.VideoCapture(gate_entrance.mp4) # persistTrue 让跟踪器在帧之间保持状态这是跟踪能用的前提 while cap.isOpened(): ret, frame cap.read() if not ret: break results model.track( frame, persistTrue, # 必须为 True否则每帧 ID 都会重置 classes[0], conf0.35, iou0.5, trackerbytetrack.yaml ) boxes results[0].boxes if boxes.id is not None: # xyxy 是框坐标id 是跟踪 ID for box, track_id in zip(boxes.xyxy, boxes.id): x1, y1, x2, y2 box.tolist() cx (x1 x2) / 2 # 用框中心点做越线判断 cy (y1 y2) / 2 # 这里把 cx, cy, track_id 交给计数模块 cap.release()persistTrue是最容易漏的参数不设它每帧 ID 都会变跟踪等于没做。trackerbytetrack.yaml指定跟踪配置ultralytics 自带这个文件一般不用改。中心点cx, cy用来做越线判断比用框的角点稳定因为框的大小会随距离变化中心点相对稳。4.2 越线计数的方向判断有了每个 ID 的中心点轨迹接下来判断它有没有跨过虚拟线以及从哪边跨到哪边。我一般维护一个字典记录每个 ID 上一次的位置。# 虚拟线水平线 y line_y跨越方向由 y 的变化决定 line_y 360 track_history {} # {track_id: 上一次的 cy} count_in 0 count_out 0 def update_count(track_id, cy): global count_in, count_out if track_id in track_history: prev_cy track_history[track_id] # 从上往下跨线记为进入 if prev_cy line_y cy: count_in 1 # 从下往上跨线记为离开 elif prev_cy line_y cy: count_out 1 track_history[track_id] cy判断逻辑是「上一次在线的一侧这一次到了另一侧」。用prev_cy line_y cy这种写法能避免同一帧反复触发。line_y要根据实际画面调一般放在画面中下部因为进出口的人流在画面里是纵向移动的。如果进出口是左右方向就把判断换成 x 坐标。这个字典要定期清理长时间不出现的 ID否则内存会慢慢涨。注意跟踪 ID 在目标长时间遮挡后会重新分配同一个人可能拿到两个 ID导致多计。这是 ByteTrack 的固有特性后面避坑章节会讲怎么缓解。5. 进出口统计的避坑清单五个真实翻车现场5.1 同一个人被计两次ID 切换现象监控回放里明明只有一个人走过计数却加了 2。原因行人在画面里被柱子或其他人挡住几秒ByteTrack 丢失目标后重新分配了新 ID越线逻辑把它当成两个人。解决一是把虚拟线放在遮挡少的位置二是给track_history加一个时间窗口ID 消失超过 N 帧才清理短暂丢失时用位置预测续上三是适当降低conf让跟踪器不容易丢目标但别低到引入误检。5.2 远处的人检不到小目标漏检现象画面远端刚进闸机的人经常不计数走近了才被检测到导致进入数偏少。原因YOLOV8 输入尺寸默认 640远处行人只有几十像素特征太弱。解决把推理尺寸提到 960 或 1280model.predict(imgsz960)代价是速度下降或者把摄像头角度调低让人在画面里占比更大。如果现场允许换更高分辨率的摄像头比调模型更有效。5.3 计数线附近来回抖动反复触发现象有人在门口徘徊计数忽增忽减。原因中心点在虚拟线附近抖动反复跨越。解决加一个滞回区间比如进入判断要求cy超过line_y 10才算数离开要求低于line_y - 10中间区域不触发。这个 10 像素的缓冲能滤掉大部分抖动。5.4 CPU 上帧率太低跟踪断档现象Ubuntu 20.04 纯 CPU 跑 YOLOV8s帧率只有个位数跟踪 ID 频繁断。原因CPU 推理慢帧间间隔大目标位移大跟踪匹配失败。解决换 YOLOV8n把imgsz降到 480 或 640或者抽帧处理——每 2 帧处理 1 帧用上一帧结果插值。如果现场有 RK3588 这类带 NPU 的板子把模型转成对应格式部署帧率能上来一大截。5.5 逆光下整片过曝检测全丢现象下午逆光时段进出口画面一片白检测框几乎消失。原因摄像头动态范围不够行人变成剪影。解决这是硬件问题调模型救不回来。加遮光罩、调摄像头曝光补偿、或者换宽动态摄像头。软件上可以试 CLAHE 做局部对比度增强但效果有限别指望它解决根本问题。6. 把统计做准的进阶技巧区域过滤与结果校验6.1 用多边形区域排除非进出口方向的人流真实场景里画面中往往有横向走过的人他们不进出但会穿过虚拟线造成误计。我的做法是再加一个多边形区域只有中心点落在进出口通道多边形内、且跨线的目标才计数。ultralytics 支持region参数做区域推理也可以自己在计数前用cv2.pointPolygonTest判断。import cv2 import numpy as np # 进出口通道的多边形顶点按实际画面标定 gate_polygon np.array([[200, 300], [440, 300], [480, 700], [160, 700]]) def in_gate(cx, cy): # 返回 1 表示点在多边形内 return cv2.pointPolygonTest(gate_polygon, (cx, cy), False) 0标定多边形时用cv2.imshow把顶点画在画面上肉眼确认覆盖了通道。pointPolygonTest第三个参数False表示只判断内外不返回距离速度快。只有in_gate为真时才走越线计数横向人流就被排除了。6.2 用离线回放校验计数误差上线前一定要用一段已知人数的录像做校验。我的习惯是拿一段 5 分钟的进出口录像人工数一遍真实进出人数再跑程序对比。误差在 5% 以内可以接受超过 10% 就得回头查是漏检还是 ID 切换。校验时把每帧的计数和 ID 打到日志里出问题时能定位到具体是哪一秒、哪个 ID 出的错。这套日志习惯帮我省了很多后悔药——现场出问题不用猜直接翻日志。6.3 参数速查与调优顺序调参别乱试按影响从大到小来先定imgsz决定能不能检到远处的人再定conf决定漏检和误检的平衡然后调虚拟线位置和滞回区间决定计数稳不稳最后才动跟踪器的匹配阈值。下面这张表是我常用的起点值具体现场再微调。参数起点值调整方向imgsz640远处漏检就提到 960conf0.35漏检多就降到 0.3误检多就升到 0.45iou0.5密集场景降到 0.45滞回区间10 像素抖动多就加大跟踪丢失容忍30 帧ID 切换多就加大这套方案我从最早用 YOLOv5 手写跟踪到后来换成 YOLOV8 加 ByteTrack最大的教训是别在检测器上死磕精度进出口统计的准确率七成靠虚拟线和区域设计三成靠检测。把线画对、把区域框准比换个更大的模型管用得多。希望帮到你。本文还有配套的精品资源点击获取