SSD：单次多框目标检测器

SSD 是一种使用单一网络进行目标检测的统一框架。

您可以使用该代码来训练、评估和测试目标检测任务。

免责声明

这是对基于 Caffe 的原始 SSD 的重新实现。官方仓库可在 这里 找到。arXiv 论文可在此查阅 这里。

本示例旨在复现这一优秀的检测器，同时充分利用 MXNet 的卓越特性。

• 该模型与 Caffe 版本完全兼容。
• 现已提供从 Caffe 转换模型的工具！
• 结果几乎与原始版本相同。然而，由于实现细节的不同，结果可能会略有差异。

新内容

• 此仓库现已弃用，我正在迁移到最新的 Gluon-CV，它更加用户友好，并且正在开发更多算法。此仓库将不再积极维护，但您仍可继续使用 MXNet 1.1.0（可能为 1.2.0）版本。
• 现在，此仓库内部已与官方 MXNet 后端的数据同步。大多数情况下，pip install mxnet 也可用于此仓库。
• 现提供 MobileNet 预训练模型。
• 增加了多个训练好的模型。
• 提供了一种更简单的方式，可以从主流分类网络（ResNet、Inception 等）中构建网络，并附有指南。
• 根据 Caffe 版本更新至最新版本，mAP 提升了 5%。
• 使用基于后端多线程引擎的 C++ 记录迭代器，在多 GPU 环境下实现了巨大的速度提升。
• 在训练过程中监控验证 mAP。
• 更多网络符号正在开发和测试中。
• 额外的算子现在位于 mxnet/src/operator/contrib 中，符号也已修改。请使用 Release-v0.2-beta 来加载旧模型。
• 为该仓库增加了 Docker 支持，预构建并包含所有软件包和依赖项。（仅限 Linux）
• 增加了 TensorBoard 支持，使研究更加便捷。（仅限 Linux）

演示结果

mAP

模型	训练数据	测试数据	mAP	备注
VGG16_reduced 300x300	VOC07+12 trainval	VOC07 test	77.8	快速
VGG16_reduced 512x512	VOC07+12 trainval	VOC07 test	79.9	慢速
Inception-v3 512x512	VOC07+12 trainval	VOC07 test	78.9	最快
Resnet-50 512x512	VOC07+12 trainval	VOC07 test	79.1	快速
MobileNet 512x512	VOC07+12 trainval	VOC07 test	72.5	超快速
MobileNet 608x608	VOC07+12 trainval	VOC07 test	74.7	超快速

• 更多内容即将添加

速度

模型	GPU	CUDNN	批量大小	FPS*
VGG16_reduced 300x300	TITAN X(Maxwell)	v5.1	16	95
VGG16_reduced 300x300	TITAN X(Maxwell)	v5.1	8	95
VGG16_reduced 300x300	TITAN X(Maxwell)	v5.1	1	64
VGG16_reduced 300x300	TITAN X(Maxwell)	N/A	8	36
VGG16_reduced 300x300	TITAN X(Maxwell)	N/A	1	28

*仅计算前向传播时间，不包括数据加载和绘图。

开始使用

• 选项 #1 - 使用 'Docker' 安装。如果您不熟悉这项技术，下方有一个 'Docker' 部分。 您可以获取最新镜像：

docker pull daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9

• 您需要 Python 模块：cv2、matplotlib 和 numpy。 如果您使用 MXNet 的 Python API，您可能已经安装了这些模块。 您可以通过 pip 或包管理器（如 apt-get）安装它们：

sudo apt-get install python-opencv python-matplotlib python-numpy

• 克隆此仓库：

# 如果您没有 git，请根据您的系统通过 apt 或 homebrew/yum 安装
sudo apt-get install git
# 切换到您希望克隆此仓库的目录
cd ~
git clone --recursive https://github.com/zhreshold/mxnet-ssd.git
# 确保使用 --recursive 进行克隆
# 如果未正确完成或您使用的是下载的仓库，请通过以下命令拉取所有子模块：
# git submodule update --recursive --init
cd mxnet-ssd/mxnet

• （如果您已安装官方 MXNet，则跳过此步骤。）编译 MXNet：cd /path/to/mxnet-ssd/mxnet。按照官方说明 这里 进行操作。

# 对于 Ubuntu/Debian
cp make/config.mk ./config.mk
# 如有必要进行修改

请记住，如果想进行训练，务必启用 CUDA，因为 CPU 训练速度极其缓慢。使用 CUDNN 是可选的，但强烈推荐。

尝试演示

• 下载预训练模型：ssd_resnet50_0712.zip，并解压到 model/ 目录。
• 运行

# 切换到 /path/to/mxnet-ssd
python demo.py --gpu 0
# 尝试示例：
python demo.py --epoch 0 --images ./data/demo/dog.jpg --thresh 0.5
python demo.py --cpu --network resnet50 --data-shape 512
# 第一次运行时需等待库加载

• 查看 python demo.py --help 以获取更多选项。

训练模型

