Faster R-CNN源码解析：从RPN到RoI Head的PyTorch实现细节

最近重看了一遍 simple-faster-rcnn-pytorch 的源码，好几处当年囫囵吞枣跳过去的细节，这次总算想明白了。这个库可太适合拿来啃了——它没有把网络结构塞进一个几千行的 mega 文件里，RPN、RoI Head、Proposal 筛选这些都是单独模块，代码量小，命名直白，连工具函数都拆得清清楚楚。如果你也想搞懂 Faster R-CNN 而不是只会调现成接口，或者你已经用成熟检测框架跑过很多实验，却一直觉得“这个框到底是怎么挑出来的”“那些标签到底是谁分配的”像黑盒，那这篇源码解析应该能帮到你。

这篇笔记我会按一条完整的阅读路线走：先从数据怎么进网络开始，再顺着 Feature Map 往下看 RPN 和 RoI Head，最后落到训练循环和推理后处理。会尽量讲清楚每个模块“为什么这样做”，而不是逐行翻译注释。

1. 为什么选择 simple-faster-rcnn-pytorch 作为 Faster R-CNN 源码入口

1.1 在众多实现里，为什么会挑这一份代码

我最早接触检测源码时，第一反应是去翻那些大型检测库。结果打开一看，几十个文件之间有复杂的继承关系，一个build函数能绕三次弯。新手进去很容易迷路，最后变成“好像看懂了又好像啥也没懂”。

simple-faster-rcnn-pytorch 走的完全是另一个路数。它用纯 PyTorch 写，没有花哨的分布式封装，也不搞注册机制，就是老老实实的类继承和函数调用。核心代码集中在model目录，每个类只干一件事：

只要把这几个文件的调用关系看懂，Faster R-CNN 的骨架就等于拿下来了。这份代码很适合做“第一个精读的检测源码”，之后再去看大型框架会轻松很多。

1.2 这份代码的结构选择：为什么用 VGG16 而不是 ResNet

项目使用的是 VGG16 作为 backbone。很多人会觉得奇怪：都什么年代了，怎么还在用 VGG？换个 ResNet 不是更好吗。

我的看法是，选 VGG16 恰恰是这个项目作为教学源码最大的优点。VGG16 结构足够简单，全是3x3 卷积加max pooling，一层叠一层，没有分支、没有残差连接，特征图的通道数变化也很好算。你拿着笔推一遍，就能知道每层之后图像尺寸缩半、通道翻倍，这种确定性对理解“Feature Map 到底哪来的”非常重要。

ResNet 虽然效果更好，但涉及残差块和两条路径相加，初学者读起来容易把注意力放到骨干网络的细节上，反而忽略了真正要学的东西——RPN 的 anchor 机制和 Proposal 筛选。等这份代码读透了，再自己动手把 VGG16 换成 ResNet，心智负担就不会太大。

1.3 读源码的正确姿势：先跑通，再打断点，最后看细节

我这几年带过不少同学，总结出一条经验：千万别上来就一行一行背代码。先按 README 把环境装好、把训练跑起来，哪怕只跑几轮，你也知道程序能正常走通。接下来再进调试器打断点，或者在关键函数里print中间变量的形状。这一步比读十遍代码都有用。

比如你想看 anchor 到底生成了多少，直接在 RPN forward 里打印anchor 的 shape；想看 proposal 经过 NMS 之后还剩多少，就去ProposalCreator里打印输出长度。这种“亲眼见到中间变量”的过程，会大幅降低抽象的代码带来的理解难度。

2. 数据入口：Dataset 类如何把图像和标注送进网络

2.1 图像预处理：缩放、归一化和 BGR 通道顺序

这个项目沿用了当时常见检测实现的做法，图像预处理看起来简单，其实有几个坑。数据加载时，图像会被缩放到短边 600 像素、长边不超过 1000 像素左右的尺度，然后做减均值归一化。为什么要限定这个范围？两层原因：一是检测框架里 anchor 的尺度和比例是按固定分辨率设计的，图像变化太大，anchor 的覆盖策略会失真；二是显存有限，太大尺寸的 Feature Map 和 RoI 批处理都吃不消。

需要注意，加载出来的图像默认是 RGB 通道，但 VGG 预训练权重通常按 BGR 顺序输入。所以代码里往往会有一步通道重排。如果你之后自己写数据加载，经常在这个地方翻车——训练了十几个 epoch 发现 loss 不降，查了一圈，结果是通道顺序反了，模型从头到尾都在看“颜色错乱”的图像。这个低级错误有多常见，谁踩谁知道。

