企业官网建设流程全解析

简介：YOLO系列算法蟑螂检测数据集，专为目标检测训练与验证场景设计，适合需要快速获取高质量标注数据的开发者、学生及算法工程师使用。压缩包内共2000个文件，核心是1786个XML与214个TXT标签文件，分别对应VOC格式与YOLO格式标注：TXT文件采用 <x_center> <y_center> 结构，坐标归一化到0~1，可直接被yolov5、yolov7、yolov8、yolov9、yolov10、yolo11等主流框架读取；XML文件则便于在LabelImg等工具中二次核对。数据集已预先划分训练集与验证集，并附有data.yaml配置文件，下载后即可完成环境配置并进入训练流程。整体包大小仅47.59MB，轻量易传输，目前已吸引130人学习浏览。对想省去人工标注与格式转换步骤的开发者而言，这份数据能有效降低数据集准备成本，帮助把精力集中在模型调参与效果优化上。

1. 蟑螂目标检测数据集：2051张图能直接开训，但先搞清标签格式

YOLO算法做目标检测，这几年从yolov5到yolov8、yolov9、yolov10再到yolo11，迭代速度肉眼可见，但真正让项目卡壳的往往不是模型结构，而是带标注的数据。蟑螂这类目标，公开数据集几乎找不到，实拍图涉及场所和卫生隐私，自己用labelImg标一张平均要两三分钟，标到三百张就手酸想放弃。这份2051张的蟑螂数据集，带yolo和voc两种格式标签，train/val/test已经划分好，还配了data.yaml，解压后理论上一句话就能拉起训练。它适合做害虫检测验证、家庭环境识别、智慧卫生间场景预研，也很适合刚入门目标检测的人跑通完整的训练-验证-推理流程。下文从标签格式讲起，再给校验脚本和具体训练命令。

2. 目录结构与双标签格式：yolo和voc到底怎么对应

解压后先别急着训练，花十分钟看清目录结构，能省掉后面一大半的排错时间。这套数据集把图像、yolo格式标签、voc格式标签分开存放在不同目录，这是很多目标检测数据集的通用做法——图像目录只放jpg，训练时由框架按文件名去匹配标签。先看整体结构：

. ├── images/ # 图像，常见按 train/val/test 子目录划分 ├── labels_yolo/ # yolo 格式 txt 标签，与 images 子集一一对应 ├── labels_voc/ # voc 格式 xml 标签，文件名与图像同名 ├── data.yaml # 数据集配置文件，训练入口 ├── train.txt # 部分版本用索引文件代替目录划分 ├── val.txt └── test.txt

关于划分方式需要说明：压缩包里data.yaml的写法会直接告诉你它是用子目录还是用索引文件。yolov5的train.txt和val.txt索引文件很常见，ultralytics系列（yolov8/yolov9/yolov10/yolo11）更喜欢把train和val直接写成文件夹路径。如果你是第一次用，先打开data.yaml看一眼path、train、val三个字段指向哪里，后面训练命令里的data参数就填这个文件。

2.1 两种标签分别长什么样

打开labels_yolo里任意一个txt文件，内容只有一行到几行，每行五个数字，对应摘要里写的yolo格式：

$ cat labels_yolo/train/img_0440_52.txt 1 0.512345 0.623456 0.154678 0.089234

第一个数字是类别索引，从0开始计；接下来四个数依次是目标框中心点的x和y坐标、目标框宽度、目标框高度，全部相对于图像尺寸做了归一化，范围在0到1之间。所以看到0.51这个值，意味着框的中心在图像水平方向约51%的位置。摘要里说文件名末尾是部分类别名称，所以img_0440_52.txt里的52可能与类别名有关，也可能只是原始采集编号，程序不认文件名，只认txt内容，别在文件名上做任何假设。

再看labels_voc里对应的xml文件，同样是这张图，结构完全不同：

<annotation> <filename>img_0440_52.jpg</filename> <size> <width>1920</width> <height>1080</height> <depth>3</depth> </size> <object> <name>cockroach</name> <bndbox> <xmin>512</xmin> <ymin>400</ymin> <xmax>809</xmax> <ymax>496</ymax> </bndbox> </object> </annotation>

xml里存的是像素级坐标，xmin/ymin/xmax/ymax直接给出框左上角和右下角的位置，还带着图像原始宽高。yolo格式用归一化比例，voc格式用绝对像素，这就是两种标签最本质的差别。下面这组换算关系建议直接收藏，任何时候做voc转yolo都用得上：

