半监督学习数据集结构：标签划分、防泄漏与加载实战

搞了几年半监督学习，隔三差五就会有人拿着自己的数据集来问我：我已经标了三百张图，剩下两万张没标，能不能直接塞进模型一起训练？目录结构到底怎么组织？为什么我照着论文建了 unlabeled 文件夹，跑出来的效果反而更差了？

这些问题表面上是训练技巧问题，实际上都指向同一个核心概念：半监督学习数据集的基本结构。它绝不只是“有标签 + 无标签”两个文件夹那么简单。一个设计得好的半监督数据集，要保证训练时数据流清晰、验证指标可信、实验结果可复现，还要避开标签泄漏这种隐蔽问题。

接下来我会从数据集结构本身拆起，结合图像分类、目标检测、遥感、故障诊断这几个常见场景，讲一讲半监督数据集应该怎么组织、怎么划分、加载器怎么写，以及实战里最容易翻车的地方。这篇内容适合正在训练自己的数据集，或者想把半监督方法落到实际项目里的朋友，不管你是做 CV、做时序还是做多模态，核心思路都是通用的。

1. 半监督学习数据集到底长什么样

1.1 半监督学习与传统监督学习的数据结构差异

我们先说最朴素的理解。传统监督学习的数据集，结构非常固定：训练集、验证集、测试集，每一张图都有对应的标签，目录上无非是 train/、val/、test/，标签可能是 JSON、XML 或者文件夹名。

半监督学习的数据集结构就不一样了。它的前提是：手里只有一小部分标注数据，剩下的大部分数据没有标注，但又不想浪费掉。所以结构上必然要出现一个监督学习里没有的分区——无标签样本池。这个池子的数据量通常是有标签数据的几倍甚至几十倍，否则半监督训练很难带来明显收益。

除此之外，半监督数据集的第二个关键差异是验证集和测试集必须严格带标签。很多初学者把无标签数据跟测试集混在一起，或者为了凑验证集，把有标签的一部分挪走，剩下的无标签数据继续用来做伪标签，这样会造成指标虚高，甚至模型早停失效。我见过不止一次，训练时损失曲线很漂亮，验证集精度也很高，但一到真实场景就崩掉，最后发现是数据划分时把无标签池里的图像当成了验证集，验证集本身已经被训练过程“看过”了。

所以一个基础但重要的结论是：半监督数据集在物理路径上要有三个独立分区——labeled、unlabeled、test，验证集可以从 labeled 里切，但绝不能从 unlabeled 里切。

1.2 一个标准半监督数据集必须包含的五个部分

结合我自己做过的项目，我认为一个可复用的半监督数据集，应该由下面五部分组成，缺一个后面都会出问题。

第一部分是有标签样本集。 这是半监督训练里的“老师”，数量少但质量要极高。标注噪声在监督学习里还能靠大量样本稀释，在半监督里会被伪标签放大，严重时直接带偏整个训练过程。所以有标签部分至少要经过两轮人工质检，尤其是边框类标注，错框漏框比错类别更致命。

第二部分是无标签样本池。 这是半监督数据集的“燃料”。它只需要原始数据，不需要任何标签。但需要保证它和有标签样本来自同一个数据分布，至少是近似的。比如做自动驾驶场景，有标签数据都是白天晴天采集的，无标签池却塞进去大量夜晚雨天数据，模型训练时就会一直震荡。分布偏移在半监督学习里没有监督学习那么扛得住。

第三部分是标准测试集。 测试集必须有标签，而且要独立，不能和训练过程有任何交集。最好的做法是测试集的图像文件先做一次哈希去重，确保没有一张图和 labeled、unlabeled 里的文件重复。很多数据集的下载来源比较杂，同一个文件可能以不同文件名反复出现，不做去重的话测试集泄漏风险很高。

第四部分是划分索引文件。 这是最容易被忽略的部分。半监督实验里经常要做消融，比如有标签数量从 1000 变成 500，或者比较不同采样策略。如果每次都在代码里随机切分，结果完全不可复现。我现在的做法是每个实验生成独立的 split 文件，把 labeled_train.txt、unlabeled_pool.txt、test.txt 固定下来，用 git 管理，这样同事之间复现结果特别快。