本示例仅涵盖 Pascal VOC 数据集上的训练。其他数据集应可通过在 dataset/imdb.py 中创建 Imdb 类的子类来轻松支持。 有关详细信息，请参阅 dataset/pascal_voc.py 示例。

• 下载转换后的预训练 vgg16_reduced 模型 此处，并将 .param 和 .json 文件默认解压到 model/ 目录。
• 下载 PASCAL VOC 数据集，如果您已有则可跳过此步骤。

cd /path/to/where_you_store_datasets/
wget http://host.robots.ox.ac.uk/pascal/VOC/voc2012/VOCtrainval_11-May-2012.tar
wget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtrainval_06-Nov-2007.tar
wget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtest_06-Nov-2007.tar

# 解压数据。
tar -xvf VOCtrainval_11-May-2012.tar
tar -xvf VOCtrainval_06-Nov-2007.tar
tar -xvf VOCtest_06-Nov-2007.tar

• 我们将使用 VOC2007/2012 中的 trainval 数据集作为通用策略。 建议的目录结构是将 VOC2007 和 VOC2012 目录存储在同一个 VOCdevkit 文件夹中。
• 然后默认将 VOCdevkit 文件夹链接到 data/VOCdevkit：

ln -s /path/to/VOCdevkit /path/to/this_example/data/VOCdevkit

使用硬链接而不是复制可以节省一些磁盘空间。

• 创建打包的二进制文件以加快训练速度：

# cd /path/to/mxnet-ssd
bash tools/prepare_pascal.sh
# 或者如果你使用的是 Windows
python tools/prepare_dataset.py --dataset pascal --year 2007,2012 --set trainval --target ./data/train.lst
python tools/prepare_dataset.py --dataset pascal --year 2007 --set test --target ./data/val.lst --shuffle False

• 开始训练：

python train.py

• 默认情况下，此示例将使用 batch-size=32 和 learning_rate=0.004。如果你有不同的配置，可能需要稍微调整这些参数。可以运行 python train.py --help 查看更多训练选项。例如，如果你有 4 张 GPU 卡，可以这样设置：

# 注意：多 GPU 的最佳训练参数组合尚未完全确定
python train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001

• 内存占用：MXNet 非常节省内存，在 VGG16_reduced 模型上使用 batch-size 32 进行训练时，不使用 CUDNN（conv1_x 和 conv2_x 固定）的情况下，大约占用 4684MB。

评估训练好的模型

使用以下命令：

# cd /path/to/mxnet-ssd
python evaluate.py --gpus 0,1 --batch-size 128 --epoch 0

将模型转换为部署模式

这一步骤会移除所有损失层，并添加一个用于合并结果和非极大值抑制的层。当无法加载 Python 符号文件时非常有用。

# cd /path/to/mxnet-ssd
python deploy.py --num-class 20
# 然后你可以使用新模型运行演示，而无需加载 Python 符号文件
python demo.py --prefix model/ssd_300_deploy --epoch 0 --deploy

转换 Caffe 模型

Caffe 到 MXNet 的转换工具位于 /path/to/mxnet-ssd/tools/caffe_converter。

该工具经过特别修改，以处理 Caffe-SSD 中的自定义层。使用方法如下：

cd /path/to/mxnet-ssd/tools/caffe_converter
make
python convert_model.py deploy.prototxt name_of_pretrained_caffe_model.caffemodel ssd_converted
# 你可以使用这个转换后的模型以部署模式运行，而无需加载 Python 符号文件
python demo.py --prefix ssd_converted --epoch 1 --deploy

虽然不能保证每次转换都能成功，但至少目前效果不错。

旧版模型

由于引入了新的网络构建接口，旧版模型的权重名称存在不一致的问题。你仍然可以通过将符号文件重命名为 legacy_xxx.py 并使用 python train/demo.py --network legacy_xxx 来加载之前的模型。例如：

python demo.py --network 'legacy_vgg16_ssd_300.py' --prefix model/ssd_300 --epoch 0

Docker

首先确保已安装 docker。要在 Nvidia GPU 上运行，还需要安装 nvidia-docker 插件。

• 预构建的 Docker 镜像可在 https://hub.docker.com/r/daviddocker78/mxnet-ssd/ 获取。要下载预构建的镜像，运行以下命令：

docker pull daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9

如果你希望自行构建镜像，可以在本仓库的 docker 文件夹中找到 Dockerfile。

• 运行容器实例：

nvidia-docker run -it --rm myImageName:tag

现在你可以在容器中执行与本地安装 MXNet 相同的操作。更多信息请参阅 指南。

TensorBoard

• 社区为将 TensorBoard 集成到 MXNet 中做出了很大努力。如果你选择使用 Docker，预构建的镜像中已经包含了 TensorBoard。否则，请按照 此处 的说明进行安装。
• 在训练过程中，若想将训练损失曲线、各类别验证 AP 以及验证 ROC 曲线保存到 TensorBoard，可以指定：

python train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001 --tensorboard True

• 如果还想保存各层的分布情况（实际上是它们的方差），可以指定：

python train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001 --tensorboard True --monitor 40