W和H是图像原始像素宽高。反过来yolo转voc就是把这四个公式逆运算，得到像素值后通常要取整。这套换算看起来简单，却是标注数据翻车率最高的地方，后面避坑章节会展开说。

2.2 为什么同时保留两种格式

老牌标注工具labelImg默认导出voc格式xml，而yolov5、yolov8这些框架训练时读的是txt。所以很多从标注平台流出的数据集会同时保留两种格式：xml用来存档和二次修改，txt用来直接训练。你实际训练时只需要labels_yolo，voc格式是给你做校验或者转其他平台用的。

另一个角度看，数据集做了划分，意味着train/val/test三个子集的图像互不重叠，标签也同步被分到各自子集。这种划分的好处是训练时不会发生“验证集图像出现在训练集里”这种泄漏问题，mAP数值才有参考意义。你可以用find命令快速确认三个子集的数量分布：

find images/train -name "*.jpg" | wc -l find images/val -name "*.jpg" | wc -l find images/test -name "*.jpg" | wc -l

2051张图，常见划分比例是8:1:1左右。如果你发现test只有几十张也不用慌，小数据集上test更多是走一遍流程，最终模型评估主要看val指标。若子集目录里文件数之和不到2051，也要先停下来查是不是有图没有标签或标签没有图。

2.3 data.yaml配置文件怎么读

data.yaml是整个训练流程的枢纽，yolov5和ultralytics系列都认这个文件名。内容一般是：

path: ./ train: images/train val: images/val test: images/test nc: 1 names: 0: cockroach

说明一下字段：path是数据集根目录，可以写成相对路径，也可以是绝对路径；train和val分别指向训练和验证图像所在的文件夹；nc是类别总数，这份数据如果只有蟑螂一个类别就是1，如果有两个类别就是2；names是类别名列表，顺序必须和txt标签里的类别索引严格对齐——索引0对应names里第一个名字，索引1对应第二个，以此类推。names里具体叫什么以你解压出来的文件为准，上面示例里的cockroach只是常见写法。

还要注意yolov5有自己的一套数据加载逻辑：训练时它会在数据集根目录下自动找名为labels的文件夹来匹配images。所以如果你的labels_yolo文件夹不叫labels，而是直接在data.yaml里指定train路径，yolov5默认不会去读labels_voc，而是按图像路径去找同目录下的labels文件夹。这个差异很坑，很多人一上来train命令报错或者跑出全背景，就是没搞清yolov5对标签目录名的约定。ultralytics系列在这个处理上更灵活，但为了少踩坑，我一般会把yolo格式的txt统一拷一份到images同级labels目录下，再开始训练。

3. 训练前三项校验：用脚本查越界、缺图、类别失衡

拿到标注数据直接就开train，是新手最容易踩的坑。先说个血泪经验：有一次我用别人给的数据集训练，loss前30个epoch降得很漂亮，但val的mAP一直是0，查了两天才发现标签txt里有一半图像的宽高写反了，检测框全是竖长条。从那以后我养成了习惯，任何数据集训练前先跑一轮自动化校验，几十秒的事，省下的排错时间是按天算的。下面三个检查项覆盖了最常出问题的三类情况：坐标越界、文件缺失、类别失衡。

3.1 检查标签坐标是否越界、框是否合法

先写一个python脚本，把labels_yolo下所有txt读一遍，检查五个字段的合法性：

import os label_dir = "labels_yolo/train" bad = 0 for name in os.listdir(label_dir): if not name.endswith(".txt"): continue path = os.path.join(label_dir, name) for line in open(path, encoding="utf-8"): parts = line.strip().split() if len(parts) != 5: print(f"[字段数不对] {name}: {line.strip()}") bad += 1 continue cls, cx, cy, w, h = int(parts[0]), float(parts[1]), float(parts[2]), float(parts[3]), float(parts[4]) if cx < 0 or cx > 1 or cy < 0 or cy > 1: print(f"[中心点越界] {name}: cx={cx} cy={cy}") bad += 1 if w <= 0 or h <= 0 or w > 1 or h > 1: print(f"[宽高异常] {name}: w={w} h={h}") bad += 1 print(f"检查完毕，异常记录 {bad} 条")

