柑橘成熟度识别全流程：从数据集构建到YOLOv8训练与部署

简介：这是基于PyTorch的柑橘成熟度识别完整项目，面向计算机视觉初学者或农业图像分类场景，内置可直接运行的深度学习代码与已标注图像数据，帮助用户从零搭建一个完整的图像分类应用。压缩包共120个文件，其中113张jpg与1张jpeg原始图像覆盖健康、成熟、病害等多种状态，3个Python脚本分别实现数据集标签生成、卷积神经网络训练和PyQt可视化界面，3个txt文本用于记录训练集与验证集的文件路径及对应标签，整包约10.8MB，目录结构清晰，便于快速定位。项目在数据预处理阶段采用短边补灰边转为正方形、随机旋转等增强策略，有效扩充样本多样性，降低过拟合风险；运行01脚本可自动读取各类别图片路径并生成标准标签文件，02脚本据此完成模型训练并保存本地权重，03脚本则启动图形界面，实现图片识别结果的可视化展示。目前已有237人学习下载，适合希望快速跑通分类任务全流程、积累PyTorch实操经验的中初级学习者。

1. 柑橘成熟度识别：为什么这个任务是 CNN 的强项，而不是阈值分割

做果品分选产线的人多半都试过这条路：用工业相机拍柑橘，按 RGB 颜色阈值判断青果还是黄果。晴天跟阴天拍出来的颜色都不一样，农户换了个品种，阈值就得重调，更不用说阳光直射产生的高光、叶片遮挡投下的阴影、以及果实表面本身的花斑——纯颜色规则在这种场景里几乎必翻车。而基于卷积神经网络的柑橘成熟度识别，是把成熟度当作一个视觉分类/检测问题来解，网络自己从数据里学颜色、纹理、形状的综合特征，光照变化和品种差异被数据覆盖掉，鲁棒性比手写规则高一个量级。

这个项目最值钱的部分其实不是网络结构，而是「含数据集」这三个字。柑橘成熟度不是 ImageNet1k 那种公开大任务，能用来训练的标注数据很少，绝大多数人卡在第一步：找不到数据，或者找到了只有几十张没法训。标题里明确带了数据集，意味着拿到的是一份可用的训练资产。适合两类人：一类是做农业信息化、果品分级设备落地的工程师，想快速验证 CNN 在这个场景的上限；另一类是入门深度学习、想拿真实业务数据走一遍完整流程的开发者。下面按我自己的落地习惯，从数据准备、模型选型、训练调参到部署验证整条链路拆开讲。

2. 先把数据集吃透：目录结构、标注格式与训练/验证划分

2.1 拿到数据集的第一件事：别急着训练，先做三样检查

我习惯把下载的数据集解压后，先跑一遍文件树和统计信息，而不是直接丢进训练脚本。很多压缩包里的数据组织方式跟常见框架默认格式不一样，直接训练大概率报路径错误，或者类别跟标签对不上。先看整体结构：

# 在数据集根目录执行，输出层级结构和每类文件数量 tree -L 3 --dirsfirst find . -type f -name "*.jpg" | wc -l find . -type f -name "*.xml" | wc -l # 如果是VOC格式 find . -type f -name "*.json" | wc -l # 如果是COCO格式 find . -type f -name "*.txt" | wc -l # 如果是YOLO格式

这里有几个关键点在输出里确认。第一，图片和标注文件的个数是否对得上，对不上说明有漏标或脏文件。第二，标注是不是跟图片一一对应同名，很多数据集图片是001.jpg、标注是001.xml，但也有图片名带下划线、标注名不带的，埋到后面就是训练时标签加载不到。第三，类别名称是什么——是unripe / semiripe / ripe这种英文，还是青果 / 半熟 / 成熟这种中文，还是干脆用0 / 1 / 2数字。这一步定下来后面做格式转换才有的放矢。

第三点特别提醒做检测的读者：有些数据集表面上写了「柑橘成熟度」，标注却是整图单标签的 CSV，或者是每个果实的框级标注，这两种标注对应的技术路线完全不同。整图单标签只能做图像分类，框级标注才能做目标检测。我看到过不少人在这一步栽跟头，拿着分类数据想训 YOLO，那肯定训不了。

