Dassl

简介

Dassl 是一个基于 PyTorch 的工具箱，最初为我们项目 领域自适应集成学习 (DAEL) 开发，旨在支持领域自适应和模型泛化方面的研究——因为在 DAEL 中，我们探索如何将这两个问题统一到一个单一的学习框架中。鉴于领域自适应与半监督学习密切相关——两者都研究如何利用未标记数据——我们也集成了支持后者研究的相关组件。

为什么取名为“Dassl”呢？Dassl 结合了领域自适应（DA）和半监督学习（SSL）的首字母，既自然又富有信息量。

Dassl 采用模块化设计和统一的接口，能够快速构建原型并实验新的领域自适应、领域泛化和半监督学习方法。借助 Dassl，只需几行代码就能实现一种新方法。不信？不妨看看 engine 文件夹，里面包含了大量现有方法的实现（看完后你一定会回来给这个仓库点个赞）。:-)

基本上，Dassl 非常适合用于以下领域的研究：

• 领域自适应
• 领域泛化
• 半监督学习

不过，得益于其整洁的设计，Dassl 也可以作为开发任何深度学习项目的代码库，比如 这个。:-)

Dassl 的一个不足之处在于，它目前还不支持分布式多 GPU 训练（Dassl 使用 DataParallel 包装模型，效率不如 DistributedDataParallel）。

与我们另一个 项目 不同，我们并未为 Dassl 提供详细的文档。这是因为 Dassl 主要面向研究用途，而作为研究人员，我们认为能够阅读源代码非常重要，也强烈鼓励大家这样做——绝不是因为我们懒惰。:-)

最新动态

• [2022年10月] 新论文 “设备端领域泛化” 已发表！代码、模型和数据集：https://github.com/KaiyangZhou/on-device-dg。

更多

• [2022年6月] v0.6.0：使 cfg.TRAINER.METHOD_NAME 与方法类名保持一致。
• [2022年6月] 新增了一种领域自适应方法 CDAC (CVPR'21)，由 Shreejal Trivedi 实现。详情请参见 这里。
• [2022年6月] 增加了来自 WILDS 基准测试的三个数据集：iWildCam、FMoW 和 Camelyon17。详情请参见 这里。
• [2022年5月] 新增了一种领域泛化方法 DDG，由 Zhishu Sun 开发，并将在 IJCAI'22 上发表。详情请参见 这里。
• [2022年3月] 新增了一种领域泛化方法 EFDM，由 Yabin Zhang (PolyU) 开发，并将在 CVPR'22 上发表。详情请参见 这里。
• [2022年2月] 如果你还不知道的话，DomainNet 数据集中绘画领域的某个类别只有测试图像（没有训练图像），这可能会影响性能。详情请参阅我们 论文 的第 4.a 节。
• [2021年10月] v0.5.0：对 transforms.py 进行了 重要更改。1) 在测试时，center_crop 成为默认变换（在将较短边调整到一定尺寸以保持图像宽高比之后应用）。2) 对于训练，当使用 random_crop 或 random_resized_crop 时，会禁用 Resize(cfg.INPUT.SIZE)。这些更改不会影响现有配置文件中使用的训练变换，也不会影响测试变换，除非原始图像不是正方形的（唯一的区别是现在会尊重图像的宽高比）。
• [2021年10月] v0.4.3：将 self.dm（数据管理器）中的属性复制到 SimpleTrainer 中，并使 self.dm 可选，这意味着从现在起，你可以从任何你喜欢的来源构建数据加载器，而不必强制使用 DataManager。
• [2021年9月] v0.4.2：一项重要的更新是在构建数据加载器时设置 drop_last=is_train and len(data_source)>=batch_size，以避免出现长度为 0 的批次。

概述

Dassl 已实现以下方法：

• 单源域适应

  • 用于半监督域适应的跨域自适应聚类（CVPR'21） [dassl/engine/da/cdac.py]
  • 基于极大极小熵的半监督域适应（ICCV'19） [dassl/engine/da/mme.py]
  • 用于无监督域适应的最大分类器差异（CVPR'18） [dassl/engine/da/mcd.py]
  • 用于视觉域适应的自集成方法（ICLR'18） [dassl/engine/da/self_ensembling.py]
  • 重新审视批量归一化以实现实用的域适应（ICLR-W'17） [dassl/engine/da/adabn.py]
  • 对抗性判别域适应（CVPR'17） [dassl/engine/da/adda.py]
  • 神经网络的域对抗训练（JMLR'16） [dassl/engine/da/dann.py]

