计算机视觉 / 系统课时
生成数据集报告
生成数据集报告
训练前先把数据集“量化”一次,可以比肉眼抽查更早发现类别失衡、目标过小、单图目标过密和标签异常。本节用一个可重复执行的脚本扫描 YOLO 检测数据集,并把关键统计与异常样本汇总为 JSON 报告,方便后续训练前验收。
学习目标
- 统计各类别实例数量、单图标签密度和目标尺寸分布
- 识别缺失标签、格式错误、越界框等需要人工复核的样本
- 把报告结果转化为训练前的数据质量检查项
报告应该回答什么
一份有用的数据集报告至少要回答四类问题。第一,类别是否严重失衡;第二,目标在图像中的相对尺寸是否过小或跨度过大;第三,每张图通常有多少个目标;第四,标签文件是否存在格式或坐标异常。
对 YOLO 检测标签,目标框通常写成 class_id x_center y_center width height,后四项是相对图像宽高归一化后的数值。报告中的尺寸统计因此不依赖原始分辨率,适合先做全局分布检查;真正决定训练输入细节时,再结合原图尺寸与训练 imgsz 判断。
生成可重复的数据集报告
下面脚本默认扫描 <PATH>/images/train 与 <PATH>/labels/train,只依赖 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 后执行:
python dataset_report.py <PATH>其中 <PATH> 替换为数据集根目录。实际统计值随数据集变化。
预期输出:
{
"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 与配置错位。
把报告变成训练门槛
建议每次数据清洗、增量标注或重新划分训练集后重新生成报告,并保留前后两份结果。真正值得设为硬门槛的是格式错误、非法坐标和类别配置错位;类别比例、目标尺寸和标签密度更适合作为趋势指标,由业务场景决定是否需要处理。
这样做的价值不只是得到一份统计表,而是把“感觉数据没问题”变成可重复验证的检查流程。训练指标异常时,也可以先回到报告确认数据分布是否发生了变化,再进入模型和超参数排查。