OpenMixup

📘文档 | 🛠️安装 | 🚀模型库 | 👀精彩混元 | 🔍精彩自监督 | 🆕新闻

简介

主分支支持 PyTorch 1.8（部分自监督方法所需）及以上版本（推荐使用 PyTorch 1.12）。对于有监督分类方法，您仍然可以使用 PyTorch 1.6。

OpenMixup 是一个基于 PyTorch 的开源工具箱，用于基于 mixup 的有监督、自监督和半监督视觉表征学习，尤其适用于与 mixup 相关的方法。近期，OpenMixup 正在更新以适配 OpenMMLab 2.0 的新特性及代码结构（#42)。

新闻与更新

[2025-03-19] OpenMixup v0.2.10 发布，支持 PyTorch >= 2.0，并增加了更多的 mixup 数据增强和网络。

安装

OpenMixup 兼容 Python 3.6/3.7/3.8/3.9 和 PyTorch >= 1.6。以下是开发模式下的快速安装步骤：

conda create -n openmixup python=3.8 pytorch=1.12 cudatoolkit=11.3 torchvision -c pytorch -y
conda activate openmixup
pip install openmim
mim install mmcv-full
git clone https://github.com/Westlake-AI/openmixup.git
cd openmixup
python setup.py develop

conda create -n openmixup python=3.9
conda activate openmixup
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118
pip install https://download.openmmlab.com/mmcv/dist/cu118/torch2.1.0/mmcv_full-1.7.2-cp39-cp39-manylinux1_x86_64.whl
git clone https://github.com/Westlake-AI/openmixup.git
cd openmixup
pip install -r requirements/runtime.txt
python setup.py develop

有关更详细的安装和数据集准备，请参阅 install.md。

快速入门

OpenMixup 支持 Linux 和 macOS。它能够轻松地在现有的有监督、自监督和半监督视觉识别模型中实现和扩展 mixup 数据增强方法。有关 OpenMixup 的基本用法，请参阅 get_started.md。

训练与评估脚本

以下提供了一个使用多块 GPU 和指定 CONFIG_FILE 进行快速端到端训练的脚本：

bash tools/dist_train.sh ${CONFIG_FILE} ${GPUS} [可选参数]

例如，您可以运行以下脚本，使用 4 块 GPU 在 ImageNet 数据集上训练 ResNet-50 分类器：

CUDA_VISIBLE_DEVICES=0,1,2,3 PORT=29500 bash tools/dist_train.sh configs/classification/imagenet/resnet/resnet50_4xb64_cos_ep100.py 4

训练完成后，您可以使用相应的评估脚本来测试训练好的模型：

bash tools/dist_test.sh ${CONFIG_FILE} ${GPUS} ${PATH_TO_MODEL} [可选参数]

开发

更多开发示例和技术细节，请参阅教程：

• 配置文件
• 添加新数据集
• 数据流水线
• 添加新模块
• 自定义调度策略
• 自定义运行时配置

自监督学习下游任务

• 分类
• 目标检测
• 图像分割

实用工具

• 分析
• 可视化
• PyTorch转ONNX
• PyTorch转TorchScript

(返回顶部)

模型库概览

请在各个配置页面上运行实验或查找结果。有关 mixup 方法的基准测试结果，请参阅Mixup 基准。查看有监督模型库和自监督模型库，其中汇集了主流骨干网络和自监督算法。我们还提供了Awesome Mixups和Awesome MIM的论文列表，供您参考。请在以下配置页面查看配置文件及模型链接。检查点和训练日志正在持续更新中！

(back to top)

Change Log

Please refer to changelog.md for more details and release history.

License

This project is released under the Apache 2.0 license. See LICENSE for more information.

Acknowledgement

• OpenMixup is an open-source project for mixup methods and visual representation learning created by researchers in CAIRI AI Lab. We encourage researchers interested in backbone architectures, mixup augmentations, and self-supervised learning methods to contribute to OpenMixup!
• This project borrows the architecture design and part of the code from MMPreTrain and the official implementations of supported algorisms.

(back to top)

Citation

If you find this project useful in your research, please consider star OpenMixup or cite our tech report:

@article{li2022openmixup,
  title = {OpenMixup: A Comprehensive Mixup Benchmark for Visual Classification},
  author = {Siyuan Li and Zedong Wang and Zicheng Liu and Di Wu and Cheng Tan and Stan Z. Li},
  journal = {ArXiv},
  year = {2022},
  volume = {abs/2209.04851}
}

(back to top)

Contributors and Contact

For help, new features, or reporting bugs associated with OpenMixup, please open a GitHub issue and pull request with the tag "help wanted" or "enhancement". For now, the direct contributors include: Siyuan Li (@Lupin1998), Zedong Wang (@Jacky1128), and Zicheng Liu (@pone7). We thank all public contributors and contributors from MMPreTrain (MMSelfSup and MMClassification)!

This repo is currently maintained by:

• Siyuan Li (lisiyuan@westlake.edu.cn), Westlake University
• Zedong Wang (wangzedong@westlake.edu.cn), Westlake University
• Zicheng Liu (liuzicheng@westlake.edu.cn), Westlake University

(back to top)

OpenMixup 快速上手指南

OpenMixup 是一个基于 PyTorch 的开源工具箱，专注于监督、自监督和半监督视觉表示学习，特别针对 Mixup 及相关数据增强方法进行了优化。它采用模块化设计，支持多种主流骨干网络（CNN & Transformer）及前沿算法。

1. 环境准备

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

• 操作系统: Linux 或 macOS
• Python: 3.6 - 3.9 (推荐 3.8 或 3.9)
• PyTorch:
  • 基础分类任务：>= 1.6
  • 自监督学习任务：>= 1.8 (推荐 1.12 或更高)
  • 最新特性支持：>= 2.0
• CUDA: 根据显卡驱动版本安装对应的 Toolkit (如 11.3, 11.8 等)

2. 安装步骤

推荐使用 conda 创建独立虚拟环境进行安装。以下提供两种常见场景的安装命令。

方案 A：标准安装 (PyTorch 1.12 + CUDA 11.3)

适用于大多数现有模型和教程。

# 1. 创建并激活 conda 环境
conda create -n openmixup python=3.8 pytorch=1.12 cudatoolkit=11.3 torchvision -c pytorch -y
conda activate openmixup

# 2. 安装 OpenMIM 工具及 MMCV
pip install openmim
mim install mmcv-full

# 3. 克隆代码库并安装
git clone https://github.com/Westlake-AI/openmixup.git
cd openmixup
python setup.py develop

方案 B：新版安装 (PyTorch 2.1 + CUDA 11.8)

适用于需要最新特性及高性能训练的场景。

# 1. 创建并激活 conda 环境
conda create -n openmixup python=3.9
conda activate openmixup

# 2. 安装 PyTorch 2.1 (官方源)
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118

# 3. 安装特定版本的 MMCV (适配 Torch 2.1)
pip install https://download.openmmlab.com/mmcv/dist/cu118/torch2.1.0/mmcv_full-1.7.2-cp39-cp39-manylinux1_x86_64.whl

# 4. 克隆代码库并安装依赖
git clone https://github.com/Westlake-AI/openmixup.git
cd openmixup
pip install -r requirements/runtime.txt
python setup.py develop

提示：国内用户若下载缓慢，可在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 使用清华镜像源。

3. 基本使用

安装完成后，您可以立即开始训练和评估模型。OpenMixup 提供了便捷的分布式训练脚本。

快速训练示例

以下命令演示了如何使用 4 张 GPU 在 ImageNet 数据集上训练一个 ResNet-50 分类器：

CUDA_VISIBLE_DEVICES=0,1,2,3 PORT=29500 bash tools/dist_train.sh configs/classification/imagenet/resnet/resnet50_4xb64_cos_ep100.py 4

• ${CONFIG_FILE}: 配置文件路径 (例如 configs/classification/imagenet/resnet/resnet50_4xb64_cos_ep100.py)
• ${GPUS}: 使用的 GPU 数量

模型评估示例

训练完成后，使用以下命令对模型进行测试：

bash tools/dist_test.sh ${CONFIG_FILE} ${GPUS} ${PATH_TO_MODEL} [optional arguments]

• ${PATH_TO_MODEL}: 训练生成的权重文件路径 (.pth)

进阶开发

如需自定义数据集、修改数据流水线或添加新模块，请参考项目目录下的 docs/en/tutorials 文档系列。