2.2 标注坐标的约定：xyxy 绝对坐标 vs 归一化坐标

目标检测项目里最让人头疼的问题之一，就是坐标体系不统一。有的数据集的标注是归一化的xywh，有的是原图绝对像素的x1y1x2y2，有的是中心点加宽高。这份代码内部使用的坐标格式是(x1, y1, x2, y2)的绝对坐标，也就是左上角和右下角的像素位置。

数据在进入模型前，代码会统一转成这个内部格式。我建议你也养成这个习惯：写任何检测代码之前，先定好内部坐标格式，然后在数据加载的入口统一转换。宁可花十分钟写一个转换函数，也不要让后面的训练代码里到处出现x / width这种加减法。后续在处理 anchor、RPN 回归目标、RoI 对齐时，全程用绝对坐标，理解起来会省很多力气。

2.3 Dataset 的数据流和 collate 问题

当时这个项目遍历一张张图像、对每张图像生成一批 anchor 的方式，和现在主流实现的padding + batched tensor不太一样。它需要自己控制 batch 的组织，每次迭代会拿一张图和对应标注送入网络。好处是代码好写，不需要考虑变长 padding；坏处是训练效率偏低，GPU 可能吃不满。

这也提醒了后来读代码的人：一份教学代码的工程取舍不一定是“最优的”，但它把逻辑展示得非常直白。你想看数据到底怎么流动，就在 Dataset 里逐行跟进，能很清楚地看到一张图如何变成 tensor、标注如何被对齐到 anchor、ROI 如何参与损失计算。等理解了这套逻辑，再去写高效的 batch 组织就只是工程问题，而不是原理障碍。

3. 共享的 Feature Map：VGG16 backbone 如何被检测模型复用

3.1 VGG16 的哪一部分被保留，哪一部分被丢掉

经典分类网络最后都带几个全连接层，但检测模型不直接需要它的分类输出，需要的是“图像经过卷积池化之后形成的空间特征”。所以这份代码会加载 VGG16 的卷积层部分，保留到conv5为止，然后自己拼接后续结构。

在faster_rcnn_vgg16.py里，可以明显看到模型的组装步骤：

# 伪代码，梳理 VGG16 backbone 的组装思路 class FasterRCNNVGG16(nn.Module): def __init__(self): super().__init__() # 使用 classification 模型的 features 部分作为特征提取器 self.features = vgg16.features # 注意这里不含最后的分类层 # 在 VGG 之后增加一个下采样层，把输出通道数调整成检测头用的大小 self.extractor = nn.Sequential( self.features, nn.Conv2d(512, 512, 3, padding=1), nn.ReLU(inplace=True), )

保留卷积层并对最后一层做针对性修改后，任意H x W的输入会变成512 x H/16 x W/16的特征图。这一步很关键，因为 RPN 和 RoI Head 共享的正是这张下采样 16 倍的图。我经常跟人说“stride 16”，这个词在检测里非常高频。每一个卷积层之后，原始像素和特征图位置的对应关系，就直接由这个 16 决定。

3.2 从卷积层到 List 输出：检测模型是怎么接住不同尺寸输入的

有一类常见问题：分类网络会要求输入固定尺寸，因为全连接层要求输入维度固定。但检测任务里面，输入图像的尺寸基本都不固定，输出特征图也就跟着变。为什么 VGG 能处理任意输入尺寸呢？

因为卷积层是滑窗操作，不限制宽高；而池化层每池化一次，尺寸减半，也不要求固定输入。只要去掉后面的全连接层，卷积网络就是“全卷积”结构，什么尺寸都能接收。这份代码正是利用了这一点：H x W的图像，经过 VGG16 的特征提取，输出H/16 x W/16的特征图。之后 RPN 在这个特征图上做小滑窗，RoI Head 则通过 RoIPooling 把任意大小的区域拉成固定尺寸。

理解了这个设计，你后面读 RPN 的时候就会觉得特别顺——为什么 anchor 的中心都排在格点上？为什么一张 800x1000 的图能出几千个 anchor？答案都在这些格点上。每个特征图上的位置，对应回原图是一个 16x16 像素的区域，而 anchor 就在这个区域里以不同比例伸展。

3.3 手动替换 backbone 的可行路径

我自己曾经尝试过把这份代码的 VGG16 换成 ResNet18，踩了些坑，但整体路线是可行的。重点是注意三件事：第一，ResNet 第一层是 7x7 大卷积，会导致最终特征图的 stride 变成 16 还是 32 有差异，计算 anchor 映射要重新对表；第二，ResNet 的输出通道数是 512，如果下采样倍数不同，RPN 的输入通道也需要做相应调整；第三，RoIPooling 的尺寸是在 VGG 假设下设定的，换成 ResNet 之后一般沿用也没问题，但要注意感受野变化。

