使用 PyTorch 的 DeepLab

这是 DeepLab v2 [1] 的非官方 PyTorch 实现，采用 ResNet-101 作为骨干网络。

• 支持 COCO-Stuff 数据集 [2] 和 PASCAL VOC 数据集 [3]。
• 可以直接使用作者提供的官方 Caffe 权重，无需构建 Caffe API。
• 同样包含了具有相同骨干网络的 DeepLab v3/v3+ 模型（未经过测试）。
• 支持 torch.hub。

性能

COCO-Stuff

训练集	验证集	代码	权重	CRF?	像素 准确率	平均 准确率	平均 IoU	频率加权 IoU
1万张 train †	1万张 val †	官方 [2]			65.1	45.5	34.4	50.4
		本仓库	下载		65.8	45.7	34.8	51.2
				✓	67.1	46.4	35.6	52.5
16.4万张 train	16.4万张 val	本仓库	下载 ‡		66.8	51.2	39.1	51.5
				✓	67.6	51.5	39.7	52.3

† 图像和标签已预先转换为 513x513 的正方形形状
‡ 对于 SPADE 的关注者请注意：提供的 COCO-Stuff 16.4 万张数据集权重自 2019 年 2 月 23 日起一直保持不变。

PASCAL VOC 2012

训练集	验证集	代码	权重	CRF?	像素 准确率	平均 准确率	平均 IoU	频率加权 IoU
trainaug	val	官方 [3]			-	-	76.35	-
				✓	-	-	77.69	-
		本仓库	下载		94.64	86.50	76.65	90.41
				✓	95.04	86.64	77.93	91.06

设置

要求

所需的 Python 包列在 Anaconda 配置文件 configs/conda_env.yaml 中。 请根据需要修改其中列出的 cudatoolkit=10.2 和 python=3.6，然后运行以下命令。

# 使用 Anaconda 进行设置
conda env create -f configs/conda_env.yaml
conda activate deeplab-pytorch

下载数据集

• COCO-Stuff 1万/16.4万
• PASCAL VOC 2012

下载预训练的 caffemodels

DeepLab 的作者发布了在 COCO 和 PASCAL VOC 数据集上预训练的 caffemodels。 根据相关论文 [1,2]，本仓库使用 COCO 上训练的参数作为初始权重。

1. 运行以下脚本下载预训练的 caffemodels（1GB 以上）。

$ bash scripts/setup_caffemodels.sh

2. 将 caffemodels 转换为与 PyTorch 兼容的格式。无需构建 Caffe API！

# 从 "init.caffemodel" 生成 "deeplabv1_resnet101-coco.pth"
$ python convert.py --dataset coco
# 从 "train2_iter_20000.caffemodel" 生成 "deeplabv2_resnet101_msc-vocaug.pth"
$ python convert.py --dataset voc12

训练与评估

在 PASCAL VOC 2012 数据集上训练 DeepLab v2：

python main.py train \
    --config-path configs/voc12.yaml

在验证集上评估模型性能：

python main.py test \
    --config-path configs/voc12.yaml \
    --model-path data/models/voc12/deeplabv2_resnet101_msc/train_aug/checkpoint_final.pth

注意：该命令会保存预测的 logits 图（.npy）和分数（.json）。

使用 CRF 后处理重新评估：

python main.py crf \
    --config-path configs/voc12.yaml

依次执行上述脚本等价于运行 bash scripts/train_eval.sh。

要监控损失，可在另一个终端中运行以下命令：

tensorboard --logdir data/logs

请为其他数据集指定相应的配置文件。

数据集	配置文件	迭代次数	类别
PASCAL VOC 2012	configs/voc12.yaml	20,000	20 前景类 + 1 背景类
COCO-Stuff 10k	configs/cocostuff10k.yaml	20,000	182 个物/stuff 类
COCO-Stuff 164k	configs/cocostuff164k.yaml	100,000	182 个物/stuff 类