• 多源域适应

  • 域适应集成学习 [dassl/engine/da/dael.py]
  • 用于多源域适应的矩匹配（ICCV'19） [dassl/engine/da/m3sda.py]

• 域泛化

  • 动态域泛化（IJCAI'22） [dassl/modeling/backbone/resnet_dynamic.py] [dassl/engine/dg/domain_mix.py]
  • 用于任意风格迁移和域泛化的精确特征分布匹配（CVPR'22） [dassl/modeling/ops/efdmix.py]
  • 使用 MixStyle 进行域泛化（ICLR'21） [dassl/modeling/ops/mixstyle.py]
  • 用于域泛化的深度域对抗图像生成（AAAI'20） [dassl/engine/dg/ddaig.py]
  • 通过交叉梯度训练实现跨域泛化（ICLR'18） [dassl/engine/dg/crossgrad.py]

• 半监督学习

  • FixMatch：简化半监督学习的一致性和置信度 [dassl/engine/ssl/fixmatch.py]
  • MixMatch：一种全面的半监督学习方法（NeurIPS'19） [dassl/engine/ssl/mixmatch.py]
  • 均值教师是更好的榜样：权重平均一致性目标提升半监督深度学习效果（NeurIPS'17） [dassl/engine/ssl/mean_teacher.py]
  • 基于熵最小化的半监督学习（NeurIPS'04） [dassl/engine/ssl/entmin.py]

欢迎提交 PR 以在此处添加您的方法，从而方便他人进行基准测试！

Dassl 支持以下数据集：

• 域适应

  • Office-31
  • Office-Home
  • VisDA17
  • CIFAR10-STL10
  • Digit-5
  • DomainNet
  • miniDomainNet

• 域泛化

  • PACS
  • VLCS
  • Office-Home
  • Digits-DG
  • Digit-Single
  • CIFAR-10-C
  • CIFAR-100-C
  • iWildCam-WILDS
  • Camelyon17-WILDS
  • FMoW-WILDS

• 半监督学习

  • CIFAR10/100
  • SVHN
  • STL10

开始使用

安装

请确保已正确安装 conda。

# 克隆此仓库
git clone https://github.com/KaiyangZhou/Dassl.pytorch.git
cd Dassl.pytorch/

# 创建一个 conda 环境
conda create -y -n dassl python=3.8

# 激活环境
conda activate dassl

# 安装 torch（要求版本 >= 1.8.1）和 torchvision
# 如果需要不同版本的 CUDA，请参考 https://pytorch.org/
conda install pytorch torchvision cudatoolkit=10.2 -c pytorch

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

# 安装本库（若源代码未修改，则无需重新构建）
python setup.py develop

请按照 DATASETS.md 中的说明对数据集进行预处理。

训练

主界面由 tools/train.py 实现，其主要流程如下：

1. 使用 cfg = setup_cfg(args) 初始化配置，其中 args 包含命令行输入（具体输入参数列表请参见 tools/train.py）；
2. 通过 build_trainer(cfg) 实例化一个 trainer，该过程会加载数据集并构建深度神经网络模型；
3. 调用 trainer.train() 进行模型的训练与评估。

下面以在流行的领域自适应数据集 Office-31 上训练源域专用基线为例：

CUDA_VISIBLE_DEVICES=0 python tools/train.py \
--root $DATA \
--trainer SourceOnly \
--source-domains amazon \
--target-domains webcam \
--dataset-config-file configs/datasets/da/office31.yaml \
--config-file configs/trainers/da/source_only/office31.yaml \
--output-dir output/source_only_office31

其中，$DATA 表示数据集的安装路径。--dataset-config-file 加载数据集的通用设置（例如本例中的 Office-31 数据集），如图像尺寸和模型架构。--config-file 则加载算法特定的设置，如超参数和优化参数。

若要使用多个源域，即进行多源领域自适应任务，只需在 --source-domains 中添加更多源域即可。例如，在 miniDomainNet 数据集上训练源域专用基线时，可以执行以下命令：

CUDA_VISIBLE_DEVICES=0 python tools/train.py \
--root $DATA \
--trainer SourceOnly \
--source-domains clipart painting real \
--target-domains sketch \
--dataset-config-file configs/datasets/da/mini_domainnet.yaml \
--config-file configs/trainers/da/source_only/mini_domainnet.yaml \
--output-dir output/source_only_minidn

