基于YOLOv8的自动售货机缺货检测：从数据标注到PyQt5部署全流程实战

简介：本资源是一套面向计算机、人工智能、自动化等专业在校学生的毕业设计级项目，聚焦校园自动售货机货道缺货智能检测场景，基于YOLOv8目标检测模型实现端到端的缺货识别与可视化分析。资源包共8个文件，含3个核心Python脚本（训练、推理、可视化界面）、3个PyTorch模型文件（含预训练与最佳权重）、2个说明文档（README与项目说明），总大小15.91MB，结构清晰、模块解耦，便于快速部署与二次开发。项目已通过完整测试，支持生成精确率-召回率曲线、混淆矩阵、F1分数变化图、验证集预测结果及标签分布统计等关键评估图表，配套详细部署教程与运行指引，开箱即用。适合毕设、课程设计或大作业实践，亦可作为深度学习与计算机视觉入门者的实战范例，兼顾工程完整性与教学友好性。

1. 项目概述与核心价值

最近在整理一些过往的课程设计和项目实践资料，翻到了这个基于YOLOv8的校园自动售货机货道缺货检测项目。这个项目最初是为了解决一个非常实际的问题：校园里那些自动售货机，经常出现某个货道商品售罄但系统未能及时补货的情况，导致学生白跑一趟。当时就想，能不能用计算机视觉技术，让机器自己“看”到哪个货道空了，然后自动通知管理员呢？

这个项目就是围绕这个想法展开的。它不是一个简单的模型训练脚本，而是一个包含了从数据准备、模型训练、到最终部署成可视化应用的全流程解决方案。我把它打包整理了出来，里面包含了完整的源代码、一个用PyQt5写的图形化操作界面、我精心标注和处理过的数据集，以及一份详细的部署教程。对于正在做计算机视觉相关毕设、课程设计，或者想快速上手YOLOv8实战应用的朋友来说，这个项目应该能提供一个非常清晰的参考路径。它的核心价值在于“开箱即用”，你不需要从零开始搜集数据、标注图片、搭建环境，按照教程简单几步就能跑起来，看到实际效果，然后可以基于此进行二次开发或深入研究。

2. 项目整体设计与思路拆解

2.1 问题定义与技术选型

校园自动售货机的缺货检测，本质上是一个目标检测问题，但有其特殊性。我们需要检测的不是常规的“人”、“车”，而是“货道”以及“货道内商品的有无”。一个货道可能包含多层商品，我们需要判断每一层是否还有商品。传统的传感器方案（如红外、重量）成本高且部署复杂，而基于摄像头+AI的方案则更具灵活性和可扩展性。

为什么选择YOLOv8？在项目启动时，我对比了当时主流的几个目标检测框架。YOLOv8由Ultralytics发布，它在YOLOv5的基础上做了大量优化，不仅精度（mAP）有提升，更重要的是在易用性上达到了新的高度。其命令行接口（CLI）和Python API设计得非常友好，训练、验证、预测、导出模型到不同格式（如ONNX, TensorRT）几乎都是一行命令的事。这对于需要快速原型验证和部署的校园项目来说，极大地降低了技术门槛。此外，YOLOv8社区活跃，遇到问题容易找到解决方案，其模型从n（纳米）到x（超大）有多种尺寸，可以根据部署设备的算力灵活选择。

2.2 系统架构与工作流程

整个项目的架构可以清晰地分为离线训练和在线推理两个阶段。

离线训练阶段：

1. 数据采集与标注：使用手机或固定摄像头，从不同角度、不同光照条件下拍摄售货机货道的图片。重点是覆盖商品满、半空、全空等多种状态。
2. 数据预处理与增强：对采集的图片进行尺寸统一、归一化，并应用数据增强技术（如随机翻转、亮度对比度调整、马赛克增强等），以提升模型的泛化能力，模拟不同时间、不同售货机的场景。
3. 模型训练与验证：使用YOLOv8在准备好的数据集上进行训练，划分训练集、验证集，监控损失函数和评价指标（如mAP@0.5）的变化，防止过拟合，选择最优的模型权重。

在线推理阶段：