第五部分是标签体系说明文件。 包括类别名、类别 ID 映射、标注格式版本。比如 class_indices.json 或 labels.txt。这个文件看起来不起眼，但当你从 COCO 格式切到 YOLO 格式，或者把类别顺序重新排序的时候，没有这个映射就会全线崩盘。

1.3 不同任务下标签信息的组织方式

半监督数据集的结构还要考虑任务类型。图像分类最简单，每个样本只需要一个类别 ID。常见做法是一个 label.txt，每一行是 图像相对路径 类别ID。也有人直接按文件夹组织，比如 labeled/cat/1.jpg，这种方式直观，但一旦样本数量很大，文件系统压力会比较大。

目标检测任务的标签就复杂一些。通用的三种格式是 COCO JSON、YOLO TXT 和 Pascal VOC XML。在半监督场景下，有标签部分必须用标准格式存好，无标签部分则完全不需要标签目录。比如你下载了 COCO2017 数据集，官方有 train2017/、val2017/ 和 unlabeled2017/ 三个目录，其中 unlabeled2017 就是典型的无标签池。很多人用 COCO 做半监督实验，直接把 unlabeled2017 路径丢给无标签加载器，这本身就是 COCO 数据集结构设计好的半监督接口。

语义分割任务则更直接，有标签部分是“原图 + mask 图”两套目录，无标签部分只有原图。时序故障诊断这类任务又不一样，比如 PHM2012 轴承数据集，它的结构是不同工况下采集到的振动信号，再分成训练记录和测试记录。做半监督时，你可以把某一工况下的无标签信号当作池子，也可以用振动时长较长的记录切出一部分当无标签数据。但时序数据必须要格外小心数据泄漏，不能把同一段信号既切进有标签训练集，又切进无标签池，否则相当于变相看过答案。

2. 经典数据集的半监督划分逻辑，照着抄就行

2.1 CIFAR-10、ImageNet-1K：图像分类的固定标签预算

图像分类领域最经典的半监督基准，是 CIFAR-10 的固定预算设定。论文里经常看到“10% labels”“4000 samples”之类的说法，意思是从 CIFAR-10 的 50000 张训练图里，只保留每类 400 个有标签样本（共 4000 个），剩下的 46000 张全部进无标签池。还有更极端的每类 40 个样本、每类 250 个样本等版本。

这个设计的核心逻辑是：无标签池大小固定，改变有标签数量来观察算法对标注预算的敏感性。但如果你去复现论文，最容易被坑的是划分方式。不同的论文可能用不同的随机种子，导致“4000 labels”对应的具体图像完全不同。为了直接横向比较，现在很多官方代码库会把 sampled_labeled_ids.npy 或者一个固定的 split.json 直接提供出来。我自己做实验时，不管数据来自哪里，第一件事就是检查有没有官方划分文件，没有的话就自己固定随机种子生成一份，再记录 MD5 值。

ImageNet-1K 数据集也是同理。它是 128 万张训练图加 5 万张验证图，半监督实验通常取 1% 或 10% 的标签，剩下的当无标签。由于原始数据是按 WordNet ID（比如 n01440764）的文件夹组织，很多人会写脚本按类别采样固定数量出来。这里我建议不只是按类均分，还要考虑类别内难易均衡。因为 WordNet 类别本身有语义层级，有些类特别相似，比如不同品种的狗，随机采样很容易让模型对容易混淆的类别彻底盲区。

2.2 COCO、BDD100K、YOLO 自建数据集：目标检测的未标注池设计

目标检测是当前工业场景里最常需要半监督解决方案的方向，毕竟标注一张图里的所有边框太贵了。COCO2017 数据集给了一个很标准的示范：有标签的 train2017 大约 11.8 万张，unlabeled2017 大约 12.3 万张，标注文件是 JSON 格式，包含 images、annotations、categories 三段结构。很多人下载 COCO 做半监督时，直接用 unlabeled2017 作为无标签池，这是最省事的方案。

自动驾驶数据集 BDD100K 也很有意思，它有一百多小时的驾驶视频，但只有部分帧提供了检测标注。那种“大量视频帧天然无标签”的结构，非常适合做成半监督数据集。只是要注意，连续视频帧之间高度相似，如果无标签池和测试集来自同一段视频的相邻帧，模型相当于见过“几乎相同”的画面，测试指标会虚高。我之前处理自动驾驶数据时，都是按视频片段 ID 来划分而不是按单帧划分，保证同一条路段的帧不会同时出现在训练池和测试集里。