• 使用 Docker 进行可视化：TensorBoard 的界面随着时间不断变化。为了获得最佳体验，建议下载最新的 TensorFlow Docker 镜像：

# 从 Docker Hub 下载预构建的镜像
docker pull tensorflow/tensorflow:1.4.0-devel-gpu
# 运行容器并使用 `-p` 标志打开端口。将存储日志的卷挂载到容器内的目录。
nvidia-docker run -it --rm -p 0.0.0.0:6006:6006 -v /my/full/experiment/path:/res tensorflow/tensorflow:1.4.0-devel-gpu
cd /res
tensorboard --logdir=.

如果不想使用 Docker，可以直接运行最后一行命令。现在 TensorBoard 正在加载你的实验事件数据。在浏览器中访问 0.0.0.0:6006，你就能看到 TensorBoard 界面了！

TensorBoard 可视化

MXNet-SSD 快速上手指南

MXNet-SSD 是基于 MXNet 框架实现的单发多框（Single Shot MultiBox）目标检测算法。本指南将帮助你快速搭建环境并运行演示。

注意：该仓库目前已停止活跃开发，作者推荐迁移至更现代且功能更全的 Gluon-CV。但本项目仍可用于复现经典 SSD 结果或与 Caffe 版本兼容的场景。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu/Debian)，Windows 需额外配置。
• GPU: 推荐使用 NVIDIA GPU 进行训练和推理（CPU 训练速度极慢）。
• 依赖软件:
  • Git
  • Python (2.7 或 3.x)
  • CUDA & cuDNN (如需 GPU 加速)

前置依赖安装

确保已安装以下 Python 模块：cv2, matplotlib, numpy。

# Ubuntu/Debian 系统安装示例
sudo apt-get update
sudo apt-get install -y git python-opencv python-matplotlib python-numpy

# 若使用 pip 安装
pip install opencv-python matplotlib numpy

2. 安装步骤

你可以选择 Docker 一键部署（推荐）或 源码编译安装。

方案 A：使用 Docker (推荐)

Docker 镜像已预装所有依赖及 MXNet，适合快速体验。

1. 拉取镜像 (支持 GPU):

   docker pull daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9
   

   (注：国内用户若拉取缓慢，可配置 Docker 国内加速器)

2. 运行容器:

   nvidia-docker run -it --rm daviddocker78/mxnet-ssd:gpu_0.12.0_cuda9
   

方案 B：源码编译安装

1. 克隆仓库 (务必使用 --recursive 参数以获取子模块):

   git clone --recursive https://github.com/zhreshold/mxnet-ssd.git
   cd mxnet-ssd/mxnet
   

   (若忘记加参数，可执行 git submodule update --recursive --init 补全)

2. 编译 MXNet:

   # 复制配置文件
   cp make/config.mk ./config.mk
   
   # 编辑 config.mk，启用 CUDA (USE_CUDA=1) 和 cuDNN (USE_CUDNN=1) 以加速
   # vim config.mk 
   
   # 开始编译 (根据 CPU 核心数调整 -j 参数)
   make -j$(nproc)
   

3. 安装 Python 接口:

   cd ../python
   python setup.py install
   # 或者添加环境变量
   export PYTHONPATH=/path/to/mxnet-ssd/mxnet/python:$PYTHONPATH
   

3. 基本使用

运行演示 (Demo)

1. 下载预训练模型: 下载 ResNet50 版本的模型并解压到 model/ 目录。

   • 模型地址: resnet50_ssd_512_voc0712_trainval.zip

   mkdir -p model
   cd model
   wget https://github.com/zhreshold/mxnet-ssd/releases/download/v0.6/resnet50_ssd_512_voc0712_trainval.zip
   unzip resnet50_ssd_512_voc0712_trainval.zip
   cd ..
   

2. 执行检测: 使用默认图片进行测试：

   python demo.py --gpu 0
   

   指定图片和阈值进行测试：

   python demo.py --epoch 0 --images ./data/demo/dog.jpg --thresh 0.5
   

   若无 GPU，可使用 CPU 模式（速度较慢）：

   python demo.py --cpu --network resnet50 --data-shape 512
   

简要训练流程 (Pascal VOC)

若需重新训练模型，请按以下步骤操作：

1. 准备数据集: 下载 Pascal VOC 2007 和 2012 数据集，并将其链接到项目目录：

   ln -s /path/to/VOCdevkit /path/to/mxnet-ssd/data/VOCdevkit
   

2. 生成二进制记录文件:

   bash tools/prepare_pascal.sh
   

3. 开始训练: 默认使用 VGG16_reduced 模型。

   python train.py
   

   多 GPU 训练示例 (4 卡):

   python train.py --gpus 0,1,2,3 --batch-size 128 --lr 0.001
   

模型部署转换

将训练好的模型转换为部署模式（移除损失层，添加 NMS 层），以便在不加载 Python 符号的情况下使用：

python deploy.py --num-class 20
python demo.py --prefix model/ssd_300_deploy --epoch 0 --deploy