逻辑很简单：按空格拆行，校验必须5个字段；中心点坐标在0到1之间；宽高必须大于0且不大于1。宽高小于等于0说明标注时把框拖反了，大于1说明归一化时用的除数不对。常见做法是把这段脚本放在数据集根目录下直接跑，输出的异常文件名按行修掉即可。需要说明的是，脚本里假定标签都是五字段规范格式，如果数据集里存在难样本或者crowd标注，字段数可能不同，这种行要单独看，而不是直接判坏。

3.2 检查图像与标签文件是否一一对应

标签文件和图像文件名一般是同名的，img_0440_52.jpg对应img_0440_52.txt。训练时框架按文件名匹配，如果某张图找不到标签，yolov5会把它当成纯背景图参与训练，这在目标检测里是致命的：模型学到的是“这个场景里没有目标”，而不是“这个目标没有被标注”。这种标签缺失不会报错，只会让mAP悄悄下降。检查脚本如下：

import os img_dir = "images/train" label_dir = "labels_yolo/train" imgs = {os.path.splitext(f)[0] for f in os.listdir(img_dir) if f.endswith(".jpg")} labels = {os.path.splitext(f)[0] for f in os.listdir(label_dir) if f.endswith(".txt")} missing_label = imgs - labels missing_img = labels - imgs print(f"有图无标签: {len(missing_label)} 个") print(f"有标签无图: {len(missing_img)} 个") for name in list(missing_label)[:10]: print(" ", name)

脚本假定train子目录下直接是图像文件，没有嵌套目录。如果missing数量少，但确实不想补标，可以把这个文件名从训练索引里剔除。这里用集合取差集是最高效的写法，2051个文件毫秒级跑完。注意图像可能不是jpg而是png或bmp，脚本里后缀要按实际扩展名调整，最稳妥的办法是os.path.splitext后只比对主文件名，别写死后缀。

3.3 统计类别分布，提前发现不均衡

蟑螂数据集虽然是单一目标，但类别索引不一定只有0。用第一个字段做直方图：

import os from collections import Counter label_dir = "labels_yolo/train" counter = Counter() for name in os.listdir(label_dir): if not name.endswith(".txt"): continue path = os.path.join(label_dir, name) for line in open(path, encoding="utf-8"): cls = line.strip().split()[0] counter[cls] += 1 for cls, count in sorted(counter.items()): print(f"类别 {cls}: {count} 个目标")

跑完如果发现某个类别索引几乎没出现，要么是这个类别在训练集里确实稀少，要么是标签文件里类别索引写错了，比如从1开始编号而不是从0。蟑螂这类单类问题，最怕的其实不是类别不均衡，而是某个索引的框尺寸全部异常——那通常是转换脚本的bug，而不是数据本身的问题。把三种检查结果合起来看，基本能确认一份数据集能不能直接进训练管线。

4. 把数据集喂给yolov5和ultralytics系列：命令与参数差异

校验过了，数据没问题，接下来就是训练。这里要分清两套训练入口：yolov5是独立的工程，训练脚本是train.py；而yolov8、yolov9、yolov10、yolo11统称ultralytics系列，共用ultralytics库，命令行入口是yolo。两者的data.yaml格式一致，但命令参数略有差异，下面分开写。

4.1 yolov5训练命令与参数说明

首先把yolov5工程clone到本地并装依赖，常见做法是：

git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt

如果你没有git环境，直接到github页面下载zip压缩包解压也能跑。然后把这份数据集放到工程外的datasets目录，重要的是把data.yaml里的path字段改成你的实际路径，或者干脆用绝对路径。启动训练：

python train.py \ --data /path/to/data.yaml \ --weights yolov5s.pt \ --img 640 \ --batch 16 \ --epochs 100 \ --project runs/train \ --name cockroach

逐项说明参数：--weights是预训练权重，yolov5s.pt是轻量版，s/m/l/x对应不同容量，蟑螂检测这种单类任务s足够，想提精度换m；--img是训练图像尺寸，yolov5会先把图缩放并letterbox到这个尺寸；--batch受显存限制，16G显存跑640和s模型一般能到16到32；--epochs是迭代轮数，100轮是起步，单类小数据集一般50到150轮之间能看到收敛；--name是本次运行的输出目录名，训练完的权重在runs/train/cockroach/weights/best.pt和last.pt。

