项目关键词YOLO 数据集质检、标签格式检查、类别统计、目标框可视化、训练集划分、data.yaml 自动生成、Python 项目实战真实测试数据本文使用 Ultralytics 官方 COCO8 数据集图像来自 COCO train2017 子集标签为 YOLO 检测格式。数据说明见 Ultralytics COCO8 官方文档下载来源为 Ultralytics assets/coco8.zip。摘要做 YOLO 目标检测项目时很多问题并不是模型本身造成的而是训练前的数据集已经存在隐患标签文件少列、类别编号越界、坐标没有归一化、图片和标签对不上、空标签混入、某些类别样本太少等。它们有时会直接让训练报错有时不会马上暴露却会影响收敛、召回率和后续评估。本文整理的是一个完整可运行的 Python 数据集质检工具。它不依赖 GPU不需要加载 YOLO 权重也不训练模型而是聚焦训练前的数据准备扫描images/和labels/校验 YOLO 标签格式统计类别和目标框分布生成可视化图表导出问题表格并自动划分train/val/test目录和data.yaml。为了避免只展示演示图本文实际下载并运行了 Ultralytics COCO8 真实数据集。COCO8 包含 8 张真实图像和对应 YOLO 标签本次运行解析出 30 个有效目标框检查结果为 0 个错误、0 个警告并生成了 HTML 报告、Markdown 报告、CSV 明细、统计图、标注样例图和可直接进入训练流程的划分目录。真实数据与运行环境本文的验证数据来自 Ultralytics COCO8它是一个很小但真实的目标检测数据集适合验证数据加载、标签解析和训练前流程是否能跑通。下载后的目录中包含images/train、images/val、labels/train、labels/val每张图像都有同名.txtYOLO 标签文件。下面是本次运行用到的 8 张真实原图。可以看到它们不是单一场景截图而是包含食物、动物、人物、室内外环境等不同目标和尺度适合用来验证类别统计、框面积分布和中心热力图。运行环境为 Python 3.10依赖为pillow、matplotlib、PyYAML、numpy。项目本身是命令行工具运行命令如下python main.py\--dataset-root external_data/coco8\--classes-path data.yaml\--output-dir outputs/coco8_report\--copy-results\--sample-count4终端实测摘要如下Images: 8 Valid boxes: 30 Classes: 80 - person, bicycle, car, ... Errors: 0 Warnings: 0 Report: outputs/coco8_report/report.html Split output: outputs/coco8_report/split_dataset运行完成后打开生成的report.html可以看到和终端摘要一致的图像数量、有效目标框、错误数和警告数。下图是本次运行得到的报告页首屏。功能设计与处理流程项目的目标不是“再训练一个 YOLO 模型”而是把训练前最容易被忽略的数据体检流程做成可复用工具。它主要回答这些问题图像和标签是否一一对应标签是否满足五列 YOLO 格式类别编号是否在合法范围内坐标是否归一化目标框面积和位置是否异常类别分布是否明显不均衡划分后的数据能不能直接交给训练程序。下面这张流程图根据实际项目流程整理图中节点全部对应代码里的真实处理步骤输入原始 YOLO 数据集后先做文件扫描再做标签校验随后汇总统计、自动划分最后输出报告和训练目录。代码层面main.py负责解析命令行参数并串联流程config.py负责配置validator.py负责标签读取和问题收集statistics.py汇总图像、类别、框面积等指标visualizer.py生成图表和标注样例splitter.py导出划分后的 YOLO 目录report.py写出 HTML 和 Markdown 报告。系统模块关系如下。图中模块和输出物都与项目实际产物一致包括网页报告、正文报告、表格明细、统计图、标注样例和data.yaml。项目目录结构保持清晰便于二次开发yolo_dataset_quality_tool/ ├── main.py ├── run_demo.py ├── requirements.txt ├── configs/ ├── src/yolo_qc/ │ ├── config.py │ ├── validator.py │ ├── statistics.py │ ├── visualizer.py │ ├── splitter.py │ └── report.py ├── external_data/coco8/ ├── outputs/coco8_report/ └── images/results/真实运行结果解析本次 COCO8 检查结果很干净8 张图片都能找到对应标签解析出 30 个有效目标框没有缺失标签、孤儿标签、空标签、格式错误、坐标越界或类别编号越界。这个总览图由项目代码直接生成适合先看整体健康状态。类别分布图显示本次 30 个目标框覆盖了 12 个实际出现的类别。其中person有 10 个框orange有 4 个框bowl有 3 个框其他类别数量较少。对于小数据集来说这种统计可以快速提示它适合作为流程验证集但不适合作为正式训练集直接追求泛化效果。目标中心热力图用于观察标注框中心点在图像中的空间分布。COCO8 的样本很少所以热力图不会像大数据集那样平滑但它仍然能证明程序确实读取了每个框的中心坐标并把标签信息转成了空间统计。框面积分布可以帮助判断数据集中大目标、小目标的比例。本次平均框面积比例约为 0.15545既有占画面较大的动物、容器目标也有较小的人物或局部目标。实际项目中如果大量框面积过小就需要检查输入分辨率、标注策略和小目标训练方案。图像尺寸分布用于发现缩略图、异常长宽比或混入的错误图片。COCO8 是真实图像子集尺寸并不完全一致工具会把尺寸统计可视化方便训练前确认数据来源是否符合预期。自动划分结果为 6 张训练集、1 张验证集、1 张测试集。因为样本只有 8 张这里的划分更适合作为流程验证而不是模型评估依据真正训练时建议使用更大的数据集并结合类别分布重新检查划分是否均衡。下面是项目从真实标签中绘制出的标注样例。第一张图展示了多目标、多类别、不同尺度目标框的叠加效果说明程序并不是只统计文本而是能把 YOLO 归一化坐标还原到图像像素空间。第二张样例中两只长颈鹿目标框大小差异明显能够检验大框和小框同时存在时的绘制效果。第三张样例展示了花瓶和盆栽两个类别背景较复杂适合观察标签框是否与真实物体边界大致对齐。第四张样例是斑马场景目标框覆盖主体区域能够验证单目标图像的标注可视化效果。代码运行与输出文件工具支持两种典型用法。第一种是快速运行内置演示数据python run_demo.py第二种是检查自己的 YOLO 数据集python main.py\--dataset-root your_dataset\--images-dir images\--labels-dir labels\--classes-path classes.txt\--output-dir outputs/my_reportWindows 命令行可以写成python main.py ^ --dataset-root your_dataset ^ --images-dir images ^ --labels-dir labels ^ --classes-path classes.txt ^ --output-dir outputs/my_report常用参数包括--train-ratio 训练集比例默认 0.70 --val-ratio 验证集比例默认 0.20 --test-ratio 测试集比例默认 0.10 --seed 随机种子默认 42 --min-box-area 小目标面积告警阈值 --strict-split 划分时排除存在错误的图片 --no-empty 划分时排除空标签图片 --no-split 只检查不导出划分数据集 --copy-results 把关键结果图复制到博客展示目录本次真实运行后outputs/coco8_report/中生成了这些文件report.html 可视化网页报告 report.md Markdown 报告 report.json 统计摘要 split_summary.json 划分摘要 tables/boxes.csv 目标框明细 tables/images.csv 图像级明细 tables/issues.csv 问题清单 figures/ 统计图 samples/ 标注样例图 split_dataset/data.yaml 自动生成的训练配置 split_dataset/images/ 划分后的图像 split_dataset/labels/ 划分后的标签其中tables/issues.csv在本次 COCO8 测试中为空问题表说明没有发现错误或警告如果换成自建数据集常见问题会以问题码形式记录便于后续定位和修复。适用场景与二次开发这个项目最适合放在 YOLO 训练之前作为数据集进入训练流程前的第一道检查。对于课程设计、毕业设计、企业内部数据治理和 CSDN 项目交付它的价值也比较明确不用 GPU不依赖大模型权重运行速度快输出物完整能把“数据是否能训练”这件事讲清楚。二次开发时可以继续扩展这些方向增加重复图片、模糊图片、过暗图片检测。增加类别级别的训练/验证/测试均衡性评分。支持 COCO JSON、VOC XML 与 YOLO TXT 之间的互转检查。增加 Web 页面上传数据集并在线生成报告。把问题表格接入标注平台形成“发现问题到修复问题”的闭环。需要注意的是数据集质检工具不能替代人工审核也不能保证模型一定训练得好。它的作用是把训练前最基础、最容易遗漏的问题提前暴露出来文件是否成对、标签是否能解析、类别是否合理、框是否落在图像里、划分结果是否可用。只要这一步做扎实后面的训练、调参和评估才有意义。