简介：基于YOLOv8的果树成熟度检测系统是一个可直接运行的毕业设计或课程设计工程包，包含源码、完整数据集、可视化界面和部署教程。项目代码经过实际测试，内置训练、验证和检测闭环流程，启动可视化页面即可操作，并自动生成混淆矩阵、F1分数曲线、精确率-召回率曲线、验证集预测结果与标签分布图等专业评估图表，为毕设答辩提供有力支撑。包内共97个文件，以70个Python源码为主，另有12个pyc编译文件、4个pt模型权重、5个XML配置、2个TXT说明、1个示例mp4视频及工程配置文件等；压缩包整体仅24.21MB，部署运行十分轻量。目前已有37人学习，适合计算机、人工智能等专业学生快速完成课设或毕设，也适合深度学习初学者参照练习；下载后按README.txt指引即可运行，代码结构清晰，便于修改或扩展至其他检测任务。
1. YOLOv8 遇上果园：成熟度检测为什么不能只靠“颜色判断”
果农最累的活之一，是每天在果园里走来走去，抬头看树上的果子熟了没有。颜色判断看起来简单——红了就是熟，绿了就是没熟——但光照一变、角度一换，人眼都会打架，更别说写死几条颜色阈值的程序了。把 YOLOv8 用在果树成熟度检测上，本质是把“熟了没有”这个问题，从颜色阈值判断换成了“目标检测+成熟度分类”：框出每个果子，同时给出生理成熟和采摘适期两个维度。这套系统适合两类人：一类是拿它做毕设或课设的学生，另有一类是果园管理者。前者需要快速跑通一整套流程，后者更关心误检率和单张推理耗时。这篇文章就按我落地的习惯，把环境搭建、数据标注、模型训练、界面展示和踩坑记录完整拆开讲。
2. 把它拆成能运行的方案：从 YOLOv8 选型到 CPU 也能走的部署环境
2.1 成熟度检测的任务边界：检测框为什么比分类器更合适
拿到“检测系统”这个需求，第一件事是分清你到底要检测还是要分类。很多人第一时间想的是做个分类器，给一张图打上“未熟/已熟/过熟”的标签。这在单果照片上可行，但果园实景里一棵树上有十几二十个果子，成熟度参差不齐，切片交给分类器会让程序崩溃。正确的做法是用带检测头的网络同时输出框和类别，让“绿色的果子”和“红色的果子”各自被框出来。YOLOv8 的 head 部分解耦了分类和回归分支，框的定位质量和类别判断互不干扰，对果实粘连、前后遮挡这种场景，比老一代 anchor-based 模型更稳。
成熟度等级划分也要设计，而不是简单写“green、red”。对于柑橘类，我把等级设为 unmature（青果）、mature（转色期，底色开始泛黄）、ripe（完熟）三档；对苹果来说，成熟度还分背景色和面色，这时候要把“底色”写进标注规范，否则标图的人会在“这个到底算不算熟”上反复扯皮。先定好这些，后面训练出来的模型才知道你要什么。
2.2 无 GPU 的 ubuntu20.04 笔记本怎么搭 YOLOv8 环境
很多人的课设机是没有 N 卡的 Windows 笔记本，但部署教程往往默认你有一块 CUDA 显卡。没有 GPU 不等于不能跑 YOLOv8，只是推理速度有上限。我一般建议用 ubuntu20.04 或 WSL2 里的 ubuntu20.04 建虚拟环境，CPU 版本的 PyTorch 就能跑通整个流程。先确认 Python 版本，3.10 以下比较稳妥。
# 建议用 conda 建独立环境，避免把系统 Python 弄乱 conda create -n yolo-fruit python=3.9 -y conda activate yolo-fruit # CPU 版 torch：注意要装 cpu 版本，不能图省事直接 pip install torch pip install torch==2.1.2+cpu torchvision==0.16.2+cpu -f https://download.pytorch.org/whl/torch_stable.html # 安装 ultralytics，会自动带上 opencv-python、numpy 等依赖 pip install ultralytics==8.1.0 pip install labelme==5.4.1 # 标注工具后面用这里有个细节必须说明：torch和torchvision的版本要匹配，否则 import 时直接报AssertionError。-f参数指定的是 PyTorch 官方 CPU wheel 索引页，Windows 下的 pip 也能识别。装完后用一条命令验证。
python -c "import torch, torchvision, ultralytics; print(torch.__version__, ultralytics.__version__)"能打印出版本号就说明环境通了。这一步失败通常两个原因：一是 conda 环境没激活，二是 pip 缓存了旧的 CPU 包。我把pip缓存清掉重来一次，基本都能过。
2.3 引入权重和推理验证：跑通最小闭环的命令要留底
环境刚建好时不要急着训练，先用官方预训练权重跑一次推理，验证“安装没装坏”。这一步也叫冒烟测试，能让后续所有问题都分隔开：环境问题、代码问题、数据问题。我习惯拿一张含果树的实拍图测试。
# 下载预训练权重并直接推理，第一次会自动下载 yolov8n.pt yolo detect predict model=yolov8n.pt source=./test_fruit.jpg save=True # 查看输出目录里的标注图 ls runs/detect/predict/yolov8n是 nano 版本，参数量最小，CPU 上单张 640x640 推理约 2-4 秒，适合做功能验证。等你的数据训练完，再换上自己训出的权重。这个最小闭环留一个命令在笔记里，之后每次换机器重新部署都先跑它，能省下大量排查时间。
3. 准备完整数据集：从 LabelMe 标注到 YOLO 格式的转换路径
3.1 成熟度等级怎么定义才不吵架
经过前两步，环境通了，接下来面对的最大工程量是数据。所谓“完整数据集”不单单指图片数量，而是标注文件、类别文件、划分脚本、yaml 配置四件套齐全。我见过太多中途翻车的案例，都是因为 label 文件格式不对，训练时报No labels found。先定等级，我这里以最常见的苹果为例，分为三个成熟阶段：
- unripe：背景色为深绿至浅绿，果面未出现红色面积；
- ripening：底色转为黄绿，果面红色面积小于 50%，这是采摘适期的前哨；
- ripe：果面红色面积超过 50%，底色偏黄，达到商品采收标准。
定好规范后，在项目目录里建好数据集骨架，后面几千张图就不会乱。
datasets/fruit/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── labels/ │ ├── train/ │ ├── val/ │ └── test/ └── fruit.yaml3.2 LabelMe 标注完的 json 怎么转成 YOLO 的 txt
LabelMe 是毕设圈最常用的标注工具，导出的是 json 文件。但 YOLOv8 训练需要的是每个图片同名、每行一个目标的 txt 文件，格式为class_id x_center y_center width height，坐标全部归一化到 0 到 1 之间。转换脚本我每次都自己写，不放心里面那些“一键转换工具”，因为边界情况只有自己心里清楚。
import json import os def convert_labelme_json_to_yolo(json_path, out_dir, classes_map): with open(json_path, "r", encoding="utf-8") as f: data = json.load(f) image_w = data["imageWidth"] image_h = data["imageHeight"] txt_name = os.path.splitext(os.path.basename(json_path))[0] + ".txt" out_path = os.path.join(out_dir, txt_name) lines = [] for shape in data["shapes"]: label = shape["label"] if label not in classes_map: print(f"警告: 未知类别 {label}，跳过，标注文件 {json_path}") continue points = shape["points"] # polygon 顶点列表 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) # 归一化到 0~1 x_center = (x_min + x_max) / 2.0 / image_w y_center = (y_min + y_max) / 2.0 / image_h box_w = (x_max - x_min) / image_w box_h = (y_max - y_min) / image_h # 过滤过小的框：可能是误标或边界噪声 if box_w < 0.005 or box_h < 0.005: continue lines.append(f"{classes_map[label]} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}") with open(out_path, "w", encoding="utf-8") as f: f.write("\n".join(lines))上面的循环逻辑里，两个点最容易踩坑。第一，LabelMe 的框坐标是绝对像素整数，必须除以宽高归一化；第二，min/max求边界时，遇到正方形框没问题，但遇到多边形手工圈选，点的顺序不一定是左上到右下，所以不能只取第一个和第三个点。加一个最小尺寸过滤，是为了防止误点产生面积过小的假正样本干扰训练。
3.3 数据增强与类别不均衡的处理
数据准备阶段的第二个大坑是类别不均衡。果园真实场景里，“未熟”果数量往往远多于“完熟”果，完熟果可能只占 5%。YOLOv8 自带hsv色域增强、随机翻转和缩放，但这些不够解决样本不均衡。我一般会在标注完成后统计各类别的目标数量：
# 统计 train 标签里每类 bbox 出现的次数 awk '{print $1}' labels/train/*.txt | sort | uniq -c如果发现某一类的框数量不足另一类的三成，优先补标数据，而不是依赖增强。对成熟度检测而言，补标的重点不是加多张照片，而是增加“不同光照方向下同一颗果子”的照片，因为背光面的红色表现完全不一样。补标不够时再考虑使用augment.py做离线增强：对完熟果图片复制三份，分别做亮度下调、对比度增强和随机遮挡，让模型见过更多“难例”。
还要留出验证集，不要跟训练集混用。我习惯按 8:1:1 划分 train/val/test，划分时按“果树个体”而不是按“单张图片”划分，避免同一棵树上的照片同时出现在训练集和验证集里，导致验证指标虚高，这一点越早做越省钱。
3.4 训练脚本参数：lr、batch 和 imgsz 怎么定
训练阶段第一个要改的文件是fruit.yaml，它的作用是告诉训练器去哪里读数据、有几个类别和类别名。我把路径写成绝对路径，省得相对路径在不同 shell 下解析出错。
# fruit.yaml path: /home/user/datasets/fruit train: images/train val: images/val test: images/test names: 0: unripe 1: ripening 2: ripe然后启动训练。CPU 上训练会非常慢，但毕设跑个千张图的小数据集也能在十小时内完成；如果有 GPU，把device=0打开。
yolo detect train \ model=yolov8n.pt \ data=fruit.yaml \ epochs=100 \ imgsz=640 \ batch=16 \ lr0=0.01 \ device=cpu \ project=./runs/fruit \ name=exp01几个参数我的经验值：batch在 CPU 上设 16 极容易内存溢出，降到 8 比较稳；imgsz不要上来就设 1280，检测精度提升有限，训练时间翻三倍，先用 640 验证流程；lr0保持默认 0.01 一般没错，迁移学习场景下调到 0.005 会更稳。训练完成后，输出目录下的weights/best.pt就是你要的最终权重。
4. 训练成型与可视化界面：从 loss 曲线到推理面板
4.1 训练启动与 loss 曲线怎么看
训练开始后，终端会滚动打印每一轮的box_loss、cls_loss、dfl_loss和mAP50。新手最容易慌的是看到 loss 在前几轮上涨，然后怀疑自己数据标注错了。实际上预训练权重迁移过来，前三轮是 warmup 阶段，loss 波动是正常的，持续到第 10 轮左右才会呈下降趋势。如果 30 轮后cls_loss还是高于 1.0，说明类别学不进去，去查标注 json 转 txt 时类别映射是不是错了，而不是改学习率。训练完去runs/fruit/exp01/下查看results.png，这张图直接反映了模型有没有正常收敛——曲线尾部应该平缓，如果还在明显下降，说明 100 轮不够，可以续训。
4.2 可视化界面三块核心区域的设计
“能跑通训练”和“交付一个可视化界面”是两回事。毕设答辩时，评委不关心你训练脚本写得多优雅，他们要看到鼠标点一点就能出结果。我的界面做法是用 PySide6 写一个轻量桌面程序，核心区域分成三块：左侧是图片/视频选择区，中间是推理预览区，右侧是结果统计区。
# ui_main.py 的结构骨架（只展示核心布局思路） from PySide6.QtWidgets import (QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QLabel, QFileDialog) from PySide6.QtGui import QImage, QPixmap import cv2 from ultralytics import YOLO class FruitDetectorUI(QWidget): def __init__(self): super().__init__() self.model = YOLO("runs/fruit/exp01/weights/best.pt") self.image_label = QLabel("等待加载图片") self.result_label = QLabel("检测结果: 未运行") self.btn_open = QPushButton("打开图片") self.btn_run = QPushButton("开始检测") self._build_layout() def _build_layout(self): layout = QVBoxLayout(self) btn_row = QHBoxLayout() btn_row.addWidget(self.btn_open) btn_row.addWidget(self.btn_run) layout.addLayout(btn_row) layout.addWidget(self.image_label) layout.addWidget(self.result_label)这个骨架里有个界面程序的通用设计：模型加载放构造函数，只加载一次；每次点“开始检测”只调用推理函数，不重新 import 模型。很多课设界面卡死就是因为每次推理都重新加载权重，白白等十几秒。加载完图片后调用下面的检测逻辑。
def run_inference(self): file_path, _ = QFileDialog.getOpenFileName( self, "选择图片", "", "图片文件 (*.jpg *.png *.jpeg)") if not file_path: return results = self.model.predict( source=file_path, conf=0.25, imgsz=640, device="cpu", verbose=False ) boxed_img = results[0].plot() # 返回带框的 BGR 图 # cv2 的 BGR 转 Qt 的 RGB rgb = cv2.cvtColor(boxed_img, cv2.COLOR_BGR2RGB) h, w, ch = rgb.shape qimg = QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) self.image_label.setPixmap(QPixmap.fromImage(qimg)) # 统计各类别数量 names = self.model.names counts = {} for box in results[0].boxes: cls_id = int(box.cls) counts[names[cls_id]] = counts.get(names[cls_id], 0) + 1 self.result_label.setText(f"检测结果: {counts}")这里的plot()方法会自动绘制检测框和标签，省去手动画框的麻烦。conf=0.25是置信度阈值，调低到 0.1 会显示出更多框但误检变多；界面上我建议暴露一个滑块让用户自己调，而不是写死。
4.3 界面推理卡死的三个原因与解决
界面跑推理时窗口“无响应”，是 PySide6 新手最常见的问题，原因出在推理阻塞了 UI 线程。predict()在 CPU 上单张图可能需要几秒，这期间 Qt 的事件循环被堵住。解决方法是把推理放到QThread里。这个细节值得写进代码注释里，答辩时老师会问。
# 用 QThread 后台推理，避免界面假死 from PySide6.QtCore import QThread, Signal class InferenceThread(QThread): finished = Signal(object) def __init__(self, model, file_path): super().__init__() self.model = model self.file_path = file_path def run(self): results = self.model.predict( source=self.file_path, conf=0.25, device="cpu", verbose=False ) self.finished.emit(results)然后把run_inference里的直接推理代码替换成启动线程，收到finished信号后再更新界面。这类改动不算复杂，但能让你的界面在 CPU 机器上依然顺滑。
5. 避坑：从 dataset.yaml 写到导出成品的几处翻车记录
5.1 训练的 loss 异常下降但 mAP 为 0：类别映射错位
现象：训练过程cls_loss下降很漂亮，mAP 却始终为 0，验证集输出全部是背景。
原因：我检查fruit.yaml时发现 names 顺序和标注 txt 里的 class_id 不一致。LabelMe 转 txt 时按字母表生成映射，ripe分到了第 2 类，但 yaml 里第 2 类写的是unripe。模型学到的类别 A 和数据显示的类别 B 对不上，评价自然全错。
解决：写一个校验脚本，随机挑一张训练图片，把 txt 里的坐标画回去叠加到原图上，人工检查框和类别对不对得上。这一步花不了十分钟，但能省下后面两小时的排错时间。转换脚本的类别映射字典从此固定下来，不再手工改。
5.2 CPU 训练显存不足的假警报
现象：训练刚开始报OutOfMemoryError，但我用的是核显共享内存，任务管理器里显示可用内存还有很大余量。
原因：YOLOv8 默认开了cache=True，会把整个数据集缓存进内存，一千张高清图在 CPU 机器上直接吃满 16GB 内存。
解决：训练命令里加cache=False，改小batch=8和workers=2。如果是 GPU 的 OOM，一般是 batch 太大或imgsz太大，先降 batch，再考虑关掉cache。不要一上来就换模型结构，那样容易引入新问题。
5.3 label 文件与图片文件不配对
现象：训练时提示“found 0 images in val”或 loss 一直不下降。
原因：我用脚本随机划分数据集时，只拷贝了图片文件，没有同步拷贝同名 txt 标签文件。YOLOv8 默认把没有标签的图片当作背景图，训练出来模型什么都检测不出来。
解决：改用程序同时复制两个目录，并做一次完整性检查：打印不存在标签的图片列表，人工决定是补标还是删除。规则是“图片必须带标签，不强迫每个标签都有对应图片”。
5.4 界面显示乱码：cv2 的 BGR 与 Qt 的 RGB 混用
现象：界面里图片颜色明显发蓝，红色的果子在界面里变成蓝紫色。
原因：OpenCV 读取图片输出 BGR 通道顺序，Qt 的 QImage 期望 RGB，直接塞进 QPixmap 后红蓝通道互换。
解决：推理后加一行cv2.cvtColor(boxed_img, cv2.COLOR_BGR2RGB)再转QImage。这条坑不仅出现在 PySide6，也出现在matplotlib显示检测图时，后者同样默认 RGB，如果直接把 cv2 结果imshow，颜色必然偏。
5.5 完熟果搭配红背景，模型把背景当成果子
现象：验证集里 ripe 精度高，但拿去果园实拍，红色防草布、红色衣服都被框成 ripe 果。
原因：训练图为了省事，大量使用了成熟果密度极高的“果子挨着果子”的照片，模型把“红色区域+圆形纹理”当成了唯一特征，没学到果柄、果型这些结构特征。
解决：补标含背景干扰的负样本，或在标注规范中强制要求：果子边界不清、被叶子遮挡超过 30% 的，要么精细圈边界，要么不标。数据集中加入一批“有红布无果实”的空背景图，类别为空，理由是让模型学会“没有果子时输出为背景”。这是完全值得做的方向，数据质量决定了模型上限。
6. 进阶：验证模型精度与迁移到边缘设备的最后一步
6.1 独立测试集和 mAP 验证脚本
训练完不能用 val 指标直接交差，要留着 test 集做最终的精度验证。跑一次正式评估。
yolo detect val \ model=runs/fruit/exp01/weights/best.pt \ data=fruit.yaml \ split=test \ imgsz=640 \ batch=8输出会给出mAP50和mAP50-95两项关键指标。对成熟度检测这种任务，目标至少是mAP50达到 0.85 以上，低于 0.7 的建议先检查标签再调参。mAP50-95偏低但mAP50很高，通常说明框的定位不够精细，这时候该调的是回归分支的 loss 权重，而不是加大训练轮数。
6.2 导出 ONNX 并想想能不能上 RK3588
毕设做到收尾，很多人会问“能不能部署到开发板上”。这是一个恰当的收尾方向，因为果园场景不可能一直背着笔记本。YOLOv8 导出 ONNX 格式非常顺滑。
yolo export model=runs/fruit/exp01/weights/best.pt format=onnx opset=12 imgsz=640导出后在 ONNX Runtime 上跑一次，比较导出前后推理结果是否有差异，以确认算子兼容。如果差值超过 0.05 的置信度，优先怀疑opset版本问题，换opset=11再试。上 RK3588 板子这类带 NPU 的边缘设备时，要做 RKNN 格式转换，同时把精度降到 FP16，成熟度检测对精度损失不如自动驾驶敏感，FP16 完全够用。板子上的推理代码和桌面端没有本质区别，只是加载引擎不同，这个方向可作为答辩的加分项。
6.3 把误检图收集成负样本库
我自己的一个工作习惯：每次跑完验证集，把预测错误的图片全部复制到一个error_analysis目录，按错误类型分文件夹——漏检、误检、类别混淆。积累三十张左右，进行一次增量训练，把误检图作为难例混入训练集。两轮迭代后，模型在实地拍摄上的表现会再上一个台阶。这是我做过几轮之后最直接的收尾建议：交完项目不是终点，把误检图留好，是继续优化的后悔药。
如果时间充裕，再到果园里拍一段 15 秒的视频，用训练好的权重跑一次视频推理，把结果导出剪辑成演示素材。现场答辩的时候，一个能实时框出成熟果的演示视频，会比十页原理说明更有说服力。把“能用”的模型优化到“好用”，功夫全在这些不显眼的迭代里，希望这些步骤能帮你少走一些弯路，把这件事一次性做扎实。
本文还有配套的精品资源，点击获取
