X光安检数据集上YOLO目标检测训练要点：格式转换与避坑指南

简介：YOLO目标检测X光安检数据集以1000张真实场景X光安检图片为核心，面向需要训练安检场景检测模型的研究者、竞赛选手与开发者。图片由LabelImg标注，标注框质量高，已整理为VOC(xml)、COCO(json)、YOLO(txt)三种格式标签并分别存放，可直接接入YOLO系列模型训练，免去自行转换格式的额外工作。压缩包共2000个文件，主要包含1000个xml标注文件、990个txt标签文件、6个html图文教程、3个python划分脚本和1个yaml配置，整体大小105.65MB。配套内容覆盖YOLO环境搭建（Linux/Windows版本）、训练案例修改思路、训练集/验证集/测试集划分脚本，以及生成ImageSets下txt文件的工具，可快速完成数据准备并复现完整训练流程。目前已有254人学习该资源，适合刚接触YOLO或需要现成多格式安检数据集开展目标检测实验的用户。

1. X光安检数据集为什么值得自己再训一轮YOLO：一千张图的差距在哪

把 YOLO 目标检测落到 X 光安检数据集上，多数人第一步不是卡在模型，而是卡在数据本身。市面上的公开安检数据集要么类别少、要么标注格式只有一种，想跟自己的业务对齐还得从头洗数据；而这份标题里的资源直接把 1000 张图片做成了 VOC、COCO、YOLO 三套标签，配了划分脚本和训练教程，等于把「从数据集到能跑的模型」这条路一次性铺好。它解决的是目标检测项目里最耗时间的三个问题：标注格式不通、训练集划分不科学、新手不知道从哪里敲第一行命令。适合刚接触 YOLO 但已经有明确安检检测需求的人，也适合手里有少量自定义数据、想参照这套流程整理成标准数据集再训练的团队。一千张图不算多，但配合合理的划分策略和迁移学习，足够把一两类违禁品检测跑到能演示、能迭代的程度。

2. 解压后先确认三样东西：VOC、COCO 与 YOLO 标签的实际长相

拿到压缩包先别急着跑训练。我见过太多人把训练命令敲下去，结果发现 yolo_txt 里的类别 ID 和 XML 里 name 对不上，模型在验证集上精度看着很高，实际一测全是错的。这一步先花十分钟把三种格式各自的结构看清楚，后面所有环节都不会跑偏。

2.1 VOC 的 XML 文件：object 节点就是你的训练目标

VOC 格式的标签文件是 XML，每个图片对应一个同名 XML。它最外层是 annotation，里面首先是 folder、filename、size 这些图片信息，然后是一个或多个 object 节点。每个 object 里有一个 name 字段和一个 bndbox 字段，bndbox 里的 xmin、ymin、xmax、ymax 是目标框在像素坐标系里的左上角和右下角坐标。

X 光安检场景下，一个包裹里经常同时出现多个目标，而且物体之间互相遮挡。VOC 格式对这种多目标、多类别的标注很友好，因为它允许一个 XML 里有任意多个 object 节点，而 labelImg 这类标注工具默认输出的也是这种格式。你可以用一段简单的 Python 把 XML 里的关键信息读出来，确认图片文件名和标注框是否真实存在：

import xml.etree.ElementTree as ET import os xml_path = "path/to/your/annotation.xml" tree = ET.parse(xml_path) root = tree.getroot() filename = root.findtext("filename") size = root.find("size") print(f"文件名: {filename}, 图片尺寸: {size.findtext('width')}x{size.findtext('height')}") for obj in root.findall("object"): name = obj.findtext("name") bndbox = obj.find("bndbox") xmin = int(bndbox.findtext("xmin")) ymin = int(bndbox.findtext("ymin")) xmax = int(bndbox.findtext("xmax")) ymax = int(bndbox.findtext("ymax")) print(f"类别: {name}, 坐标: ({xmin}, {ymin}) -> ({xmax}, {ymax})")