1. 模型部署：将训练好的最优模型（通常是.pt文件）部署到推理环境中。本项目支持在本地电脑（Windows/Linux/macOS）上通过Python脚本或图形界面运行。
2. 图像输入：通过图形界面选择单张图片、批量图片或直接调用摄像头进行实时视频流捕获。
3. 推理与后处理：YOLOv8模型对输入的图像进行推理，输出每个检测到的目标（即“有商品”的货道格子）的边界框坐标、置信度和类别。后处理过程包括非极大值抑制（NMS）过滤重叠框。
4. 结果可视化与输出：在原始图像上绘制检测框，并将缺货的货道位置信息（如“第三排第二列”）输出到界面或日志文件中。图形界面会直观地高亮显示缺货区域。

注意：这里的“货道”在数据标注时，我们通常标注的是“有商品”的状态。因此，模型检测到目标，意味着该货道有货；未检测到目标，则推断该货道缺货。这是一种“反向检测”的逻辑，在实际应用中更稳定，因为“有商品”的状态特征相对固定，而“空”的状态（只剩下背景）特征多变。

3. 核心细节解析与实操要点

3.1 数据集构建的“坑”与技巧

数据集是模型效果的基石。这个项目附带的完整数据集是我花了大量时间处理的，这里分享一些构建过程中的关键点。

1. 标注规范的制定：

• 类别定义：我们只定义一个类别，例如goods（商品）。标注对象是每一个清晰可见的、独立的商品包装。如果商品堆叠，只标注最前面完整的一个。
• 边界框精度：框要紧贴商品边缘，但不必过于精确到像素级，适当留一点背景有助于模型学习上下文。
• 遮挡与模糊处理：对于部分被遮挡或拍摄模糊的商品，如果仍能大致判断其存在，则进行标注；如果完全无法辨认，则不标。这教会模型在非理想条件下进行推断。

2. 数据增强策略： YOLOv8训练时内置了丰富的数据增强，但我们也可以在预处理阶段加入自己的策略。针对售货机场景，我特别注重：

• 亮度与对比度变化：模拟售货机内部灯光昏暗、外部阳光直射等不同光照条件。
• 随机裁剪与缩放：模拟摄像头安装位置略有偏差的情况。
• 模拟运动模糊：因为有时摄像头可能会因机器震动或行人经过产生轻微模糊。

3. 数据平衡： 确保数据集中“有货”的样本覆盖所有货道位置，并且包含不同品牌的商品（颜色、形状、大小各异）。如果数据集中某种商品过多，模型可能会对其过拟合，而对其他商品检测效果差。

实操心得：标注工具我推荐使用labelImg或更先进的CVAT。在标注时，为每张图片建立一个对应的txt文件（YOLO格式），内容为[class_id] [x_center] [y_center] [width] [height]，坐标是归一化后的值。这个过程很枯燥，但至关重要。项目提供的数据集已经完成了这部分最耗时的工作。

3.2 YOLOv8模型训练的关键参数调优

拿到数据集后，训练并非一键无脑运行。理解几个关键参数，能让你用更少的资源获得更好的模型。

1. 模型尺寸选择 (model)：

• yolov8n.pt(纳米)：参数量最小，速度最快，适合嵌入式设备或实时性要求极高的场景。在算力有限的设备上作为首选。
• yolov8s.pt(小)：速度和精度的良好平衡，是大多数桌面级应用的首选，也是本项目推荐的基础模型。
• yolov8m.pt(中)/yolov8l.pt(大)/yolov8x.pt(超大)：精度依次提高，但速度变慢，模型文件变大。除非你对精度有极致要求，且拥有强大的GPU，否则不建议在初期使用。

2. 图像尺寸 (imgsz)： 默认是640。如果你的商品细节非常小（比如货道很远），可以尝试增大到832甚至1024，但这会显著增加显存消耗和训练时间。通常640对于售货机场景足够。

3. 训练轮数 (epochs)和批次大小 (batch)：

• epochs：一般从100轮开始。观察验证集mAP曲线，当曲线平稳或开始波动下降（可能过拟合）时，就可以提前停止。项目提供的预训练模型大约训练了150轮。
• batch：在显存允许的前提下，越大越好，如batch=16。大的批次能使梯度更新更稳定。如果出现CUDA out of memory错误，就减小batch或imgsz。

