通知（2019年11月2日）

这个仓库是在两年前搭建的，当时还没有能够达到合理性能的 PyTorch 目标检测实现。如今，已经有许多更优秀的项目，例如：

• detectron2（这真是一部杰作。）
• mmdetection

因此，本仓库将不再进行积极维护。

重要提示：

如果您在 2017年9月26日之前使用过主分支及其对应的预训练模型，请务必注意： 旧的主分支现已移至 old_master 分支。您仍然可以运行代码并下载预训练模型，但该旧主分支的预训练模型与当前主分支不兼容！

新旧主分支的主要区别在于以下两个提交：9d4c24e 和 c899ce7。 这些改动与 此问题 相关；现在的主分支已完全匹配 tf-faster-rcnn 中的所有细节，因此我们现在可以将 TensorFlow 的预训练模型转换为 PyTorch 模型。

pytorch-faster-rcnn

基于 Xinlei Chen 的 tf-faster-rcnn 的 Faster R-CNN 目标检测框架的 PyTorch 实现。Xinlei Chen 的仓库则基于可用的 Python Caffe 版本的 Faster R-CNN 实现，详见 此处。

注：在重新实现该框架时，我们做了一些小的修改，这些修改带来了潜在的性能提升。有关具体修改及消融实验的详细信息，请参阅技术报告《Faster R-CNN 的实现及其区域采样研究》（arXiv:1702.02138）。如果您希望复现原始论文中的结果，请使用 官方代码 或者 半官方代码。关于 Faster R-CNN 架构的详细信息，请参阅论文《Faster R-CNN：基于区域建议网络的实时目标检测》（arXiv:1506.01497）。

检测性能

当前代码支持 VGG16、Resnet V1 和 Mobilenet V1 模型。我们主要在普通的 VGG16 和 Resnet101 架构上进行了测试。作为基准，我们报告的是在单个卷积层上使用单个模型的结果，因此未采用多尺度、多阶段边界框回归、跳跃连接或额外输入等技术。唯一的数据增强技术是在训练过程中按照原始 Faster RCNN 的方式进行左右翻转。所有模型均已公开发布。

使用 VGG16（conv5_3）：

• 在 VOC 2007 trainval 上训练，并在 VOC 2007 test 上测试，71.22（从零开始训练）70.75（转换后）（tf-faster-rcnn 为 70.8）。
• 在 VOC 2007+2012 trainval 上训练，并在 VOC 2007 test 上测试（R-FCN 训练计划），75.33（从零开始训练）75.27（转换后）（tf-faster-rcnn 为 75.7）。
• 在 COCO 2014 trainval35k 上训练，并在 minival（900k/1190k）上测试，29.2（从零开始训练）30.1（转换后）（tf-faster-rcnn 为 30.2）。

使用 Resnet101（最后一个 conv4）：

• 在 VOC 2007 trainval 上训练，并在 VOC 2007 test 上测试，75.29（从零开始训练）75.76（转换后）（tf-faster-rcnn 为 75.7）。
• 在 VOC 2007+2012 trainval 上训练，并在 VOC 2007 test 上测试（R-FCN 训练计划），79.26（从零开始训练）79.78（转换后）（tf-faster-rcnn 为 79.8）。
• 在 COCO 2014 trainval35k 上训练，并在 minival（800k/1190k）上测试，35.1（从零开始训练）35.4（转换后）（tf-faster-rcnn 为 35.4）。

更多结果：

• 在 COCO 2014 trainval35k 上训练 Mobilenet（1.0, 224），并在 minival（900k/1190k）上测试，21.4（从零开始训练），21.9（转换后）（tf-faster-rcnn 为 21.8）。
• 在 COCO 2014 trainval35k 上训练 Resnet50，并在 minival（900k/1190k）上测试，32.4（转换后）（tf-faster-rcnn 为 32.4）。
• 在 COCO 2014 trainval35k 上训练 Resnet152，并在 minival（900k/1190k）上测试，36.7（转换后）（tf-faster-rcnn 为 36.1）。

近似的 基准 设置 来自 FPN（本仓库目前尚未包含 FPN 的训练代码）：