2.2 VOC 转 YOLO 格式：转换脚本与三个边界坑

我默认你拿到的数据集是 VOC 格式（xml 标注），因为国内多数农业类数据集的标注都是用 LabelImg 做的，导出就是 VOC。而 YOLOv8 训练自定义数据集用的是 txt 格式，每行一个目标：class_id cx cy w h，坐标是相对图片宽高的归一化值。转换脚本如下：

import xml.etree.ElementTree as ET import os, glob def voc_to_yolo(xml_path, out_dir, class_dict): tree = ET.parse(xml_path) root = tree.getroot() img_w = int(root.find("size/width").text) img_h = int(root.find("size/height").text) txt_lines = [] for obj in root.iter("object"): cls_name = obj.find("name").text if cls_name not in class_dict: continue # 忽略未定义类 cls_id = class_dict[cls_name] bbox = obj.find("bndbox") x1 = float(bbox.find("xmin").text) y1 = float(bbox.find("ymin").text) x2 = float(bbox.find("xmax").text) y2 = float(bbox.find("ymax").text) # 归一化，并做边界裁剪，防止坐标越界 x1 = max(0, min(x1, img_w - 1)) y1 = max(0, min(y1, img_h - 1)) x2 = max(0, min(x2, img_w - 1)) y2 = max(0, min(y2, img_h - 1)) if x2 <= x1 or y2 <= y1: continue # 无效框，丢弃 cx = (x1 + x2) / 2.0 / img_w cy = (y1 + y2) / 2.0 / img_h w = (x2 - x1) / img_w h = (y2 - y1) / img_h # 归一化后坐标理论在[0,1]，但浮点计算可能超一点，裁剪到[0,1] cx = max(0, min(cx, 1.0)) cy = max(0, min(cy, 1.0)) w = max(0, min(w, 1.0)) h = max(0, min(h, 1.0)) txt_lines.append(f"{cls_id} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}") # 输出同名txt到指定目录 out_name = os.path.basename(xml_path).replace(".xml", ".txt") with open(os.path.join(out_dir, out_name), "w") as f: f.write("\n".join(txt_lines)) class_dict = {"unripe": 0, "semiripe": 1, "ripe": 2} xml_list = glob.glob("labels/*.xml") os.makedirs("labels_yolo", exist_ok=True) for x in xml_list: voc_to_yolo(x, "labels_yolo", class_dict)

这个脚本做了几件容易漏的事。第一是坐标边界裁剪，标注软件偶尔会标出超出图片边界的框，不处理的话归一化后坐标可能跑到[0,1]之外，YOLO 训练时会报警甚至跳过。第二是无效框过滤，x2 <= x1这种情况虽然少见但存在，多半是手误，直接丢弃比带着跑安全。第三是忽略class_dict里没有的类别，如果数据里混了leaf、branch这种标注，要么删掉、要么单独给类，不能静默跳过，否则后续统计分析会发现样本数莫名其妙变少。

转完后抽样检查五到十个 txt 文件，手工算一下坐标对不对。常见做法是写一个反向脚本，把 txt 里画回图片上存成可视化的 jpg，肉眼确认框的位置跟果实贴合。这一步别省，转换脚本的 bug 在可视化下最多十分钟就暴露，放到训练里能浪费一整天。

2.3 训练/验证/测试划分：随机划分是给自己埋雷

数据集划分是另一个容易被低估的环节。很多人图省事直接random.shuffle后按 8:2 切，如果数据里同一个果实的多角度照片都来自同一棵树，这种做法会让模型「作弊」——验证集里出现训练集同株果实的其他角度照片，mAP 虚高到离谱，一上真实果园就现原形。我一般按拍摄批次或植株 ID 分组划分，确保同一个体的所有样本只在训练集或验证集里出现。下面这段脚本是按文件名前缀分组的划分逻辑：

