简介面向目标检测学习者的YOLOv8棉花识别项目代码包聚焦农业场景下的棉花检测适合具备一定深度学习基础并希望快速上手YOLOv8训练与部署的开发者。包内共475个文件压缩包大小约35.44MB主要包含130个Python训练脚本、43个YAML配置与数据标注文件、3个预训练模型权重、C推理源码、Jupyter Notebook示例、Dockerfile以及228个Markdown说明文档覆盖环境配置、数据准备、模型训练、评估与推理的完整链路。目前已有95人学习下载。资源附带清晰的requirements.txt依赖清单按说明配置即可运行同时包含训练事件日志tfevents、CITATION引用信息与results.csv测试结果便于复现实验和查看输出。对于希望参考完整项目结构、免去从零搭建环境的训练者这套代码能直接提供可运行的YOLOv8棉花识别基线方案也可基于自有图像数据进一步迁移学习与调优。1. 为什么棉花识别要把 YOLOv8 当成首选方案农业目标检测里棉花识别比通用物体检测更考验模型棉桃体积小棉叶和背景颜色接近大田环境还有褶皱、反光、遮挡和光照突变。YOLOv8 能在这类场景里站稳靠的不只是精度提升而是把 anchor-free 检测头、C2f 特征融合和更稳的训练动态整合到一起对中小目标更友好。这个项目给的不是单个权重文件而是一套可以从零复现的工程包训练阶段产生的 TensorBoard 日志、数据集组织方式、C 推理源码和 results.csv 检测结果正好覆盖了从标注到部署的完整链路。对做农业智能化、无人机巡检或边缘盒子的人来说这套代码比单纯跑一个 demo 有价值得多。接下来按模型结构、文件解析、数据训练、C 推理和结果验证五条线展开每步都会给你能直接执行的命令和参数。2. YOLOv8 棉花检测的网络结构C2f 与 Anchor-Free Head 怎么改2.1 C2f 模块为什么适合小目标YOLOv8 最核心的改动是把 YOLOv5 的 C3 模块替换成 C2f。C2f 的结构可以理解为先经过一个 1x1 卷积降维再并行经过多个 Bottleneck最后把所有分支的通道在输出维度上做拼接。这种 dense residual 连接让梯度在深层网络里流动更顺畅同时不同感受野的特征可以在同一层内被重新组合对小目标定位和分类都有帮助。棉花检测中棉桃在原始图像里可能只占几十个像素如果特征提取阶段过早下采样后续回归头根本看不到足够细节。YOLOv8 的 PAN-FPN 保留了高分辨率特征层配合 C2f 的多分支融合比传统 C3 更能保留中层语义。实际改模型时你可以在 ultralytics 的cfg/models/v8/yolov8.yaml中调整 C2f 的shortcut或 Bottleneck 重复次数。常见做法是把max_channels提高比如改为 512防止大模型在浅层丢失纹理。2.2 Decoupled Head 与 Anchor-Free 的回归逻辑YOLOv8 的检测头从耦合改成了解耦分类和回归分成两个分支这样分类任务和定位任务不会互相干扰。回归头使用 anchor-free 形式直接在特征图上预测每个位置到目标框四条边的距离不再需要预设 anchor 的尺寸和比例。你只需要告诉模型目标有几个类别所有框都由网络自己回归。这种方式对棉花识别的好处是标注框的尺寸波动很大有的棉桃非常近有的却只有几个像素固定 anchor 难以覆盖。使用 distribute focal loss 让回归分支对边界框的任意表示都有效。查看网络结构时可以用model YOLO(yolov8s.pt); model.info()打印每一层参数量和输出形状。下面这段代码可以快速统计模型复杂度。from ultralytics import YOLO model YOLO(yolov8s.pt) model.info() print(model.model.yaml)这段代码中model.info()会输出每层模块名、类型、参数数量和 FLOPsmodel.model.yaml返回模型配置字典。你可以在配置里看到head部分有box和cls两个独立分支这就是解耦头的体现。参数解读nc是类别数棉花识别设置为 1 时检测头会把输出通道调整为(4 1) * 1和1 * 1分别对应边框回归和类别概率。2.3 针对棉花的类别数设置与损失函数权衡默认 YOLOv8 使用 CIoU 作为定位损失加上 DFL 和 BCE 分类损失。棉花场景里如果只想识别棉桃类别数就是 1如果还要识别棉花植株、棉铃或土壤背景可以扩展到多类。但类别增加会直接影响正负样本分布容易让模型过度拟合背景。项目原始训练使用的是单类棉花从 results.csv 可以看出框数量集中在单类。损失权重参数在args.yaml或训练命令中通过--cls、--box传递。多数情况下box7.5、cls0.5是稳定起点。但棉花很多小目标建议把box权重提高到 8 以上DFL 保持默认。你还可以开启--mosaic和--mixup做数据增强让模型适应遮挡和重叠。下表是小目标场景下推荐超参和默认值的对比。参数默认值棉花识别建议原因box7.58.5小目标更依赖回归精度cls0.50.4避免背景误判dfl1.51.5分布损失对模糊边有利mosaic1.01.0增强小目标上下文fl_gamma0.00.2缓解正负样本不均设置这些参数时如果你用的训练脚本是yolo train可以写成yolo train datadata.yaml modelyolov8s.pt box8.5 cls0.4 fl_gamma0.2。调参后观察损失曲线的下降幅度如果box_loss出现锯齿说明学习率太高或增强过强。3. 训练日志与项目代码文件拆解从 events.out.tfevents 到 results.csv3.1 目录中的每个文件是什么角色项目文件列表里出现了events.out.tfevents.1718092109.QR.10160.0这是 TensorBoard 的二进制事件文件记录了训练过程的 loss、mAP、学习率等标量。文件名中的1718092109是 Unix 时间戳QR是主机名后面是进程 ID。打开这个文件可以还原训练曲线判断模型是否收敛。setup.cfg是环境安装配置里面声明了依赖包用于pip install -e .。CITATION.cff是引文格式文件一般作者用来让别人引用项目。CNAME是 GitHub Pages 的域名配置说明这个项目可能有配套网页展示。style.css是展示页面的样式不是核心代码。3.2 从 tfevents 里解析损失曲线默认 TensorBoard 日志被训练脚本写入runs/train/exp路径而这里的事件文件在项目根目录可能是手动导出或调整过--project参数。你可以用如下代码读取该文件并转成 DataFrame。from tensorboard.backend.event_processing.event_accumulator import EventAccumulator log_dir . acc EventAccumulator(log_dir) acc.Reload() for tag in acc.Tags()[scalars]: events acc.Scalars(tag) print(tag, len(events))这段代码从当前目录加载训练日志acc.Reload()会扫描所有格式正确的事件文件。acc.Tags()[scalars]返回所有可用的指标名称比如train/box_loss、val/mAP50-95、lr/pg0。你会发现训练过程中每个 epoch 都会记录一次值方便你确认模型在哪个 epoch 开始过拟合。如果该文件是多个实验混合写入的你需要用acc.Reload()后按 wall_time 排序把最早一次实验的数据单独截取。也可以直接用命令行看曲线tensorboard --logdir.启动后在浏览器访问http://localhost:6006左侧选择SCALARS面板勾选train/box_loss和val/mAP50-95两张图。若看到 mAP 曲线在训练中段后不再上升说明模型已经收敛可以提前停止。3.3 results.csv 与 C 代码的关联results.csv是每次验证或测试的检测输出常见格式为image_name, class_id, confidence, x1, y1, x2, y2。这个文件既可以从 PyTorch 的val模式导出也可以从 C 推理程序写入。项目里的inference.cpp和main.cpp都会读取同一个模型文件并输出结果到该 CSV目的是让 C 端的结果能直接与 Python 训练时生成的指标做对比。我通常会把 CSV 第一列设置为图片文件名第二列是类别编号第三列是置信度后四列是像素坐标。读取时要注意坐标是原图坐标还是经过 letterbox 后的坐标如果两者不一致后续画框就会偏移。下面的 Python 片段演示了怎么检查坐标的范围。import pandas as pd df pd.read_csv(results.csv, headerNone, names[img, cls, conf, x1, y1, x2, y2]) print(df.describe()) print(df[df[x2] 2000])该代码读取 results.csv 并统计各列的统计信息df.describe()能看到 x2 的最大值和均值如果 x2 超过原图宽度且原图只有 1280 宽说明坐标是在 letterbox 填充图上计算的而不是原图尺度。此时要在 C 端做反向映射把坐标减去填充边距后除以缩放比例。3.4 编译与运行配置setup.cfg和CITATION.cff本身不是直接执行的但setup.cfg里的install_requires决定了训练环境。项目要求的依赖通常包括ultralytics8.0.0、torch、opencv-python。你可以用下面的命令创建虚拟环境并安装。python -m venv venv source venv/bin/activate pip install -r requirements.txt pip install -e .安装时注意torch的版本要和你机器的 CUDA 版本对应。如果requirements.txt里只写了torch默认会装最新版可能与你本地的驱动程序不兼容。我一般会先用nvidia-smi查看驱动支持的 CUDA 版本再单独安装指定版本比如pip install torch2.1.0 --index-url https://download.pytorch.org/whl/cu118。4. 用项目自带数据训练棉花识别模型数据集格式与 YOLOv8 训练命令4.1 数据集目录结构必须长什么样YOLOv8 训练期望数据集目录按下述结构组织。datasets/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── data.yaml其中images存放原始图片labels存放同名 txt 文件每行格式为class_id x_center y_center width height坐标值均为相对图片宽高的比例范围在 0~1 之间。棉花项目的数据集在链接里单独提供下载后你会看到标注文件。注意检查是否有类别编号为 0 的标签如果你只训练一类所有 txt 内容首列都应该是 0。还需要一份data.yaml文件来声明路径和类别。项目通常已经提供缺失时需手动创建。内容参考如下。path: ./datasets train: images/train val: images/val nc: 1 names: 0: cotton这份配置告诉 Ultralytics 库训练集和验证集的相对路径nc1表示背景外只有一个目标类别names的索引必须和标注文件中的第一列对应。如果你的标签文件用了非零编号比如从 1 开始训练就会报错因为模型内部只使用 0 起始的类别索引。4.2 训练命令与参数说明Ultralytics 的 CLI 提供了非常紧凑的入口。训练棉花检测模型时我用下面命令。yolo train modelyolov8s.pt datadata.yaml epochs120 imgsz640 batch16 lr00.01 augmentTrue patience20参数含义如下modelyolov8s.pt使用 COCO 预训练权重做迁移学习datadata.yaml指向刚创建的数据配置epochs120是最大训练轮数imgsz640表示输入图像会被 resize 到 640x640batch16根据显存调整如果显存不够可以降到 8lr00.01是初始学习率带动量 SGD 时常用patience20表示验证指标连续 20 轮不提升就早停。训练时如果出现CUDA out of memory可以加--cache设为 False 或直接换成yolov8n.pt小模型。4.3 如何读取训练日志并判断是否需要调整训练完成后runs/detect/train目录下会生成results.csv、weights/best.pt和last.pt。你要查看是否正常收敛通常关心三个指标train/box_loss、val/box_loss、metrics/mAP50-95。下面代码直接读取 latest 的 results.csv 并打印焦点信息。import pandas as pd res pd.read_csv(runs/detect/train/results.csv) res.columns res.columns.str.strip() print(res[[epoch, train/box_loss, val/box_loss, metrics/mAP50-95]].tail())这里results.csv的列名可能包含空格需要用str.strip()清理。如果train/box_loss下降但val/box_loss持续上升说明过拟合此时应增加数据增强或设置dropout参数。如果 mAP50-95 在 60 左右不再变化可以尝试从yolov8m.pt开始训练提高特征提取能力。4.4 从 TensorBoard 事件文件恢复训练曲线项目根目录的事件文件events.out.tfevents.1718092109.QR.10160.0可能来自一次完整训练也包含中间验证结果。当你需要复现训练时可以用命令行直接从这个文件夹启动 TensorBoard。tensorboard --logdir. --port 6006打开后能看到result标签下的曲线。如果早期损失出现尖峰可能是初始学习率过大如果曲线整体平缓但 mAP 一直很低可以检查标注文件是否错位。我遇到过部分图片名和 txt 文件名不一致导致训练样本很少的问题检查方式是写个脚本对比images/train和labels/train两个目录下的文件名前缀。5. C 端推理实现main.cpp 与 inference.cpp 的完整流程5.1 为什么用 C 而不是 Python训练可以用 Python生产部署往往要推到 C。棉花识别通常部署在无人机机载电脑或边缘盒子上C 运行时没有 Python 解释器和 torch 依赖内存占用更低启动更快。项目中的main.cpp是入口处理命令行参数和图像读入inference.cpp封装模型加载、推理和后处理。两个文件分离后你可以只替换推理实现比如把 OpenCV DNN 换成 TensorRT而不影响主程序逻辑。5.2 OpenCV DNN 加载 ONNX 模型的核心代码常见做法是先把训练好的 PyTorch 权重导出为 ONNX再用 OpenCV 的dnn模块加载。C 推理主流程如下。#include opencv2/dnn.hpp #include opencv2/opencv.hpp #include fstream const float kConf 0.25; const float kNms 0.45; std::vectorcv::Rect detectQ(cv::Mat img, cv::dnn::Net net) { cv::Mat blob cv::dnn::blobFromImage(img, 1.0 / 255.0, cv::Size(640, 640), cv::Scalar(0, 0, 0), true, false); net.setInput(blob); cv::Mat output net.forward(); // output shape: [1, 84, 8400] for 1 class ... return boxes; }blobFromImage将输入图像转换成深度神经网络需要的四维张量缩放系数 1.0/255.0 把像素归一化到 [0,1]cv::Size(640,640)强制缩放第三个参数是均值由于 YOLOv8 不默认减均值全部设为零swapRBtrue将 BGR 转 RGB。net.forward()的输出形状是[1, 84, 8400]其中 84 表示 4 个坐标 1 个类别置信度 一个类别的 79 个额外值默认80类如果只训练 1 类这个数字是 5 1 6但导出的模型结构仍为nc 4 1个通道。5.3 后处理置信度筛选与 NMS单类检测时输出张量每一列对应一个预测框的信息。你需要解析坐标先做反预处理的尺度还原再运行 NMS。代码片段如下。cv::Mat transposed output.t(); std::vectorcv::Rect boxes; std::vectorfloat scores; for (int i 0; i transposed.rows; i) { float obj_conf transposed.atfloat(i, 4); float cls_conf transposed.atfloat(i, 5); float conf obj_conf * cls_conf; if (conf kConf) continue; float cx transposed.atfloat(i, 0) * img.cols; float cy transposed.atfloat(i, 1) * img.rows; float w transposed.atfloat(i, 2) * img.cols; float h transposed.atfloat(i, 3) * img.rows; boxes.push_back(cv::Rect(cx - w / 2, cy - h / 2, w, h)); scores.push_back(conf); } std::vectorint idx; cv::dnn::NMSBoxes(boxes, scores, kConf, kNms, idx);这里第 4 列是目标置信度第 5 列是类别概率二者相乘得到最终置信度。坐标需要乘以原图宽高因为网络输出是归一化坐标。注意 YOLOv8 的模型输出可能是xywh格式也可能是xyxy格式取决于导出脚本。建议在导出 ONNX 时设置opset12并让脚本给每个输出层命名方便在 C 侧校验。5.4 坐标对齐letterbox 是最大的坑在 C 中如果输入图片不是正方形直接 resize 到 640x640 会破坏宽高比导致检测框偏移。OpenCV DNN 的blobFromImage不自动填充你需要写 letterbox 代码把长边缩放到 640短边等比缩放后填充灰色边。推理得到的坐标要减去填充边距再除以缩放比例。float scale std::min(640.0 / img.cols, 640.0 / img.rows); int new_w round(img.cols * scale); int new_h round(img.rows * scale); int dx (640 - new_w) / 2; int dy (640 - new_h) / 2; cv::Mat resized; cv::resize(img, resized, cv::Size(new_w, new_h)); resized.copyTo(letterbox(cv::Rect(dx, dy, new_w, new_h)));这段代码先计算缩放比例再把原图缩放后放入画布中央。如果省略这一步模型实际见过的是被挤压的图片推断能力会大幅下降。在项目代码中inference.cpp应该有对应的letterbox函数你可以检查它是否在blobFromImage之前被调用。6. 结果验证与调优实战解析 results.csv 并修正坐标偏移6.1 快速验证 C 输出与 Python 输出是否一致训练完成后先用 Python 的predict接口跑几张测试图生成基准坐标。然后使用编译好的 C 程序跑同样图片输出到results.csv。可以用下面的脚本比较两组坐标的 IoU。import pandas as pd import numpy as np cpp pd.read_csv(cpp_results.csv, headerNone) py pd.read_csv(py_results.csv, headerNone) def iou(b1, b2): x1, y1, x2, y2 b1 x3, y3, x4, y4 b2 xx1, yy1 max(x1, x3), max(y1, y3) xx2, yy2 min(x2, x4), min(y2, y4) inter max(0, xx2 - xx1) * max(0, yy2 - yy1) area1 max(0, x2 - x1) * max(0, y2 - y1) area2 max(0, x4 - x3) * max(0, y4 - y3) return inter / (area1 area2 - inter) for i in range(min(len(cpp), len(py))): i iou(cpp.iloc[i, 3:7], py.iloc[i, 3:7]) print(i)脚本中iou函数计算两个矩形框的重合度。如果所有框的 IoU 大于 0.9说明坐标转换逻辑正确如果持续偏低优先检查是否漏掉 letterbox 的边距还原。很多 C 项目在部署时只写了blobFromImage忘了反向映射这种错误非常隐蔽。6.2 调整置信度与 NMS 阈值的技巧当误检棉桃叠在一起时通常不是模型问题而是后处理阈值设置太宽松。项目默认没有暴露阈值你可以在inference.cpp中把kConf改成可配置文件。经验是大田远景图调高置信度到 0.35近景大棉桃可以降到 0.15NMS 阈值保持 0.45。使用一张密集棉桃图测试不同阈值统计框数量和平均面积。当框的数量从 200 突然降到 30 时说明阈值压掉了大量低置信度小框这时需要检查召回率。你可以在 results.csv 中按置信度排序看看真实目标是否集中于低分区间。6.3 让 C 程序支持动态阈值参数main.cpp可以接受命令行参数这样无需重新编译就能调阈值。./inference --modelweights/best.onnx --inputtest/ --conf0.3 --nms0.45 --outresult.csv在main.cpp中用getopt或简单的strcmp解析这些参数把值传给inference.cpp中的全局变量。这个方法能让你在田地现场直接微调而不带笔记本电脑反复编译。改进后的inference.cpp中可以加一个--img-size参数来实现动态输入尺寸比如--img-size736对小目标更友好但推理速度会慢一半部署时可根据实际帧率选用。本文还有配套的精品资源点击获取