简介：一套面向集装箱表面缺陷检测的标注数据集，为工业质检与计算机视觉目标检测场景提供基准数据。数据覆盖凹坑、孔洞、锈蚀三类缺陷，对应4127张图片的标注信息，标注框总数达10117个，其中凹坑框4943个、孔洞框1218个、锈蚀框3956个，每类缺陷均有独立标签，便于分类训练与评估。压缩包共2000个文件，核心为1999个XML标注文件，另附TXT说明文档，整体大小约163.61MB，文件结构清晰。每个缺陷目标均采用labelImg工具以矩形框精确标注，标注规则统一，边界框坐标与类别信息完整、格式标准，可直接转换为YOLO、Faster R-CNN等主流检测模型所需的训练样本。已有348人学习，适合需要快速获取高质量表面缺陷数据集的算法研究者与工业视觉开发者，可有效缩短数据采集与标注周期。
1. 集装箱缺陷检测数据集：压缩包里的双格式标注到底怎么用
4127张图、3个类别、VOC和YOLO双格式、一个7z压缩包——这个数据集的标题已经把你要做的事基本写完了：解压、看标签、喂给YOLO训练。集装箱缺陷检测在港口、物流园、堆场视觉项目里是典型的高频需求，做安全检测、箱体损伤定损、自动化验箱的团队都绕不开它。这个包的价值在于同时给了VOC和YOLO两种标注，意味着你既可以用YOLO系列快速出基线，也能用VOC格式转成Faster R-CNN、SSD或mmdetection的输入，不用自己重新标一张图。
适合谁用？手里没有集装箱图片的算法工程师，想验证YOLO训练流程的学生，以及需要快速给客户出demo的交付团队。要注意一点：数据集的3个类别具体是哪三种缺陷，解压后以labels目录里的类名或data.yaml为准，不同打包者的命名习惯差别很大，别拿到手就按经验猜。下面从格式解读开始，一步步把它变成能正常跑训练的工程目录。
2. 数据集里有什么：VOC与YOLO标注格式的差异和选型
2.1 4127张样本是什么规模：单类还是多场景
4127张在工业缺陷检测里属于中等偏小的规模。对比公开数据集，COCO有十几万张，但集装箱缺陷这种垂直场景能凑到四千多张已经能覆盖常见锈蚀、破损、变形等表现。关键是这个数量决定了训练策略：直接随机初始化训练很难收敛，必须用预训练权重做迁移学习；数据增强的强度要比通用检测大一些。
这个体量也暗示了类别分布大概率不均衡。工业采集中大面积锈蚀容易拍到，小目标的开焊、凹坑往往只有几十个像素，框的数量可能相差十倍。拿到包后第一件事不是训练，而是统计每个类别的标签数量。常见做法是在labels目录下执行统计命令：
for i in 0 1 2; do count=$(grep -h "^$i " labels/*.txt | wc -l) echo "class $i: $count" done这段命令遍历0、1、2三个类别id，在labels目录的所有TXT文件里统计以对应数字开头的行数。TXT每行代表一个标注框，行首数字就是类别id。如果输出的三个数字差距超过5倍，后面训练时要考虑类别加权，否则样本多的类会垄断loss。执行前注意把labels路径换成你解压后的实际路径。
2.2 VOC格式目录结构与XML标注字段解读
VOC格式的结构固定，解压后通常能看到JPEGImages、Annotations、ImageSets三个目录。JPEGImages放原图，Annotations放同名XML标注文件，ImageSets/Main里是train.txt、val.txt这类划分文件，内容是图片文件名（不带后缀）的列表。这套结构从PASCAL VOC沿用至今，很多检测框架可以直接读取。
XML文件里最关键的是object节点，每个object对应一个标注框。拿一个集装箱缺陷样本举例：
<annotation> <size> <width>1920</width> <height>1080</height> <depth>3</depth> </size> <object> <name>dent</name> <difficult>0</difficult> <bndbox> <xmin>152</xmin> <ymin>410</ymin> <xmax>640</xmax> <ymax>720</ymax> </bndbox> </object> </annotation>size节点下的width和height是图像原始尺寸，bndbox里的四个值分别是框的左上角x、左上角y、右下角x、右下角y，单位是像素。注意XML里没有归一化，坐标值直接对应原图像素。判读时有一个常见误区：xmin/ymin不一定是框的最小值，如果标注工具输出不规范，可能出现xmin>xmax的情况，训练前要做一次交换或过滤。difficult字段表示该样本是否难以识别，部分框架会忽略difficult=1的样本。
2.3 YOLO格式目录结构与TXT归一化坐标换算
YOLO格式是另一个世界。目录结构通常是images和labels两个平级目录，图片放在images，同名TXT放在labels。TXT每行五个数字：第一个是类别id，从0开始；后面四个是归一化坐标。一行代表一个框：
0 0.412 0.410 0.254 0.287四个数字依次是框中心x、中心y、框宽、框高，全部除以图像宽高做了归一化，取值在0到1之间。所以如果你的图像是1920×1080，这个框对应的像素坐标是：中心点x=0.412×1920≈791，中心点y=0.410×1080≈443，宽=0.254×1920≈488，高=0.287×1080≈310。
VOC和YOLO之间的换算关系可以记成一组公式：
cx = (xmin + xmax) / 2 / width cy = (ymin + ymax) / 2 / height w = (xmax - xmin) / width h = (ymax - ymin) / height反过来从YOLO转VOC也是同一组公式逆推。很多数据集打包者会同时提供两种格式，但要注意：两个目录如果分开存放，训练时只喂YOLO格式即可，VOC格式留作标注审查——因为XML可读性更好，发现TXT有异常时对照XML更容易定位是哪张图、哪个框出了问题。不要同时把两种格式的标签都放进一个训练目录，YOLO训练流程只会读取与图片同名的TXT文件，多余的XML不会报错但会干扰你排查。
3. 解压7z压缩包：三平台落地命令与文件完整性校验
3.1 Linux、macOS、Windows解压7z的最小命令
7z不是系统自带的压缩格式，三平台都需要先装工具。Linux下，Debian/Ubuntu用apt装p7zip-full，CentOS/RHEL用yum装p7zip和p7zip-plugins：
sudo apt install p7zip-full # Debian / Ubuntu sudo yum install p7zip p7zip-plugins # CentOS / RHEL装完直接解压：
7z x container_defect_dataset.7zx命令会保留压缩包内的完整目录结构。如果你只需要看压缩包里有什么，先用l命令列目录，确认结构后再解压，避免把一堆不知道哪来的文件散到当前目录：
7z l container_defect_dataset.7zmacOS用Homebrew装p7zip，命令一样。Windows最简单的方式是装7-Zip，右键“解压到当前文件夹”就行。但命令行方式在大批量处理时更可控，PowerShell里这样调用：
& "C:\Program Files\7-Zip\7z.exe" x "D:\data\container_defect_dataset.7z" -o"D:\data\container_output"-o参数指定解压输出目录，注意-o后面没有空格。命令行方式比右键多一个好处：解压日志会逐条列出文件，哪个文件报错可以直接看到。如果你的压缩包设了密码，尽量不要在命令行里直接写-p密码——shell的历史记录会记住它。先不带密码执行，等交互提示再输入。
3.2 解压后先做三件事：图片可读、标签可解析、文件一一对应
解压完成不等于数据可用。我习惯先跑一个三连校验：图片能不能被解码、XML/TXT能不能被解析、图片和标签是否一一对应。跳过这一步直接训练，后面大概率会翻车在某个不知道哪来的损坏文件上。
图片解码校验用Python最直接：
import os from PIL import Image img_dir = "JPEGImages" broken = [] for name in os.listdir(img_dir): if not name.lower().endswith((".jpg", ".jpeg", ".png")): continue try: img = Image.open(os.path.join(img_dir, name)) img.verify() except Exception as e: broken.append((name, str(e))) print("broken images:", len(broken)) for item in broken[:10]: print(item)verify()方法只校验文件头和数据完整性，不会真正解码，速度很快。如果broken列表不为空，优先重新下载对应文件，别自己裁剪修复——一张损坏图在训练时会导致数据加载中断，而且报错信息不直观。接着校验TXT标签的数值范围，这一步直接决定训练会不会出nan：
import os label_dir = "labels" bad_files = [] for name in os.listdir(label_dir): if not name.endswith(".txt"): continue with open(os.path.join(label_dir, name)) as f: for line in f: parts = line.strip().split() if len(parts) != 5: bad_files.append((name, "field count != 5", line)) 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 or w <= 0 or h <= 0: bad_files.append((name, "out of range or zero size", line)) print("bad label files:", len(bad_files)) for item in bad_files[:20]: print(item)这个脚本逐行检查五个字段是否齐全、归一化坐标是否在0到1之间、框的宽高是否为正。w=0或h=0的框是YOLO训练的定时炸弹，反向传播时梯度会变成非法值。最后做图片和标签的对应关系检查，用集合差集一眼就能看出谁多谁少：
img_names = {os.path.splitext(f)[0] for f in os.listdir("images") if f.lower().endswith((".jpg", ".png"))} label_names = {os.path.splitext(f)[0] for f in os.listdir("labels") if f.endswith(".txt")} print("images without labels:", len(img_names - label_names)) print("labels without images:", len(label_names - img_names))正常情况两个差集都应为空。如果出现“labels without images”，说明这张图的图片文件缺失，训练时dataloader会报FileNotFoundError，且错误信息可能指向完全不相关的文件，排查起来很费劲。
4. 把数据集接入YOLO训练：目录调整、data.yaml与train/val划分
4.1 目录结构重排：YOLOv5/v8约定的数据组织方式
YOLOv5和YOLOv8对数据目录的约定一致：images和labels两个平级目录，图片和标签文件名相同（后缀不同），然后在一个YAML文件里指定路径。如果压缩包里的YOLO格式目录已经是这种结构，直接跳过这一步。如果不是，需要把图片和标签各自归拢到一起。常见做法是用软链接而不是复制文件，省磁盘且速度快：
mkdir -p datasets/container_defect ln -s /path/to/original_images datasets/container_defect/images ln -s /path/to/original_labels datasets/container_defect/labels软链接的坑在于：如果路径写错，YOLO训练时报错信息是“No such file or directory”，但不会告诉你链接断了，检查起来比较隐蔽。所以我一般倾向于复制而不是链接，尤其当原始目录结构混杂的时候：
mkdir -p datasets/container_defect/images datasets/container_defect/labels cp JPEGImages/*.jpg datasets/container_defect/images/ cp labels/*.txt datasets/container_defect/labels/训练集和验证集的划分有两种方式：一种是在YAML里分别指定train和val的目录或文件列表，另一种是直接按目录划分。我建议用文件列表方式，灵活且可复现——把划分结果写进txt，跑多次实验时保证每次用的都是同一份列表。划分脚本：
import os import random base_dir = "datasets/container_defect" image_dir = os.path.join(base_dir, "images") names = [os.path.splitext(f)[0] for f in os.listdir(image_dir) if f.endswith(".jpg")] random.seed(42) random.shuffle(names) split = int(len(names) * 0.8) train_names, val_names = names[:split], names[split:] with open(os.path.join(base_dir, "train.txt"), "w") as f: f.write("\n".join(f"{base_dir}/images/{n}.jpg" for n in train_names) + "\n") with open(os.path.join(base_dir, "val.txt"), "w") as f: f.write("\n".join(f"{base_dir}/images/{n}.jpg" for n in val_names) + "\n") print(f"train: {len(train_names)}, val: {len(val_names)}")80/20划分在4127张的规模下是常见起点。如果某个类别的样本很少，可以考虑按类别分层划分——先按类别id分组，再从每组里按比例抽，保证验证集里每个类都存在。随机划分在小样本下容易出现某个类别在验证集里只有几张的情况，导致验证mAP波动很大。这个脚本里我把random.seed固定为42，保证每次运行划分结果一致，排查问题时不会因为数据顺序变化引入额外变量。
4.2 data.yaml配置与预训练权重选择
data.yaml是YOLO训练的总入口，内容很简短但每个字段都关键：
path: /absolute/path/to/container_defect train: train.txt val: val.txt nc: 3 names: 0: dent 1: rust 2: crackpath必须是绝对路径或相对YOLO项目根目录的路径，train和val填train.txt和val.txt时，YOLO会基于path拼接。nc是类别数，标题说3类别就填3。names列表的顺序就是模型输出类别的顺序，这个顺序必须和标签TXT里第一列的数字完全一致——0对应names里第0个类，1对应第1个类，以此类推。
names里的类名从哪里来？解压后看labels里每个TXT第一列数字的统计，再看VOC的XML里object节点的name字段，两边对照。如果labels里数字1对应XML里的“rust”，names[1]就必须写rust。写错不会报错，但训练出来的模型预测结果全部错位，而且loss曲线看起来完全正常——这类错位是最阴间的bug。
预训练权重方面，YOLOv5和v8在首次运行时会自动下载coco预训练权重。网络条件不允许的情况下，在另一台机器上提前下载好pt文件，拷到项目根目录再训练。YOLOv8的启动命令：
yolo train data=datasets/container_defect/data.yaml model=yolov8n.pt epochs=100 imgsz=640 batch=16yolov8n是轻量级模型，适合先跑通流程。确认数据没问题后换yolov8s或yolov8m提升精度。YOLOv5的对应命令是：
python train.py --data datasets/container_defect/data.yaml --weights yolov5s.pt --img 640 --batch 16 --epochs 100两个版本的数据集格式兼容，同一份data.yaml可以直接复用，只是命令行参数写法不同。batch=16是在单张消费级显卡上比较稳的起点，显存不够降到8，不要为了凑batch把imgsz从640改到320——集装箱缺陷是小目标，分辨率降低会直接丢掉小缺陷的召回。
4.3 用统计脚本核对类别id与names顺序
训练前再跑一遍这个检查，它能发现你在names里写错类别名或漏了某个类别。把labels目录里所有TXT第一列的数字统计出来：
awk '{print $1}' labels/*.txt | sort | uniq -c输出示例：
2100 0 3500 1 640 2三个数字和nc=3吻合，且每个TXT第一列的最大值不超过2。如果出现数字3，说明要么这个数据集不止3类，要么某个标签文件写错了。此时先不要训练，去VOC的XML里找那张图对应的object节点，确认真实的类别名是什么。用uniq -c而不是直接数行数，是因为这个统计能看到类别分布——如果数字分布极不均匀，前面提到的类别加权策略就要安排上。
5. 训练翻车排查：这个数据集最容易踩的5个坑
5.1 解压报“密码正确但数据错误”：7z的编码玄学
现象：用7-Zip右键输入密码解压，界面提示“数据错误：文件已经损坏”，但密码明明是从下载页面原样复制的。更有迷惑性的是，同一个人发的其它压缩包能正常解压，唯独这个包报错。
原因分两种。第一种是压缩包在传输过程中不完整——网盘下载中断、迅雷拉取不全，解压到某个文件时CRC校验失败。第二种是文件名包含中文或特殊字符，7-Zip在非UTF-8区域设置下默认用系统编码解压文件名，导致文件名乱码，但文件内容其实是完整的。
解决：先用test命令确认压缩包本身是否完整，再决定走哪条路：
7z t container_defect_dataset.7z如果test通过，说明压缩包没坏，问题在文件名编码，解压时加UTF-8开关：
7z x container_defect_dataset.7z -scsUTF-8-scsUTF-8参数让7-Zip用UTF-8解析压缩包内的文件名。如果test报错，说明文件确实不完整，重新下载或换下载工具，不要尝试修复。这里有个习惯值得养成：下载完先test再解压，尤其从网盘拉下来的大文件。另外，7z的加密走AES-256，密码忘记基本没有后悔药，暴力破解不现实，唯一出路是回到原始来源重新获取。所以密码要存在一个本地txt里，跟压缩包放一起。
5.2 loss=nan与BatchNorm崩溃
现象：训练第一轮就出现nan，或者前10轮正常、第11轮loss突然变成nan然后永远恢复不回来。YOLOv5的训练日志里表现为“nan”出现在loss列，YOLOv8可能在验证阶段直接报“RuntimeError: value cannot be converted to type float”。
原因通常有两个方向。一是标签里有非法框，前面校验脚本查出来的w=0或h=0的框，在loss计算时产生除零或对数运算越界。集装箱场景下这种错误多半来自标注工具导出时的坐标精度丢失——某个框的右下角坐标和左上角坐标相同，算出来高就是0。二是学习率过大和batch过大叠加，梯度的数值范围失控，BatchNorm层的统计量崩掉，这是yolo训练中bn崩溃最常见的诱因。
解决：先把标签里的零尺寸框过滤掉：
import os label_dir = "labels" for name in os.listdir(label_dir): if not name.endswith(".txt"): continue path = os.path.join(label_dir, name) with open(path) as f: lines = f.readlines() valid = [] for line in lines: parts = line.strip().split() if len(parts) != 5: continue w, h = float(parts[3]), float(parts[4]) if w > 0 and h > 0: valid.append(line) with open(path, "w") as f: f.writelines(valid)然后调低学习率和batch重训。YOLOv8里：
yolo train data=datasets/container_defect/data.yaml model=yolov8n.pt imgsz=640 batch=8 lr0=0.001 amp=Falseamp=False关闭混合精度训练，这一步能排除很多fp16下的数值稳定性问题。如果关闭amp后正常，说明你的数据和当前loss组合在fp16下不稳定，保持关闭即可，集装箱缺陷检测不需要靠混合精度那点显存节省。
5.3 类别id错位：标签看起来没事，mAP全是0
现象：训练流程正常走完，验证集mAP@0.5显示0，但loss曲线在正常下降。看预测结果图片，模型输出的框位置基本合理，但类别标签全部张冠李戴——比如把“dent”预测成“rust”。
原因：标签TXT里第一列的数字和data.yaml里names的顺序对不上。假设打包者在VOC格式里定义的顺序是dent=0、rust=1、crack=2，但他下载了别人的YOLO转换脚本，脚本里写死了names顺序，这3个类在YOLO标签里可能就变成了rust=0、dent=1、crack=2。你只看到nc=3就填了names，实际类别对应已经完全错位。YOLO训练不会校验这个，因为数字本身是合法的。
解决：训练前用VOC的标注做一次交叉核对。写个脚本读取所有XML里object的name，统计每个名字出现次数；再统计YOLO标签里每个数字出现次数，两个列表必须是一一对应且数量接近：
import os import xml.etree.ElementTree as ET voc_dir = "Annotations" label_dir = "labels" voc_counts = {} for name in os.listdir(voc_dir): if not name.endswith(".xml"): continue tree = ET.parse(os.path.join(voc_dir, name)) for obj in tree.getroot().findall("object"): cls = obj.find("name").text voc_counts[cls] = voc_counts.get(cls, 0) + 1 label_counts = {} for name in os.listdir(label_dir): if not name.endswith(".txt"): continue with open(os.path.join(label_dir, name)) as f: for line in f: cls = int(line.strip().split()[0]) label_counts[cls] = label_counts.get(cls, 0) + 1 print("VOC:", voc_counts) print("YOLO:", label_counts)对照输出结果，把data.yaml里的names按YOLO标签实际数字调整过来。这个坑不报错、不警告，但直接废掉整个训练结果，是数据集类项目最常见的隐蔽bug。
5.4 类别不平衡导致某类mAP虚低
现象：三个类别的mAP差距悬殊，样本最多的类mAP能达到0.85，样本最少的类只有0.3。这不是模型能力问题，是数据集本身分布决定的。另一个相关现象是yolo混淆矩阵总合不唯一——矩阵里横向加起来不等于100%，很多人误以为是bug，其实是归一化口径不同，矩阵默认按行归一化，看每一行应该约等于100%，看列就没有这个约束。
集装箱缺陷的场景里，锈蚀往往大面积出现，容易标注也容易学习；开焊、裂缝这类缺陷面积小、对比度低，标注框可能只占图像的百分之几，模型很难提特征。加上样本数量本来就少，双重不均衡叠加。
解决：先确认不平衡的程度，用之前的awk统计看三个数字的比例。如果差距在3倍以内，调整loss权重即可；超过5倍，要在数据层面做增强。YOLOv5可以用分类权重参数，按样本量反比设置；YOLOv8在配置文件里给每个类设置loss权重。更有效的是数据增强——把少样本类的缺陷区域从原图上裁下来，粘贴到无缺陷的集装箱表面，生成合成样本。这种增强在工业质检里很常用，比翻转和裁剪有效得多，因为它直接增加了关键正样本。
5.5 中文路径和特殊字符导致的加载失败
现象：训练启动时报错找不到文件，但路径明明存在。检查发现数据集存放在“D:\数据\集装箱缺陷\”，或者图片文件名里有空格和“#”号。
原因：YOLO的数据加载对路径和文件名里的特殊字符很敏感，Windows下中文路径和空格会让opencv读取失败或dataloader混淆。集装箱项目的数据通常来自现场拍摄，文件名经常是“IMG_20240315_143200_#2.jpg”这种风格。
解决：统一规范。把数据集放到纯英文路径下，文件名全部改成无特殊字符的编号格式：
for f in images/*.jpg; do newname=$(echo "$f" | sed 's/[^A-Za-z0-9._\/-]//g') if [ "$f" != "$newname" ]; then mv "$f" "$newname" fi done对应的标签文件名也要同步修改，否则图片和标签就失配了。改完后重新跑一遍图片与标签的对应关系检查。
6. 验证与进阶：用混淆矩阵和mAP反向检查数据质量
6.1 混淆矩阵里三处值得警惕的异常
训练完看results.png里的混淆矩阵，很多人只会看对角线数值高不高。对角线当然要关注，但更有价值的是三类异常。第一类是background列有明显数值——模型把集装箱表面的铆钉、锁杆、焊缝、阴影误检成了缺陷，这说明你的负样本不够，需要收集更多无缺陷集装箱的图片做背景样本。第二类是某一个类别的行里，非对角线单元格明显高于其它行，这说明两类缺陷外形相似，模型分不清，典型的处理方式是检查标注是否有边界模糊——同一个特征在一张图里标成锈蚀、另一张图里标成裂缝。第三类是行和列的分布总和差异大，这基本就是类别不平衡的直接体现，按前面说的加权方案处理。
6.2 集装箱场景的数据增强边界
集装箱外观有三个显著特点：表面是重复的波纹纹理，强反光会造成高光区域，顶部和底部结构不同。这些特点直接限制了数据增强的选择。mosaic增强可以开，它把四张图拼在一起，对学习小目标有利。旋转设±10度足够，集装箱的边框线是垂直的，旋转角度太大会让箱体结构变得不自然。水平翻转可以开，左右对称对集装箱成立；但垂直翻转要关掉——箱顶有锁杆和角件，箱底是平面，翻转后特征完全错乱。色彩抖动要克制，锈蚀的颜色特征是关键线索，RGB扰动太大会把锈色洗没，HSV空间里把saturation扰动适度调大一点，模拟不同光照下的色彩衰减，hue扰动保持很小。
我拿这个数据集的习惯是：先花二十分钟把标签当代码审一遍，再做训练。只要发现一个XML和TXT对不上的框，就停下来搞清楚原因再继续——这种数据问题不会自己消失，只会以更隐蔽的方式在mAP上给你一刀。希望帮到你。
本文还有配套的精品资源，点击获取
