计算机视觉 / 系统课时

生成数据集报告

生成数据集报告

训练前先把数据集“量化”一次,可以比肉眼抽查更早发现类别失衡、目标过小、单图目标过密和标签异常。本节用一个可重复执行的脚本扫描 YOLO 检测数据集,并把关键统计与异常样本汇总为 JSON 报告,方便后续训练前验收。

学习目标

  • 统计各类别实例数量、单图标签密度和目标尺寸分布
  • 识别缺失标签、格式错误、越界框等需要人工复核的样本
  • 把报告结果转化为训练前的数据质量检查项

报告应该回答什么

一份有用的数据集报告至少要回答四类问题。第一,类别是否严重失衡;第二,目标在图像中的相对尺寸是否过小或跨度过大;第三,每张图通常有多少个目标;第四,标签文件是否存在格式或坐标异常。

对 YOLO 检测标签,目标框通常写成 class_id x_center y_center width height,后四项是相对图像宽高归一化后的数值。报告中的尺寸统计因此不依赖原始分辨率,适合先做全局分布检查;真正决定训练输入细节时,再结合原图尺寸与训练 imgsz 判断。

生成可重复的数据集报告

下面脚本默认扫描 <PATH>/images/train 与 <PATH>/labels/train,只依赖 Python 标准库。它把没有对应标签文件的图像单独计数,不直接判定为错误,因为它们也可能是合法的负样本。

python
from collections import Counter
from pathlib import Path
from statistics import mean, median
import json
import sys

IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".bmp", ".webp"}

def percentile(values, ratio):
    if not values:
        return None
    ordered = sorted(values)
    index = min(len(ordered) - 1, int((len(ordered) - 1) * ratio))
    return ordered[index]

def main():
    if len(sys.argv) != 2:
        raise SystemExit("usage: python dataset_report.py <dataset-root>")

    root = Path(sys.argv[1])
    image_dir = root / "images" / "train"
    label_dir = root / "labels" / "train"

    images = sorted(
        p for p in image_dir.rglob("*")
        if p.is_file() and p.suffix.lower() in IMAGE_EXTS
    )
    if not images:
        raise SystemExit(f"no images found under {image_dir}")

    class_counts = Counter()
    box_widths, box_heights = [], []
    labels_per_image = []
    anomalies = []
    unlabeled_images = 0

    for image in images:
        relative_label = image.relative_to(image_dir).with_suffix(".txt")
        label_file = label_dir / relative_label

        if not label_file.exists():
            unlabeled_images += 1
            labels_per_image.append(0)
            continue

        valid_boxes = 0
        for line_no, raw in enumerate(
            label_file.read_text(encoding="utf-8").splitlines(), start=1
        ):
            if not raw.strip():
                continue

            parts = raw.split()
            if len(parts) != 5:
                anomalies.append(f"{label_file}:{line_no}: field_count")
                continue

            try:
                cls, x, y, w, h = map(float, parts)
            except ValueError:
                anomalies.append(f"{label_file}:{line_no}: non_numeric")
                continue

            if cls < 0 or not cls.is_integer():
                anomalies.append(f"{label_file}:{line_no}: invalid_class")
                continue
            if not (0 <= x <= 1 and 0 <= y <= 1 and 0 < w <= 1 and 0 < h <= 1):
                anomalies.append(f"{label_file}:{line_no}: normalized_range")
                continue
            if x - w / 2 < 0 or x + w / 2 > 1 or y - h / 2 < 0 or y + h / 2 > 1:
                anomalies.append(f"{label_file}:{line_no}: box_crosses_image")
                continue

            class_counts[int(cls)] += 1
            box_widths.append(w)
            box_heights.append(h)
            valid_boxes += 1

        labels_per_image.append(valid_boxes)

    report = {
        "images": len(images),
        "unlabeled_images": unlabeled_images,
        "boxes": sum(class_counts.values()),
        "labels_per_image_avg": round(mean(labels_per_image), 3),
        "class_counts": dict(sorted(class_counts.items())),
        "bbox_width_median": round(median(box_widths), 4) if box_widths else None,
        "bbox_width_p90": round(percentile(box_widths, 0.9), 4) if box_widths else None,
        "bbox_height_median": round(median(box_heights), 4) if box_heights else None,
        "bbox_height_p90": round(percentile(box_heights, 0.9), 4) if box_heights else None,
        "anomaly_count": len(anomalies),
        "anomaly_samples": anomalies[:20],
    }
    print(json.dumps(report, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

把脚本保存为 dataset_report.py 后执行:

bash
python dataset_report.py <PATH>

其中 <PATH> 替换为数据集根目录。实际统计值随数据集变化。

预期输出:

json
{
  "images": "<VALUE>",
  "unlabeled_images": "<VALUE>",
  "boxes": "<VALUE>",
  "labels_per_image_avg": "<VALUE>",
  "class_counts": {
    "0": "<VALUE>"
  },
  "bbox_width_median": "<VALUE>",
  "bbox_width_p90": "<VALUE>",
  "bbox_height_median": "<VALUE>",
  "bbox_height_p90": "<VALUE>",
  "anomaly_count": "<VALUE>",
  "anomaly_samples": []
}

解读类别、尺寸和标签密度

先看 class_counts。不要只比较绝对数量,还要关注最大类别与最小类别的倍数差,以及少数类是否少到无法覆盖不同场景。明显失衡时,应优先补数据或调整采样策略,而不是直接依赖训练参数“补救”。

再看目标宽高的中位数与 P90。中位数很小说明多数目标在图像中占比低,训练时需要重点验证输入尺寸、裁剪策略和小目标召回;P90 与中位数差距很大,则说明目标尺度跨度大,增强策略和分辨率需要更谨慎。

labels_per_image_avg 反映标签密度。高密度场景通常伴随遮挡、相邻框接近和小目标增多,应在验证集中保留足够的高密度样本,避免总体指标掩盖拥挤场景下的错误。

处理异常样本

anomaly_samples 只保留前 20 条,便于快速定位。field_count 和 non_numeric 属于格式错误;normalized_range 表示归一化值本身非法;box_crosses_image 表示由中心点和宽高还原后的框越过图像边界。

unlabeled_images 不能机械地当作脏数据。如果任务允许“图中没有任何目标”的负样本,这类图片可能完全合法;如果数据规范要求每张训练图都必须包含目标,再把它们列入待修复清单。类别编号也应继续与数据集配置中的类别数和名称逐项核对,避免标签 ID 与配置错位。

把报告变成训练门槛

建议每次数据清洗、增量标注或重新划分训练集后重新生成报告,并保留前后两份结果。真正值得设为硬门槛的是格式错误、非法坐标和类别配置错位;类别比例、目标尺寸和标签密度更适合作为趋势指标,由业务场景决定是否需要处理。

这样做的价值不只是得到一份统计表,而是把“感觉数据没问题”变成可重复验证的检查流程。训练指标异常时,也可以先回到报告确认数据分布是否发生了变化,再进入模型和超参数排查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成数据集报告

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通