4. 学习率 (lr0)： 这是最重要的超参数之一。YOLOv8有自动调整学习率的能力，默认设置通常效果不错。但如果你发现训练初期损失下降很慢，或者波动巨大，可以尝试微调。一般不建议初学者大幅修改。

训练命令示例：

yolo task=detect mode=train model=yolov8s.pt data=your_data.yaml epochs=150 imgsz=640 batch=16 workers=4

提示：workers参数用于数据加载的并行进程数，在Windows下有时设为0更稳定，在Linux下可以适当调高以加速数据读取。

3.3 可视化界面的设计与交互逻辑

为了让项目更易用，我使用PyQt5开发了一个图形用户界面。设计原则是：功能集中、操作直观、结果清晰。

核心功能模块：

1. 模型加载区：允许用户选择自己训练的.pt模型文件，或者使用项目提供的预训练模型。
2. 输入源选择区：
   • 图片检测：选择单张或多张图片进行批量检测。
   • 视频检测：选择视频文件。
   • 实时摄像头：调用电脑自带或外接USB摄像头进行实时流检测。
3. 参数调整区（高级选项）：
   • 置信度阈值：滑块控制，过滤掉低置信度的检测框。默认0.25，调高可减少误检，但可能漏检；调低则相反。
   • IOU阈值：用于非极大值抑制（NMS），控制重叠框的合并程度。
4. 结果显示区：
   • 主画面：实时显示原始画面和绘制了检测框的结果画面。检测框用绿色表示有货，并在旁边显示置信度。
   • 信息面板：显示检测统计信息，如检测到的商品总数、每个货道的状态（通过坐标映射判断）、推理耗时（FPS）等。
   • 日志窗口：记录操作日志和检测结果，方便回溯。

交互逻辑： 界面通过多线程实现，将耗时的模型推理放在子线程中，避免阻塞UI主线程导致界面卡死。当用户点击“开始检测”按钮后，界面会根据选择的输入源，循环读取帧，送入模型推理，再将结果返回给主线程更新UI。实时摄像头模式下，可以流畅地达到20-30 FPS（取决于模型大小和硬件）。

实操心得：PyQt5的界面设计可以用Qt Designer拖拽完成，非常高效。关键难点在于线程间通信（信号与槽机制）和图像数据的传递（需要将OpenCV的BGR格式转换为RGB，并转换为Qt可显示的QImage格式）。项目源码中这部分已经封装好，你可以直接复用或学习其实现方式。

4. 完整部署与运行教程

4.1 基础环境搭建（一步一坑指南）

部署的第一步是准备好Python环境。强烈建议使用Anaconda来管理环境，避免包冲突。

步骤1：创建并激活虚拟环境

conda create -n yolov8_vending python=3.8 -y conda activate yolov8_vending

选择Python 3.8是因为它在深度学习领域的兼容性最广。

步骤2：安装PyTorch这是最大的一个坑，必须根据你的CUDA版本（如果有NVIDIA GPU）来安装。

• 查看CUDA版本：在命令行输入nvidia-smi，右上角显示的就是CUDA版本（如12.4）。
• 访问PyTorch官网：获取对应的安装命令。例如，对于CUDA 12.1：

  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

• 仅CPU安装：如果你的电脑没有NVIDIA GPU，则安装CPU版本：

  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

步骤3：安装Ultralytics YOLOv8

pip install ultralytics

这个命令会安装YOLOv8核心库以及一些依赖。

步骤4：安装图形界面和其他依赖进入项目解压后的目录，通常有一个requirements.txt文件。

pip install -r requirements.txt

这个文件里主要包含了PyQt5（界面）、opencv-python（图像处理）、numpy等。

避坑指南：

• 错误：ImportError: DLL load failed：通常是PyTorch版本与CUDA或不匹配，或者VC++运行库缺失。确保安装了对应CUDA版本的PyTorch，并安装Microsoft Visual C++ Redistributable。
• 错误：PyQt5相关错误：可以尝试用pip install PyQt5 PyQt5-tools重新安装。在某些系统上，可能需要先安装一些系统依赖，如Ubuntu下的sudo apt-get install qt5-default。
• 速度慢：pip安装时可以使用国内镜像源，如-i https://pypi.tuna.tsinghua.edu.cn/simple。