这里有一个关键细节：yolov5默认要求标签放在images同级目录的labels文件夹里。你的数据集标签在labels_yolo，所以训练前要把txt拷过去，或者做个软链接：

ln -s /path/to/labels_yolo/train /path/to/datasets/cockroach/labels/train

软链接不占空间且不会污染原始数据，我常用这个办法。val和test子集也按同样方式处理。

4.2 ultralytics系列：一条yolo命令通吃v8/v9/v10/yolo11

yolov8之后框架统一，训练入口变成了yolo命令。先装ultralytics：

pip install ultralytics

然后训练命令非常简洁：

yolo train data=/path/to/data.yaml model=yolov8s.pt imgsz=640 batch=16 epochs=100 project=runs/train name=cockroach

如果换yolov9、yolov10或者yolo11，只改model参数就行：

yolo train data=/path/to/data.yaml model=yolov9t.pt imgsz=640 batch=16 epochs=100 yolo train data=/path/to/data.yaml model=yolov10n.pt imgsz=640 batch=16 epochs=100 yolo train data=/path/to/data.yaml model=yolo11n.pt imgsz=640 batch=16 epochs=100

注意model不是随便填的，要按各个版本官方release里实际发布的权重文件名来，填错了会直接下载失败。yolov8s.pt是最常用的起步权重，n是nano更小更省显存，t是tiny，c是compact。参数写法上，ultralytics不要求路径前带引号，用等号传参，和yolov5的--key value风格不一样，这是两套入口最容易搞混的地方。另外，yolov7是独立于ultralytics的另一套工程，训练入口也是train.py，参数风格更像yolov5，data.yaml是通用的，命令不能直接照搬yolo，但数据集本身不用改。

还有一个常见问题：第一次训练都要下载预训练权重，下载超时的时候进程会一直卡在Downloading...很久不动。yolov5和ultralytics都支持把pt文件手动放到工程目录下，它检测到本地已有就不会再下载。如果你遇到卡住，直接把权重文件放进当前目录重跑，一般就能跳过下载这一步。

4.3 超参怎么设：batch、imgsz、epochs的取舍

蟑螂目标有个特点：在画面里通常偏小，可能只占几十到一两百像素。对这种小目标，imgsz用640时，小目标在特征图上的像素很少，容易漏检。有条件的话试试1280，但显存占用会变成约4倍，batch就要跟着减半甚至减到4。我的习惯是先640跑通流程，验证没问题再上1280刷一轮精度。

batch size的选择要先看显存。一个粗略估算：imgsz=640时，yolov5s单张图约占2到3G显存，所以12G显存下batch开16比较稳。batch太小会导致BN统计不稳定，loss震荡明显；太大容易OOM。epochs不要无脑调大，建议开EarlyStopping，ultralytics默认的patience是100个epoch没有提升就停。单类数据集如果100个epoch还没看到mAP超过0.8，优先怀疑数据问题而不是加轮数。

4.4 后台训练与日志观察

训练时间通常以小时计，建议用nohup放后台跑：

nohup yolo train data=/path/to/data.yaml model=yolov8s.pt imgsz=640 batch=16 epochs=100 > train.log 2>&1 &

然后随时用tail看进度：

tail -f train.log

日志里每行会打印epoch号、box_loss、cls_loss、mAP50、mAP50-95这些指标。如果box_loss在前10个epoch里没有明显下降，要先回去看数据校验那一步是不是漏了。训练完成后，runs/train/cockroach/目录下有weights子目录，best.pt就是最终要用的权重，val测出来的mAP记录在results.csv里。

5. 避坑：五个最容易翻车的配置细节

这一章写的都是实际训练场景里见过、并且在这类蟑螂或昆虫数据集上高概率复现的问题。每条按现象、原因、解决三个角度说，方便你对应排查。

5.1 训练正常跑完但loss不降，val全背景

现象：训练能跑完，loss下降缓慢，val的mAP一直是0或者接近0，推理结果全是背景框。

原因：最常见是标签没对齐图片。yolov5约定标签放在与images同级的labels目录且按子集对应，而这份数据的标签单独放在labels_yolo下，路径没配对时框架把图像全部当背景训练。

解决：先把labels_yolo下的txt按train/val/test分别软链接到labels/train、labels/val、labels/test，再跑训练。做完后用第3.2节的脚本检查一次，确保有图无标签的数量是0。

5.2 voc转yolo换算时框全部偏移