如果你用的是 YOLOv8 这类工具训练自己的数据集，最常见的问题是“只有一小批已标注图片，还有一大堆抓拍的原始图片”。我建议目录结构这样设计：

code复制yolo_semi/
├── labeled/
│   ├── images/
│   └── labels/
├── unlabeled/
│   └── images/
├── test/
│   ├── images/
│   └── labels/
└── splits/

其中 labeled/labels 和 test/labels 用 YOLO 的 TXT 格式，每一行是 class x_center y_center width height 的归一化坐标；unlabeled/images 里纯粹放图。训练时让有标签分支走正常强增强，无标签分支走弱增强，并且对无标签分支做置信度过滤，再配合伪标签写入机制，这样就能把 YOLO 系训练扩展成半监督训练，而无需改动主网络结构。

2.3 DOTA、HRSC2016：遥感旋转框任务中的特殊难点

遥感目标检测里常用的 DOTA 数据集和 HRSC2016 数据集，结构和普通目标检测不一样的地方在于它们大量使用旋转框。DOTA 的标注不是普通轴对齐矩形，而是多边形的顶点坐标，类别包含飞机、舰船、车辆等。HRSC2016 专门做舰船检测，图像尺寸大、目标小且密集。

这类数据做半监督，最大的难点不是文件夹怎么建，而是无标签池里的目标尺度分布和有标签部分严重不一致。比如 HRSC2016 中有些图像是单艘大船，有些是港口密密麻麻的小船，随机把图像分成有标签和无标签后，很可能有标签部分全是简单的大目标，无标签部分全是复杂的小目标，模型训练后会对小目标彻底失效。

解决思路有几个：一是按目标的尺度或复杂度做分层采样，确保有标签子集能覆盖各种尺度；二是对大图做切片预处理时，把切片策略统一应用于有标签和无标签数据，确保分布一致。还有一个很实用的经验：遥感图像动辄几千像素，直接把整张大图塞进模型会很吃显存。半监督训练通常需要同时处理有标签和无标签两个分支，显存占用翻倍。所以一般先做 1024 或 608 的切片，再按 patch 建立数据集索引。这个切片索引本身就是数据集结构的一部分，必须和标签同步处理，否则切出来的无标签 patch 和标注框对不上，后端训练再优化也白搭。

2.4 PHM2012、时序信号：半监督数据集要额外防泄漏

PHM2012 轴承数据集的结构是把振动加速度信号分成 36 个文件，对应不同工况和不同程度的轴承故障。它原本没有专门的半监督版本，但很多故障诊断论文在用。做半监督时，常见做法是把同一工况下的完整信号切成长度相同的窗口，一部分窗口给标签，一部分不给。

这里有个特别隐蔽的坑：有标签窗口和无标签窗口如果来自同一段原始连续信号，并且窗口之间有重叠，那无标签窗口里其实包含了一部分有标签窗口的数据。模型从有标签窗口看到故障特征，又在无标签窗口里以伪标签形式强化一次，测试指标就会虚高。我现在的做法是，按“信号记录”为单位划分，而不是按“窗口”为单位划分。比如一个有 10 万个采样点的记录文件，如果窗口长度是 1024，有重叠地滑动，绝对不能同时把前半部分分成有标签、后半部分分成无标签，而是应该整个记录文件只属于一个分区。这样虽然会牺牲一些样本量，但划分是干净的。

3. 从零搭建自己的半监督数据集：目录规范与实操步骤

3.1 推荐目录结构与 Split 文件设计

我一直坚持的原则是“路径即索引，Split 即真相”。也就是说，数据集的文件路径稳定不变，具体哪些文件用于训练、哪些用于无标签池，全部由 Split 文件决定。这样你不需要反复拷贝大文件，硬链接和软链接也能派上用场。

半监督数据集目录结构可以这样组织：

text复制semi_dataset/
├── raw/
│   ├── images/          # 所有原始图像，无差别存放
│   └── labels/          # 所有原始标注，无差别存放
├── splits/
│   ├── labeled_train.txt
│   ├── unlabeled_pool.txt
│   └── test.txt
├── class_indices.json
└── README.md