如果你也想改，建议先用一个最小的替换方案跑通：ResNet18 的features部分输出之后接一个 1x1 卷积调整通道，把 RPN 的输入通道改成 ResNet 的输出通道。先不管性能，先看 loss 能不能降，再逐步加细节。这个过程非常练兵。

4. RPN 源码拆解：从 anchor 生成到 proposal 筛选的完整链路

4.1 anchor 的生成逻辑：为什么是 9 个框

RPN 是 Faster R-CNN 最核心的部分，它的作用是在特征图上为“可能含有目标的区域”——也就是 proposal——打分并粗调位置。很多人一上来就被“anchor”这个概念卡住了，所以我建议从生成 anchor 的代码读起。

这份代码里，最基础的 anchor 由base_size=16、三种比例[0.5, 1, 2]和三种尺度[8, 16, 32]组合而来。为什么是 9 个？3 种宽高比 x 3 种尺度 = 9。base_size 对应的是特征图上一个格子映射回原图的边长，而 anchor 不会超出这个格子的概念——它是以这个格子为中心、按不同尺度和比例画出来的框。

下面这段是生成基本 anchor 的典型逻辑：

def generate_anchor_base( base_size=16, ratios=[0.5, 1, 2], anchor_scales=[8, 16, 32] ): """生成 base_size 对应的 9 个基础 anchor，坐标为 x1,y1,x2,y2""" py = base_size / 2. px = base_size / 2. anchor_base = np.zeros((len(ratios) * len(anchor_scales), 4), dtype=np.float32) for i, ratio in enumerate(ratios): for j, scale in enumerate(anchor_scales): h = base_size * scale * np.sqrt(ratio) w = base_size * scale * np.sqrt(1. / ratio) idx = i * len(anchor_scales) + j anchor_base[idx, 0] = py - h / 2. anchor_base[idx, 1] = px - w / 2. anchor_base[idx, 2] = py + h / 2. anchor_base[idx, 3] = px + w / 2. return anchor_base

每个 anchor 由(y1, x1, y2, x2)构成，暂时假设原图上的一块 16x16 区域就是这个 anchor 的“视野”。之后随着特征图滑窗，这个基础 anchor 会在每个位置被复制一份，平移到对应格点上，形成整张图密密麻麻的候选框。

4.2 RPN 的 forward：滑窗卷积与两条分支

RPN 的 forward 接收 backbone 输出的特征图，先做一次3x3卷积提取局部特征，然后分两条路径：

• 分类分支：每个位置输出 9 个值，表示该位置 9 个 anchor 里包含目标的概率；
• 回归分支：每个位置输出 9 x 4 个值，表示这 9 个 anchor 到真实框的偏移。

为什么要用3x3滑窗？因为相邻区域之间的上下文信息对判断“这里有没有物体”很重要。你可以把它理解成一个小探照灯，在整张特征图上扫过去，每到一个位置，就把这个格子附近的特征提取出来，判断“这里该不该出框”。

4.3 ProposalCreator：NMS 之前和之后的处理

RPN 原始输出可能有好几万个框，不能全扔给后面的分类器。ProposalCreator要做三件事：

1. 按照分类分数从高到低排序，先筛掉大部分低分框；
2. 用非极大值抑制（NMS）去掉重复的、高度重叠的框；
3. 将剩下的框缩放到图像边界内，再挑前 N 个作为 proposal。

我当时第一次看到 NMS 的代码时以为很高深，其实就是一个“先挑分最高的，再删掉所有和它 IoU 太高的框，然后重复”的过程。你可以把它想象成一群人排队领奖：分最高的先上台，所有跟他长得太像的人就直接回家；剩下的人里再重新排序、重新挑。这样能保证最终选出来的框各有各的位置，不会十几个框同时罩住同一个物体。

在这个项目里，训练时一般挑出 2000 个 proposal，推理时挑出 300 个。这个数量设置非常影响显存和精度：proposal 太少，会漏掉真框；proposal 太多，后面的 RoI Head 计算量爆炸。实际项目里，这个数字值得你专门做一组实验调一下。

4.4 RPN 分类分支为什么不直接用 Softmax 的结果

有一个小细节：RPN 的分类分支输出的是二分类分数，但有些实现会用 softmax 归一化后再排序，有些直接用原始 score 排序。这份代码的做法更偏向“logits 直接参与排序”，然后在计算损失时才用交叉熵。为什么排序时用原始 logits 而不用 softmax？