import os, random, shutil from collections import defaultdict img_files = [f for f in os.listdir("images") if f.endswith(".jpg")] # 按文件名下划线前的部分作为分组ID（假设拍摄时按株编号命名） groups = defaultdict(list) for f in img_files: group_id = f.split("_")[0] groups[group_id].append(f) group_ids = list(groups.keys()) random.seed(42) random.shuffle(group_ids) split = int(len(group_ids) * 0.8) train_groups = set(group_ids[:split]) val_groups = set(group_ids[split:]) train_files = [] val_files = [] for gid, files in groups.items(): if gid in train_groups: train_files.extend(files) else: val_files.extend(files) # 写入train.txt / val.txt，供YOLO训练使用 os.makedirs("data_split", exist_ok=True) with open("data_split/train.txt", "w") as f: f.write("\n".join([os.path.abspath(os.path.join("images", x)) for x in train_files])) with open("data_split/val.txt", "w") as f: f.write("\n".join([os.path.abspath(os.path.join("images", x)) for x in val_files]))

分组划分的核心是用split("_")[0]把同一株柑橘的样本锁在同一个分组里。我在实际项目里还见过另一种划分泄漏：同一个视频序列截取的帧，前缀相同但时间连续，按帧随机切会让时序上的相邻帧同时出现在两边，模型等于提前看到了答案。分组维度可以是植株、可以是拍摄批次、也可以是视频序号，原则只有一个——信息不能跨集合泄露。

3. CNN 两套选型：轻量分类网络与 YOLO 检测网络怎么定

3.1 看标注形式决定技术路线，别把分类数据集硬拿去训检测

拿到数据后第一件事是分辨标注粒度，这直接决定后面走哪条路线。整图单标签的数据集，每张图只有「成熟 / 半熟 / 未熟」一个标签，这种只能走图像分类路线：ResNet、EfficientNet、MobileNet 这类 CNN 分类网络，输入单果或单图，输出成熟度类别概率。而框级标注（每张图上有若干个框，每个框标了类别）的数据集，才能走目标检测路线：YOLO 系列、Faster R-CNN 这类网络，输出每个果实的位置框和成熟度类别。

这两条路线没有绝对优劣，取决于你的落地场景。如果做的是产线分选，果实是一个个过相机，背景干净、单果居中，分类网络就够了，速度快、部署简单、标注成本也低。如果做的是果园测产、采摘机器人，相机拍到的是一整棵树，果实密集且相互遮挡，这时候检测网络是唯一选择——你得先知道果实在哪，再谈成熟度。标题里没写明标注形式，但「含数据集」通常指的是包含果实级别框标注的 VIA 或 VOC 格式，这是做检测用得最多的。

我把两条路线的对比列成表格，方便照着选型：

3.2 分类路线的模型选择与训练入口

如果数据集是整图单标签，我一般直接用 torchvision 里预训练好的 ResNet18 或 EfficientNet-B0，先用 ImageNet1k 预训练权重初始化，再在自己的数据上微调。原因是柑橘成熟度的底层特征（边缘、纹理、颜色区块）跟 ImageNet 的自然图像特征高度通用，从头训的话收敛慢且数据量大概率不够。训练入口的 pytorch 代码核心部分如下：

import torch, torchvision from torchvision import transforms, models transform_train = transforms.Compose([ transforms.Resize((224, 224)), transforms.RandomHorizontalFlip(p=0.5), transforms.ColorJitter(brightness=0.1, contrast=0.1, saturation=0.1), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), ]) model = models.resnet18(weights=models.ResNet18_Weights.IMAGENET1K_V1) model.fc = torch.nn.Linear(model.fc.in_features, 3) # 三类成熟度 criterion = torch.nn.CrossEntropyLoss() optimizer = torch.optim.SGD(model.parameters(), lr=0.001, momentum=0.9, weight_decay=1e-4) scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=30)

这里注意两点。第一，model.fc替换成三分类输出层，因为预训练模型最后是 1000 类，不换的话前向传播就报维度错误。第二，学习率设为0.001而不是从头训练常用的0.01，因为预训练权重已经很接近最优点了，学习率太大会把学好的底层特征破坏掉。Resize((224, 224))是 torchvision 分类模型的通用输入尺寸，如果想用 256 或 512 也行，但要注意数据量少时大分辨率反而容易过拟合。