训练完成后，模型权重将保存到指定的输出目录中，并附带日志文件和用于可视化的 TensorBoard 文件。

若需打印日志文件中保存的结果（避免手动逐个查看日志文件并计算均值与标准差），可使用 tools/parse_test_res.py 工具。具体使用说明可在代码中找到。

对于其他训练器，如 MCD，只需将 --trainer 设置为 MCD，同时保持配置文件不变，即沿用与 SourceOnly 相同的训练参数（最简单的情况）。若需修改 MCD 的超参数，例如 N_STEP_F（更新特征提取器的步数），可在现有命令行参数后追加 TRAINER.MCD.N_STEP_F 4（否则将使用默认值）。此外，也可以创建一个新的 .yaml 配置文件来存储自定义设置。有关算法特定超参数的完整列表，请参阅 此处。

测试

模型测试可通过 --eval-only 参数完成，该参数会调用代码中的 trainer.test() 方法。此外，还需提供已训练好的模型，并指定使用的模型文件（即保存于哪个 epoch）。例如，若要使用保存在 output/source_only_office31/model.pth.tar-20 的模型，可执行以下命令：

CUDA_VISIBLE_DEVICES=0 python tools/train.py \
--root $DATA \
--trainer SourceOnly \
--source-domains amazon \
--target-domains webcam \
--dataset-config-file configs/datasets/da/office31.yaml \
--config-file configs/trainers/da/source_only/office31.yaml \
--output-dir output/source_only_office31_test \
--eval-only \
--model-dir output/source_only_office31 \
--load-epoch 20

请注意，--model-dir 应指向训练阶段 --output-dir 中指定的目录路径。

编写新的训练器

建议先阅读 dassl/engine/trainer.py，熟悉基础训练器类，这些类提供了通用的功能和训练循环。若要编写用于领域自适应或半监督学习的训练器类，新类可继承自 TrainerXU；而对于领域泛化任务，则可继承自 TrainerX。特别地，TrainerXU 和 TrainerX 的主要区别在于是否使用无标签数据的数据加载器。借助这些基础类，新训练器通常只需实现 forward_backward() 方法，该方法负责损失计算和模型更新。具体示例可参考 dassl/enigne/da/source_only.py。

添加新的骨干网络/头部/网络

backbone 对应于执行特征提取的卷积神经网络模型。head（可选模块）则位于 backbone 之上，用于进一步处理，例如多层感知机（MLP）。backbone 和 head 是构建 SimpleNet() 的基本组件（详见 dassl/engine/trainer.py），而 SimpleNet() 则作为任务的主要模型。network 则包含自定义的神经网络模型，如图像生成器。

要添加新的模块，即骨干网络、头部或网络，首先需要使用相应的注册表进行注册：BACKBONE_REGISTRY 用于骨干网络，HEAD_REGISTRY 用于头部，NETWORK_RESIGTRY 用于网络。需要注意的是，对于新的骨干网络，要求其必须继承 dassl/modeling/backbone/backbone.py 中定义的 Backbone 类，并指定 self._out_features 属性。

下面提供一个添加新骨干网络的示例：

from dassl.modeling import Backbone, BACKBONE_REGISTRY

class MyBackbone(Backbone):

    def __init__(self):
        super().__init__()
        # 创建各层
        self.conv = ...

        self._out_features = 2048

    def forward(self, x):
        # 提取并返回特征

@BACKBONE_REGISTRY.register()
def my_backbone(**kwargs):
    return MyBackbone()

随后，可通过设置 MODEL.BACKBONE.NAME 为 my_backbone 来使用您自定义的架构。更多详细信息请参考 dassl/modeling 中的源代码。

添加数据集

以下是一个示例代码结构。请确保继承 DatasetBase 类，并使用 @DATASET_REGISTRY.register() 注册数据集。您只需加载 train_x、train_u（可选）、val（可选）和 test，其中 train_u 和 val 可以为 None 或直接忽略。这些变量各自包含一个 Datum 对象列表。Datum 对象（实现于 此处）包含单张图像的相关信息，如 impath（字符串）和 label（整数）。

from dassl.data.datasets import DATASET_REGISTRY, Datum, DatasetBase

@DATASET_REGISTRY.register()
class NewDataset(DatasetBase):

    dataset_dir = ''

    def __init__(self, cfg):
        
        train_x = ...
        train_u = ...  # 可选，可以为 None
        val = ...  # 可选，可以为 None
        test = ...

        super().__init__(train_x=train_x, train_u=train_u, val=val, test=test)

