TorchSSL 已弃用且不再维护。请参考 USB，它是 TorchSSL 的升级版本。使用 USB 进行训练仅需 TorchSSL 训练时间的 12.5%，且效果更优。

对 TorchSSL 代码的后续修改及合并的 Pull Request 将不再重新运行以更新结果。

TorchSSL

一个基于 PyTorch 的半监督学习工具箱。这也是发表于 NeurIPS 2021 的论文 FlexMatch: 利用课程伪标签提升半监督学习 的官方实现。[arXiv] [知乎文章] [视频]

新闻与更新

2023年1月31日

• 我们新增了 [FreeMatch] 和 [SoftMatch] 的代码。请注意，freematch.py 对应的是不包含 SAF 的 FreeMatch，而 freematch_entropy.py 则是同时包含 SAT 和 SAF 的 FreeMatch。训练日志也可在 https://1drv.ms/u/s!AlpW9hcyb0KvmyCfsCjGvhDXG5Nb?e=Xc6amH 找到。

2022年8月17日

• TorchSSL（本仓库）已停止维护和更新。我们已创建并更新了一个更为全面的半监督学习代码库和基准测试——USB。它基于 TorchSSL 构建，但使用起来更加灵活、扩展性更强，涵盖了计算机视觉、自然语言处理和音频处理等多个领域的数据集。

2021年2月15日

• 日志和模型权重已共享！我们注意到部分模型权重缺失，未来会尝试补全这些缺失的权重。
• BestAcc 的结果已更新！我在 CIFAR-10 和 SVHN 上使用单块 P100，在 STL-10 上使用单块 P40，在 CIFAR-100 上使用单块 V100-32G。

简介

TorchSSL 是一个基于 PyTorch 的一体化半监督学习（SSL）工具箱。目前，我们实现了 9 种流行的 SSL 算法，以便进行公平比较并推动 SSL 算法的发展。

支持的算法： 除了全监督学习（作为基线），TorchSSL 还支持以下流行算法：

1. PiModel（NeurIPS 2015）[1]
2. MeanTeacher（NeurIPS 2017）[2]
3. PseudoLabel（ICML 2013）[3]
4. VAT（虚拟对抗训练，TPAMI 2018）[4]
5. MixMatch（NeurIPS 2019）[5]
6. UDA（无监督数据增强，NeurIPS 2020）[6]
7. ReMixMatch（ICLR 2019）[7]
8. FixMatch（NeurIPS 2020）[8]
9. FlexMatch（NeurIPS 2021）[9]
10. FreeMatch（ICLR 2023）[10]
11. SoftMatch（ICLR 2023）[11]

此外，我们还为 PseudoLabel 和 UDA 实现了课程伪标签方法（CPL），分别称为 Flex-Pseudo-Label 和 Flex-UDA。

支持的数据集： TorchSSL 目前支持 SSL 研究中常用的 5 个数据集：

1. CIFAR-10
2. CIFAR-100
3. STL-10
4. SVHN
5. ImageNet

主要结果

结果为最佳准确率及其标准误差。表中“40”、“250”、“1000”等数字表示不同数量的标注样本（例如，CIFAR-10 中的“40”表示每个类别仅有 4 个标注样本）。所有实验均使用随机种子 0、1、2。所有配置文件均位于 config/ 文件夹下。您可以直接在自己的研究中引用这些结果。

请注意，全监督学习的结果是在不考虑表格中标注样本数量的情况下，使用数据集中全部训练数据训练得到的。

CIFAR-10 和 CIFAR-100

		CIFAR-10				CIFAR100
	40	250	4000		400	2500	10000