现象：推理出的框位置明显不对，整体向右下或左上偏移，但宽高比例看着正常。

原因：voc的bndbox给的是像素左上角和右下角，有人转换时直接用xmax除以图片宽当作w，忘了先算(xmax-xmin)再除，也没算中心点，结果框变成从原点出发的长条。

解决：严格按第2.1节表格里的公式算。cx=(xmin+xmax)/2再除以W，w=(xmax-xmin)/W。转换后抽一张图，用opencv把txt坐标画回图像上叠加对比，肉眼确认框的位置和原标注一致再批量训练。

5.3 类别索引和data.yaml的names对不上

现象：训练正常，loss正常，但算出来mAP很低，且混淆矩阵里的类别和实际标的东西对不上。

原因：txt里的第一个数字是类别索引，它对应names列表里的第几个名字。如果标注工具导出时类别ID从1开始，而yaml里的names从第0项对齐，整个模型从头到尾学的是错位标签。

解决：打印labels_yolo里所有出现的类别索引最大值，和nc对比。如果索引最大值等于nc，说明索引是从1开始的，把yaml里nc加1，或者批量把txt的第一列全部减1，二选一，关键是要让索引变成从0开始的连续整数。

5.4 单类数据集mAP显示1.0或全0，感觉不真实

现象：nc=1时，mAP50直接冲到0.99，或者另一头一直是0，中间没有渐变过程。

原因：单类数据集的mAP只统计一个类，数据量少时波动本来就大。而且如果验证集里大部分是纯背景图，没有蟑螂的图会直接拉低指标，反之全是有目标的图，mAP会虚高。

解决：看PR曲线和confusion matrix，别只盯mAP。单类场景里precision和recall比mAP更有参考价值，目标是把confidence阈值调到precision和recall的交点附近，这个在推理阶段做，第6章会说。

5.5 图像尺寸杂乱导致检测框长宽比失真

现象：训练不报错，但推理时蟑螂被框成细长条或压扁形，尤其画面边缘的目标。

原因：数据集里图片如果来自手机拍摄，宽高比不统一，常见做法是letterbox填充灰边保持比例。如果哪个环节用了全图拉伸resize，目标长宽比就变形了，而训练和推理必须用同一种预处理方式。

解决：确认训练和predict都用imgsz参数且框架默认letterbox。不要自己在外部先把图resize成正方形再喂给模型，那等于让模型看变形图。检查推理时输出的结果图，如果蟑螂框明显变形，优先查预处理而不是模型。

6. 推理验证三件事：让模型在测试集上真正认蟑螂

训练完成只是第一步，真正要交付的是一个能落地的检测模型。我一般会在测试集上完整跑一遍验证和推理，重点看三件事：框的位置准不准、置信度阈值挑得对不对、小目标漏检多不多。先跑一遍验证集指标，这一步能看到模型在没见过的图上的真实水平：

yolo val model=runs/train/cockroach/weights/best.pt data=data.yaml imgsz=640

输出里最关键是mAP50和mAP50-95。前者是IoU阈值0.5时的平均精度，适合快速判断模型有没有学到东西；后者更严格，小目标数据集上比前者低0.2以上是正常现象。接着对测试集里的典型图做单张推理：

yolo predict model=runs/train/cockroach/weights/best.pt source=images/test/img_0440_52.jpg conf=0.25 iou=0.5

source可以指向单个文件，也可以指向一个文件夹。conf是置信度阈值，0.25是框架默认，但默认不一定是最好的；跑完打开runs/detect目录下的结果图，如果一堆重叠框，就把iou调高或者conf调高；如果目标明明可见却没框出来，就往下调conf再试。

三件事里我最后看的是小目标。蟑螂数据里如果拍摄距离远，目标可能只有几十个像素高。把这种图单独挑出来看推理结果，如果频繁漏检，回到训练阶段提高imgsz，或者考虑把数据集里小目标较多的图像做切片。这一步没有玄学，就是拿典型图反复看输出。

确认没问题后，把best.pt备份出来，标注好对应的是哪个yaml、哪个imgsz，不同超参训练出来的模型不能混着用，这是我最常犯也是最后悔踩过的坑之一。从那以后我每次拿到新数据集，都强制先跑第3章的校验脚本，再按第4章的参数启动训练，模型出来先跑一遍val再开推理。希望这份蟑螂数据集的拆解能帮你少走几个来回。

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