这段代码的逻辑很简单：先把 XML 解析成树结构，拿到文件名和图片尺寸，再遍历所有 object 节点输出类别和坐标。注意 bndbox 里的四个值是字符串，必须转成整数才能参与后续计算。如果某个坐标超过图片宽高，说明标注工具在导出时出了问题，需要回头检查原图。

2.2 COCO 的 JSON 注解：从 images 到 annotations 的链式结构

COCO 格式把所有标注集中在一个 JSON 文件里，不是每个图片一个文件。这个 JSON 顶层有五个常用字段：info、licenses、images、annotations、categories。images 是一个列表，每个元素对应一张图片，包含 id、file_name、width、height；annotations 是另一个列表，每个元素对应一个目标框，包含 id、image_id、category_id、bbox、area、iscrowd；categories 则是类别名的索引表。

COCO 的 bbox 跟 VOC 有一个关键区别：它是「左上角 x、左上角 y、宽度 w、高度 h」，不是右下角坐标。X 光图片里目标多、框也密集，用 COCO 格式时最容易犯的错就是把 bbox 当成 VOC 的 xmin、ymin、xmax、ymax 直接用。要知道原图尺寸只能从 images 字段里去查，而不是从标注本身推断：

import json with open("path/to/annotations.json", "r") as f: coco = json.load(f) # 打印前两类的 id 和名称映射 for cat in coco["categories"][:2]: print(f"类别ID {cat['id']} -> {cat['name']}") # 找到第一个标注，定位到它的原图 first_ann = coco["annotations"][0] image_id = first_ann["image_id"] image_info = next(img for img in coco["images"] if img["id"] == image_id) print(f"标注框: {first_ann['bbox']}") print(f"对应图片: {image_info['file_name']}, 尺寸: {image_info['width']}x{image_info['height']}")

这段代码做的事情是建立「标注 → 图片」的关联。COCO 的 annotations 里只有 image_id，不会重复写图片尺寸，所以想验证 bbox 是否越界，必须先回查 images 列表。bbox 里的四个数分别是 x、y、w、h，验证时用「x + w 是否超过 width」来判断，不要下意识去比较 xmax 和 ymax。

2.3 yolo_txt 的五行数字：归一化坐标不能反着读

YOLO 训练真正用的是 text 格式：每个图片对应一个同名 txt 文件，每一行标注一个目标，内容是「类别ID 中心点x 中心点y 宽度 高度」。这五个数全部归一化到 0~1 之前，必须除以图片本身的宽高。类别 ID 从 0 开始计数，对应一个独立的 classes.txt 文件里的类别顺序。

这个格式是三种里边最容易手滑的。很多人拿到 txt 之后把前两个数当成左上角坐标，实际上它们是中心点坐标；还有人忘记归一化，直接用像素值写进去，YOLO 训练时会把所有超出 0~1 范围的框直接丢弃。你可以写个小工具把 txt 转回像素框，直观检查有没有越界：

img_w, img_h = 640, 480 with open("path/to/label.txt", "r") as f: lines = f.readlines() for line in lines: parts = line.strip().split() cls_id = int(parts[0]) x_center, y_center = float(parts[1]), float(parts[2]) w, h = float(parts[3]), float(parts[4]) # 归一化坐标转回像素坐标 x_pixel = x_center * img_w y_pixel = y_center * img_h box_w, box_h = w * img_w, h * img_h print(f"类别: {cls_id}, 像素框: ({x_pixel:.1f}, {y_pixel:.1f}) 尺寸: {box_w:.1f}x{box_h:.1f}") if x_pixel - box_w / 2 < 0 or y_pixel - box_h / 2 < 0: print(" 警告: 目标框越界!")

注意这段代码里的边界检查用的是中心点减半宽、半高，因为 YOLO 格式记录的是中心点而不是左上角。不要觉得这个检查多余，X 光安检图里目标经常紧贴边缘，标注软件自动生成的框偶尔会超出边界几个像素，这种情况训练时不报错但会拉低精度。确认格式没问题之后，再去做划分脚本。

3. 用划分脚本拆训练集与验证集：类别均衡、随机种子与同步落地