建议您参考一些基于 Dassl 构建的项目中的数据集代码，例如 此项目。

相关研究

我们在此分享与 Dassl 相关的研究：

• 设备端领域泛化
• 领域泛化：综述（TPAMI 2022）
• 领域自适应集成学习（TIP 2021）
• 用于领域泛化与适应的 MixStyle 神经网络
• 基于随机 StyleMatch 的半监督领域泛化
• 使用 MixStyle 的领域泛化（ICLR 2021）
• 为领域泛化学习生成新域（ECCV 2020）
• 用于领域泛化的深度领域对抗图像生成（AAAI 2020）

引用

如果您认为此代码对您的研究有帮助，请引用以下论文：

@article{zhou2022domain,
  title={Domain generalization: A survey},
  author={Zhou, Kaiyang and Liu, Ziwei and Qiao, Yu and Xiang, Tao and Loy, Chen Change},
  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
  year={2022},
  publisher={IEEE}
}

@article{zhou2021domain,
  title={Domain adaptive ensemble learning},
  author={Zhou, Kaiyang and Yang, Yongxin and Qiao, Yu and Xiang, Tao},
  journal={IEEE Transactions on Image Processing},
  volume={30},
  pages={8008--8018},
  year={2021},
  publisher={IEEE}
}

Dassl.pytorch 快速上手指南

Dassl (Domain Adaptive Semi-Supervised Learning) 是一个基于 PyTorch 的模块化工具箱，专为域适应 (DA)、域泛化 (DG) 和半监督学习 (SSL) 的研究而设计。它提供了统一的接口和大量预实现的算法与数据集，支持快速原型开发。

环境准备

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

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.8 及以上版本
• 包管理器: Conda (推荐)
• PyTorch: 1.8.1 及以上版本
• GPU: 支持 CUDA 的 NVIDIA 显卡（可选，但强烈建议用于训练）

注意: 目前 Dassl 使用 DataParallel 进行多卡包装，尚未原生支持高效的 DistributedDataParallel 分布式训练。

安装步骤

建议使用 Conda 创建独立的虚拟环境以避免依赖冲突。国内用户可使用清华或中科大镜像源加速下载。

# 1. 克隆仓库
git clone https://github.com/KaiyangZhou/Dassl.pytorch.git
cd Dassl.pytorch/

# 2. 创建并激活 Conda 环境 (指定 Python 3.8)
conda create -y -n dassl python=3.8
conda activate dassl

# 3. 安装 PyTorch 和 torchvision
# 国内用户推荐使用清华源加速 (-c 参数后添加镜像源地址)
# 请根据您的 CUDA 版本调整 cudatoolkit 版本，此处以 10.2 为例
conda install pytorch torchvision cudatoolkit=10.2 -c pytorch -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

# 4. 安装其他依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 以开发模式安装 Dassl 库
# 此步骤允许您修改源代码后立即生效，无需重新编译
python setup.py develop

安装完成后，请参考项目中的 DATASETS.md 文档下载并预处理所需的数据集（如 Office-31, PACS 等），并将数据放置在指定目录。

基本使用

Dassl 的核心入口脚本是 tools/train.py。使用前需准备两个配置文件：

1. 数据集配置 (--dataset-config-file): 定义图像大小、模型架构等通用设置。
2. 训练器配置 (--config-file): 定义特定算法的超参数和优化策略。

最简单的使用示例

以下命令演示了如何在 Office-31 数据集上训练一个基础的 SourceOnly (仅源域) 基线模型，将 amazon 作为源域，webcam 作为目标域。

请确保已将 $DATA 替换为您本地数据集的实际根目录路径。

CUDA_VISIBLE_DEVICES=0 python tools/train.py \
--root $DATA \
--trainer SourceOnly \
--source-domains amazon \
--target-domains webcam \
--dataset-config-file configs/datasets/da/office31.yaml \
--config-file configs/trainers/da/source_only/office31.yaml \
--output-dir output/source_only_office31

参数说明

• --root: 数据集存放的根目录。
• --trainer: 指定要使用的算法类名（如 SourceOnly, DANN, MixStyle 等，可在 dassl/engine 目录下查看支持列表）。
• --source-domains / --target-domains: 指定源域和目标域名称。多源域适应只需在此处添加多个源域名称即可。
• --output-dir: 模型权重和日志的输出目录。

通过修改 --trainer 和对应的配置文件，您可以轻松切换至域泛化或半监督学习任务。