目录

1. 新闻与更新
2. 简介
3. 开始使用
   • 先决条件
   • 安装
4. 使用
5. 基准测试结果
6. 模型库
7. 社区
8. 许可证
9. 致谢

新闻与更新

• [2024年3月16日] 添加 EPASS、SequenceMatch 和 ReFixMatch。修复了一些拼写错误。

• [2023年7月7日] 添加 DeFixmatch。修复了一些 bug。发布 semilearn=0.3.1/

• [2023年6月1日] USB 已正式加入 PyTorch 生态系统！[Pytorch 博客]

• [2023年1月30日] 更新 semilearn==0.3.0。添加 FreeMatch 和 SoftMatch。增加不平衡数据算法。更新结果并支持 wandb。详情请参阅 CHANGE_LOG。[结果][日志][Wandb]。旧的经典日志可以在这里找到：[TorchSSL 日志]。

• [2022年10月16日] 数据集下载链接和处理说明发布！[数据集]

• [2022年10月13日] 我们已完成最终版本，并更新了 [结果]。[Openreview]

• [2022年10月6日] USB 的训练日志和结果已更新！可用的数据集将很快上传。[日志] [结果]

• [2022年9月17日] USB 论文已被 NeurIPS 2022 数据集与基准赛道接受！[Openreview]

• [2022年8月21日] USB 正式发布！

简介

USB 是一个基于 PyTorch 的 Python 包，用于半监督学习 (SSL)。它易于使用和扩展，对小型团队来说经济实惠，并且功能全面，适合开发和评估 SSL 算法。USB 提供了基于一致性正则化的 14 种 SSL 算法的实现，以及来自计算机视觉、自然语言处理和音频领域的 15 项评估任务。

(返回顶部)

开始使用

这是一个在本地设置 USB 的示例。 要搭建一个本地副本，请按照以下简单步骤操作。

先决条件

USB 基于 PyTorch 构建，依赖 torchvision、torchaudio 和 transformers。

要安装所需的包，您可以创建一个 conda 环境：

conda create --name usb python=3.8

然后使用 pip 安装所需包：

pip install -r requirements.txt

从现在开始，您可以通过输入以下命令来开始使用 USB：

python train.py --c config/usb_cv/fixmatch/fixmatch_cifar100_200_0.yaml

安装

我们提供了一个名为 semilearn 的 USB Python 包，方便用户快速在其数据上训练和测试支持的 SSL 算法：

pip install semilearn

(返回顶部)

开发

你也可以开发自己的SSL算法，并通过克隆USB来评估它：

git clone https://github.com/microsoft/Semi-supervised-learning.git

(返回顶部)

准备数据集

详细的下载和处理说明请参见数据集下载。在运行或开发算法之前，请按照该说明下载数据集。

(返回顶部)

使用方法

USB易于使用且易于扩展。通过以下示例，你可以快速熟悉USB的使用方法，也可以在自己的数据集上评估现有的SSL算法，或者开发新的SSL算法。

使用USB包快速入门

请先参阅安装部分以安装USB。我们提供了以下Colab教程：

• 入门示例
• 自定义数据集

使用Docker开始

步骤1：检查你的环境

你需要先正确安装Docker和NVIDIA驱动程序。要在Docker容器中使用GPU， 还需要安装nvidia-docker2（安装指南）。 然后，请通过nvidia-smi检查你的CUDA版本。

步骤2：克隆项目

git clone https://github.com/microsoft/Semi-supervised-learning.git

步骤3：构建Docker镜像

在构建镜像之前，你可以根据自己的CUDA版本修改Dockerfile。 我们使用的CUDA版本是11.6。你可以根据NVIDIA CUDA镜像标签页更改基础镜像标签。 此外，你还需要根据自己的CUDA版本更改--extra-index-url，以便安装正确版本的PyTorch。 可以通过PyTorch官网查看对应的URL。

使用以下命令构建镜像：

cd Semi-supervised-learning && docker build -t semilearn .

完成！你可以将刚刚构建的镜像用于自己的项目。别忘了在需要使用GPU的容器中添加--gpu参数。

训练

以下是一个在CIFAR-100数据集上使用200个标签训练FixMatch的示例。训练其他支持的算法（在不同数据集上使用不同标签设置）可以通过配置文件指定：