4.2 项目结构与快速启动

解压项目包后，你会看到类似如下的目录结构：

yolov8_vending_detection/ ├── data/ │ ├── images/ # 存放训练和测试图片 │ ├── labels/ # 存放对应的YOLO格式标注文件 │ └── data.yaml # 数据集配置文件，定义了路径和类别 ├── models/ # 存放训练好的模型权重文件 (.pt) │ └── best.pt # 项目提供的预训练模型 ├── runs/ # 训练过程中产生的日志、权重等（训练后生成） ├── src/ # 源代码目录 │ ├── ui_main.py # PyQt5主界面程序 │ ├── detector.py # 检测器核心类，封装YOLOv8推理 │ └── utils.py # 工具函数（如文件处理、绘图） ├── requirements.txt # Python依赖包列表 ├── train.py # 模型训练脚本 ├── detect.py # 命令行检测脚本 └── README.md # 项目说明文档

快速启动图形界面：

1. 确保已激活虚拟环境并安装所有依赖。
2. 在项目根目录下，运行：

   python src/ui_main.py

3. 图形界面弹出后，点击“加载模型”，选择models/best.pt。
4. 在“输入源”区域，可以选择“图片”、“视频”或“摄像头”。
5. 点击“开始检测”，即可看到实时效果。

使用命令行进行快速检测： 如果你更喜欢命令行，或者想在服务器上运行，可以使用detect.py：

python detect.py --weights models/best.pt --source data/images/test.jpg --conf 0.5

• --weights: 指定模型权重路径。
• --source: 指定输入源，可以是图片、视频文件、文件夹路径或0（代表摄像头）。
• --conf: 设置置信度阈值。

4.3 使用自己的数据进行训练与迭代

如果你想用自己的售货机图片来训练模型，或者想增加新的商品类别，可以遵循以下流程：

步骤1：准备数据将自己的图片放入data/images/train/和data/images/val/文件夹（分别用于训练和验证）。使用标注工具（如labelImg）进行标注，将生成的.txt标注文件放入data/labels/train/和data/labels/val/，确保文件名与图片名一一对应。

步骤2：修改数据集配置文件编辑data/data.yaml文件：

path: ./data # 数据集根目录 train: images/train # 训练集图片相对路径 val: images/val # 验证集图片相对路径 # 类别数量和名称 nc: 1 # 类别数，如果只检测‘有货’状态，就是1 names: ['goods'] # 类别名称列表

步骤3：开始训练运行训练脚本：

python train.py --data data/data.yaml --epochs 100 --imgsz 640 --batch 16 --weights yolov8s.pt

训练过程会在runs/detect/train/目录下生成一系列结果，包括损失曲线、精度曲线、模型权重等。你可以通过tensorboard --logdir runs/detect/train来可视化监控训练过程。

步骤4：评估与测试训练完成后，最好的模型会保存在runs/detect/train/weights/best.pt。使用这个模型进行测试：

python detect.py --weights runs/detect/train/weights/best.pt --source data/images/val --save-txt

--save-txt参数会将检测结果也保存为YOLO格式的txt文件，方便与真实标签进行对比分析。

5. 常见问题与排查技巧实录

在实际部署和运行过程中，你可能会遇到以下问题。这里我把自己踩过的坑和解决方法记录下来。

5.1 环境与依赖问题

问题1：运行ui_main.py时提示No module named ‘PyQt5.something‘

• 排查：这通常是PyQt5安装不完整或环境有多个Python解释器导致。
• 解决：
  1. 在当前激活的虚拟环境中，确认Python路径：which python或where python。
  2. 彻底重装PyQt5：pip uninstall PyQt5 PyQt5-tools -y，然后pip install PyQt5 PyQt5-tools。
  3. 如果使用IDE（如PyCharm），检查项目解释器是否设置为正确的虚拟环境。

问题2：导入ultralytics时报警告或错误，提及PIL或opencv

• 排查：某些依赖的版本可能存在冲突。
• 解决：
  1. 确保按照requirements.txt安装。如果文件内没有指定具体版本，可以尝试安装较新的兼容版本。
  2. 对于PIL（Pillow）问题，可以pip install --upgrade Pillow。
  3. 对于OpenCV，有时需要pip install opencv-python-headless以避免一些GUI冲突。