• 在 COCO 2014 trainval35k 上训练 Resnet50，并在 minival（900k/1190k）上测试，34.2。
• 在 COCO 2014 trainval35k 上训练 Resnet101，并在 minival（900k/1190k）上测试，37.4。
• 在 COCO 2014 trainval35k 上训练 Resnet152，并在 minival（900k/1190k）上测试，38.2。

注：

• 由于 GPU 训练的随机性，尤其是在 VOC 数据集上，此处报告的是经过 2–3 次尝试后得到的最佳结果。根据 Xinlei 的经验，对于 COCO 数据集，尽管存在随机性，几乎总是可以获得非常接近的结果（误差在 ~0.2% 以内）。

• 这些数字是使用 默认 测试方案得出的，该方案通过非极大值抑制（TEST.MODE nms）来选择区域建议。另一种测试方案（TEST.MODE top）可能会带来略微更好的性能（参见 报告，对于 COCO 数据集可提升 0.X AP）。

• 由于我们保留了小的建议区域（宽度/高度小于 16 像素），我们的性能在检测小物体时尤为出色。

• 我们并未为检测结果设置阈值（而非 0.05），这提高了召回率。

• 权重衰减设置为 1e-4。

• 其他细微的修改请参阅 报告。值得注意的是，我们使用了 crop_and_resize，并在训练过程中将真实框排除在 RoI 之外。

• 对于 COCO 数据集，我们发现随着迭代次数的增加，性能会有所提升，而进一步增加迭代次数可能会带来更好的效果。

• 对于 Resnets 模型，在微调网络时，我们固定了第一个模块（共 4 个），并仅使用 crop_and_resize 来调整 RoI 大小（7×7），而不进行最大池化（Xinlei 认为这对于 COCO 数据集尤其没有帮助）。最终的特征图会进行平均池化以用于分类和回归。所有批量归一化参数均被固定。偏置的学习率并未加倍。

• 对于 Mobilenets 模型，在微调网络时，我们固定了前五个层。所有批量归一化参数均被固定。Mobilenet 层的权重衰减设置为 4e-5。

• 对于近似的 FPN 基准设置，我们只需将图像缩放至 800 像素，添加 32^2 个锚点，并在测试时选取 1000 个建议区域。

• 请访问 这里 / 这里 / 这里 获取最新模型，包括更长训练时间的 COCO VGG16 模型和 Resnet 模型。

TensorBoard 上显示的真实框	TensorBoard 上显示的预测结果

附加功能

为了使研究工作更加便捷，我们添加了一些 报告 中未提及的附加功能：

• 支持训练与验证同时进行。在训练过程中，验证数据也会不时被测试，以监控训练进程并检查潜在的过拟合现象。理想情况下，训练和验证应分开进行，每次加载模型到验证集上进行测试。然而，Xinlei 实现了一种联合的方式，以节省时间和 GPU 内存。尽管在默认设置中验证数据也用于测试，但并未刻意针对测试集进行过拟合。
• 支持恢复训练。Xinlei 在保存快照时尽可能多地存储信息，以便能够从最新的快照正确地恢复训练。元信息包括当前图像索引、图像排列顺序以及 numpy 的随机状态。然而，当您恢复训练时，tensorflow 的随机种子会被重置（目前尚不清楚如何保存 tensorflow 的随机状态），因此可能会导致差异。请注意，即使设置了随机种子，当前实现仍无法使模型表现出确定性行为。欢迎提出建议或解决方案，我们将不胜感激。
• 支持可视化。当前实现会在训练过程中汇总真实框、损失统计、激活值和变量，并将其转储到一个单独的文件夹中，以便在 tensorboard 上进行可视化。计算图也会被保存下来，便于调试。

前置条件

• 需要安装基础的 PyTorch。代码遵循 1.0 版本。如果你使用的是旧版本如 0.1.12、0.2、0.3 或 0.4，可以检出对应的分支。
• Torchvision 0.3。此代码使用 torchvision.ops 中的 nms、roi_pool 和 roi_align。
• 可能尚未安装的 Python 包：opencv-python、easydict（类似于 py-faster-rcnn）。对于 easydict，请确保版本正确，Xinlei 使用的是 1.6 版。
• tensorboard-pytorch，用于可视化训练和验证曲线。请从源码构建以使用最新版本的 tensorflow-tensorboard。
• Docker 用户：自最近升级以来，Docker Hub 上的镜像（https://hub.docker.com/r/mbuckler/tf-faster-rcnn-deps/）已不再有效。不过，你仍然可以使用位于 docker 文件夹中的 Dockerfile 构建自己的镜像（CUDA 8 版本，因为 TensorFlow r1.0 要求）。同时，请按照 TensorFlow 的安装说明安装并使用 nvidia-docker[https://github.com/NVIDIA/nvidia-docker]。最后，在启动容器后，必须在运行中的容器内构建 Cython 模块。

