简介：面向目标检测入门与楼梯场景识别任务，这份数据集以VOC与YOLO双格式提供1043张清晰楼梯图像及对应矩形框标注，标签统一为staircase，共1224个标注框；图像未做增强，适合直接用于YOLO系列或Faster R-CNN等模型的训练与验证。压缩包共2000个文件，以xml标注文件与txt标签文件为主要类型，VOC格式的xml便于通用检测框架读取，YOLO格式的txt与classes.txt配合可无缝接入常用训练流程，整体包大小仅9.49MB，目录按JPEGImages、Annotations、labels划分，结构直观。目前已有88人学习下载，适合需要快速获取规范数据集、专注模型调参与迭代的开发者使用。数据提供准确且合理的矩形框标注，可用于楼梯检测的基线实验、课程设计或算法对比。
1. 拿到 1043 张楼梯数据集，先别急着训练：格式对不对决定后面三天的心情
做目标检测的人拿到一个新数据集，第一反应往往不是“这个模型能跑多准”，而是“这套标注能不能被我的框架直接吃进去”。1043 张的楼梯数据集同时给了 YOLO 和 VOC 两种格式，表面只是多一个标签目录，背后是两套截然不同的标注组织逻辑。楼梯检测在行人监控、园区巡检和机器人爬楼场景里都算典型需求，但大部分公开数据集喜欢混入一堆无关类，这个包按楼梯场景收得相对干净，拿来练微调和小规模验证都比较合适。下面全程按一条主线走：解压、校验、划分、训练、验格式，每一步都给能直接抄的命令和脚本。
2. 读懂 YOLO 与 VOC 双格式的组织方式：从目录结构到坐标换算
2.1 YOLO 与 VOC 的目录约定和标注格式差别
先讲清楚一件事：同样一张楼梯照片，YOLO 和 VOC 的标签描述方式完全不同，但它们描述的是同一个物理框。VOC 格式的标签是一个 XML 文件，里面记录图片宽高和 object 的 bndbox，四个坐标是绝对像素值；YOLO 格式的标签是跟图片同名的 txt 文件，每行一个目标，五个数字依次是类别 ID、归一化中心点 x、归一化中心点 y、归一化宽、归一化高。这里的“归一化”指的是除以图片的宽和高，所以 YOLO 标签里不会出现大于 1 的坐标值，除非标注工具导出了脏数据。
两种格式的目录组织习惯也不一样。常见做法是 VOC 数据集把图片放在 JPEGImages，XML 放在 Annotations，外加一个 ImageSets/Main 存放 train.txt、val.txt 这些划分文件；YOLO 数据集则通常直接分成 images/train、images/val、labels/train、labels/val 四个目录，图片和标签一一同名对应。拿到 zip 解压后，我一般第一件事就是看根目录结构，确认它是“VOC 风格”还是“YOLO 风格”，因为训练脚本要按不同的路径规则去读。
| 对比项 | VOC 格式 | YOLO 格式 |
|---|---|---|
| 标签文件后缀 | .xml | .txt |
| 坐标描述 | bndbox 绝对像素 (xmin, ymin, xmax, ymax) | 归一化浮点 (cx, cy, w, h) |
| 类别记录 | object 节点里嵌 name 文本 | 每行第一个数字是类别 ID |
| 目录常见形态 | Annotations / JPEGImages / ImageSets | images/train + labels/train |
| 读取方式 | 需要解析 XML 树 | 直接按行 split 即可 |
VOC 转 YOLO 时，核心换算是 cx = (xmin + xmax) / 2 / width，w = (xmax - xmin) / width，注意 YOLO 的 h 用的是图片高度做分母，别拿宽度去除。反过来 YOLO 转 VOC 时，xmin = (cx - w/2) * width，ymin = (cy - h/2) * height，算完要取整并截断到图片边界内。
2.2 双格式对齐：命名前缀与缺漏检查脚本
双格式数据集最常见的病就是“两张图的名字前缀一样，但图片和标签对不上”。比如图片叫 stair_001.jpg，txt 叫 stair_001.txt，XML 也应该是 stair_001.xml。实际导出时经常出现后缀不一致、名字被手动改过、甚至 XML 里记录的 filename 和实际文件名不同。我拿到压缩包第一件事不是训练，而是跑一遍对齐检查，确认三件套一一对应。
from pathlib import Path root = Path("path/to/dataset") # 改成你的解压路径 img_dir = root / "images" # 图片目录 txt_dir = root / "labels" # YOLO 标签目录 xml_dir = root / "annotations" # VOC 标签目录 imgs = {p.stem: p.suffix.lower() for p in img_dir.iterdir() if p.suffix.lower() in {".jpg", ".jpeg", ".png", ".bmp"}} txts = {p.stem for p in txt_dir.iterdir() if p.suffix == ".txt"} xmls = {p.stem for p in xml_dir.iterdir() if p.suffix == ".xml"} missing_txt = sorted(set(imgs) - txts) missing_xml = sorted(set(imgs) - xmls) extra_txt = sorted(txts - set(imgs)) print("缺 txt 的图片:", missing_txt[:10], "共", len(missing_txt)) print("缺 xml 的图片:", missing_xml[:10], "共", len(missing_xml)) print("多余 txt:", extra_txt[:10], "共", len(extra_txt))这段脚本用 Path.stem 取文件名主干，不管后缀是 .JPG 还是 .jpg 都能正确匹配，比字符串 replace 更稳。常见坑是 zip 解压后 macOS 系统会生成一堆 .DS_Store 和 __MACOSX 目录，如果直接遍历整个根目录，会把非图片文件也当成样本，所以这里限定后缀白名单。跑完如果缺标签数量为零，再进入下一步；如果不为零，先把缺的补上或者移出数据集，否则这些图会变成无标签负样本混进训练，直接拉低指标。
2.3 VOC 与 YOLO 互转：最小脚本与四个边界条件
很多开源标注工具默认导出 VOC XML，而训练又要 YOLO 格式，所以互转脚本几乎是必写工具。下面这段参考实现假设 VOC XML 里的对象是楼梯这一类，类名映射放在 class_map 里统一管理。
import xml.etree.ElementTree as ET def voc_to_yolo(xml_path, class_map): tree = ET.parse(xml_path) root = tree.getroot() size = root.find("size") width = int(size.find("width").text) height = int(size.find("height").text) lines = [] for obj in root.iter("object"): name = obj.find("name").text if name not in class_map: continue cls_id = class_map[name] bndbox = obj.find("bndbox") xmin = float(bndbox.find("xmin").text) ymin = float(bndbox.find("ymin").text) xmax = float(bndbox.find("xmax").text) ymax = float(bndbox.find("ymax").text) if xmax <= xmin or ymax <= ymin: continue cx = ((xmin + xmax) / 2) / width cy = ((ymin + ymax) / 2) / height w = (xmax - xmin) / width h = (ymax - ymin) / height cx = max(0.0, min(1.0, cx)) cy = max(0.0, min(1.0, cy)) w = max(0.0, min(1.0, w)) h = max(0.0, min(1.0, h)) lines.append(f"{cls_id} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}") return lines这里处理了四个边界条件：一是 class_map 里没有的类直接跳过，避免训练时类别 ID 越界报错；二是 xmax <= xmin 的退化框直接丢弃，这种框会让 YOLO 的宽高变成负值或零值，训练早期直接输出 NaN；三是坐标做了 clamp 到 [0,1]，防止标注工具生成越界坐标后归一化仍大于 1；四是统一输出六位小数，减少浮点误差累积。坐标格式我推荐固定六位，太短会丢失像素精度，太长文件体积变大且没有实际意义。
3. 把 1043 张拆成 train/val/test：划分策略与三个边界坑
3.1 先建目录再做分层划分：别让某一类从验证集消失
1043 张说多不多，说少不少，随机划分很容易翻车。楼梯数据集的标签分布往往不均匀，可能 900 张图里只有 30 张包含远距离小目标楼梯，如果随机打乱，验证集里可能一张小目标都没有，结果就是训练 loss 正常但 mAP50-95 始终上不去。常见做法是分层划分，先按“每张图里有哪些类别”分组，再从每个组里按比例抽 train、val、test。
import random from pathlib import Path from collections import defaultdict random.seed(42) label_dir = Path("labels") groups = defaultdict(list) for txt in label_dir.glob("*.txt"): classes = set() for line in txt.read_text().strip().splitlines(): parts = line.split() if parts: classes.add(parts[0]) groups[tuple(sorted(classes))].append(txt.stem) train, val, test = [], [], [] for key, samples in groups.items(): random.shuffle(samples) n = len(samples) n_val = max(1, int(n * 0.2)) n_test = max(1, int(n * 0.1)) val += samples[:n_val] test += samples[n_val:n_val + n_test] train += samples[n_val + n_test:] print("train:", len(train), "val:", len(val), "test:", len(test))注意这里 val 和 test 的抽取比例是 0.2 和 0.1，对应 7:2:1 的划分习惯。实测 1043 张的情况下，val 至少要留 100 张以上才有统计意义，如果某个类别只有十几张，强制抽 20% 会导致训练集几乎看不到这个类。遇到极端类别可以用“每个类别最少留 5 张到 val”这种保底逻辑去覆盖。
3.2 查缺补漏：空标签、坏图与超小目标
划分之后还要做一轮质量审计。楼梯数据集经常出现的情况是：某张图片本来就没楼梯，标注工具还是生成了一个空 txt；或者图片其实已损坏，但文件大小不为零，复制时也没报错。空标签在 YOLO 训练里被当背景样本，少量没问题，但如果占了 10% 以上，模型会倾向把所有区域判成背景。
from PIL import Image from pathlib import Path img_dir = Path("images") label_dir = Path("labels") broken, empty, tiny = [], [], [] for img_path in img_dir.iterdir(): stem = img_path.stem label_file = label_dir / f"{stem}.txt" if not label_file.exists(): continue content = label_file.read_text().strip() if not content: empty.append(stem) try: with Image.open(img_path) as im: w, h = im.size for line in content.splitlines(): parts = line.split() if len(parts) == 5: box_w = float(parts[3]) * w box_h = float(parts[4]) * h if box_w * box_h < 16: tiny.append(stem) except Exception: broken.append(stem) print("空标签:", len(empty), "坏图:", len(broken), "超小目标:", len(tiny))图片尺寸信息一定要从 PIL 实际读，不能直接用 EXIF 里的值，因为有的相机旋转了图片但 EXIF 没更新，读出来的宽高是反的。超小目标阈值 16 像素平方是我常用的主观经验，楼梯扶手的远端投影经常只有十几个像素，这种目标不是不能学，而是学的时候容易当噪声，建议单独统计数量再决定去留。
3.3 楼梯场景的预处理与增强取向：逆光、反光与同向性约束
楼梯照片的光照条件非常刁钻。楼道里逆光拍摄时，楼梯踏步处于大阴影区域，边缘对比度低；而瓷砖墙面反光会在画面里形成高光条，和楼梯踏板的边缘纹理很像。直接套用通用目标检测增强方案会出问题，Mosaic 增强虽然能提升整体鲁棒性，但对这种纹理密集场景，mosaic 之后多个楼梯的纹理互相拼接，模型学到的是“纹理复合体”而不是“楼梯本体”。我一般会把 Mosaic 概率降下来，或者用 YOLOv8 自带的 close_mosaic 参数在训练后期关闭 mosaic。
翻转增强要特别小心。楼梯是有方向性的结构，水平翻转对楼梯检测影响不大，因为楼梯语义和左右方向无关；但垂直翻转等于把“上楼”变成“下楼”，如果标注框没有同步改变方向语义，模型很容易在上下楼识别任务上翻车。所以这里建议只开水平翻转和轻微旋转，旋转角度控制在 ±10 度以内，超过这个范围楼梯的透视畸变会明显偏离真实拍摄分布。亮度扰动和对比度扰动优先做，数值范围选 0.8 到 1.2，模拟楼道里不同时段的光照差异。
4. 用 YOLOv8 在本地跑通最小训练：命令、参数与首轮结果解读
4.1 目录整理与 data.yaml：YOLO 框架只认这一份配置
YOLO 系列框架在训练时只认一份 data.yaml，里面写清楚图片路径和类别名。常见布局是数据集根目录下建 images 和 labels 两个总目录，然后 train、val 分别做硬链接或拷贝，避免数据重复占用磁盘。1043 张原图加两个格式的标签文件加起来不大，直接拷贝问题也不大，但如果以后换成几万张的数据集，用软链接省出来的磁盘空间非常可观。
path: /home/user/datasets/staircase # 改成你的绝对路径 train: images/train val: images/val test: images/test nc: 1 names: 0: staircasepath 字段我推荐写成绝对路径。很多人翻车在相对路径上：命令行在项目根目录执行跟在别的目录执行，YOLO 对相对路径的解析结果不一样，而且不同版本之间行为也有差异。names 里类别顺序必须和标签文件里的 ID 完全对应，如果压缩包里的 classes.txt 把楼梯排在第二位，那这里的 names 字典也要从 1 开始对应。训练前先跑一次yolo detect train ...的 dry-run 或者直接加载模型看类别数，能省不少定位时间。
4.2 用 yolov8n 预训练权重跑最小训练命令：参数怎么选
解压出来的数据集按 YOLO 目录整理好后，训练命令其实很短。预训练权重建议先下载 yolov8n.pt 这类轻量权重跑通流程，等验证完数据和代码没问题，再换 yolov8s 或更大模型刷精度。第一次跑不要追求高分，目标是确认全流程无报错。
yolo detect train \ data=/home/user/datasets/staircase/staircase.yaml \ model=/home/user/weights/yolov8n.pt \ epochs=100 \ imgsz=640 \ batch=16 \ patience=15 \ close_mosaic=10 \ project=/home/user/runs \ name=staircase_v1 \ device=0参数说明：epochs=100 对 1043 张的小数据集足够，楼梯目标结构不算复杂，通常 50 到 60 epoch 就已经收敛，超过 100 开始过拟合。batch=16 是 8G 显存的一个安全值，V100 这类 32G 显存的卡可以开到 32，批大小翻倍时学习率一般也要跟着微调。patience=15 表示连续 15 轮 val 指标不提升就早停，训练日志明显变平后自动收工。close_mosaic=10 表示最后 10 个 epoch 关闭 mosaic，避免过度拟合合成纹理。device=0 是用第一张 GPU，没有 GPU 就改成 device=cpu，但训练速度会慢十倍以上。
运行完看 runs/staircase_v1/ 目录下的 results.csv，重点看 val/box_loss、metrics/mAP50(B)、metrics/mAP50-95(B) 三列。如果 mAP50-95 始终在 0.3 以下，先别怀疑模型，回看第 3 章的质量审计列表，大概率是标签或数据划分的问题。
4.3 首轮结果验证：train_batch 图远比 loss 曲线诚实
训练过程中 YOLO 会在 runs 目录下生成 train_batch*.jpg，这些图把原始图片和标注框叠加在一起。我建议每个新手训练开始后先打开这几张图，确认标注框和楼梯轮廓对齐。很多时候 loss 下降正常，但框画在楼梯扶手下方或者只框住楼梯的一半，这种标签偏差在 loss 曲线上根本看不出来。
训练完成后用 best.pt 在 test 集上做一次推理：
yolo detect predict \ model=/home/user/runs/staircase_v1/weights/best.pt \ source=/home/user/datasets/staircase/images/test \ conf=0.25 \ save=True \ project=/home/user/runs \ name=staircase_predictpredicted 目录里会生成带框的图，肉眼扫一遍就能看出模型是真正理解楼梯结构，还是只学会识别栏杆纹理。conf=0.25 是默认置信度阈值，粒子目标多可以把阈值降到 0.15，代价是误报变多；如果追求精确率，可以把阈值提到 0.5 再跑一次对比。
5. 楼梯数据训练避坑：四条高频故障定位
5.1 现象：训练日志里 BoxP 一直为 0，loss 从第一步就不正常
原因：data.yaml 的 path 写错，或者 labels 目录和 images 目录不在同一级，YOLO 按规则找不到标签文件时不会报错，而是把整张图当背景样本，所以 precision 恒为 0。
解决：训练前手动检查 labels/train 下 txt 文件数量是否等于 images/train 下图片数量。最直接的办法是写个脚本统计两个目录的文件数，再抽查一个 stem 同时读 txt 和图片确认尺寸匹配。跑训练时看第一轮输出的 “All class names” 是否和 data.yaml 一致，如果显示的是 COCO 的 80 个类名，说明预训练权重头没有被正确替换，问题大概率出在 yaml 本身。
5.2 现象：校验时报“缺标签”，但 Annotations 里明明有 XML
原因：图片是 .jpg 后缀，标签是 .JPG 后缀对应的同名文件，或者 VOC XML 里 filename 字段和实际文件名不一致。Windows 和 macOS 的文件系统在大小写敏感性上的差异，会让同一个压缩包在解压后行为不一样。
解决：统一后缀白名单，用 Path.stem 做匹配，不要直接拼文件名。另外把 XML 里的 filename 字段读出来和实际图片 stem 比对一遍，不一致的全部重命名或重写 filename 字段。这条坑在字幕数据集和爬楼梯数据集里尤其常见，因为很多图是从视频抽帧来的，抽帧工具生成的文件名本身就混乱。
5.3 现象：训练到一半 loss 变成 NaN，或者出现 BN 崩溃
原因：标签文件里有脏值，比如 w 或 h 写成 0、坐标归一化后大于 1、或者类别 ID 超过 nc。PyTorch 在遇到 NaN 输入时不会直接报错，而是把梯度传播污染，通常到第 5 到第 10 个 epoch 才在 loss 曲线上暴雷，定位成本极高。batch 太小也会让 BN 层的统计量剧烈抖动，batch=2 训练小数据集时经常触发这类问题。
解决：训练前用 2.3 节的转换脚本把所有标签过一遍，加过滤和 clamp 逻辑。对 batch，我的一般做法是精度要求不高时直接 batch=16 起步，显存不够就降 imgsz 而不是降 batch，640 降到 480 对楼梯这种中大型目标影响不大，但 batch 减半对 BN 的影响要明显得多。同时可以把损失函数换成 CIoU 或给 loss 加梯度裁剪，看你的框架版本支持哪个。
5.4 现象：微调崩了，加载预训练权重后 loss 直接爆炸
原因：自定义数据集的类别数和 COCO 不一致时，模型头部结构变化，预训练权重不能直接复用。很多人的做法是修改预训练模型源码来适配，结果越改越乱。
解决：用 ultralytics 的标准训练入口，框架会自动检测 nc 变化并重建检测头，常见做法是先冻结 backbone 训练前 20 个 epoch，让检测头先适应新数据分布，再解冻整个网络微调。超参里有个 freeze 参数可以控制冻结层数，具体值参考框架文档。如果 loss 仍然爆炸，把 AMP 混合精度关掉重试，某些数据集在低精度下 BN 统计不稳定是已知问题。
6. 双格式往返校验：用同一批标签验证两套框架
6.1 YOLO 与 VOC 互转的无损往返脚本
标题既然给了 YOLO 和 VOC 两种格式，那这两套标签必须描述完全相同的物理框。最可靠的验证方法是做一次往返转换：YOLO 转 VOC，再把 VOC 转回 YOLO，对比原始 txt 和回写 txt 的数值误差。误差超过 1e-5 就说明某个环节有精度损失。
from pathlib import Path def yolo_line_to_voc(line, img_w, img_h): cls_id, cx, cy, w, h = map(float, line.split()) xmin = (cx - w / 2) * img_w ymin = (cy - h / 2) * img_h xmax = (cx + w / 2) * img_w ymax = (cy + h / 2) * img_h return cls_id, xmin, ymin, xmax, ymax往返验证时注意一个细节：VOC 的 bndbox 通常存整数，从 YOLO 转过去再转回来，中心点坐标会有 0.5 像素左右的舍入误差，这对训练影响可以忽略，但如果你在脚本里用精确等于比较一定会误报。建议用 abs diff 和容差 1e-3。我现在的习惯是把这套往返脚本存成 repo 里的 make check 命令，每次数据集更新都跑一遍，确认两种格式没有互相污染。格式读取出问题往往不是训练时报错，而是模型在某个细分场景里表现奇怪，查半天最后还是标注错位。双格式数据集的价值就在这儿：两套框架可以交叉验证同一个模型，互相兜底。希望帮到你。
本文还有配套的精品资源，点击获取