注意：尽管 COCO-Stuff 10k/164k 中的标签索引范围为 0 到 181，但仅有 171 个类别 被监督学习。

常见设置：

• 模型：采用 ResNet-101 作为骨干网络的 DeepLab v2。ASPP 的空洞率分别为 (6, 12, 18, 24)。输出步幅为 8。
• GPU：使用进程中可见的所有 GPU。可通过 CUDA_VISIBLE_DEVICES= 指定使用的 GPU 范围。
• 多尺度损失：损失定义为来自多尺度输入（1x、0.75x、0.5x）响应的总和，并在各个尺度之间取逐元素最大值。未标记 类别在损失计算中被忽略。
• 梯度累积：由于 GPU 显存占用较高，不一次性处理 10 张样本的 mini-batch，而是先累积 5 张小 batch 的梯度共 2 次，最后再进行权重更新（batch_size * iter_size = 10）。默认设置下显存占用约为 11.2 GB（在单块 Titan X 上测试）。可通过减小 batch_size 来降低显存占用。
• 学习率：采用带有 0.9 动量的随机梯度下降法（SGD），初始学习率为 2.5e-4。使用多项式学习率衰减策略；每 10 次迭代，学习率乘以 (1-iter/iter_max)**power。
• 监控：可在 TensorBoard 中监控移动平均损失（Caffe 中的 average_loss）。
• 预处理：输入图像会随机缩放至 0.5 至 1.5 倍，必要时填充，并随机裁剪为 321x321。

COCO-Stuff 164k 中处理后的图像和标签：

推理演示

您可以使用 预训练模型、转换后的模型 或您自己的模型。

处理单张图像：

python demo.py single \
    --config-path configs/voc12.yaml \
    --model-path deeplabv2_resnet101_msc-vocaug-20000.pth \
    --image-path image.jpg

使用摄像头实时运行：

python demo.py live \
    --config-path configs/voc12.yaml \
    --model-path deeplabv2_resnet101_msc-vocaug-20000.pth

若需进行 CRF 后处理，可添加 --crf 参数。若要在 CPU 上运行，可添加 --cpu 参数。

杂项

torch.hub

只需两行代码即可完成模型加载：

import torch.hub
model = torch.hub.load("kazuto1011/deeplab-pytorch", "deeplabv2_resnet101", pretrained='cocostuff164k', n_classes=182)

与 Caffe 版本的区别

• 官方代码仅对 0.5x 输入的标签采用 1/16 双线性插值（Interp 层）进行下采样，而本代码库则对 0.5x 和 0.75x 输入均采用最近邻插值（PIL.Image.resize，相关问题见 GitHub issue #51）。
• 对图像和 logits 的双线性插值使用了 align_corners=False。

批归一化层的训练

本代码库仅支持冻结批归一化层的 DeepLab v2 训练，而 v3/v3+ 协议要求对这些层进行训练。如果您在项目中也需要在多 GPU 上训练这些参数，请安装以下 额外库：

pip install torch-encoding

模型中的批归一化层会在 libs/models/resnet.py 中自动切换：

try:
    from encoding.nn import SyncBatchNorm
    _BATCH_NORM = SyncBatchNorm
except:
    _BATCH_NORM = nn.BatchNorm2d

参考文献

1. L.-C. Chen, G. Papandreou, I. Kokkinos, K. Murphy, A. L. Yuille. DeepLab：基于深度卷积网络、空洞卷积和全连接 CRF 的语义图像分割。IEEE TPAMI，2018 年。
   项目 / 代码 / arXiv 论文

2. H. Caesar, J. Uijlings, V. Ferrari. COCO-Stuff：上下文中的“物”与“stuff”类别。发表于 CVPR，2018 年。
   项目 / arXiv 论文

3. M. Everingham, L. Van Gool, C. K. I. Williams, J. Winn, A. Zisserman. PASCAL 视觉目标类别（VOC）挑战赛。IJCV，2010 年。
   项目 / 论文

DeepLab-PyTorch 快速上手指南