安装

1. 克隆仓库

git clone https://github.com/ruotianluo/pytorch-faster-rcnn.git

2. 安装 Python COCO API。代码需要该 API 来访问 COCO 数据集。

cd data
git clone https://github.com/pdollar/coco.git
cd coco/PythonAPI
make
cd ../../..

数据准备

请参照 py-faster-rcnn 的说明 这里 设置 VOC 和 COCO 数据集（COCO 的部分已完成）。步骤包括下载数据，并可选地在 data 文件夹中创建软链接。由于 Faster R-CNN 不依赖于预计算的候选框，因此可以忽略设置候选框的相关步骤。

如果你觉得有用，Xinlei 方面创建的 data/cache 文件夹也在此共享 这里。

使用预训练模型进行演示和测试

1. 下载预训练模型（仅 Google Drive 可用）

• 另一台服务器 这里。
• Google Drive 这里。

(可选) 除了下载我提供的预训练或转换后的模型，你也可以从 tf-faster-rcnn 模型进行转换。 你可以从 tf-faster-rcnn 下载 TensorFlow 预训练模型。 然后运行：

python tools/convert_from_tensorflow.py --tensorflow_model resnet_model.ckpt 
python tools/convert_from_tensorflow_vgg.py --tensorflow_model vgg_model.ckpt

该脚本将在与 TensorFlow 模型同名的文件夹中生成一个 .pth 文件。

2. 创建文件夹并建立软链接以使用预训练模型

NET=res101
TRAIN_IMDB=voc_2007_trainval+voc_2012_trainval
mkdir -p output/${NET}/${TRAIN_IMDB}
cd output/${NET}/${TRAIN_IMDB}
ln -s ../../../data/voc_2007_trainval+voc_2012_trainval ./default
cd ../../..

3. 自定义图像的演示与测试

# 在仓库根目录下
GPU_ID=0
CUDA_VISIBLE_DEVICES=${GPU_ID} ./tools/demo.py

注意：Resnet101 的测试可能需要数 GB 内存，因此若遇到内存不足的问题，请仅使用 CPU 支持的方式运行。参考 Issue 25。

4. 使用预训练的 Resnet101 模型进行测试

GPU_ID=0
./experiments/scripts/test_faster_rcnn.sh $GPU_ID pascal_voc_0712 res101

注意：如果无法得到报告的指标（我这边是 79.8），则可能是 NMS 函数编译不当，可参考 Issue 5。

训练你自己的模型

1. 下载预训练模型和权重。当前代码支持 VGG16 和 Resnet V1 模型。预训练模型由 pytorch-vgg 和 pytorch-resnet（名称中带有“caffe”的版本）提供，你可以下载这些预训练模型并将其放置在 data/imagenet_weights 文件夹中。例如，对于 VGG16 模型，可以按以下步骤设置：

   mkdir -p data/imagenet_weights
   cd data/imagenet_weights
   python # 在终端中打开 Python 并运行以下 Python 代码
   

   import torch
   from torch.utils.model_zoo import load_url
   from torchvision import models
   
   sd = load_url("https://s3-us-west-2.amazonaws.com/jcjohns-models/vgg16-00b39a1b.pth")
   sd['classifier.0.weight'] = sd['classifier.1.weight']
   sd['classifier.0.bias'] = sd['classifier.1.bias']
   del sd['classifier.1.weight']
   del sd['classifier.1.bias']
   
   sd['classifier.3.weight'] = sd['classifier.4.weight']
   sd['classifier.3.bias'] = sd['classifier.4.bias']
   del sd['classifier.4.weight']
   del sd['classifier.4.bias']
   
   torch.save(sd, "vgg16.pth")
   

   cd ../..
   

   对于 Resnet101，可以按以下步骤设置：

   mkdir -p data/imagenet_weights
   cd data/imagenet_weights
   # 从我的 Google Drive 下载（链接在 pytorch-resnet 中）
   mv resnet101-caffe.pth res101.pth
   cd ../..
   

   对于 Mobilenet V1，可以按以下步骤设置：

   mkdir -p data/imagenet_weights
   cd data/imagenet_weights
   # 从我的 Google Drive 下载（https://drive.google.com/open?id=0B7fNdx_jAqhtZGJvZlpVeDhUN1k）
   mv mobilenet_v1_1.0_224.pth.pth mobile.pth
   cd ../..
   