因为 softmax 是单调变换，它不会改变排序结果，多算一步反而浪费运算。你只要记住“排序依赖的是相对大小，不是绝对概率”，就会发现很多检测代码里宁可直接用 logits 来做 top-k 筛选，这也是工程上常见的取舍。

5. 训练阶段的样本分配：标签、回归目标与多任务损失的计算细节

5.1 AnchorTargetCreator：谁负责给几万个 anchor 决定“正/负样本”

RPN 生成了几万个 anchor，但训练的时候不能拿所有 anchor 一起算 loss，因为绝大多数是背景，直接算会淹没真正有目标的部分。因此需要规则的AnchorTargetCreator来给每个训练样本打标签。

分配规则大致如下：

• 与任意 Ground Truth 框的 IoU 大于 0.7 的 anchor 视为正样本；
• IoU 小于 0.3 的视为负样本；
• 剩下的既不是正也不是负，不参与损失计算；
• 如果一个 Ground Truth 找不到大于 0.7 的 anchor，就直接把 IoU 最大的那个 anchor 给他当正样本，保证每个真框至少有一个 anchor 负责。

这个“保底机制”很重要。一张图里如果目标很小，或者目标之间极度拥挤，只靠阈值可能一个正样本都选不出来。有了这个兜底规则，每个 Ground Truth 至少能牵动一个 anchor，训练才不会崩。

5.2 回归目标：Smooth L1 背后的尺度问题

RPN 回归分支的预测值不是“直接预测框的坐标”，而是预测“anchor 到 Ground Truth 的相对偏移”。为什么要预测偏移而不是绝对坐标？因为绝对像素值跨度太大，从几十像素到上千像素都有，训练时神经网络很难学稳定。偏移做了归一化之后，数值通常落在个位数区间，收敛就快得多。

回归目标的两种常见表示是中心坐标偏移和宽高对数偏移：

t_x = (gt_cx - anchor_cx) / anchor_w t_y = (gt_cy - anchor_cy) / anchor_h t_w = np.log(gt_w / anchor_w) t_h = np.log(gt_h / anchor_h)

在损失这边，这份代码使用的是 Smooth L1。它其实是个分段函数：误差绝对值小于 1 的时候用平方项，梯度会平滑地变小；误差大的时候退化成绝对值，梯度不会爆炸。你想想训练初期预测得不准，误差可能很大，如果用 MSE，梯度会被误差放大得很离谱，导致训练发散。Smooth L1 就是为这个场景设计的。

5.3 ProposalTargetCreator：RoI Head 的训练样本怎么来

RPN 输出 2000 个 proposal，但 RoI Head 不能把 2000 个全拿来算分类，因为其中很多是背景。这里的ProposalTargetCreator有点像一个“数据清洗器”：

• 它会从 proposal 里挑出和某个 Ground Truth IoU 较大的框作为 RoI Head 的正样本；
• 再随机挑一些 IoU 较小的框作为负样本；
• 最终组成一个几十到一百多数量的小批量 RoI 送去训练。

我记得这个项目里，一般会从 2000 个 proposal 中挑出约 128 个 RoI，保持正负样本比例大致均衡。这跟 RPN 阶段一样，都是为了不让“背景”淹没问题，让分类器能学到真正的判别特征。

5.4 损失相加：一次迭代的总 loss 是怎么拼出来的

训练时，整张图的前向传播会产生两类损失：RPN 的分类损失加回归损失、RoI Head 的分类损失加回归损失。整体 loss 就是这四个值按一定权重相加。简单来说，网络一次前向就同时把“在哪里找框”和“框里是什么”两件事都学起来了。这也是 Faster R-CNN 名字里“Faster”的核心优势之一——RPN 和 Fast R-CNN 共享同一个特征提取器，一次前向不重复算骨干网络。

读完这一块你会发现，虽然每个模块看起来简单，但它们之间的样本传递环环相扣：RPN 产出 proposal，然后 RoI Head 用自己的正负采样规则再过滤一次。如果你在调试的时候发现某个 loss 一直降不下去，可以先分别打印四个 loss 的曲线，看看是哪个部分的贡献出了问题。这是最直接的排错思路，比盲调学习率靠谱太多。

6. 主训练循环里的实际参数与常见坑

6.1 学习率、优化器与 batch 的配合

