简介：面向目标检测学习者的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()会输出每层模块名、类型、参数数量和 FLOPs，model.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传递。多数情况下box=7.5、cls=0.5是稳定起点。但棉花很多小目标，建议把box权重提高到 8 以上，DFL 保持默认。你还可以开启--mosaic和--mixup做数据增强，让模型适应遮挡和重叠。下表是小目标场景下推荐超参和默认值的对比。
| 参数 | 默认值 | 棉花识别建议 | 原因 |
|---|---|---|---|
| box | 7.5 | 8.5 | 小目标更依赖回归精度 |
| cls | 0.5 | 0.4 | 避免背景误判 |
| dfl | 1.5 | 1.5 | 分布损失对模糊边有利 |
| mosaic | 1.0 | 1.0 | 增强小目标上下文 |
| fl_gamma | 0.0 | 0.2 | 缓解正负样本不均 |
设置这些参数时，如果你用的训练脚本是yolo train，可以写成yolo train data=data.yaml model=yolov8s.pt box=8.5 cls=0.4 fl_gamma=0.2。调参后观察损失曲线的下降幅度，如果box_loss出现锯齿，说明学习率太高或增强过强。
3. 训练日志与项目代码文件拆解：从 events.out.tfevents 到 results.csv
3.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", header=None, 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决定了训练环境。项目要求的依赖通常包括ultralytics>=8.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 torch==2.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 库训练集和验证集的相对路径，nc=1表示背景外只有一个目标类别，names的索引必须和标注文件中的第一列对应。如果你的标签文件用了非零编号，比如从 1 开始，训练就会报错，因为模型内部只使用 0 起始的类别索引。
4.2 训练命令与参数说明
Ultralytics 的 CLI 提供了非常紧凑的入口。训练棉花检测模型时，我用下面命令。
yolo train model=yolov8s.pt data=data.yaml epochs=120 imgsz=640 batch=16 lr0=0.01 augment=True patience=20参数含义如下：model=yolov8s.pt使用 COCO 预训练权重做迁移学习；data=data.yaml指向刚创建的数据配置；epochs=120是最大训练轮数；imgsz=640表示输入图像会被 resize 到 640x640；batch=16根据显存调整，如果显存不够可以降到 8；lr0=0.01是初始学习率，带动量 SGD 时常用；patience=20表示验证指标连续 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::vector<cv::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 不默认减均值，全部设为零，swapRB=true将 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::vector<cv::Rect> boxes; std::vector<float> scores; for (int i = 0; i < transposed.rows; ++i) { float obj_conf = transposed.at<float>(i, 4); float cls_conf = transposed.at<float>(i, 5); float conf = obj_conf * cls_conf; if (conf < kConf) continue; float cx = transposed.at<float>(i, 0) * img.cols; float cy = transposed.at<float>(i, 1) * img.rows; float w = transposed.at<float>(i, 2) * img.cols; float h = transposed.at<float>(i, 3) * img.rows; boxes.push_back(cv::Rect(cx - w / 2, cy - h / 2, w, h)); scores.push_back(conf); } std::vector<int> idx; cv::dnn::NMSBoxes(boxes, scores, kConf, kNms, idx);这里第 4 列是目标置信度，第 5 列是类别概率，二者相乘得到最终置信度。坐标需要乘以原图宽高，因为网络输出是归一化坐标。注意 YOLOv8 的模型输出可能是xywh格式，也可能是xyxy格式，取决于导出脚本。建议在导出 ONNX 时设置opset=12并让脚本给每个输出层命名，方便在 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", header=None) py = pd.read_csv("py_results.csv", header=None) 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.15，NMS 阈值保持 0.45。
使用一张密集棉桃图测试不同阈值，统计框数量和平均面积。当框的数量从 200 突然降到 30 时，说明阈值压掉了大量低置信度小框，这时需要检查召回率。你可以在 results.csv 中按置信度排序，看看真实目标是否集中于低分区间。
6.3 让 C++ 程序支持动态阈值参数
main.cpp可以接受命令行参数，这样无需重新编译就能调阈值。
./inference --model=weights/best.onnx --input=test/ --conf=0.3 --nms=0.45 --out=result.csv在main.cpp中用getopt或简单的strcmp解析这些参数，把值传给inference.cpp中的全局变量。这个方法能让你在田地现场直接微调，而不带笔记本电脑反复编译。改进后的inference.cpp中，可以加一个--img-size参数来实现动态输入尺寸，比如--img-size=736对小目标更友好，但推理速度会慢一半，部署时可根据实际帧率选用。
本文还有配套的精品资源，点击获取