2. 训练（以及测试、评估）

./experiments/scripts/train_faster_rcnn.sh [GPU_ID] [DATASET] [NET]
# GPU_ID 是你要用来测试的 GPU 编号
# NET 可取 {vgg16, res50, res101, res152}，表示要使用的网络架构
# DATASET {pascal_voc, pascal_voc_0712, coco} 在 train_faster_rcnn.sh 中定义
# 示例：
./experiments/scripts/train_faster_rcnn.sh 0 pascal_voc vgg16
./experiments/scripts/train_faster_rcnn.sh 1 coco res101

注意：请务必在训练前删除指向预训练模型的软链接。如果在训练过程中遇到 NaN 值，请参考 Issue 86。此外，如果你希望支持多 GPU 训练，请查看 Issue 121。

3. 使用 TensorBoard 可视化

tensorboard --logdir=tensorboard/vgg16/voc_2007_trainval/ --port=7001 &
tensorboard --logdir=tensorboard/vgg16/coco_2014_train+coco_2014_valminusminival/ --port=7002 &

4. 测试与评估

./experiments/scripts/test_faster_rcnn.sh [GPU_ID] [DATASET] [NET]
# GPU_ID 是你要用来测试的 GPU 编号
# NET 可取 {vgg16, res50, res101, res152}，表示要使用的网络架构
# DATASET {pascal_voc, pascal_voc_0712, coco} 在 test_faster_rcnn.sh 中定义
# 示例：
./experiments/scripts/test_faster_rcnn.sh 0 pascal_voc vgg16
./experiments/scripts/test_faster_rcnn.sh 1 coco res101

5. 你可以使用 tools/reval.sh 进行重新评估。

默认情况下，训练好的网络会保存在以下路径：

output/[NET]/[DATASET]/default/

测试输出会保存在以下路径：

output/[NET]/[DATASET]/default/[SNAPSHOT]/

TensorBoard 的训练和验证信息会保存在以下路径：

tensorboard/[NET]/[DATASET]/default/
tensorboard/[NET]/[DATASET]/default_val/

默认的训练迭代次数与原始 Faster R-CNN 对于 VOC 2007 的设置相同，然而 Xinlei 发现延长训练时间是有益的（参见 COCO 的 报告），这可能是因为图像批次大小为 1。对于 VOC 07+12 数据集，我们采用了 80k/110k 的调度策略，遵循 R-FCN 的做法。另外请注意，由于当前实现的非确定性，性能可能会略有波动，但通常应在 VOC 报告数值的 ±1% 以内，COCO 报告数值的 ±0.2% 以内。欢迎提出建议或贡献。

引用

如果你觉得本实现或我们在报告中进行的分析有所帮助，请考虑引用以下内容：

@article{chen17implementation,
    Author = {Xinlei Chen and Abhinav Gupta},
    Title = {An Implementation of Faster RCNN with Study for Region Sampling},
    Journal = {arXiv preprint arXiv:1702.02138},
    Year = {2017}
}

为了方便起见，以下是 Faster R-CNN 的引用：

@inproceedings{renNIPS15fasterrcnn,
    Author = {Shaoqing Ren and Kaiming He and Ross Girshick and Jian Sun},
    Title = {Faster {R-CNN}: Towards Real-Time Object Detection
             with Region Proposal Networks},
    Booktitle = {Advances in Neural Information Processing Systems ({NIPS})},
    Year = {2015}
}

来自 COCO 服务器的详细指标（不支持）

所有模型均在 COCO 2014 trainval35k 数据集上训练。