FullySupervised	95.38±0.05	95.39±0.04	95.38±0.05		80.7±0.09	80.7±0.09	80.73±0.05
PiModel [1]	25.66±1.76	53.76±1.29	86.87±0.59		13.04±0.8	41.2±0.66	63.35±0.0
PseudoLabel [3]	25.39±0.26	53.51±2.2	84.92±0.19		12.55±0.85	42.26±0.28	63.45±0.24
PseudoLabel_Flex [9]	26.26±1.96	53.86±1.81	85.25±0.19		14.28±0.46	43.88±0.51	64.4±0.15
MeanTeacher [2]	29.91±1.6	62.54±3.3	91.9±0.21		18.89±1.44	54.83±1.06	68.25±0.23
VAT [4]	25.34±2.12	58.97±1.79	89.49±0.12		14.8±1.4	53.16±0.79	67.86±0.19
MixMatch [5]	63.81±6.48	86.37±0.59	93.34±0.26		32.41±0.66	60.24±0.48	72.22±0.29
ReMixMatch [7]	90.12±1.03	93.7±0.05	95.16±0.01		57.25±1.05	73.97±0.35	79.98±0.27
UDA [6]	89.38±3.75	94.84±0.06	95.71±0.07		53.61±1.59	72.27±0.21	77.51±0.23
UDA_Flex [9]	94.56±0.52	94.98±0.07	95.76±0.06		54.83±1.88	72.92±0.15	78.09±0.1
FixMatch [8]	92.53±0.28	95.14±0.05	95.79±0.08		53.58±0.82	71.97±0.16	77.8±0.12
FlexMatch [9]	95.03±0.06	95.02±0.09	95.81±0.01		60.06±1.62	73.51±0.2	78.1±0.15

STL-10 和 SVHN

		STL-10				SVHN
	40	250	1000		40	250	1000
FullySupervised	无	无	无		97.87±0.02	97.87±0.01	97.86±0.01
PiModel [1]	25.69±0.85	44.87±1.5	67.22±0.4		32.52±0.95	86.7±1.12	92.84±0.11
PseudoLabel [3]	25.32±0.99	44.55±2.43	67.36±0.71		35.39±5.6	84.41±0.95	90.6±0.32
PseudoLabel_Flex [9]	26.58±2.19	47.94±2.5	67.95±0.37		36.79±3.64	79.58±2.11	87.95±0.54
MeanTeacher [2]	28.28±1.45	43.51±2.75	66.1±1.37		63.91±3.98	96.55±0.03	96.73±0.05
VAT [4]	25.26±0.38	43.58±1.97	62.05±1.12		25.25±3.38	95.67±0.12	95.89±0.2
MixMatch [5]	45.07±0.96	65.48±0.32	78.3±0.68		69.4±8.39	95.44±0.32	96.31±0.37
ReMixMatch [7]	67.88±6.24	87.51±1.28	93.26±0.14		75.96±9.13	93.64±0.22	94.84±0.31
UDA [6]	62.58±8.44	90.28±1.15	93.36±0.17		94.88±4.27	98.08±0.05	98.11±0.01
UDA_Flex [9]	70.47±2.1	90.97±0.45	93.9±0.25		96.58±1.51	97.34±0.83	97.98±0.05
FixMatch [8]	64.03±4.14	90.19±1.04	93.75±0.33		96.19±1.18	97.98±0.02	98.04±0.03
FlexMatch [9]	70.85±4.16	91.77±0.39	94.23±0.18		91.81±3.2	93.41±2.29	93.28±0.3

ImageNet

	100k 标签
	top-1	top-5
FixMatch [8]	56.34	78.20
FlexMatch [9]	58.15	80.52

日志和权重

您可以在此处下载共享的日志和权重。

https://1drv.ms/u/s!AlpW9hcyb0KvmyCfsCjGvhDXG5Nb?e=Xc6amH

使用方法

在运行或修改代码之前，您需要：

1. 将此仓库克隆到您的机器上。
2. 确保已安装 Anaconda 或 Miniconda。
3. 运行 conda env create -f environment.yml 来初始化环境。

运行实验