python train.py --c config/usb_cv/fixmatch/fixmatch_cifar100_200_0.yaml

评估

训练完成后，你可以通过训练日志查看评估性能，或者运行评估脚本：

python eval.py --dataset cifar100 --num_classes 100 --load_path /PATH/TO/CHECKPOINT

开发

请查阅开发文档，以创建你自己的SSL算法！

更多示例，请参阅文档

(返回顶部)

基准测试结果

有关不同任务的基准测试结果，请参阅结果。

(返回顶部)

模型库

TODO：添加预训练模型。

(返回顶部)

待办事项

• 完成README
• 更新SUPPORT.MD，加入关于该项目支持经验的内容
• 多语言支持
  • 中文

完整的功能建议列表（以及已知问题）请参阅GitHub上的开放问题。

(返回顶部)

贡献

本项目欢迎贡献和建议。大多数贡献都需要你同意贡献者许可协议（CLA），声明你有权并将实际授予我们使用你贡献的权利。详情请访问https://cla.opensource.microsoft.com。

当你提交拉取请求时，CLA机器人会自动判断你是否需要提供CLA，并相应地标记PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于所有使用我们CLA的仓库，你只需执行一次此操作。

本项目采用了微软开源行为准则。更多信息请参阅行为准则常见问题解答，或如有任何其他疑问或意见，请联系opencode@microsoft.com。

如果你有使USB更好的建议，可以fork该项目并创建一个拉取请求。你也可以直接打开带有“enhancement”标签的问题。别忘了给项目点个赞！再次感谢！

1. Fork项目
2. 创建你的分支（git checkout -b your_name/your_branch）
3. 提交你的更改（git commit -m '添加一些功能'）
4. 推送到分支（git push origin your_name/your_branch）
5. 打开拉取请求

(返回顶部)

商标

本项目可能包含项目、产品或服务的商标或标志。对微软商标或标志的授权使用须遵守并遵循 微软商标与品牌指南。 在本项目的修改版本中使用微软商标或标志时，不得造成混淆或暗示微软的赞助关系。任何第三方商标或标志的使用均受其各自政策的约束。

许可证

根据MIT许可证分发。更多信息请参阅LICENSE.txt。

(返回顶部)

社区与联系方式

USB社区由以下人员维护：

• 王一东（yidongwang37@gmail.com），东京工业大学
• 陈浩（haoc3@andrew.cmu.edu），卡内基梅隆大学
• 范悦（yfan@mpi-inf.mpg.de），马克斯普朗克信息学研究所
• 侯文欣（wenxinhou@microsoft.com），微软STCA
• 陶然（rant@andrew.cmu.edu），卡内基梅隆大学
• 王进东（jindwang@microsoft.com），微软亚洲研究院

(返回顶部)

引用 USB

如果您觉得本项目对您的研究或论文有帮助，请引用我们：