labeled_train.txt 和 unlabeled_pool.txt 的格式一般就是每行一个相对路径，比如：

text复制raw/images/train/000001.jpg raw/labels/train/000001.txt

有标签的每一行带着标签文件路径，无标签的只需要图像路径。test.txt 则必须带标签路径，因为测试时要算指标。

为什么要把所有图先统一放在 raw/images 下？因为半监督实验经常要对比不同的标签率。比如今天用 10% 标签，明天用 20% 标签，以后可能想用主动学习挑样本。如果一开始就把文件物理拷贝到 labeled/ 和 unlabeled/，每次调整划分都要重新挪文件，非常消耗磁盘 IO。用 Split 文件做逻辑隔离，每次只需要重新生成一个索引文件，训练代码读索引就行。这也是目前主流开源库如 PyTorch 生态里比较推荐的思路。

3.2 标签子集的采样策略：随机、均衡还是难样本优先

固定好有标签数量之后，下一个问题是：到底选哪些样本进有标签集？

随机采样最省事，但经常踩坑。如果你的原始数据里类别天然不均衡，随机采样会让频次少的类在标签集里消失，模型就彻底放弃那个类了。所以一般至少要做一个分层随机采样，也就是按类别先分组，每类抽相同比例或固定数量，保证每个类别在标签集中都出现。

比分层随机更进阶的是难样本优先，这其实已经接近主动学习了。比如先用一个在少量标签上预训练的模型，对候选样本做预测，然后挑那些预测置信度低、或者模型认为最不确定的样本，优先标注它们。这样做的好处是标签预算利用率更高，单位标注成本带来的收益更大。缺点是流程复杂：你需要先训一个粗模型，再跑一轮推理排序，再人工标注，再重训，如此迭代。

我自己的建议是：如果项目预算紧张、对效果要求高，用难样本优先；如果是做研究对比算法，老老实实用固定随机种子加分层采样，因为论文里横向比较要求划分标准统一，主动学习反而引入额外变量。

3.3 无标签池的数据清洗与伪标签管理

无标签池不是“乱七八糟的图全部扔进去”。常见的数据清洗至少包括三步。

第一步是去重。用感知哈希或者简单的 dHash/pHash，把所有无标签图像两两比较，去掉重复或近乎重复的图。分类任务里重复图像会让模型对某些样本过分记忆，检测任务里重复图像还会让伪标签反复强化同一个错误框。

第二步是去损坏文件。下载公开数据时经常遇到截断的 JPEG、全黑的 PNG、尺寸异常的图。写个脚本遍历一遍，用 PIL 或 OpenCV 读一下，读不出来的直接挪到一个 corrupted/ 目录，不让它进入训练。

第三步是去标签冲突。如果你的无标签池里其实混入了一些原先标过本轮却被当成无标签的样本，那就必须彻底隔离。最简单的方法是做文件路径比对和哈希比对，确保无标签池里的文件不出现在任何标注文件列表中。

伪标签管理则是训练过程中的事。给无标签数据打伪标签时，我习惯保存到独立的目录，比如 pseudo_labels/ep1/，而不是直接覆盖掉原来的 unlabeled_pool.txt。每一轮伪标签单独版本，这样如果某轮伪标签质量太差，还能回滚。

3.4 数据读取时的路径与缓存设计

最后落实到代码层面，数据读取逻辑要稳定高效。我的核心思路是不要让每个 epoch 都重新扫描整个数据集目录。第一次启动时扫描一次，生成索引列表，之后直接吃内存索引。

python复制class SemiDataset(torch.utils.data.Dataset):
    def __init__(self, split_file, root_dir, labeled=True):
        self.samples = []
        with open(split_file, 'r') as f:
            for line in f:
                parts = line.strip().split()
                img_path = os.path.join(root_dir, parts[0])
                label_path = os.path.join(root_dir, parts[1]) if len(parts) > 1 else None
                self.samples.append((img_path, label_path))
        self.labeled = labeled

    def __getitem__(self, idx):
        img_path, label_path = self.samples[idx]
        image = read_image(img_path)
        if self.labeled:
            label = read_label(label_path)
        else:
            label = None
        return image, label