3.3 检测路线的 YOLOv8 训练命令与数据集组织

如果数据集是框级标注，直接用 YOLOv8 是当前最省事的选择，不需要自己搭网络结构。先把标注文件按上一章的方法转成 YOLO txt 格式，然后把数据集按官方要求的目录组织好，写一个data.yaml：

# data.yaml：类名顺序必须与转化脚本的class_dict一致 path: ./citus_dataset train: images/train val: images/val nc: 3 names: ['unripe', 'semiripe', 'ripe']

names的顺序必须跟第 2 章转换脚本里class_dict定义的顺序完全一致，否则训练时类别标签对应关系就乱了——比如转换脚本里unripe: 0，但这里 names 写成['ripe', 'unripe', 'semiripe']，那么原来标 0 的未熟果会被当成成熟果训练，模型直接学歪。接着用官方命令训练：

yolo detect train \ model=yolov8s.pt \ data=data.yaml \ epochs=100 \ imgsz=640 \ batch=16 \ lr0=0.01 \ patience=15 \ device=0

model=yolov8s.pt里的 s 是 small 版本，柑橘果实不算小目标但数量多，s 版本在速度和精度之间平衡得最好，用n（nano）精度掉太多，用m（medium）对数据集量要求更高。imgsz=640是训练时的输入分辨率，如果原始图片是 4K 的果园大图，后面推理还要做切图，训练分辨率不必跟原图一致。batch=16取决于显卡显存，8GB 显存的卡跑yolov8s用 16 没问题，显存不够就调到 8，batch 太小训练不稳定。lr0=0.01是初始学习率，用预训练权重时这个值用官方默认即可。

训练完成后会输出runs/detect/train/目录，里面有weights/best.pt和weights/last.pt，best 是按验证集指标保存的最优权重，last 是最后一轮的权重，正式用的时候取 best。从实践来看，第一次训练不要急着调参，先把一条基线跑通，看损失曲线和各类别 mAP，再决定下一步是调增强、加轮次还是换模型尺寸。

4. 训练配置与调参：让模型在半标注数据上收敛的关键参数

4.1 预训练权重与冻结训练：数据量少时的后悔药

农业类数据集通常只有几百到两三千张图，这个量级从头训练一个 CNN 是玩不转的，几乎必然陷入过拟合，训练集准确率 99%、验证集 60% 都是常事。预训练权重就是数据不足时的后悔药，它把网络前几层已经训成了通用边缘检测器和纹理提取器，你需要做的只是在它基础上学习柑橘成熟度特有的高级语义。常见做法是分两步走，第一步冻结骨干网络只训分类头，第二步解冻全部层用小学习率微调：

# 第一步：冻结骨干，只训分类头 for name, param in model.named_parameters(): if "fc" not in name and "classifier" not in name: param.requires_grad = False optimizer = torch.optim.SGD(filter(lambda p: p.requires_grad, model.parameters()), lr=0.001) # 训练5~10轮，分类头先收敛 # 第二步：解冻全部层，学习率降10倍做微调 for param in model.parameters(): param.requires_grad = True optimizer = torch.optim.SGD(model.parameters(), lr=0.0001, momentum=0.9)

冻结训练的成本很低但收益明确，它让先训的分类头在骨干特征还没被扰动时稳定下来，之后再解冻，所有层一起调的时候损失函数已经有了一个比较好的起点。这套「先冻结后解冻」的节奏在做柑橘这类小数据集时非常稳定，几乎不会翻车。要是直接全程微调，学习率稍大一点就可能把预训练权重破坏掉，损失曲线震荡不降。

4.2 数据增强的参数边界：别把柑橘增强成橙子

数据增强是小数据集训练的必需品，但增强幅度要卡在真实场景的物理范围内。柑橘成熟度识别的关键特征就是果皮颜色从青到橙的渐变，HSV 颜色增强里hue参数尤其敏感——默认的hue=0.015对 YOLOv8 是大范围增强，但对柑橘来说，色调漂移超过 0.03 就能把青果变成橙果，模型学到的是「橙色=成熟」这个假规律，真实场景下青果都被误判成成熟果。