这个项目训练时用的是 SGD，配合 momentum，学习率一般从 0.001 量级开始。为什么检测任务里 SGD 依然能打？因为它在小 batch 下的泛化能力通常优于 Adam，这在当时的目标检测社区几乎是共识。后来大家为了省事也会用 Adam+onecycle 之类的方案，但如果你想严格复现这份代码的实验，最好先照着 SGD + 阶梯下降学习率的套路来。

训练循环本身不复杂：对每一张图，前向得到 loss，反向传播，更新参数。唯一要留意的是，RPN 的回归分支只对正样本计算损失，所以如果训练初期正样本太少，整个模型的梯度信号都是弱的，loss 可能久久不动。这时候不要急着加学习率，先检查样本分配结果是否正常。

6.2 显存不足时的应急手段与代价

如果你是在普通显卡上跑这份代码，一万多个 anchor 的中间结果很容易吃显存。我当时第一次跑时直接爆显存，后来用的几个方案，按推荐度排：

1. 减小输入图像的缩放上限，从 1000 缩到 800，显存占用立刻掉一截，代价是模型对大目标的检测精度会下降；
2. 减小训练时 proposal 数量，从 2000 降到 1200，训练依然能稳定跑；
3. 减小 batch size，但这份代码本身对每张图单独过网络，效果有限；
4. 开启混合精度，但当时的代码结构要额外加梯度缩放，改动量不小。

如果你只是学习，建议直接走方案 1，简单粗暴，不影响理解原理。

6.3 断点调试时最值得打印的几个中间量

我有几个固定的调试动作，每次都能迅速定位问题：

• 打印anchor的坐标范围和图像尺寸，检查 anchor 有没有跑到图像外面太远；
• 打印正样本数量，如果一张图才两三个正样本，说明参数设置有问题；
• 打印 RPN 输出的 proposal 数量和 Ground Truth 的 IoU 分布，检查 RPN 有没有学到东西；
• 打印 RoI Head 分类层的得分分布，看是不是所有框都停在“背景”上。

这些中间量配合起来，效果比盯着总 loss 曲线发呆好得多。很多情况下，四五个 epoch 之后总 loss 其实已经降得很慢了，但你去看 RoI Head 对真实目标的分类分数，会发现它已经有了不错的判别能力。

7. 推理与可视化：如何把模型输出变成最终的检测框

7.1 推理阶段的前向流程：少了什么，多了什么

推理和训练最大的区别在于：推理没有 Ground Truth，不需要计算损失，也不需要样本分配器。RPN 在前向时还是照常生成 proposal，但 RoI Head 不再做正负样本筛选，而是把 NMS 后的 proposal 直接拉成固定尺寸做分类和回归。

最后一层分类器会输出每个 proposal 对所有类别的得分；回归器会输出对每个类别的框偏移。你需要做的是：先根据得分筛掉低概率框，再对每个类别单独做一次 NMS，把冗余框去掉。注意“按类别分别做 NMS”这个小细节——如果不分开，两个挨得很近的不同类别物体可能被误删。

7.2 可视化代码：画框的坐标尺度要对齐

可视化时最容易范的错，是忘记把坐标从训练尺度还原回原图尺度。之前提过，数据在前处理时会做缩放，模型输出的坐标都是在“缩放后的图像”上的。如果你直接把这些坐标画到原图上，框的位置一定会偏。

正确做法是：记录下原图和缩放图的宽高比，在输出坐标上除以这个比例，再画框。这类小问题看着不起眼，但排查起来特别浪费时间。我现在写完一段检测代码，第一件事就是顺手跑一遍可视化，如果有偏移，八成是坐标系的坑。

7.3 从这份源码里能带走的东西

这份极简实现把 Faster R-CNN 的每个零件都摆得很清楚，尤其是 anchor 机制和样本分配这两块。你在这份代码上积累的细节，之后迁移到更大规模的检测框架时会非常有用。比如一看到AnchorTargetCreator，就能明白很多大型框架里assigner和sampler的来历；一看到ProposalTargetCreator，就能理解现代框架里的RoIHead正负样本采集是怎么演进出来的。

我个人的建议是，读完这份源码别急着关掉，试两件事：一是把 VGG16 换成 ResNet18，强迫自己动手重写 backbone 的接口；二是写一个自定义数据集的加载器，把整套训练流程用自己的数据跑通。只有当你自己动手改过、跑过、翻过车，Faster R-CNN 的那些概念才会真正长在脑子里。

最后分享一个小经验：看源码解析文章的时候，别只看结论，最好把项目 clone 下来，跟着文章里的路径走一遍，打印一遍中间变量。哪怕只是改一个参数观察效果，也比纯阅读印象深刻得多。希望这篇笔记能帮你省下一些绕路的时间。