本指南基于 deeplab-pytorch 项目，帮助开发者快速在 PyTorch 环境中部署和运行 DeepLab v2 语义分割模型（ResNet-101 骨干网络）。

环境准备

本项目依赖 Anaconda 管理环境，推荐使用 Linux 系统并配备 NVIDIA GPU。

• 操作系统: Linux (推荐)
• Python: 3.6+ (默认配置为 3.6)
• CUDA: 10.2 (可根据实际显卡驱动调整)
• 核心依赖: PyTorch, torchvision, numpy, pillow, scipy, tensorboardX 等

注意：请确保已安装正确的 CUDA 驱动和 cuDNN。

安装步骤

1. 克隆仓库与创建环境

首先克隆代码库，并根据提供的配置文件创建 Conda 环境。如需适配国内网络，建议在创建环境前配置清华或中科大镜像源。

git clone https://github.com/kazuto1011/deeplab-pytorch.git
cd deeplab-pytorch

# (可选) 配置国内镜像源加速下载
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/

# 创建环境 (如需修改 Python 或 CUDA 版本，请先编辑 configs/conda_env.yaml)
conda env create -f configs/conda_env.yaml
conda activate deeplab-pytorch

2. 下载预训练权重

本项目支持直接使用官方发布的 Caffe 权重，无需安装 Caffe。运行脚本下载权重并转换为 PyTorch 格式。

# 下载官方 Caffe 预训练模型 (约 1GB+)
bash scripts/setup_caffemodels.sh

# 将 COCO 数据集预训练模型转换为 PyTorch 格式
python convert.py --dataset coco

# 将 PASCAL VOC 数据集预训练模型转换为 PyTorch 格式
python convert.py --dataset voc12

转换后将生成 deeplabv1_resnet101-coco.pth 和 deeplabv2_resnet101_msc-vocaug.pth 等文件。

3. 准备数据集 (可选)

如需重新训练或评估，需下载以下数据集并按项目说明放置：

• COCO-Stuff: 下载链接
• PASCAL VOC 2012: 下载链接

基本使用

方式一：使用 torch.hub 快速加载 (推荐)

无需下载代码库，直接通过两行代码加载预训练模型进行推理。

import torch
import torch.hub

# 加载在 COCO-Stuff 164k 上预训练的 DeepLab v2 (ResNet-101)
model = torch.hub.load("kazuto1011/deeplab-pytorch", "deeplabv2_resnet101", pretrained='cocostuff164k', n_classes=182)
model.eval()

# 准备输入图像 (假设 input_tensor 形状为 [1, 3, H, W])
# with torch.no_grad():
#     output = model(input_tensor)

方式二：命令行单图推理

使用本地转换好的模型对单张图片进行语义分割预测。

python demo.py single \
    --config-path configs/voc12.yaml \
    --model-path deeplabv2_resnet101_msc-vocaug-20000.pth \
    --image-path image.jpg

• 实时摄像头演示:

  python demo.py live \
      --config-path configs/voc12.yaml \
      --model-path deeplabv2_resnet101_msc-vocaug-20000.pth
  

• 附加选项:
  • 添加 --crf 启用 CRF 后处理以提升边缘细节。
  • 添加 --cpu 在无 GPU 环境下运行。

方式三：训练与评估

使用 PASCAL VOC 2012 数据集进行训练示例：

# 开始训练
python main.py train \
    --config-path configs/voc12.yaml

# 验证集评估
python main.py test \
    --config-path configs/voc12.yaml \
    --model-path data/models/voc12/deeplabv2_resnet101_msc/train_aug/checkpoint_final.pth

# 使用 CRF 重新评估
python main.py crf \
    --config-path configs/voc12.yaml

提示: 训练过程中可新开终端运行 tensorboard --logdir data/logs 监控损失曲线。默认配置使用多尺度损失和梯度累积策略，显存占用约为 11.2GB (Titan X)，可通过减小 batch_size 优化显存使用。