我用的增强配置有两条原则：一是hue幅度控制在 0.01 到 0.02 之间，只模拟不同品种间细微的底色差异，不改变成熟度主色调；二是saturation和brightness可以适当放宽到 0.3 左右，因为实际果园里光照变化对饱和度和亮度的影响远大于对色调的影响。YOLOv8 的增强参数在hyp.scratch-low.yaml里定义，训练时用hyp参数指定自定义配置：

# hyp_citus.yaml 关键增强参数 hsv_h: 0.01 # 色调增强幅度，比默认的0.015更保守 hsv_s: 0.3 # 饱和度增强 hsv_v: 0.3 # 亮度增强 fliplr: 0.5 # 水平翻转概率 mosaic: 0.5 # mosaic增强概率

一个对照组实验就能验证增强幅度是否合适：用同一份数据、同一个种子，分别用默认增强和上面的保守增强训练 50 轮，对比验证集 mAP。我做过一次这种实验，默认增强的 mAP@0.5 是 0.82，保守增强能到 0.87，差别就在 hue 漂移把训练分布带偏了。

4.3 早停、学习率与批次尺寸的联动关系

训练时的三个超参数是互相牵制的，不能单独调。patience早停参数控制模型在验证集指标连续多少轮不提升就停止训练，一般设 15 到 20，数据集越小这个值可以越大一点，因为小数据集每轮波动大，太早停会错过后续的回升。学习率策略上，YOLOv8 默认用余弦退火，lr0设 0.01 时整个训练过程学习率会平滑降到接近 0；如果发现损失曲线在高位震荡不降，先把lr0降到 0.005 试试，比调别的参数都见效。

batch size 跟学习率是联动的：batch 翻倍，梯度估计更准，学习率可以适当加大；batch 减半，梯度噪声更大，学习率最好也减半。这条经验在分类和检测任务里都适用。我用 8GB 显存的卡训练时，batch=16配lr0=0.01跑 YOLOv8s 没问题；换到 4GB 的卡，batch 降到 8，lr0就改成 0.005。忘记了这条，最常见的翻车就是显存不足改小 batch 后忘记调学习率，损失直接炸到 NaN。

5. 柑橘成熟度识别踩坑记录：5 个让我翻车的细节

5.1 标注文件与图片文件名不对齐，训练集样本数悄悄减半

现象：训练日志显示 800 张图只加载了 400 张，且没有任何报错，mAP 也低得离谱。

原因：数据集的图片文件名是DJI_0001.jpg，标注文件是0001.txt，转格式时按os.path.basename(xml_path)输出，导致生成的 txt 文件名跟图片对不上。YOLO 训练按图片名去查找对应 txt，找不到就跳过该图片，且静默处理。

解决：写一个校验脚本，遍历每张图片检查同名 txt 是否存在，不存在就打印文件名。更重要的是在 VOC 转 YOLO 时，以图片文件名为准生成 txt 文件名，而不是以 xml 文件名为准。做数据准备时多花十分钟跑校验，能省掉后续排查的一整天。

5.2 类别不平衡：未熟果占七成，模型学成「永远猜未熟」

现象：训练完成后混淆矩阵里未熟果的召回率 0.95，成熟果召回率只有 0.4，但整体 mAP 看着还不低。

原因：果园里未熟果远多于成熟果是物理事实，数据集天然倾斜。模型发现全预测未熟就有 70% 准确率，懒得学成熟果的特征了。

解决：一是按类别做采样，训练时每轮从成熟果样本里过采样，让每个 batch 里三类比例接近均衡；二是把损失函数里的类别权重调成反比于类别频率，YOLOv8 里可以在data.yaml中设置weight=参数，分类网络里直接给CrossEntropyLoss(weight=torch.tensor([0.3, 1.0, 1.5]))。我一般两个一起上，效果比单用任一更稳。

5.3 青果与叶片颜色接近，小目标漏检集中在小果上

现象：验证集里漏检的框 90% 是青果，而且集中在果实占整图面积小于 2% 的那些图上。