python复制labeled_set = SemiDataset('splits/labeled_train.txt', root_dir='semi_dataset', labeled=True)
unlabeled_set = SemiDataset('splits/unlabeled_pool.txt', root_dir='semi_dataset', labeled=False)
labeled_loader = DataLoader(labeled_set, batch_size=16, shuffle=True, num_workers=8)
unlabeled_loader = DataLoader(unlabeled_set, batch_size=64, shuffle=True, num_workers=8)

这里有个小技巧我一直用：无标签分支的 batch_size 可以比有标签分支大几倍。因为有标签分支要做强增强，计算量更大；无标签分支通常只在弱增强下算一个一致性损失，显存占用相对小。两个 loader 独立 shuffle，每个 step 里分别取一个 batch，组成一个大 batch 塞给模型。

4. 半监督训练中的数据加载与划分细节

4.1 强烈建议用双 DataLoader 而不是混合采样

半监督数据集的两部分数据，本质上是两个分布状态，有标签数据量小但信息密度高，无标签数据量大但噪声多。如果你把两部分合并到一个 Dataset 里，用一个参数控制是否给标签，代码写起来简洁，但批次构成很难控制。

比如总 batch size 是 32，如果直接混在一起随机采样，很可能某个 epoch 里 32 张全是无标签数据，另一个 step 又全是标签数据。这样梯度更新忽偏忽偏，半监督的一致性损失没法保持稳定。所以更稳的做法是维护两个独立 DataLoader，每个 step 同时读一批有标签数据和一批无标签数据，再把两部分的损失加起来求梯度。

python复制for labeled_batch, unlabeled_batch in zip(labeled_loader, unlabeled_loader):
    images_l, labels_l = labeled_batch
    images_u, _ = unlabeled_batch
    # forward on both, compute supervised loss + unsupervised consistency loss

这里的 zip 会以较短的 loader 为终点。一般有标签数据更少，意味着每个 epoch 会跑固定数量的迭代，无标签池不会每次都完整遍历，这正好符合半监督学习里“少量标签迭代多次、无标签数据随机采样”的常见设计。

4.2 有标签和验证集之间的隔离不能只靠路径

数据隔离不能只靠“路径不同”。我曾经踩过一个很深的坑：从某个开源数据集下载的训练包和测试包，文件名分别是 00001.jpg 和 00001.jpg，但内容其实是同一张图被二次压缩后另存为。路径完全不一样，哈希也不一样，但视觉上几乎相同。如果不做感知哈希去重，这种近重复数据会对验证指标产生严重干扰。

我现在的做法是：第一次把原始数据收上来后，统一做一次感知哈希登记。每张图算出一个 dHash 字符串，存成一个 hash_index.json。划分数据集时，不仅要保证路径不重叠，还要保证感知哈希的汉明距离小于一定阈值的图像不会同时出现在有标签池和测试集里。检测任务还得多看一层：如果两图几乎重复但标注框位置有一两个像素偏移，这种也属于泄漏。

4.3 验证集/测试集的规模与标签率选择

半监督实验的验证集不要太小。监督学习里，验证集占 10% 或 20% 都行，但半监督里总训练数据很大，有标签部分又很少，验证集如果只有一百张，涨跌一个点都看不出趋势。一般我建议验证集至少要有标签样本数量的两到三倍，并且类别分布接近真实场景。测试集则尽量固定，不要因为算法效果不好就换测试集，否则容易过拟合这份测试集。业界常用 ImageNet-1K 作为评测基准，正因为它的验证集组织形式固定且规模达到 5 万张，指标相对可信。

标签率的选择取决于你的场景。公开基准上常见的是 1%、10%、50%。工业项目里，我更建议直接给定一个绝对预算，比如“单类别最多标 500 张”。因为百分比看起来公平，但如果类特别多，1% 可能只有几十张，模型连基本特征都学不到。绝对预算更直观，也方便估算人工标注成本。

5. 实战中容易踩的坑和排查方法

5.1 标签泄漏：看着没问题实则崩掉的典型案例

我这里写几个实际见过的问题。

第一个是把 unlabeled 里图像误加入了验证集，导致验证损失忽高忽低。排查方法是检查验证集文件里每个路径，是否能在 splits/unlabeled_pool.txt 中找到完全相同的路径。如果找到，立刻移出并重新训练。