使用 TorchSSL 进行实验非常方便。例如，如果您想运行 FlexMatch 算法：

1. 根据需要修改 config/flexmatch/flexmatch.yaml 中的配置文件。
2. 运行 python flexmatch.py --c config/flexmatch/flexmatch.yaml。

自定义

如果您想编写自己的算法，请按照以下步骤操作：

1. 为您的算法创建一个目录，例如 SSL，并在其中编写您自己的模型文件 SSl/SSL.py。
2. 在 SSL.py 中编写训练文件。
3. 在 config/SSL/SSL.yaml 中编写配置文件。

引用 TorchSSL

如果您认为本工具包或相关成果对您的研究有所帮助，请引用我们的论文：

@article{wang2023freematch,
  title={FreeMatch: 自适应阈值的半监督学习},
  author={王一东、陈浩、衡强、侯文欣、范悦、吴振、王金东、萨维德斯、筱崎隆弘、拉杰、席勒、谢星},
  booktitle={国际表征学习会议 (ICLR)},
  year={2023}
}

@article{chen2023softmatch,
  title={SoftMatch: 解决半监督学习中的数量-质量权衡问题},
  author={陈浩、陶然、范悦、王一东、王金东、席勒、谢星、拉杰、萨维德斯},
  booktitle={国际表征学习会议 (ICLR)},
  year={2023}
}

@article{zhang2021flexmatch,
  title={FlexMatch: 通过课程伪标签提升半监督学习},
  author={张博文、王一东、侯文欣、吴浩、王金东、奥村学、筱崎隆弘},
  booktitle={神经信息处理系统会议 (NeurIPS)},
  year={2021}
}

维护者

王一东¹、陈浩²、范悦³、吴浩¹、张博文¹、侯文欣^1,4、陈宇豪⁵、王金东⁴

东京工业大学¹

卡内基梅隆大学²

马克斯普朗克信息研究所³

微软亚洲研究院⁴

旷视科技⁵

贡献

1. 欢迎您就 bug、问题和建议提出 issue。
2. 如果您希望加入 TorchSSL 团队，请发送邮件至王一东（646842131@qq.com；yidongwang37@gmail.com）以获取更多信息。我们计划添加更多 SSL 算法，并将 TorchSSL 从计算机视觉扩展到自然语言处理和语音领域。

声明

关于 ImageNet 数据集： 请从官方网站下载 ImageNet 2014 数据集（与 2012 年版本相同）（链接：https://image-net.org/challenges/LSVRC/2012/2012-downloads.php）。将训练集和验证集解压到*子文件夹*中（测试集不使用），并分别放入 train/ 和 val/ 目录下。每个子文件夹代表一个类别。 注意：官方验证集并未按类别压缩成子文件夹，您可以使用：https://github.com/jiweibo/ImageNet/blob/master/valprep.sh，这是一段用于准备文件结构的优秀脚本。

参考文献

[1] Antti Rasmus、Harri Valpola、Mikko Honkala、Mathias Berglund 和 Tapani Raiko. 半监督学习中的梯形网络。NeurIPS，页 3546–3554，2015 年。

[2] Antti Tarvainen 和 Harri Valpola. 平均教师是更好的榜样：加权平均一致性目标可提高半监督深度学习效果。NeurIPS，页 1195–1204，2017 年。

[3] Dong-Hyun Lee 等人. 伪标签：一种简单高效的深度神经网络半监督学习方法。ICML 表征学习挑战研讨会，第 3 卷，2013 年。

[4] Takeru Miyato、Shin-ichi Maeda、Masanori Koyama 和 Shin Ishii. 虚拟对抗训练：一种用于监督和半监督学习的正则化方法。IEEE TPAMI，41(8):1979–1993，2018 年。

[5] David Berthelot、Nicholas Carlini、Ian Goodfellow、Nicolas Papernot、Avital Oliver 和 Colin Raffel. Mixmatch：一种全面的半监督学习方法。NeurIPS，页 5050–5060，2019 年。