原因：青果颜色跟绿叶太接近，网络学到的高层特征里「绿色 + 圆形」还不够独特，加上小目标本身在下采样过程中特征被稀释。这是自然场景的通病，不是模型结构的问题。

解决：第一，训练分辨率从 640 提到 960（显存允许的话），小目标的特征保留要好很多；第二，推理时做大图切块，把 4K 图切成 640×640 的块，检测完再把框映射回原图坐标，这个过程常用 SAHI 框架实现。这两招组合，青果漏检率我实际做过能降 40% 以上。

5.4 数据增强把成熟度特征破坏了，模型学会的是奇怪颜色

现象：训练损失降得很快，但验证集 mAP 只有 0.6 出头，而且错误集中在把半熟果判成未熟果。

原因：YOLOv8 默认的hsv_h: 0.015对一般物体检测没问题，但柑橘成熟度的判别特征就是皮色，色调一偏移，训练样本里成熟果的「橙色」被漂成了别的色，模型反而学到了不稳定的色相模式。

解决：把hsv_h降到 0.01 或直接关掉，同时把hsv_s和hsv_v保留在 0.3 水平模拟光照变化。这个坑最隐蔽的地方在于训练曲线一切正常，只有做可解释性分析时才发现网络激活区域集中在果皮的边缘而不是整体颜色。

5.5 验证集和训练集同源，mAP 虚高导致上线翻车

现象：本地验证 mAP 0.89，拉到现场果园实拍数据测试，mAP 直接掉到 0.55。

原因：数据划分时按文件随机切分，同一棵树上采集的几十张照片被切到了两边。模型已经在训练时「见」过这颗树的纹理、光照和背景，验证指标是作弊指标，真实场景没有这种同源关系。

解决：回到第 2 章的按组划分方案，以植株 ID 或拍摄批次为分组单位，确保整棵树的样本只在训练集或验证集中出现。这一条也是我做柑橘识别最大的血泪教训，当时被 demo 指标欺骗，差一点带着虚高模型上产线。

6. 不止看 mAP：置信度阈值、分类错误矩阵与部署验证

训练完模型只是第一步，离「能上产线」还有一段路。分类模型的落地验证要看两类错误各自的代价：把未熟果判成成熟果（漏掉次果）比把成熟果判成未熟果（浪费好果）代价更高，因为前者会砸口碑，后者只是损失一点利润。这个代价不对称决定了置信度阈值不能简单取 0.5。我用验证集画出各类别的置信度分布曲线，取误差代价最小的交叉点作为阈值——产线场景我一般把成熟类的阈值提到 0.7，未熟类的阈值压到 0.4。

检测模型的有效做法是看混淆矩阵，YOLOv8 训练结束会在runs/detect/train/confusion_matrix.png输出归一化混淆矩阵，重点看ripe被错分成unripe的比例。如果这个值偏高，说明模型对果皮色的过渡段不敏感，可以针对性增大semiripe类别的样本权重。另一个容易被忽略的指标是各类别的置信度直方图，如果大量正确检测的框置信度集中在 0.3-0.5 区间，说明训练不充分或者增强过度，先别急着部署。

部署侧的验证我习惯用 ONNX 导出后跑到边缘设备上实测帧率，而不是只看 GPU 上的 FPS。YOLOv8 官方提供导出命令：

yolo export model=best.pt format=onnx imgsz=640

导出后在边缘设备上跑一个简单的推理脚本，统计单帧处理时间。我踩过的一个坑是：训练时用的imgsz=640是 640×640，但推理时输入的实际是 4K 原图，letterbox处理后实际推理分辨率超过 640 导致速度大打折扣。解决方案是先做图像缩放再做切块推理，每块固定 640×640，检测结果映射回原图坐标。我用 Jetson Orin Nano 跑 YOLOv8s + 切块推理，实测单棵果树（约 4K 图）处理时间在 1.2 秒左右，这个速度对产线按个分选够用，对实时采摘机器人还偏慢，得换 TensorRT 或剪枝到 nano 模型。验证完这些再谈上线，是我现在做农业视觉项目的固定流程。希望帮到你。

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