标题里的「划分脚本」是整个压缩包里最容易被忽略但最值钱的部分。1000 张图你不可能手动分，也不可能用 Windows 里「新建两个文件夹」的方式拖一遍。划分脚本要做的事不只是随机挑 80% 扔到 train 目录，而是要保证每个类别在训练集和验证集里的分布比例尽量一致，否则可能出现「测试集里全是刀、训练集里全是枪」这种低级错误。

3.1 先按类别分布抽样本：避免小类别全跑进验证集

一个常见的错误写法是random.shuffle(图片列表)然后按比例一刀切。这种全局随机在数据量大的时候问题不大，但在 1000 张图这种规模下，如果某个类别只出现 50 次，随机切分完全可能让它过度集中在某一侧。正确做法是按类别标签做分层采样：先把所有图片按「包含哪些类别」分组，然后每一组内部按 8:1:1 或 7:2:1 的比例抽。

import random from collections import defaultdict random.seed(42) def split_by_stratified_sampling(image_ids: list, labels: dict, ratios=(0.8, 0.1, 0.1)): """ image_ids: 全部图片文件名列表 labels: dict, {图片名: 标注列表}, 每个标注里包含类别字符串 ratios: train/val/test 比例 """ # 先把包含某一类别的图片收集到一个桶里 category_buckets = defaultdict(set) for img_id in image_ids: for label_info in labels[img_id]: category_buckets[label_info["class_name"]].add(img_id) train_set, val_set, test_set = set(), set(), set() for category, img_set in category_buckets.items(): imgs = list(img_set) random.shuffle(imgs) n_train = int(len(imgs) * ratios[0]) n_val = int(len(imgs) * ratios[1]) train_set.update(imgs[:n_train]) val_set.update(imgs[n_train:n_train + n_val]) test_set.update(imgs[n_train + n_val:]) # 有些图片可能包含多个类别，已经在多个桶里出现过 # 这里做兜底排序，保证输出稳定 return sorted(train_set), sorted(val_set), sorted(test_set) train, val, test = split_by_stratified_sampling( image_ids=list(labels.keys()), labels=labels ) print(f"训练集 {len(train)} 张, 验证集 {len(val)} 张, 测试集 {len(test)} 张")

这里关键的一步是random.seed(42)，把随机种子写死。种子不写死的后果是每次运行脚本划分结果都不一样，别人就没法复现你的实验。分层采样用的是「按类别桶分别洗牌再合并」的方式，注意一个图片如果同时含枪和刀两个类别，它会被分别放进两个桶，最终划分时可能被分到不同集合产生冲突，实际工程里要对这种交集情况做一次仲裁，比如「出现冲突时优先归入训练集」。

3.2 把划分结果同步到三种格式目录：一套索引、三处流转

划分脚本的核心输出不是打印行数，而是生成三套目录结构：VOC 训练需要的 JPEGImages + Annotations，COCO 需要的 train.json / val.json，YOLO 需要的 images/train + labels/train。很多开源脚本偷懒只输出一套，你换格式跑另一套代码时还得重新划一遍，类别分布就变了。更合理的做法是只维护一份划分索引，三个目录都按这份索引去复制或软链接文件。

import os import shutil def build_yolo_dirs(train_ids, val_ids, test_ids, out_root, img_src, label_src): for subset in ["train", "val", "test"]: os.makedirs(f"{out_root}/images/{subset}", exist_ok=True) os.makedirs(f"{out_root}/labels/{subset}", exist_ok=True) # 这里只演示 train 集，val/test 逻辑完全一致 for img_id in train_ids: # 图片复制到 images/train，后缀换成 .jpg dst_img = f"{out_root}/images/train/{img_id}" # 标签复制到 labels/train，后缀换成 .txt src_txt = os.path.join(label_src, img_id.replace(".jpg", ".txt")) dst_txt = f"{out_root}/labels/train/{img_id.replace('.jpg', '.txt')}" src_img = os.path.join(img_src, img_id) shutil.copy2(src_img, dst_img) shutil.copy2(src_txt, dst_txt)

