简介：这份基于 Caffe 框架的 R-FCN 目标检测模型源代码包，面向需要将算法落地为可配置应用的算法研究与工程开发人员。源码以 ResNet 为基础网络，完整覆盖位置敏感得分图、RPN 区域提议、分类与回归分支等关键模块，并提供了从数据准备、网络构建到训练验证的 MATLAB 脚本和 prototxt 配置文件。包内共94个文件，以 .m 脚本为主，辅以 12 个 prototxt 网络配置、C++/CUDA 扩展及少量示例图片与 mat 数据，压缩包仅349KB，便于快速下载和对照阅读。已有550人学习，说明其在目标检测学习者中有一定参考价值。通过该代码，读者可直观了解 R-FCN 如何在 Caffe 中组织训练测试流程，掌握 imdb/roidb 数据接口、区域提议生成、NMS 后处理等实现细节，为后续在自动驾驶、视频监控等场景中的应用迁移提供基础。 R-FCN 这个模型，在目标检测的发展史上属于那种“你不一定再用了，但源码值得反复吃透”的类型。我第一次读 R-FCN 的源代码时，最强烈的感受是：它的核心其实不是一个多么复杂的网络，而是对“特征图上的空间信息”做了一次极其聪明的重新组织。今天我想把阅读 R-FCN 源代码时整理出来的东西完整分享一遍，包括主干结构、位置敏感分数图、PSRoIPool 的实现逻辑，以及训练时容易踩的坑。
1. 读懂R-FCN代码前，先搞清它解决了Faster R-CNN的什么问题
1.1 Faster R-CNN的一个别扭之处：全连接层与平移敏感性的矛盾
要理解 R-FCN 源代码里那些看似绕弯的设计，得先回到 Faster R-CNN 的一个老问题上。Faster R-CNN 的检测头通常有两层全连接层，分别负责分类和回归。全连接层有个特点：它对输入特征的位置是高度敏感的——同一张特征图，平移一个像素，全连接层输出的结果就可能明显变化。这在检测任务里反而是好事，因为你希望框出目标时，能精确知道目标在哪里。
但坏处也出在这里。基于全连接层的检测头要求每个 RoI 都先被缩放成固定尺寸（通常是 7x7），再做全连接计算。这意味着两件事：第一，整个检测头的计算量和 RoI 数量强相关，RoI 一多，全连接层就成为瓶颈；第二，分类网络主干（比如 ResNet）本身是平移等变的，把它的输出接上这么一层全连接后，整个模型在“平移不变性”和“平移敏感性”之间的平衡非常别扭。说到底，你只是借用了一个分类网络的骨架，却在后面接了一套与卷积网络风格完全不同的全连接检测头。
1.2 R-FCN的解题思路：把“目标在哪”写进特征图上
R-FCN 源代码里最醒目的做法，是彻底抛弃了 RoI 之后的全连接层。作者 Dai 等人的想法很直接：既然我们想要的是“平移敏感”，那就不要把位置信息交给后端的全连接层，而是直接把它编码在特征图里，让后续的池化操作自然地去读取这些位置信息。
具体怎么做呢？在 R-FCN 中，骨干网络（ResNet-101）输出的特征图之后，会接一层 1x1 卷积，把通道数映射到k x k x (C + 1)。这里的k是你想把 RoI 划分成多少个网格，论文默认是 7，所以就是 7x7 个网格；C+1是类别数加上背景类。这k x k x (C+1)个通道的含义非常关键：对于某个类别，第(i, j)个位置对应的那一组通道，只负责回答“RoI 中被切成i行j列的这个小格子里，是否有该类别的目标”。
读源码时你会看到，这个输出通常叫ClsScore，形状是[N, (C+1), k, k, H, W]，其中H和W是特征图的尺寸。看到这个形状，你就能理解 R-FCN 的整个设计哲学：它把“分类”从“对整块 RoI 分类”变成了“对 RoI 内每个小格子分别判断”，然后再用投票的方式综合起来。
1.3 理解代码中常见的几个关键缩写
R-FCN 的公开实现版本很多，早期官方的是 MXNet 版本，后来 PyTorch 复现也大量出现。不管哪种语言，源码里的关键缩写基本是通用的。读代码前先把这几个缩写刻在脑子里，能省下大量查阅时间：
PSRoIPool：Position-Sensitive RoI Pooling，位置敏感 RoI 池化，这是 R-FCN 的灵魂操作；ClsScore：分类分支输出的位置敏感分数图，形状里带着(C+1)个类别和k x k个网格；BboxPred：回归分支输出的位置敏感偏移量，形状通常是[N, 4, k, k, H, W]，这里的 4 是 tx, ty, tw, th；vote：对k x k个网格的池化结果做平均投票，得到最终分数。
我见过不少初学者看 R-FCN 源码时一头扎进训练循环，然后被im_info、roidb、blob这些字段搞晕。我的建议是：先看前向传播里 tensor 的形状变化，再回来看数据流。
2. R-FCN源代码主干：从配置文件到前向传播的整体脉络
2.1 网络结构定义：ResNet作为骨干+位置敏感卷积
R-FCN 的骨干网络默认是 ResNet-101，但在源码结构上，它会去掉 ResNet 最后的全局平均池化和全连接层，只保留到conv5的输出。这一阶段输出的特征图按输入图片尺寸做了 32 倍下采样，也就是一张 224x224 的图，到conv5出来是 7x7。检测任务里不会直接用这么小的分辨率，所以输入往往会 resized 到 600x1000 左右，特征图大小大约在 19x31。
从conv5之后，代码会接上一个1x1卷积，把通道数扩到1024，然后分叉成两个分支：分类分支再接一个1x1卷积，输出196 x (C+1)个通道（因为 7x7=49，49 x 4 = 196，这里 196 = k x k，但实际是k x k个网格）。严格来说，分类分支输出的通道数是(C+1) x k x k，例如 PASCAL VOC 有 20 类加背景共 21 类，那分类分支输出21 x 49 = 1029个通道。这部分在代码里通常是：
# 简化版，来源于常见PyTorch复现结构 self.cls_score = nn.Conv2d(1024, (num_classes + 1) * 7 * 7, kernel_size=1, stride=1) self.bbox_pred = nn.Conv2d(1024, 4 * 7 * 7, kernel_size=1, stride=1)注意这里用的是1x1卷积而非全连接层，这是一个很“卷积化”的设计。整个网络从输入到输出全程没有全连接层，这也是 R-FCN 名字里“Fully Convolutional”的来源。
2.2 源代码中的核心tensor形状变化
把 R-FCN 前向传播中几个关键 tensor 的形状变化列出来，你会非常直观地看到这个模型到底在做什么：
| 阶段 | Tensor形状 | 说明 |
|---|---|---|
| 输入图片 | [1, 3, H, W] | 单张图，H/W 按需缩放 |
| ResNet conv5输出 | [1, 2048, h, w] | h/w 是输入图的 1/32 |
| 共享卷积（1x1, 1024） | [1, 1024, h, w] | 降维，减少后续计算 |
| 分类分支输出 | [1, (C+1)*k*k, h, w] | 每个位置对应所有类别所有网格的分数 |
| 回归分支输出 | [1, 4*k*k, h, w] | 每个位置对应 4 个偏移量在所有网格上的预测 |
| PSRoIPool输出 | [num_rois, (C+1), k, k] | 每个 RoI 在每个格子上的池化分数 |
| 投票后输出 | [num_rois, (C+1)] | 每个 RoI 的类别分数 |
看这个流程你会发现一个重要特点：RoI 的数量只会影响 PSRoIPool 之后的计算，完全不会影响前面的卷积前向传播。对于大量候选框的场景，这能把计算省下一大截。这也解释了为什么源码中 RPN 部分生成 300 个 RoI 但整体训练速度仍然远快于基于全连接头的检测器。
2.3 训练与推理的共享路径
R-FCN 源代码里，训练和推理阶段的前向传播是高度共享的，区别主要在于：
- 训练时使用
roidb中标注的 ground truth RoI（正负样本都有）作为 PSRoIPool 的输入，推理时则使用 RPN 的输出； - 训练时会计算分类损失和回归损失，推理时只做 NMS（非极大值抑制）和阈值过滤；
- 训练时通常会做 OHEM（在线难例挖掘），源码里会看到对每个 RoI 的损失排序，只回传前 128 或前 256 个难例的梯度。
理解了这个共享路径，你就明白为什么修改数据预处理或者 RoI 采样策略会直接影响模型的检测效果——因为这些逻辑隐藏在训练循环里，而不是网络结构配置文件里。
3. PSRoIPool层源码精读：R-FCN最核心的一段代码
3.1 从普通RoIPooling到PSRoIPooling的变化
R-FCN 最值得细读的代码就是 PSRoIPool 的实现。普通的 RoIPooling 做的事情是：把一个 RoI 对应的特征图区域划分成7x7个小格子，对每个格子做 max pooling，输出一个7x7xC的特征图，再交给后续全连接层。
PSRoIPool 做的事情看起来很像，但有一个关键区别：普通 RoIPooling 是在同一张特征图上做池化，而 PSRoIPool 是在k x k组不同的通道上分别做池化。怎么理解呢？假设分类分支的输出是[C+1, k, k, h, w]，对某一个 RoI，它的(i, j)格子不是去原始特征图上对应的(i, j)区域做池化，而是去这个输出张量的第(c, i, j)个通道上对应的(i, j)区域做池化。也就是说，每个格子使用的特征通道是不同的。
这种设计让模型可以自主学习：为了让某个格子的分类正确，网络会选择性地在第(c, i, j)个通道上存储“该格子内有类别 c 目标”的证据。你可以把 R-FCN 想象成一个决策委员会：委员会里有 7x7 名成员，每个人只负责观察目标的某一个局部区域，最终“投票”决定这个 RoI 属于哪个类别。
3.2 一个简化版的PSRoIPool实现
为了讲清楚源码细节，我写一个简化版的 PyTorch 实现（完整版还要处理坐标归一化、动态 shape、CPU/GPU 分支等）：
import torch import torch.nn.functional as F def psroi_pooling(score_maps, rois, output_size=7, spatial_scale=0.0625): """ score_maps: [batch_size, (C+1)*k*k, h, w] rois: [num_rois, 5] 每行是 (batch_id, x1, y1, x2, y2) output_size: k, 默认7 """ num_rois = rois.size(0) num_channels = score_maps.size(1) k = output_size num_classes = num_channels // (k * k) pooled = [] for i in range(num_rois): roi = rois[i] batch_id = int(roi[0]) x1 = int(roi[1] * spatial_scale) y1 = int(roi[2] * spatial_scale) x2 = int(roi[3] * spatial_scale) y2 = int(roi[4] * spatial_scale) roi_h = max(y2 - y1, 1) roi_w = max(x2 - x1, 1) # 按网格切分特征区域 grid_h = torch.linspace(y1, y2 - 1, k + 1).long() grid_w = torch.linspace(x1, x2 - 1, k + 1).long() roi_scores = [] for c in range(num_classes): class_map = score_maps[batch_id, c * k * k: (c+1) * k * k, :, :] # class_map: [k*k, h, w] grid_scores = [] for gi in range(k): for gj in range(k): # 第 (gi, gj) 个格子用对应通道 channel_idx = gi * k + gj patch = class_map[channel_idx, grid_h[gi]:grid_h[gi+1], grid_w[gj]:grid_w[gj+1]] if patch.numel() > 0: grid_scores.append(F.adaptive_avg_pool2d(patch.unsqueeze(0).unsqueeze(0), (1,1))) else: grid_scores.append(torch.zeros(1,1,1,1, device=patch.device)) # 组合成 [k, k] grid_scores = torch.cat([g.view(-1) for g in grid_scores]).view(k, k) roi_scores.append(grid_scores) pooled.append(torch.stack(roi_scores)) # [num_classes, k, k] return torch.stack(pooled) # [num_rois, num_classes, k, k]这个简化版省略了很多工程细节，比如对spatial_scale的处理方式（把原图坐标映射到特征图坐标）、边界裁剪、跨 batch 的索引方式，但核心逻辑是一模一样的：每个网格使用一组专属通道，然后对局部区域做均值池化。实际源码里会用 C++/CUDA 扩展来加速这个操作，而不是用 Python 循环，但理解思路才是关键。
3.3 为什么这个pooling能同时保住“分类”和“定位”
你可能会问：只用k x k个小格子做平均池化，为什么不直接对整块 RoI 分个类？关键就在于每个格子用了不同的通道。
想象一个场景：RoI 里有一只猫，但头部偏向左上角。如果使用普通 RoIPooling，网络可能会把“左上角有猫头”的证据和“右下角是背景”的证据混在一起，最终判别模糊。但在 R-FCN 中，左上角格子的通道会学习到“猫眼的纹理”，右下角格子的通道则会对应“背景/地板纹理”，两部分证据是分开存储的。投票时，49 个格子会根据自己学到的局部模式给出判断，这比统一的一整块特征更具空间分辨力。
在回归分支里，这种逻辑也成立：BboxPred 输出的4 x 7 x 7个通道，分别存储“该网格内目标应该往左/上方移动多少”的信息。通过投票，网络能更精细地修正 RoI 的位置。R-FCN 源代码用这种方法，把“位置信息”写进了特征通道里，绕过了全连接层带来的平移敏感性问题。
4. 训练源码里的细节和踩坑记录
4.1 损失函数和ground truth的生成逻辑
R-FCN 的训练损失由分类和回归两部分组成，形式上和 Faster R-CNN 的 multi-task loss 非常相似：
L({p_i}, {t_i}) = 1/N_cls * sum_i L_cls(p_i, c_i) + lambda * 1/N_loc * sum_i L_loc(t_i, t_i*)读完源码你会注意到，分类分支输出的投票分数，实际计算的是每个 RoI 在 softmax 之前的 logits。也就是说，虽然它在结构上是用卷积“画”出来的位置敏感分数图，但最终的损失函数仍然把它当作一个普通的多分类问题来处理。
ground truth 的生成逻辑隐藏在数据加载器里。对每个 RoI，代码会根据它和标注框的 IoU 分配类别标签：IoU 大于 0.5 认作正样本，类别由覆盖其上的 ground truth 决定；IoU 在 0.1 到 0.5 之间作为负样本（背景类）；IoU 低于 0.1 的直接忽略。这段逻辑在源码中通常不在网络定义里，而是在roidb.py或dataset.py这类文件中，改起来相当灵活，也容易踩坑——很多人改完数据增强后忘了同步调整 IoU 分配规则，导致训练不稳定。
4.2 在线难例挖掘（OHEM）等训练技巧在代码里的体现
R-FCN 官方的训练配置普遍会用 OHEM，这对最终性能影响非常明显。OHEM 的代码实现思路是在前向传播后按损失排序，只回传最难的一部分样本的梯度：
# 常见 OHEM 实现，伪代码 rois = rpn_proposals cls_score, bbox_pred = model(images, rois) losses = compute_all_losses(cls_score, bbox_pred, rois, roidb) # 按分类损失从大到小排序，取 top_k sorted_idx = torch.argsort(losses, descending=True) rois_hard = rois[sorted_idx[:128]] # 用这些难例再算一次前向并回传梯度注意这里有个隐性的计算开销：OHEM 通常需要两次前向传播，第一次算出所有候选框的损失，第二次只对筛选后的难例做反向传播。源码里为了省显存，往往把第二次前向放在no_grad或者在一个子图上共享特征，然后只反传难例的部分。这类细节在代码注释里不太容易看出来，常常需要你对照显存占用和反向传播 tensor 的依赖图去推。
4.3 复现时最容易踩的三个坑
我在读 R-FCN 源码并复现时，踩过三个坑，特别值得新读者注意：
第一，特征图的spatial_scale搞错。ResNet 到 conv5 是 32 倍下采样，也就是spatial_scale=1/32=0.0625。但如果你改了骨干网络或者输入分辨率，这个值必须同步调整。有一次我在 ResNet-50 上把下采样改成了 16 倍，忘了改 scale，结果训练收敛后检测框全部偏移，看上去是“预测不准”，其实是坐标映射错了。
第二，RoI 池化的坐标对齐问题。部分 PyTorch 版本中，RoIPool 和 PSRoIPool 对边界坐标的处理存在细微差别，尤其是ceil_mode和半像素偏移。源码里如果用 Cython/CUDA 实现，可能和平常使用grid_sample的直觉不一样。遇到检测框整体偏移半个像素级别的问题时，优先排查这里。
第三，OHEM 中正负样本比例失控。OHEM 在极其难分的数据上可能会把正样本全部挤掉，导致训练退化。源码里一般会有fg_fraction和fg_threshold来约束，但如果你自定义数据集时目标太小、样本太稀疏，最好把正样本最低比例卡在 0.05 以上，否则模型很容易“摆烂”，把所有 RoI 都预测成背景。
5. 基于源码的调参思路和实测结论
5.1 代码可以改哪些地方来提点
R-FCN 的源码比起现在流行的 DETR、YOLO 系列来说，结构要简单得多，所以做魔改的空间反而很大。我自己试过几个改动，实测有效：
一个是在 PSRoIPool 之后、投票之前插入一层1x1卷积或 group norm。这样做相当于在投票前对各格子的局部特征做了一次 cross-grid 的信息混合，虽然不是原始 R-FCN 的设计，但画面中目标遮挡严重时，能小幅度提升准确率。
另一个是把k值从 7 调大，比如 9 或 11。k越大，位置敏感划分越精细，对小目标更友好，但代价是分类分支的输出通道数量平方级增长。以 21 类为例，k=7时是 1029 个通道，k=11会变成 2541 个通道，显存压力明显上来了。实测在 GTX 1080Ti 上k=9是一个比较实用的平衡点。
5.2 与Faster R-CNN源码对比的直观差异
如果你同时读过 Faster R-CNN 和 R-FCN 的源码，会发现最大差异在于“RoI 之后网络有多重”。Faster R-CNN 的 RoI 之后还有整个head网络（包含全连接层），而 R-FCN 的 RoI 之后只有一个 PSRoIPool 和投票操作。这意味着：
- 推理速度显著提升，尤其在候选框数量很多时；
- 模型整体更契合“全卷积”的部署需求，利于移植到 TensorRT 这类推理引擎；
- 精度在某些数据集上略低于精心调参的 Faster R-CNN，因为 R-FCN 牺牲了一部分“全局语义”来换取速度。
这个差异也解释了为什么后来 Mask R-CNN 又回到了“RoI 后接全卷积头部”的路线——当任务从单纯的检测扩展到实例分割时，位置敏感分数图的表达力就不够用了。
5.3 实操中我自己的建议
如果你现在仍然想在项目中用 R-FCN 而不是直接上更现代的模型，我的建议是：不要完全照搬论文默认配置，而是把 R-FCN 当作一个“高效的 RoI-based 基线”，然后基于源码改造成更适合自己数据的模型。比如在特征金字塔、可变形卷积、更深的骨干之间做组合，代码结构的侵入成本远低于那些端到端的 DETR 类模型。
维护源码时也记得保留一个基准配置版本，每次改动过后回到基准跑一遍验证集，防止性能悄悄回退。我自己维护 R-FCN 复现代码时就固定跑 VOC2007 test 作为 sanity check，数据预处理一变，mAP 掉零点几个点都能立刻看出来。这种“先锁定一个可复现基线，再逐步迭代”的方式，对任何从源代码开始学习或者魔改一个老模型的场景都适用。
本文还有配套的精品资源，点击获取