@inproceedings{usb2022,
  doi = {10.48550/ARXIV.2208.07204},
  url = {https://arxiv.org/abs/2208.07204},
  author = {Wang, Yidong and Chen, Hao and Fan, Yue and Sun, Wang and Tao, Ran and Hou, Wenxin and Wang, Renjie and Yang, Linyi and Zhou, Zhi and Guo, Lan-Zhe and Qi, Heli and Wu, Zhen and Li, Yu-Feng and Nakamura, Satoshi and Ye, Wei and Savvides, Marios and Raj, Bhiksha and Shinozaki, Takahiro and Schiele, Bernt and Wang, Jindong and Xie, Xing and Zhang, Yue},
  title = {USB: A Unified Semi-supervised Learning Benchmark for Classification},
  booktitle = {Thirty-sixth Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
  year = {2022}
}

@article{wang2023freematch,
  title={FreeMatch: Self-adaptive Thresholding for Semi-supervised Learning},
  author={Wang, Yidong and Chen, Hao and Heng, Qiang and Hou, Wenxin and Fan, Yue and and Wu, Zhen and Wang, Jindong and Savvides, Marios and Shinozaki, Takahiro and Raj, Bhiksha and Schiele, Bernt and Xie, Xing},
  booktitle={International Conference on Learning Representations (ICLR)},
  year={2023}
}

@article{chen2023softmatch,
  title={SoftMatch: Addressing the Quantity-Quality Trade-off in Semi-supervised Learning},
  author={Chen, Hao and Tao, Ran and Fan, Yue and Wang, Yidong and Wang, Jindong and Schiele, Bernt and Xie, Xing and Raj, Bhiksha and Savvides, Marios},
  booktitle={International Conference on Learning Representations (ICLR)},
  year={2023}
}

@article{zhang2021flexmatch,
  title={FlexMatch: Boosting Semi-supervised Learning with Curriculum Pseudo Labeling},
  author={Zhang, Bowen and Wang, Yidong and Hou, Wenxin and Wu, Hao and Wang, Jindong and Okumura, Manabu and Shinozaki, Takahiro},
  booktitle={Neural Information Processing Systems (NeurIPS)},
  year={2021}
}

致谢

我们感谢以下项目在创建 USB 时提供的参考：

• TorchSSL
• FixMatch
• CoMatch
• SimMatch
• HuggingFace
• Pytorch Lighting
• README 模板

(返回顶部)

USB 半监督学习快速上手指南

USB (Unified Semi-supervised learning Benchmark) 是一个基于 PyTorch 的开源工具包，旨在为计算机视觉 (CV)、自然语言处理 (NLP) 和音频分类领域提供统一、易用且高效的半监督学习 (SSL) 算法开发与评估框架。它内置了 14 种主流 SSL 算法（如 FixMatch, FreeMatch, SoftMatch 等）及 15 个基准任务。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux 或 macOS (Windows 需通过 WSL 或 Docker 运行)
• Python 版本: 推荐 Python 3.8
• 硬件: 支持 CUDA 的 NVIDIA GPU (可选，但强烈推荐用于训练)
• 前置依赖:
  • PyTorch
  • torchvision
  • torchaudio
  • transformers

建议先安装 conda 来管理虚拟环境。

安装步骤

您可以选择直接安装发布包进行快速使用，或克隆源码进行二次开发。

方式一：快速安装 (推荐新手)

如果您只想快速运行现有的 SSL 算法，可以直接通过 pip 安装 semilearn 包：

# 创建并激活 conda 环境
conda create --name usb python=3.8 -y
conda activate usb

# 安装核心依赖包
pip install semilearn

方式二：源码安装 (推荐开发者)

如果您需要修改算法代码、添加新数据集或复现最新研究结果，请克隆官方仓库：

# 克隆项目
git clone https://github.com/microsoft/Semi-supervised-learning.git
cd Semi-supervised-learning

# 创建并激活 conda 环境
conda create --name usb python=3.8 -y
conda activate usb

# 安装项目所需依赖
pip install -r requirements.txt

提示：国内用户若下载依赖较慢，可添加清华源加速： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

数据准备

在运行训练前，您需要下载并预处理数据集。详细的下载链接和处理脚本请参考项目内的 preprocess 目录： 数据集下载与处理指南

基本使用

安装完成后，您可以通过配置文件轻松启动训练或评估。

1. 开始训练

以下示例展示如何使用 FixMatch 算法在 CIFAR-100 数据集上进行训练（设定标签数量为 200）：

python train.py --c config/usb_cv/fixmatch/fixmatch_cifar100_200_0.yaml

• --c: 指定配置文件路径。
• 您可以修改 config/ 目录下的 YAML 文件来切换算法、数据集或调整超参数。

2. 模型评估

训练完成后，使用以下命令加载检查点并进行评估：

python eval.py --dataset cifar100 --num_classes 100 --load_path /PATH/TO/CHECKPOINT

请将 /PATH/TO/CHECKPOINT 替换为您实际保存的模型权重文件路径。

3. 在线体验 (Colab)

如果您不想在本地配置环境，可以使用 Google Colab 快速体验：

• 基础示例教程
• 自定义数据集教程

4. 使用 Docker (可选)

如果您希望环境完全隔离，可以使用 Docker 部署：

# 克隆项目
git clone https://github.com/microsoft/Semi-supervised-learning.git
cd Semi-supervised-learning

# 构建镜像 (注意：可能需要根据本地 CUDA 版本修改 Dockerfile)
docker build -t semilearn .

# 运行容器 (需添加 --gpus all 参数以启用 GPU)
docker run --gpus all -it semilearn bash