BBN：用于长尾视觉识别的累积学习双边分支网络

周博彦、崔权、魏秀申*、陈兆民

本仓库是论文《BBN：用于长尾视觉识别的累积学习双边分支网络》（https://arxiv.org/abs/1912.02413）的官方 PyTorch 实现。（该工作已被 CVPR2020 接受，口头报告）

主要依赖

• torch == 1.0.1
• torchvision == 0.2.2_post3
• tensorboardX == 1.8
• Python 3

环境配置

本仓库是在 Ubuntu 16.04.5 LTS 上使用 Python 3.5.2/3.6.7 开发的。CUDA 和 cuDNN 的版本分别为 9.0 和 7.1.3。对于 CIFAR 数据集的实验，我们使用 一块 NVIDIA 1080ti 显卡 进行训练和测试。（iNaturalist 数据集则使用 四块显卡）。其他平台或显卡尚未经过全面测试。

iNaturalist 数据集的预训练模型

我们提供了 iNaturalist 2018 和 iNaturalist 2017 数据集的 BBN 预训练模型，分别对应 1x 和 2x 学习率调度器。

iNaturalist 2018：百度网盘、Google Drive

iNaturalist 2017：百度网盘、Google Drive

使用方法

# 使用不平衡比为 50 的长尾 CIFAR-10 数据集进行训练：
python main/train.py  --cfg configs/cifar10.yaml     

# 使用最佳模型进行验证：
python main/valid.py  --cfg configs/cifar10.yaml

# 在 CPU 模式下调试：
python main/train.py  --cfg configs/cifar10.yaml   CPU_MODE True

您可以通过修改 YAML 配置文件中的参数来调整实验设置。

数据格式

数据集的标注是一个字典，包含两个字段：annotations 和 num_classes。 其中，annotations 是一个列表，每个元素是一个字典，包含 image_id、fpath、im_height、im_width 和 category_id。

以下是一个示例：

{
    'annotations': [
                    {
                        'image_id': 1,
                        'fpath': '/home/BBN/iNat18/images/train_val2018/Plantae/7477/3b60c9486db1d2ee875f11a669fbde4a.jpg',
                        'im_height': 600,
                        'im_width': 800,
                        'category_id': 7477
                    },
                    ...
                   ]
    'num_classes': 8142
}

您可以使用以下代码将 iNaturalist 的原始格式转换为所需格式。图像和标注可从 iNaturalist 2018 和 iNaturalist 2017 下载。

# 从 iNaturalist 原始格式转换
python tools/convert_from_iNat.py --file train2018.json --root /home/iNat18/images --sp /home/BBN/jsons

引用本仓库

如果您在研究中使用了本代码，请考虑引用我们：

@article{zhou2020BBN,
	title={{BBN}: Bilateral-Branch Network with Cumulative Learning for Long-Tailed Visual Recognition},
	author={Boyan Zhou and Quan Cui and Xiu-Shen Wei and Zhao-Min Chen},
	booktitle={CVPR},
	pages={1--8},
	year={2020}
}

联系方式

如对我们的工作有任何疑问，请随时通过电子邮件与我们联系。

魏秀申：weixs.gm@gmail.com

周博彦：zhouboyan94@gmail.com

崔权：cui-quan@toki.waseda.jp

BBN 快速上手指南

BBN (Bilateral-Branch Network) 是一个用于长尾视觉识别的双分支网络，支持累积学习。本项目基于 PyTorch 实现，曾发表于 CVPR 2020 (Oral)。

环境准备

在开始之前，请确保您的系统满足以下要求。本项目主要在 Ubuntu 16.04 LTS + Python 3.5/3.6 环境下开发测试。

• 操作系统: Ubuntu 16.04.5 LTS (推荐)
• Python 版本: 3.5.2 或 3.6.7
• GPU 驱动: CUDA 9.0, cuDNN 7.1.3
• 硬件建议:
  • CIFAR 实验：1 张 NVIDIA 1080ti
  • iNaturalist 实验：4 张 NVIDIA 1080ti

核心依赖库

请安装以下特定版本的依赖，以保证复现效果：

• torch == 1.0.1
• torchvision == 0.2.2_post3
• tensorboardX == 1.8

提示：国内用户建议使用清华源或阿里源加速安装。例如： pip install torch==1.0.1 torchvision==0.2.2_post3 tensorboardX==1.8 -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 克隆代码仓库

   git clone <repository_url>
   cd BBN
   

2. 安装依赖 确保已安装对应版本的 PyTorch 后，安装其他必要包：

   pip install tensorboardX==1.8
   

3. 数据准备 (可选) 若使用 iNaturalist 数据集，需先将原始标注格式转换为 BBN 所需格式。 下载图片与标注文件后，运行以下命令转换：

   python tools/convert_from_iNat.py --file train2018.json --root /home/iNat18/images --sp /home/BBN/jsons
   

   注：如需预训练模型，可从提供的百度网盘或 Google Drive 链接下载。

基本使用

配置文件位于 configs/ 目录下，修改 YAML 文件即可调整实验参数。

1. 训练模型

以不平衡比为 50 的长尾 CIFAR-10 数据集为例：

python main/train.py  --cfg configs/cifar10.yaml

2. 验证模型

使用训练得到的最佳模型进行验证：

python main/valid.py  --cfg configs/cifar10.yaml

3. CPU 调试模式

若无 GPU 环境，可开启 CPU 模式进行调试：

python main/train.py  --cfg configs/cifar10.yaml   CPU_MODE True

数据格式说明

自定义数据集的标注文件需为字典格式，包含 annotations (列表) 和 num_classes (整数)。 annotations 列表中每个元素需包含：image_id, fpath, im_height, im_width, category_id。