5.2 模型推理与性能问题

问题3：检测速度很慢（FPS很低）

• 排查：首先确认是否在使用GPU进行推理。在代码中，加载模型时可以指定设备。
• 解决：
  1. 在detector.py或推理命令中，确保模型加载到CUDA上。在YOLOv8中，通常会自动使用GPU。你可以通过打印torch.cuda.is_available()来确认。
  2. 如果确实在使用GPU但依然慢，可能是模型太大。尝试换用更小的模型，如yolov8n.pt。
  3. 降低推理图片尺寸imgsz，如从640降到320，速度会成倍提升，但精度会有所损失。
  4. 检查是否有其他程序大量占用GPU资源。

问题4：检测结果不准，误检或漏检严重

• 排查：这是模型本身的问题，根源通常在数据或训练过程。
• 解决：
  1. 调整置信度阈值：在界面中调高conf值可以减少误检（将一些不可信的框过滤掉），调低可以减少漏检（但会增加误检）。这是一个需要权衡的旋钮。
  2. 检查训练数据：回顾你的训练数据，是否缺少某些场景（如强光、暗光、侧面角度）的样本？是否某些类别的样本数量严重不足？补充数据是最根本的解决方法。
  3. 重新训练或微调：如果提供了预训练模型但不符合你的场景，最好的方法是在你的新数据上对预训练模型进行微调（迁移学习），而不是从头训练。命令类似：python train.py --data your_data.yaml --weights yolov8s.pt --epochs 50。这会比从头训练快很多，效果也更好。

5.3 界面与功能问题

问题5：摄像头打不开，或打开后画面卡住

• 排查：摄像头索引错误或被其他程序占用。
• 解决：
  1. 通常，内置摄像头索引是0，外接USB摄像头可能是1或2。在界面中尝试切换不同的摄像头索引。
  2. 关闭其他可能占用摄像头的软件（如微信、Zoom、其他监控软件）。
  3. 在某些操作系统上，可能需要授予Python程序访问摄像头的权限。

问题6：检测结果框的位置偏移很大

• 排查：模型训练时使用的图片尺寸 (imgsz) 与推理时输入的图片尺寸不一致，且预处理或后处理中的坐标转换逻辑有误。
• 解决：
  1. 确保训练和推理时使用的imgsz参数一致。
  2. 在图形界面中，我写的代码已经处理了缩放和坐标映射。如果你自己修改了推理代码，请检查将YOLO输出的归一化坐标[x_center, y_center, width, height]转换为原始图像像素坐标的逻辑是否正确。公式通常是：x_pixel = x_center * img_width,y_pixel = y_center * img_height，框的宽高同理。

问题7：如何将模型部署到没有界面的服务器或嵌入式设备？

• 解决：你需要剥离图形界面部分，只使用核心的检测逻辑 (detector.py)。
  1. 将模型推理部分封装成一个函数或类，接收图像数组，返回检测结果。
  2. 在服务器上，可以通过Flask或FastAPI搭建一个简单的HTTP API服务，接收客户端上传的图片，返回JSON格式的检测结果（如缺货货道列表）。
  3. 在嵌入式设备（如Jetson Nano、树莓派+AI加速棒）上，首先需要将PyTorch模型转换为该设备优化的格式（如ONNX、TensorRT、NCNN等）。YOLOv8提供了model.export(format='onnx')或model.export(format='engine')的方法，可以很方便地导出。然后使用对应的推理引擎（如ONNX Runtime, TensorRT）加载模型进行推理，这部分代码需要重写。

这个项目就像一个功能齐全的“样板间”，你不仅可以直接入住（部署使用），更能清楚地看到每一面墙是怎么砌的，每一根线是怎么走的（源码和设计思路）。无论是为了完成一个具体的课程设计，还是想深入理解目标检测项目的全流程，希望它都能给你带来实实在在的帮助。在实际捣鼓的过程中，最深的体会就是：数据质量决定模型上限，而清晰的代码结构和文档决定项目的可维护性和你的开发体验。如果在运行中遇到任何问题，不妨多看看控制台输出的错误信息，那往往是解决问题的第一把钥匙。

本文还有配套的精品资源，点击获取