这段代码里的img_id是整个流程的「主键」，图片名和标签名必须严格一致才能让 YOLO 训练找到对应关系。注意实际做的时候图片可能不是 JPG，可能是 PNG 或者 TIF，后缀要统一成 YOLO 期望的格式，名称尽量不含中文、空格和特殊符号。如果你的原图本身就是压缩包里的那 1000 张，建议先做一个「统一改文件名」的预处理步骤，比如全部改成img_0001.jpg这种连续编号，比带着原始名跑训练稳得多。

3.3 划分脚本的参数化改造：改比例、改种子、改输出路径

一个好的划分脚本要能复用，不要写死路径和比例。把关键值抽成命令行参数，换个数据集、换个任务只要改参数不用改代码。我一般用 argparse 把三个参数暴露出来：train 集比例、随机种子、输出根目录。

python split_dataset.py \ --images path/to/images \ --labels path/to/labels \ --output path/to/yolo_dataset \ --train-ratio 0.8 \ --val-ratio 0.1 \ --seed 42 \ --format yolo

跑完先别急着训练，花一分钟检查输出：看一眼train/和val/里每类目标的数量，确认没有哪个类别的验证集数量是 0。分类别统计这一步看起来不起眼，却能救你命——如果某个小类全在训练集里，验证集永远看不到它，mAP 曲线再好看都是假的。

4. 用 ultralytics 把 YOLO 训练跑通：环境配置、数据 YAML 与 1000 张图的调参

前面数据整理好了，这一步才真正进入训练环节。标题里带了「训练教程」，估计你也是冲着这个来的。常见做法是用 ultralytics 仓库提供的 CLI 和 Python API，这也是目前 YOLO 新手里完成度最高、踩坑资料最全的一条路，从环境配置到训练命令，每一步网上都有对应的问题记录。

4.1 从零配置环境：不要重复造轮子

环境配置最大的坑不是装不上去，而是装了和别人的版本不一致，报错一堆。我建议直接建一个独立 Python 环境，别用系统自带的 Python 裸跑，避免把全局环境搞乱。新建虚拟环境之后安装 ultralytics 和 pytorch，然后跑一行验证命令确认 GPU 能被识别。

# 创建独立环境，避免污染系统 Python conda create -n yolo python=3.10 -y conda activate yolo # 安装 GPU 版 torch 和 ultralytics pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics # 验证 GPU 可用，同时检查 yolo 命令是否存在 python -c "import torch; print(torch.cuda.is_available())" yolo --help

这里的torch.cuda.is_available()输出 True 才算环境真正合格；如果输出 False，说明安装的是 CPU 版 pytorch，训练速度会慢到一个难以接受的程度。注意 conda 的 Python 版本建议选 3.10 或 3.11，版本太旧会导致很多依赖装不上，版本太新又可能出现编译问题。这一套流程也适用于离线部署机，只是要把 pip install 换成离线 wheel 包安装。

4.2 数据 YAML 与 classes.txt 的对应

ultralytics 训练时不需要你手动写 classes.txt，它读取的是数据集 YAML 里的 names 字段。这个 names 的顺序决定了类别 ID，你在前面划分脚本里转出的 txt 第一列数字必须和这个顺序完全一致。常见数据 YAML 长这样：

path: /absolute/path/to/yolo_dataset train: images/train val: images/val test: images/test nc: 4 names: 0: gun 1: knife 2: lighter 3: bottle

path要用绝对路径，这是新手最容易出问题的地方。如果path写相对路径，YOLO 会在当前工作目录下找images/train，而你的数据实际放在别处，报错找不到图片。另一个容易忽略的点是：names的索引顺序一旦定好，就不要随便增删类别，否则之前的 txt 标注全部作废。你可以在训练前做一次对照脚本，把names输出和 YOLO 标签里的 ID 逐一打印，确认没有错位。

4.3 训练参数怎么设：1000 张图的显存与收敛平衡

1000 张图属于典型的小规模数据集。参数设大了模型过拟合，设小了训练半天不收敛。我一般会用预训练权重起步，而不是从随机权重开始训，因为在 ImageNet 或 COCO 上预训练过的权重已经学会基础纹理和边缘特征，X 光图虽然灰度为主，但底层特征仍然通用。