[6] Qizhe Xie、Zihang Dai、Eduard Hovy、Thang Luong 和 Quoc Le. 用于一致性训练的无监督数据增强。NeurIPS，33 届，2020 年。

[7] David Berthelot、Nicholas Carlini、Ekin D Cubuk、Alex Kurakin、Kihyuk Sohn、Han Zhang 和 Colin Raffel. Remixmatch：基于分布匹配和增强锚定的半监督学习。ICLR，2019 年。

[8] Kihyuk Sohn、David Berthelot、Nicholas Carlini、Zizhao Zhang、Han Zhang、Colin A Raf-fel、Ekin Dogus Cubuk、Alexey Kurakin 和 Chun-Liang Li. Fixmatch：通过一致性和置信度简化半监督学习。NeurIPS，33 届，2020 年。

[9] 张博文、王一东、侯文欣、吴浩、王金东、奥村学和筱崎隆弘. FlexMatch：通过课程伪标签提升半监督学习。NeurIPS，2021 年。

[10] 王一东、陈浩、衡强、侯文欣、范悦、吴振、王金东、萨维德斯、筱崎隆弘、拉杰、席勒、谢星. FreeMatch：自适应阈值的半监督学习。ICLR，2023 年。

[11] 陈浩、陶然、范悦、王一东、萨维德斯、王金东、拉杰、谢星、席勒. SoftMatch：解决半监督学习中的数量-质量权衡问题。ICLR，2023 年。

TorchSSL 快速上手指南

⚠️ 重要提示：TorchSSL 项目已停止维护（Deprecated）。官方推荐使用其升级版 USB。USB 基于 TorchSSL 构建，支持更广泛的数据集（CV/NLP/Audio），且训练速度提升显著（仅需 TorchSSL 12.5% 的时间），效果更优。以下内容仅作为 TorchSSL 的历史参考或特定复现需求使用。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS (Windows 需通过 WSL 运行)
• Python 版本：建议 Python 3.6 - 3.8
• 依赖管理：必须安装 Anaconda 或 Miniconda
• 硬件要求：支持 CUDA 的 NVIDIA GPU（用于加速训练）

2. 安装步骤

第一步：克隆代码库

将项目代码下载到本地：

git clone https://github.com/TorchSSL/TorchSSL.git
cd TorchSSL

第二步：创建虚拟环境

使用项目提供的 environment.yml 文件自动安装所有依赖。 (注：若下载速度慢，可尝试配置 conda 国内镜像源，如清华源)

# 配置清华镜像源（可选，加速下载）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/

# 创建并激活环境
conda env create -f environment.yml
conda activate torchssl

3. 基本使用

TorchSSL 采用配置文件驱动的方式运行实验。以下以运行 FlexMatch 算法在 CIFAR-10 数据集上的实验为例：

第一步：准备数据集

确保已下载所需数据集（如 CIFAR-10, SVHN, ImageNet 等）。

• 对于 ImageNet，需手动整理目录结构：将训练集和验证集分别解压到 train/ 和 val/ 子文件夹中，每个类别一个子文件夹。

第二步：修改配置文件

编辑对应的配置文件以调整超参数或数据路径。 例如，修改 FlexMatch 的配置：

vim config/flexmatch/flexmatch.yaml

在文件中确认 dataset、num_labels 以及数据根目录路径是否正确。

第三步：运行实验

执行对应的 Python 脚本并指定配置文件路径：

python flexmatch.py --c config/flexmatch/flexmatch.yaml

自定义新算法（可选）

若您希望基于此框架开发新的半监督学习算法：

1. 在根目录创建新文件夹（如 SSL）。
2. 在其中编写模型逻辑 SSL/SSL.py 及训练流程。
3. 在 config/SSL/ 下创建对应的 SSL.yaml 配置文件。
4. 参照上述命令运行即可。