第二个是伪标签覆盖真实标签。我见过有人把伪标签文件保存到了 labeled/labels 目录，然后下一次训练加载时同时读出原标签和伪标签，同一张图产生两个互相矛盾的监督信号，loss 曲线直接乱跳。所以伪标签目录一定要保持物理隔离，例如 pseudo_labels/。

第三个是测试集没有独立采集。比如做行人检测时，所有数据都来自同一条街道的监控视频，测试集和训练集只是时间上不同，但还是同一批摄像头、同一类光照条件、同一批行人活动范围。这种情况下模型泛化到新摄像头时效果通常很差。我只能提醒：如果条件允许，测试集最好来源于不同的采集时段和场景。

下面这张表格是我常用的排查清单：

5.2 类别分布不均衡：无标签池分布不明怎么处理

半监督场景下，无标签池常常没有类别标签，你根本不知道里面有多少比例的猫、多少比例的狗。这会导致一个很麻烦的问题：有标签数据里猫比狗多，无标签池里其实狗更多，模型训练时一致性损失不断把样本往猫的方向拉，结果狗的精度越来越差。

处理办法有两个。一个是用一个预训练分类器对无标签池做一次粗略类别统计，根据估计出的分布调整有标签采样的权重，让有标签部分尽量去平衡无标签池的偏差。另一个是动态调整无标签损失的类别权重，在训练中统计伪标签的类别频次，给频次低的类别更高的损失权重。后者实现稍微复杂一点，但效果更直接。

说实话，这一类问题没有通解。如果你发现无标签池和真实目标分布差距太大，优先考虑减少无标签损失权重，甚至放弃部分无标签数据，也不要硬着头皮把所有数据都塞进模型。

5.3 海量数据集的 IO 瓶颈与存储方案

半监督数据集无标签部分往往动辄几十万张图，直接用普通 ImageFolder 在机械硬盘上读，训练会被 IO 拖死。我试过最简单的办法是把小图打包成 LMDB 或 WebDataset，顺序读取效率能提升一个量级。尤其在云端训练时，小文件数量多会让文件系统 inode 开销特别大，打包进程可以大大减少元数据操作。

我推荐用 WebDataset 这类基于 tar 包的格式，因为它天然支持流式读取和分布式打乱，而且每个 epoch 可以只遍历一部分 tar 分片，非常适合半监督里“无标签数据量大但不需要每轮都完整看到”的需求。如果你已经按 Split 文件方式组织数据，把 unlabeled_pool.txt 里的相对路径对应到 tar 内的 key，转换成本也不高。

5.4 数据集版本管理与协作建议

最后聊一下团队协作。半监督项目搞到后面，数据版本混乱会非常痛苦。我今天跑了一个实验，用的 split_v2.txt，下周同事告诉我最新的应该是 split_v3.txt，但其实 v3 的随机种子不同，导致有标签集合变了，实验结果没法对比。

建议给数据集目录加一个 README.md，里面写清楚每个版本的划分依据、随机种子、标签数量、哈希文件位置。Split 文件一律用 Git 管理，图片文件用软链接，或者用 DVC 做版本追踪。每次生成新的划分，都记录命令和随机种子，比如：

bash复制python tools/split_dataset.py --root semi_dataset --seed 42 --labeled_ratio 0.1 \
    --output splits/labeled_train_42.txt

这样别人拿到你的拆分脚本和一串参数，就能复现出完全一样的划分结果。半监督学习对划分尤其敏感，不同划分下的结果差异甚至可能超过不同算法之间的差异。把划分这件事认真对待，是所有半监督项目的前提。

我个人在实际项目里吃过太多亏，最大的体会是：半监督学习研究到最后，很多问题不是模型结构的问题，而是数据集的“基本结构”出了问题。每次实验前多花半小时检查一遍 Split 文件、检查一遍测试集隔离、检查一遍无标签池去重，往往比换一个更强的模型更有效。最后再分享一个省心技巧：新建项目时，第一件事永远是把 class_indices.json 和 split 文件放进 Git，哪怕数据还在硬盘上拷来拷去，只要这两个文件是确定的，任何一次实验都能追溯到底。