yolo detect train \ data=/path/to/dataset.yaml \ model=yolov8n.pt \ epochs=150 \ batch=16 \ imgsz=640 \ lr0=0.01 \ patience=30 \ device=0 \ project=/path/to/runs

几个关键参数的含义和调整逻辑：epochs设 150 是因为小数据集需要足够轮次才能看到 mAP 稳定上升，同时用patience=30做早停，避免模型已经不涨了还在空跑；batch要结合显存调整，8GB 显存跑 16 没问题，6GB 就降到 8；imgsz是训练分辨率，X 光安检图细节多，建议从 640 起步，如果显存富余可以调到 768 或 832，小目标检测能力会明显提升；lr0是初始学习率，数据量小的数据集不要用太激进的 0.1，0.01 是稳妥值。这些参数不是拍脑袋定的，而是小数据集 + 迁移学习场景下的默认起点，后面完全可以在跑通后做一次小范围搜索微调。

4.4 训练输出怎么看：loss 曲线和 mAP 不是一回事

训练启动之后会有实时输出，新手最容易盯着看的是那个不断跳动的 loss 值。YOLO 的损失函数包含分类损失 cls_loss、目标框坐标损失 box_loss、以及 DFL 损失，这三项加起来才是总 loss。通过损失函数曲线，你可以判断模型是否欠拟合或过拟合：如果训练 loss 下降但验证 loss 掉头上升，说明模型已经开始背训练集了，这时候应该调大正则或增加数据增强，而不是继续加 epoch。

训练结束后确认三个指标：验证集 mAP@0.5、mAP@0.5:0.95、以及每个类别的单独 AP。X 光安检场景下 mAP@0.5 通常代表「能不能用」，而 mAP@0.5:0.95 更严格，反映的是定位精度。如果你的 mAP@0.5 很高、mAP@0.5:0.95 很低，说明框的位置不够稳，需要回头检查标注质量，特别是 X 光重叠场景下那些互相遮挡的小目标，标注框稍偏半个身位，提升空间就全被埋掉。

5. X光安检模型训练避坑清单：五条血泪经验

数据整理得再好，真正跑训练的时候还是会踩坑。这一章把 X 光安检场景下最容易翻车的五个问题集中写出来，每条都是我见过或者自己处理过的真实案例，按「现象 → 原因 → 解决」的顺序写，后面做项目时可以直接对照排查。

5.1 数据泄漏：同一件行李的多个物体被拆到 train 和 val

现象：训练时 mAP 一路涨到 0.9 以上，验证集也非常好看，但一部署到现场，漏检率高得离谱。原因：划分数据时只按「图片名」随机切分，而同一件行李在不同角度的照片被当成了不同样本，模型在训练里已经「见过」验证集的同一场景。解决：划分前先按行李编号或拍摄批次分组，同一组内的图片全部进同一个子集。如果压缩包没有这个分组信息，至少把连续拍摄的同源图片视作一组，保证最小划分单位是「一个场景」而不是「一张图」。

5.2 灰度图增强：增强完的图颜色通道和你想象的不一样

现象：训练数据增强开启了 HSV 扰动，loss 不降反升，验证集 mAP 很稳定但精确率暴跌。原因：X 光安检图是单通道灰度图，很多增强脚本先把它当成三通道处理，HSL 操作把灰度图的「明度」当成了「饱和度」强行拉偏，噪声被无限放大。解决：处理单通道图时关掉色彩扰动，只用随机旋转、平移、缩放、翻转这类几何增强；如果一定要用 color jitter，先把单通道灰度图复制成三通道再做增强，最后训练时再用灰度预处理回到单通道。

5.3 小目标漏检：刀片、打火机往往只有十几个像素

现象：loss 收敛正常，模型能认出大瓶装液体，但对画面角落的小刀片完全无感，召回率极低。原因：X 光安检图视野大、目标占比小，默认 640 分辨率下一个小目标可能只有 20×20 像素，特征经过几次下采样之后就没了。解决：第一优先把 imgsz 提到 832 或 1024，让模型输入看到更多细节；第二是在自制数据集上检查目标面积分布，如果大量目标小于 32×32，考虑在数据 YAML 里开启小目标增强，或者直接使用专门优化过小目标检测的 YOLO 变体版本，不用执着于某个具体的大版本号。

