简介基于YOLOv8的智能门禁系统是一套面向毕业设计、课程设计与工程实践的完整目标检测项目资源包适用于计算机视觉、人工智能、自动化等专业学生及需要快速搭建检测系统的开发者。项目包含全部Python源码、完整标注数据集、可视化操作界面和详尽部署教程运行后可生成混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果以及标签分布图等核心评估图表有助于在答辩或项目汇报中直观展示模型性能代码已测试通过可直接使用或二次开发。资源压缩包共97个文件以70个py源码文件为主辅以12个pyc字节码文件、4个pt模型权重、5个xml配置、2个txt说明及1个mp4演示视频整体体积仅24.21MB结构紧凑便于下载和学习。目前已有52人学习适合需要短时间完成从训练到部署全流程的读者参考。1. 智能门禁系统为什么值得选 YOLOv8从「人脸比对」到「行为检测」做课设和毕设的朋友常问我一个问题同样是智能门禁系统为什么我更推荐基于 YOLOv8 来做而不是传统的人脸比对。原因很现实——大多数答辩现场只有一台普通笔记本加一个 USB 摄像头没有人脸库也没有指纹虹膜硬件硬做人脸识别大概率卡在数据量上。YOLOv8 这类检测模型思路完全不同先把「有人吗、是不是戴了安全帽、有没有进入警戒区」检测出来再由业务层决定是否开门、是否报警训练门槛低、演示效果好。市面上的「基于YOLOv8的智能门禁系统」项目包也喜欢把源码、完整数据集、可视化界面、部署教程打包在一起解压后简单配置就能跑通。这里只讲落地路径环境怎么搭、数据怎么整、模型怎么训、界面怎么写、坑在哪。2. 先把 YOLOv8 跑起来CPU 与 GPU 环境配置和第一个检测框2.1 环境准备Ubuntu 20.04 CPU 版怎么搭GPU 版怎么选先说结论如果只是做课设演示CPU 也能跑通但模型必须选 yolov8n如果有独立显卡训练直接在显卡上进行推理速度能到实时。最常见的组合是 Ubuntu 20.04 加 Python 3.9 加虚拟环境Windows 上流程完全一样只是路径分隔符和 conda 激活命令略有差异。先创建虚拟环境然后安装 ultralytics 主包conda create -n door python3.9 -y conda activate door pip install -U ultralyticsultralytics 是 YOLOv8 的官方实现包模型结构、训练、推理、导出都在里面安装时会自动拉取 PyTorch、OpenCV 等依赖。如果网络一般建议先单独装 PyTorch 再装 ultralytics避免依赖解析超时重来。CPU 机器最忌讳直接pip install torch默认装的是带 CUDA 的大体积版本CPU 上用不了还白占几个 G 磁盘。推荐走 CPU 专用源pip install torch torchvision --index-url https://download.pytorch.org/whl/cpuGPU 机器先确认驱动nvidia-smi看到 CUDA Version 12.x 之后装对应 cu121 版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121参数说明cu121表示 CUDA 12.1 运行时驱动版本比它新就行不必完全相同。这一步没弄对后面训练会报Torch not compiled with CUDA enabled那是 PyTorch 装错了不是模型代码的问题修改方向别搞反。2.2 用预训练模型跑通第一个检测命令环境装好后先别急着上自己的数据。用官方预训练权重把整条链路验证一遍再做任何二次开发yolo detect predict modelyolov8n.pt sourcesample.jpg saveTruemodelyolov8n.pt指定 nano 版本权重是 YOLOv8 最小最快的规格source可以填图片路径、文件夹路径也可以直接填0调摄像头saveTrue把预测结果图写到runs/detect/predict目录下。跑通后会在输出图片上看到带类别名和置信度的检测框。这个 CLI 入口值得记牢后面训练、验证、导出一套命令风格完全一致。我自己做 PyQt 界面时也习惯先用这条命令验证模型文件可用再往界面里集成能少踩一半的坑。摄像头实时预览把source改成0并加showTrueyolo detect predict modelyolov8n.pt source0 showTrue按q退出预览。这一步卡顿属于正常现象nano 模型在 CPU 上单帧推理要 100 到 200 毫秒能把窗口缩小一点就缩小一点。如果手里只有 CPU后面训练和部署都建议锁死 nano 或 small 规格不要碰 large 和 xlarge。2.3 从通用检测到门禁目标网络结构图与类别选择预训练模型输出的是 COCO 80 类人、车、猫狗都有门禁系统用不到这么多。这里需要理解 YOLOv8 的输出本质backbone 用 C2f 结构提取特征检测头是 anchor-free 设计输出每个目标的类别、置信度和归一化边界框。网络结构图在网上能查到的版本很多核心记住一点——它对门禁场景不需要改结构只需要换数据集、换类别名。典型门禁组合是「人员检测 安全帽检测」。当检测框进入警戒区域且头部没有安全帽时界面弹出告警并写日志。这种情况下训练类别就是person和helmet推理时再用框之间的几何关系做二次判定。这也是市面项目包最常见的方案。有的项目为了省事用官方权重做人员检测再叠一个自训练的安全帽模型双模型推理慢但数据准备量小。我建议课设选单模型数据量要求低训练和推理链路都短答辩解释起来也顺畅。3. 训练自己的门禁数据集标注、格式转换与损失曲线3.1 YOLO 数据集目录结构与 data.yaml 写法项目包自带完整数据集的话目录结构通常是这样的dataset/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml标注文件是 txt和图片同名每行格式为class x_center y_center width height坐标值是相对图片宽高的归一化小数。data.yaml 是整个训练流程的入口也是最常写错的文件。Windows 上尤其注意path不要写绝对路径直接写dataset这种相对路径train和val再相对于path写path: dataset train: images/train val: images/val names: 0: person 1: helmetnames里类别顺序必须和标注文件第一个数字一致否则训练出来的模型类别对应关系全乱。验证路径和类别配置是否正确可以直接跑一轮训练yolo detect train datadataset/data.yaml modelyolov8n.pt epochs1路径有问题时这里立刻会报Dataset not found或AssertionError不用等到训练跑一半才发现。3.2 用 labelme 标注并转成 YOLO 格式转换脚本和四个边界坑热词里反复出现的「labelme 标注用于 YOLOv8」落到实操上就是「JSON 转 TXT」。labelme 导出的是 JSON 文件里面记录的是多边形顶点、shape_type 和 imagePathYOLO 训练不认这个需要脚本转一遍import json from pathlib import Path def convert_labelme_to_yolo(json_path, out_dir, class_map): with open(json_path, r, encodingutf-8) as f: data json.load(f) img_w, img_h data[imageWidth], 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_min, x_max min(xs), max(xs) y_min, y_max min(ys), max(ys) bw x_max - x_min bh y_max - y_min x_c x_min bw / 2.0 y_c y_min bh / 2.0 lines.append(f{class_map[label]} {x_c/img_w:.6f} {y_c/img_h:.6f} {bw/img_w:.6f} {bh/img_h:.6f}) out_path Path(out_dir) / (Path(json_path).stem .txt) out_path.write_text(\n.join(lines), encodingutf-8)逻辑说明借助imageWidth和imageHeight把像素坐标归一化到 0 到 1这是 YOLO 训练时的标准输入要求。class_map是 label 名称到类别 id 的映射比如{person: 0, helmet: 1}。门禁这类目标直接用多边形外接矩形就够了不需要转成分割掩码。转换时有几个边界坑要留意。第一labelme 的imagePath经常只写文件名图片不一定在 JSON 同级目录转换脚本里路径要自己拼。第二shape_type如果标成circlepoints解析方式和多边形不一样需要单独处理。第三画面里小目标多的时候归一化后宽高会很小训练容易丢建议原图不要低于 640×640。第四标注框要紧贴物体边界把整个桌面框进去会让模型学偏这属于标注质量问题调参数救不回来。3.3 训练脚本与超参数建议yolov8n 起步看损失曲线训练参数比训练本身更值得花时间。从预训练权重继续训练比从零开始收敛快得多所以model参数建议保留预训练文件yolo detect train \ datadataset/data.yaml \ modelyolov8n.pt \ epochs100 \ imgsz640 \ batch16 \ device0 \ patience20参数说明epochs100对课设足够数据量小的时候再多的轮数只会过拟合imgsz640是输入分辨率CPU 训练或内存吃紧可以降到 480batch16受显存限制GTX 1660 Ti 6GB 显存跑 nano 建议 16跑 s 建议 8device0指定 GPUCPU 机器改成devicecpupatience20表示 20 轮 mAP 不再提升就提前停止能省掉很多无效等待。训练开始后runs/detect/train目录下会自动生成results.png里面包含训练损失曲线、验证损失曲线、mAP 曲线这就是你要的「yolov8 损失函数曲线图」。答辩展示时直接贴这张图比命令行日志直观得多。想看每张验证图片的预测效果去同目录下翻val_batch*_pred.jpg通常最后几轮的图最有说服力。3.4 评估模型mAP 怎么读混淆矩阵怎么看训练完不要直接打包先用验证集跑一次评估yolo detect val \ modelruns/detect/train/weights/best.pt \ datadataset/data.yaml输出里会给出mAP50和mAP50-95。门禁场景 mAP50 到 0.85 以上就够用mAP50-95 不用死磕。重点看每类别的 precision 和 recallhelmet 类 recall 太低说明戴安全帽的样本不够或漏标太多回去补数据比调参有效。混淆矩阵在confusion_matrix.png能直观看到「person 误判成 helmet」「背景误识别成人」这两类错误。门禁场景最怕漏报宁可多框一个也不能放掉真实目标所以推理时会建议把置信度阈值从默认 0.25 降到 0.15这在后面的业务代码里以conf0.15传入即可。4. 把模型包进可视化界面PyQt5 门禁控制台的实现4.1 界面骨架预览区、状态栏、日志区三件套可视化界面这块最稳妥的落地是 PyQt5 加 OpenCV。不用 Flask 是因为答辩现场演示容易卡在网络请求上不用 Tkinter 是因为控件太朴素显示视频帧也费劲。PyQt5 的 QLabel 直接显示 QImageQThread 原生支持多线程是最省事的选择。界面分成三块左侧摄像头预览区右侧上方是通行状态、人员统计、当前时间右侧下方是通行记录表格和日志输出。先搭最小窗口import sys from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel class DoorMainWindow(QWidget): def __init__(self): super().__init__() self.setWindowTitle(基于YOLOv8的智能门禁系统) layout QVBoxLayout(self) self.video_label QLabel(等待视频流...) layout.addWidget(self.video_label) self.status_label QLabel(系统就绪) layout.addWidget(self.status_label) if __name__ __main__: app QApplication(sys.argv) win DoorMainWindow() win.show() sys.exit(app.exec_())逻辑说明QLabel负责显示视频帧QVBoxLayout负责垂直排布控件。这段跑通之后再逐步加按钮、表格、日志框一上来堆满控件信号槽和布局会缠成一团。4.2 用 QThread 跑推理不让界面卡死的核心YOLOv8 推理是耗时操作放界面主线程里会导致视频一帧一帧跳、按钮点不动。正确做法是把「摄像头读取 YOLOv8 推理 画框」全部放进 QThread用信号把处理好的帧发回主线程import cv2 from ultralytics import YOLO from PyQt5.QtCore import QThread, pyqtSignal class DetectThread(QThread): frame_signal pyqtSignal(object) def __init__(self, model_path, camera_index0): super().__init__() self.model YOLO(model_path) self.cap cv2.VideoCapture(camera_index) self.running True def run(self): while self.running: ret, frame self.cap.read() if not ret: break results self.model.predict(frame, conf0.25, imgsz640, verboseFalse) for r in results: for box in r.boxes: x1, y1, x2, y2 map(int, box.xyxy[0]) conf float(box.conf[0]) cls int(box.cls[0]) label f{self.model.names[cls]} {conf:.2f} cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, label, (x1, y1 - 8), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2) self.frame_signal.emit(frame) self.cap.release() def stop(self): self.running False self.wait()参数说明conf0.25是置信度阈值检测结果低于这个值会被过滤verboseFalse关闭推理时的终端刷屏这个参数很多人漏掉结果 PyQt 界面被日志刷得卡顿。box.xyxy是边界框像素坐标box.conf是置信度box.cls是类别 id。主线程收到frame_signal信号后需要先把 OpenCV 的 BGR 转成 RGB 再显示忘记转的话画面颜色会整体偏蓝属于常见翻车现场。4.3 业务联动区域判定、通行记录、报警只画框不算门禁系统答辩老师一问「门禁体现哪」就卡壳。最基本的联动有三件事判断检测框中心是否进入警戒区域、记录通行时间、发现未戴安全帽时报警。警戒区域用一组矩形坐标定义比如摄像头画面里门口区域是[(200, 300), (600, 700)]检测框中心点落在里面就触发计数def in_danger_zone(center_x, center_y, zone): x1, y1, x2, y2 zone return x1 center_x x2 and y1 center_y y2逻辑很直白zone是预标定的区域检测框中心落进去就触发事件。这段代码放在 DetectThread 的run循环里不放界面线程否则频繁调用会拖慢界面。通行记录用 CSV 比 SQLite 更合适课设答辩现场直接用 Excel 打开看记录不用解释数据库连接问题。每次触发事件就往 CSV 追加一行import csv from datetime import datetime def write_record(csv_path, event): with open(csv_path, a, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([datetime.now().strftime(%Y-%m-%d %H:%M:%S), event])event传entry或alarm。CSV 路径用相对路径项目包解压到哪就写到哪不用配绝对路径。报警联动在检测线程里发现「无安全帽且框中心在警戒区」时发一个布尔信号给主线程主线程弹 QMessageBox 或播放系统提示音不需要真接门锁硬件。5. 部署与避坑从训练机迁到课设演示机的 5 个关键问题5.1 模型导出与离线部署ONNX、TensorRT 与 RK3588 注意事项训练好的best.pt直接给别人用有隐性风险对方机器的 ultralytics 版本比你的旧就可能加载失败。「简单部署即可运行」的关键不是依赖训练环境而是导出一个通用格式最常见的是 ONNXyolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640导出后生成best.onnx部署机上只需要pip install onnxruntime opencv-python不用装 PyTorch 和 ultralytics启动快也没有「换台机器就报错」的版本问题。参数说明format支持onnx、engine、openvino、tflite等imgsz必须和训练时一致否则输入张量维度对不上。如果后续要上瑞芯微 RK3588 这类嵌入式板卡标准流程是先把 pt 导出成 ONNX再用 rknn-toolkit2 转成 RKNN 格式部署到 NPU。板端 NPU 对算子支持有限导出时建议把opset降到 12 左右兼容性更好。5.2 从零到一跑通项目的 5 个高频坑这里集中列一下这类项目最常见的几个问题方便直接对照排查。第一训练报CUDA out of memory。现象是训练一开始就爆显存。原因一般是 batch 开太大或输入图太大。解决办法batch从 16 降到 8 或 4imgsz从 640 降到 480再加ampTrue开混合精度低显存显卡上效果很明显。第二摄像头打开黑屏或读不到流。现象是窗口弹出来了但画面全黑。原因多数不是代码问题而是cv2.VideoCapture(0)的索引被占用或者 USB 摄像头供电不足。解决办法先cap.isOpened()判断打不开就试索引 1、2再不行换 USB 口。这种情况经常让人误以为模型挂了其实模型根本没参与。第三训练时 loss 掉得快但 mAP 上不去。现象是results.png里 mAP50 一直徘徊在低位。原因通常是数据集标注错位、图片和标签不对应或者类别顺序和 names 不一致。解决办法回查 label 文件和 data.yaml特别注意 labels 目录里有没有空 txt空文件会让该样本没有正样本参与训练。第四PyQt 窗口关闭后摄像头还亮着。现象是窗口关了、进程退不干净、摄像头指示灯还在闪。原因是 QThread 的 stop 逻辑没有在窗口关闭事件里调用。解决办法在主窗口覆写closeEvent先thread.stop()再app.quit()。第五CPU 上推理时界面卡死。现象是视频一帧一帧跳鼠标也没响应。原因除了 CPU 推理本来就慢还可能是 OpenCV 的imshow和 PyQt 显示同时进行两个窗口抢占资源。解决办法把 OpenCV 预览窗口全部去掉只保留 QLabel 显示并把cv2.waitKey从循环里拿掉。5.3 版本匹配问题模型文件与 API 之间的隐性坑ultralytics 版本更新很快不同版本的YOLO()类接口参数名经常变。比如某个版本把conf改成conf_thres照抄旧教程会报got an unexpected keyword argument。解决办法是先跑yolo version确认版本再去对应版本的官方 API 查参数名。模型文件也一样yolov8n.pt建议在当前版本环境下重新下载跨版本用权重大多能加载但偶尔会遇到unable to load的玄学错误重新下载通常能解决。还有一类特别隐蔽的问题项目包里的模型训练在 COCO 80 类上但 UI 代码里写死了安全帽类别推理结果一定对不上。检查方式很直接模型加载后打印model.names看类别 id 和显示名是否匹配。花 30 秒做这个检查能省下后面三个小时的调试时间。6. 演示现场最稳的一招按时序导出 CSV 和回放视频答辩演示最怕两件事现场光线不好导致摄像头识别效果差或者系统跑完没有可展示的结果。我现在的习惯是在门禁系统里加一个「记录导出」按钮把一次演示过程中所有检测事件按时间顺序归档同时把带框的预测画面录成视频。现场效果再差也能从历史记录里找回能讲的东西。实现上在 DetectThread 里加一个record开关打开时用 OpenCV 的VideoWriter把画框后的帧写进result.aviwriter cv2.VideoWriter( result.avi, cv2.VideoWriter_fourcc(*XVID), 20.0, (frame_width, frame_height), )参数说明fourcc选XVID是为了兼容性MP4 的 H264 编码在部分机器上没有编码器反而写不出文件。帧率 20.0 要和摄像头实际帧率匹配写高了录像会加速写低了会慢放。写入前用writer.isOpened()确认文件创建成功。事件导出放在业务判定那一层不在画框那一层。检测到进入警戒区、检测到未戴安全帽人员、检测到离开这三个节点各写一行 CSV字段按「时间、事件类型、目标类别、置信度」四列。演示时把 CSV 打开按时间线讲一遍比口头说「识别率还行」有说服力得多。我每次做演示前还会做一件事先用固定图片或录好的短视频代替实时摄像头跑一遍保证核心链路 100% 不死现场再接 USB 摄像头做增强展示。这个小习惯帮我躲过了好几次现场黑屏的尴尬希望帮到你。本文还有配套的精品资源点击获取