VGG16 COCO 2015 test-dev（90万/119万）：

 平均精度（AP）@[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.297
 平均精度（AP）@[ IoU=0.50      | area=   all | maxDets=100 ] = 0.504
 平均精度（AP）@[ IoU=0.75      | area=   all | maxDets=100 ] = 0.312
 平均精度（AP）@[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.128
 平均精度（AP）@[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.325
 平均精度（AP）@[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.421
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.272
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.399
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.409
 平均召回率（AR）@[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.187
 平均召回率（AR）@[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.451
 平均召回率（AR）@[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.591

VGG16 COCO 2015 test-std（90万/119万）：

 平均精度（AP）@[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.295
 平均精度（AP）@[ IoU=0.50      | area=   all | maxDets=100 ] = 0.501
 平均精度（AP）@[ IoU=0.75      | area=   all | maxDets=100 ] = 0.312
 平均精度（AP）@[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.119
 平均精度（AP）@[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.327
 平均精度（AP）@[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.418
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.273
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.400
 平均召回率（AR）@[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.409
 平均召回率（AR）@[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.179
 平均召回率（AR）@[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.455
 平均召回率（AR）@[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.586

pytorch-faster-rcnn 快速上手指南

⚠️ 重要提示：本项目已于 2019 年停止主动维护。作者推荐目前更先进且活跃的项目，如 detectron2 或 mmdetection。本指南仅适用于需要复现旧版实验或使用特定历史模型的用户。

1. 环境准备

本项目基于 PyTorch 开发，对版本有特定要求。

• 操作系统: Linux (推荐 Ubuntu)
• Python: 建议 Python 3.6+
• PyTorch: 1.0 版本 (代码遵循此版本)。若使用 0.1.12 - 0.4 版本，请切换至对应分支。
• Torchvision: 0.3 版本 (必须，用于 nms, roi_pool, roi_align)
• 其他依赖:
  • opencv-python
  • easydict (建议使用版本 1.6)
  • tensorboard-pytorch (用于可视化训练过程)

安装依赖示例：

pip install torch==1.0.0 torchvision==0.3.0 opencv-python easydict==1.6 tensorboard-pytorch

2. 安装步骤

2.1 克隆仓库

git clone https://github.com/ruotianluo/pytorch-faster-rcnn.git
cd pytorch-faster-rcnn

2.2 安装 COCO API

代码访问 COCO 数据集需要 Python COCO API 支持。

cd data
git clone https://github.com/pdollar/coco.git
cd coco/PythonAPI
make
cd ../../..

(注：国内用户若克隆缓慢，可尝试使用 Gitee 镜像或配置 git 代理)

2.3 数据集准备

本项目支持 VOC 和 COCO 数据集。请参考原 py-faster-rcnn 的说明下载数据并在 data 文件夹下建立软链接。

• 无需预计算候选框 (proposals)，可直接忽略相关设置步骤。
• 如需缓存文件，可从作者提供的 Google Drive 链接下载 data/cache 内容。

3. 基本使用

3.1 获取预训练模型

你可以直接下载作者转换好的 PyTorch 模型，或者从 TensorFlow 版本转换。

方式 A：直接下载 (Google Drive) 访问 此链接 下载模型文件并放入 data/models 目录（具体路径需根据脚本调整）。

方式 B：从 TensorFlow 模型转换 如果你已有 tf-faster-rcnn 的预训练模型，可以运行以下命令进行转换：

python tools/convert_from_tensorflow.py --tensorflow_model <path_to_tf_model> --output_model <path_to_save_pt_model>

3.2 运行演示 (Demo)

使用预训练模型对单张图片进行检测。假设你已准备好模型文件和测试图片：

python demo.py --model <path_to_model.pth> --image <path_to_image.jpg>

程序将输出检测结果，并可选地在 TensorBoard 中可视化预测框。

3.3 训练与验证

项目支持训练过程中自动进行验证监控。确保数据集路径配置正确后，运行训练脚本（具体脚本名通常为 trainval_net.py 或类似，需查看 experiments/scripts/ 下的具体配置）：

# 示例命令，具体参数需根据配置文件调整
python trainval_net.py --dataset voc_2007_trainval --model VGG16 --max_iter 70000

特性说明：

• 断点续训：支持从最新的 snapshot 恢复训练，保留图像索引和随机状态信息。
• 可视化：训练过程中的 Loss、激活值统计及 Ground Truth 会自动保存至 TensorBoard 日志目录。