5.4 类别 ID 错位：txt 第一列不是你想的那个类别

现象：训练代码不报错，训练出的模型把枪识别成刀，打开日志发现类别名和标注 ID 对不上。原因：VOC 转 YOLO 时用了 ASCII 排序，python 字典遍历顺序和 classes.txt 不一致，导致 ID 顺序错乱。解决：转格式脚本里把类别顺序写成固定列表，比如["gun", "knife", "lighter", "bottle"]，之后所有环节——包括数据 YAML、标注脚本、验证脚本——都用这个列表作为唯一真源，禁止任何地方再做一次set()去重排序。

5.5 16 位深度图直接喂给 YOLO：黑屏或过曝

现象：图片在文件夹里双击能看到内容，但训练时读取出来全是黑的，或者目标区域过曝白茫茫一片。原因：安检设备导出的图经常是 16 位灰度或 DICOM 格式，像素范围 0~65535，而 YOLO 的预处理期望 8 位 0~255，高位数据被直接截断。解决：先把所以图转成 8 位 PNG，转换时做一次直方图拉伸或分位数裁剪，比如把 1% 到 99% 分位之间的像素映射到 0~255，然后再参与划分和训练。这也是拿到新数据集后第一件要做的预处理，别等到训练结果诡异才回头查。

6. 标签一致性校验脚本：三种格式对齐的最后一公里

数据在 VOC、COCO、YOLO 三种格式之间反复转换之后，极容易出现「三份标注描述的不是同一个目标」的情况。我习惯在每次转换后跑一遍一致性校验脚本，它的逻辑是从三份标注里分别解析出每张图片的目标框集合，然后比对数量和坐标。如果同一张图三种格式解析出的目标数不一样，或者对应框的 IoU 低于 0.9，就直接报错——宁可在这里花 30 秒，也不要在训练完 150 个 epoch 之后才发现标注源就有问题。

def check_consistency(image_list, voc_parser, coco_parser, yolo_parser, iou_threshold=0.9): """ image_list: 所有参与训练的图片名 三个 parser 分别接收图片名，返回 (类别, bbox) 列表，bbox 统一为像素格式 """ for img_name in image_list: voc_boxes = voc_parser(img_name) coco_boxes = coco_parser(img_name) yolo_boxes = yolo_parser(img_name) if not (len(voc_boxes) == len(coco_boxes) == len(yolo_boxes)): print(f"目标数量不一致: {img_name}") # 按类别分组再比较，因为 bbox 顺序可能不同 for idx, box in enumerate(zip(voc_boxes, coco_boxes, yolo_boxes)): v_box, c_box, y_box = box # 计算每两个框之间的 IoU，低于阈值就报警 iou_vc = compute_iou(v_box[1], c_box[1]) iou_vy = compute_iou(v_box[1], y_box[1]) if iou_vc < iou_threshold or iou_vy < iou_threshold: print(f"坐标偏差过大: {img_name}, 目标 {idx}, IoU={min(iou_vc, iou_vy):.4f}")

这段代码的算法核心是「按图遍历、按目标对比」。因为三种格式的标注顺序往往不同，所以不能按下标直接比，必须先按类别分组，再组内排序，最后两两计算 IoU。iou_threshold设 0.9 是合理的——小数点后一两位的偏差可能是标注软件四舍五入造成的，低于 0.8 就说明两个格式之间的坐标变换出问题了。

我自己做数据集迭代的时候，最深的体会是「格式转换脚本一定要留底」。每拿一个新数据集，先跑一遍格式检查、再跑一遍一致性校验，确认没问题才进入训练。这个习惯帮我省掉的返工时间远超写脚本的十分钟。X 光安检数据集的标注成本高、获取渠道少，1000 张图已经是很好的起点，把这份数据维护成「一套真源、三份视图」的体系，后续每加一批新图片都走固定的转化和校验流程，模型迭代才能又快又稳。希望你也能从这套流程里少踩几个坑。

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