PV-RCNN这个名字，很多刚开始做3D目标检测的人都听过，但真正打开代码工程时，不少人的第一反应是不知道从哪一行看起。训练脚本 train 和测试脚本 test 虽然是两个入口，其实共用同一套模型定义，只是数据流、计算图和关注点完全不同。这篇笔记会按代码执行顺序，把数据怎么进、特征怎么提、框怎么出、指标怎么算一条条讲清楚，适合已经跑过基础3D检测、想深入源码，或者从2D检测转过来准备把点云检测作为主线的同学。
我习惯把这两个入口分开读，训练阶段重点看 loss 和梯度，测试阶段重点看后处理和指标。为什么要分开？因为训练时你关心的是网络有没有学起来，测试时你关心的是模型框得准不准，同一个 forward，两种关注点会引导你找到完全不同的代码路径。下面先花一点时间回顾 PV-RCNN 的设计动机，这决定了代码里的模块划分，也决定了 train 和 test 的调用关系。
1. 拆代码之前，先把PV-RCNN的设计动机过一遍
1.1 体素分支到底在解决什么
点云本质上是一堆无序的三维坐标点，数量不定，稀疏程度不一，直接丢进普通卷积里是行不通的。普通卷积要求数据有规律的网格结构，而原始点云没有行列关系，所以 PV-RCNN 第一步做的事情就是体素化：把空间中一个固定范围内的点云，划分成一个个小立方体，然后把落在同一个立方体里的点聚合起来。
这个过程在代码里对应一组非常显眼的参数：voxel_size 表示每个体素的实际物理尺寸，point_cloud_range 表示场景范围，两者一除，就是三个维度上的体素网格数量。举个直观的例子，如果范围是 80 米乘 80 米，体素大小是 0.1 米，那平面方向就有 800 乘 800 个格子，再乘上高度方向的数量，网格总量一下就上去了。早期方案会在这些格子上全部跑 3D 卷积，浪费很多计算；PV-RCNN 用稀疏卷积，只对有点的格子做计算，复杂度大幅下降。
可以这么理解：体素化就像把一个城市按街区做人口统计，最终得到的是每个街区有多少人，而不是每个人的精确住址。这样做的好处是全局结构清晰，坏处是个体位置细节被抹掉了。只靠体素分支，能大致知道哪里可能有目标，但框的边界很难精确，这就是为什么要引入关键点分支。
1.2 关键点模块为什么不能去掉
体素化之后，点的精确坐标已经没有了，每个点只知道自己在第几个格子里。对自动驾驶场景来说，几厘米的误差可能就会让一个框贴不紧车辆边缘，所以 PV-RCNN 在体素特征之外，又保留下了一批关键点，让这些关键点成为连接“体素网格”和“原始几何位置”之间的桥梁。
关键点的选取方式很常见，主要是最远点采样。这个算法从初始点开始，反复挑离已有集合最远的点，最后得到一批在空间上尽量分散、覆盖整个场景的点。代码里你会看到 num_keypoints、samples_per_point 这类参数，前者控制整帧保留多少个关键点，后者控制每个关键点聚合周围多少个体素格子里的特征。可以把它理解成在压缩过的地图上重新打了一批均匀分布的采样点，每个采样点都能就近读取周围区域的特征，还原局部几何。
这些关键点既保留了较精确的位置信息，又通过邻域聚合拿到了多尺度体素特征，相当于把两种表示方式的优点拼在一起。实际调参时，关键点数量是个灵敏度很高的开关，数量太少会漏检，数量太多会拖慢速度，而且会和后面的候选框细化模块互相影响。
1.3 两个检测头决定了训练和测试的代码形态
PV-RCNN 是两阶段结构，这一点直接影响 train 和 test 的逻辑。网络里先有一个区域建议网络，在体素特征上产出比较粗糙的候选框；这些候选框会对齐到关键点上，再由一个细化头对每个候选框做更精细的分类和回归，输出最终框。
训练时，两个头的损失要一起算，一起回传；测试时，建议网络可以理解为把候选框送到细化头的前置步骤，代码里虽然还会跑一遍，但它的分类分数往往只用来做早期过滤。很多人在阅读测试代码时感到混乱，就是因为在脑中没有分清这两条路径：某一部分的输出只是中间变量，而不是最终结果。
清楚这一点之后，读代码会顺畅很多。建议网络里的 anchor、IoU 匹配策略影响的是“能不能找到候选框”；细化头里的关键点聚合、采样半径影响的是“候选框能不能被修准”。train 脚本里调权重、调 loss，其实就是在平衡这两个阶段的配合关系。
2. 训练入口：从数据到loss的一整条流水线
2.1 数据 loader 在干什么
训练入口第一步是构建数据加载器。PV-RCNN 的数据 flow 不长，但每个环节都值得看仔细。首先从数据集读取点云文件，一般点的内容是 x、y、z 和强度，有时候还有时间戳之类的额外通道，但核心常用的是前四维。读进来之后，数据预处理会做几件事：过滤掉超出 point_cloud_range 的点，滤掉地面或把地面点标记出来，然后按帧组织成张量。
接下来是数据增强。这一步很多人容易忽略，但它在代码里占据的篇幅往往不小。常见的增强手段有全局旋转、全局缩放、水平翻转、随机平移，还有从其他帧里复制 GT 框到当前帧的 GT 采样。增强的目的是提高泛化能力，但要注意它只会出现在训练流程里，测试流程绝不能做同样的事，否则结果没意义。
loader 最终产出的 sample，一般包含几个关键字段：
- 点云张量，形状类似 (B, N, 4)，N 是一帧里最多的点数，不够的部分用 0 补齐；
- 用于标记哪些点是有效点的 mask；
- 真值框张量，形状类似 (B, M, 7)，每行代表 (x, y, z, l, w, h, angle)；
- 每个框对应的类别标签。
整帧点云被补齐到固定 N，是因为 GPU 上的张量要求形状统一，但这也带来了一个性能问题：大量 0 填充点会在后续计算中浪费资源。所以工程实现中通常会带上有效的 batch index，让稀疏卷积和采样模块知道该跳过哪些无效点。
2.2 配置文件里的关键参数与它们之间的耦合
跑 PV-RCNN 之前，一定要先翻配置文件，而不是先看网络代码。因为网络结构里很多维度是从配置里算出来的，你看到的每一层输出通道、每一个采样半径，都不是随便写的。下面这几个参数是我每次开始实验前必查的，它们彼此之间的耦合关系也列在表里。
| 参数 | 作用 | 常见坑 |
|---|---|---|
| voxel_size | 体素物理尺寸，决定网格分辨率 | 调太小容易显存爆，调太大直接掉召回 |
| point_cloud_range | 点云保留范围 | 和体素尺寸一起决定网格数量，往往要一起改 |
| max_points_per_voxel | 每个体素最多聚多少点 | 超过上限的点会被随机丢弃或平均 |
| num_keypoints | 每帧保留的关键点数量 | 太多拖慢速度，太少细化头效果变差 |
| anchor_size | 每个类别的先验框尺寸 | 尺寸和真实目标差别大时，AP 可能直接崩 |
| score_threshold 与 nms_threshold | 测试阶段的过滤阈值 | 训练代码里不出现，改错地方不会生效 |
很多人只把 attention 放在学习率上，shfbvg 忽略了这些数据侧参数。实际上体素尺寸和点云范围是一对强力组合：范围固定后，体素越小，体素数越多，稀疏卷积的内存和耗时都会上涨。如果显存紧张，优先检查是不是体素太小，而不是盲目换显卡。
anchor 参数也容易被低估。例如某一类目标在数据集中集中在特定尺度附近，如果先验框明显偏大或偏小，训练时正样本匹配率会很低，网络可能一直收不到有效的回归信号，表现就是训练 loss 下降很慢，测试 AP 基本为零。遇到这种问题，回到配置文件里对齐 anchor 尺寸，比调任何优化器参数都有效。
2.3 标签匹配与损失分支
PV-RCNN 的标注框不会直接参与网络计算，而是先和 anchor 做匹配。匹配方式一般就是计算每个 anchor 和每个 GT 框之间的 3D IoU，然后设定阈值：大于某个阈值的 anchor 是正样本，小于另一个阈值的是负样本，中间的不参与分类损失。这个过程在代码里可能封装在 target assigner 里，看起来不长，却决定了模型能不能学到正确的回归目标。
训练损失通常是一个组合损失。建议网络部分有分类损失和框回归损失，关键点分割部分有分割损失，细化头部分还有候选框的分类和回归损失。最终训练脚本里的 loss 是这些分项按权重相加，常见形式可以写成：
[ L = L_{rpn_cls} + L_{rpn_box} + L_{seg} + L_{head_cls} + L_{head_box} ]
各分项前面的权重在配置里都可以调。读代码时不要只盯着loss.backward()那一行，要看每个 loss 分项是从哪个模块传出来的，这样才能定位问题。比如边界框回归 loss 在训练早期总是很大，可以检查是不是回归目标没有做归一化；如果分割 loss 一直很高，可以检查关键点周围采样得到的体素特征是否真的和 GT 对应上。
训练循环本身不长，核心就是这个样子：
# train.py 的简化流程，实际工程里还有日志、断点保存等细节 for epoch in range(max_epoch): for sample in train_loader: sample = to_device(sample) preds = model(sample) loss = compute_loss(preds, sample) optimizer.zero_grad() loss.backward() grad_norm = clip_grad_norm_(model.parameters(), max_norm) optimizer.step() scheduler.step()看起来简单，但这里有两个容易被忽略的点。梯度裁剪在很多框架里默认开启，如果关闭，训练后期偶尔会出现 loss 突然变大的现象；学习率调度器每一步都在更新，如果它和 batch 数量、epoch 数量没对应好，可能出现训练到一半学习率已经衰减为零的情况。这些都不是模型结构问题，全在入口脚本的细节里。
3. 测试入口：表卡分数是怎么出来的
3.1 test脚本和 checkpoint 加载
测试入口的逻辑比训练简单得多，它没有 loss，没有反向传播，也不该有数据增强。进入测试脚本后，第一件事是加载模型和 checkpoint。这里最常见的错误是拿着训练中途保存的权重，却忽略了保存内容里除了model_state_dict之外，还有optimizer_state_dict和scheduler_state_dict。如果你只想要模型权重，加载时应该明确使用模型状态字典，而不是直接load整个文件。
加载模型后，必须执行评估模式。这一步平时不起眼，但对带有 BatchNorm 和 Dropout 的模块影响非常大：评估模式会关闭 Dropout，同时让 BatchNorm 使用当前 batch 的统计信息还是固定统计信息，两者的结果差异也很大。有些框架里，保存 checkpoint 时会把模型整体序列化，加载出来自动带着当时的状态，这就埋下了训练测试行为不一致的坑。
test 脚本通常会遍历测试集，把所有预测结果先存起来，再统一交给评估脚本。分离“推理”和“评估”是一个很好的设计，原因在于 PV-RCNN 输出的是原始分数和框坐标，而指标脚本需要按类别、按难度分别统计，如果在一个文件里同时做，一旦后处理规则要调整，整个推理都要重来一遍。
3.2 原始输出到边界框的转换
网络输出的并不是直接可用的三维框坐标，而是一组相对 anchor 的偏移量。在使用 anchor 的检测网络里，回归目标通常是标准化之后的差异，解码过程不复杂：
[ x_{\text{pred}} = x_a + \delta x \cdot w_a ] [ y_{\text{pred}} = y_a + \delta y \cdot l_a ] [ z_{\text{pred}} = z_a + \delta z \cdot h_a ]
其中 (x_a、w_a) 等来自 anchor 的原始位置和尺寸。这个过程必须和你训练时定义的回归目标完全一致。有的人在测试代码里忘了乘 anchor 尺寸，或者在解码长宽时把顺序调反，结果 box 全部错位，定位却查不到原因。
序列化输出框之后，还需要把类别标签和置信度分数带上。类别标签通常来源于某个 anchor 所属的类别分支，因为不同类别的 anchor 可能叠加在同一个位置，解码时要按各分支自己的 anchor 尺寸来算。这也是为什么很多框架里的 anchor 管理代码看起来复杂，它本质上是在维护一张“哪个位置、哪个方向、哪个类别对应什么先验框”的表。
3.3 NMS 的细节
拿到一组预测框后，NMS 是最后一步也是影响分数最明显的一步。NMS 的思路很简单：按置信度从高到低排序，保留当前最高分的框，然后删掉和它重叠度超过阈值的其他框。但在 3D 检测里，重叠度计算不是普通二维矩形的 IoU，而是带旋转角度的三维框 IoU，计算量比 2D 大得多。
代码实现上，最常见的是按类别分别做 NMS。如果所有类别放在一起做，一辆占据很大空间的卡车框可能会抑制旁边行人的框，导致两类目标互相打架，类别不均衡严重时，小目标几乎全被抑制掉。按类别分开之后，每个类别独立选框，再用全场景统一的置信度阈值做最终过滤。
NMS 阈值也是调参高敏感点。阈值设得过高，重叠的框会大量保留，误检增加；阈值设得过低，检测框会被过度抑制，召回下降。很多情况下，官方默认值只是通用起点，需要结合你的任务场景、目标密度和评估指标来反复试。
3.4 指标计算与可视化
测试阶段最后一步是评估。常见指标是各类别下的平均精度，也就是 AP，通常是逐类计算，再把所有类别平均得到 mAP。评估脚本会按 GT 框和预测框的 IoU 匹配情况，把预测框分为正确检测、误检、漏检，然后根据不同置信度阈值画出 PR 曲线，计算曲线下面积。
这里最容易栽跟头的地方是预测框的格式必须和评估脚本要求的格式一致。有些评估脚本要求角度范围是 0 到 π，有些要求是 -π/2 到 π/2，如果训练时预测头输出的角度约束方式和评估脚本不一致，看起来损失很低，实测分数却惨不忍睹。代码里常常会有一个专门的函数负责对角度做 wrap 处理，改动时两边都要检查。
除了指标，可视化也是测试阶段的重要输出。把点云、GT 框和预测框画在同一张图上，虽然不能直接算分数，但能快速发现“框出来了但位置整体偏左”“高度方向完全不准”“角度全转了 90 度”这类模式。可视化结果比 loss 曲线更直观，排查空间相关的问题时效率极高。
4. 训练和测试中最容易翻车的现场
4.1 训练和测试数据预处理不对称
这是我见到最多的故障原因。训练时 loader 会把点云裁剪到指定范围内，测试时如果漏掉这一步，模型会看到范围外的点，虽然大多数情况下不至于崩溃，但特征分布已经变了，分数会悄悄掉一截。反过来，如果训练时做了增强而测试时忘记关闭，也会出现同样的不稳定情况。
另一个隐蔽的不对称在点云排序和填充上。训练 loader 为了提高效率，可能会对点云做乱序、随机降采样、强制补齐到统一长度，测试代码如果用的是另一套预处理，输入分布就会漂移。遇到测试分数和训练分数差距很大时，第一步不是调模型，而是把 train 和 test 两套 loader 增强函数并排打开，逐行确认哪些操作的训练状态是开启的、哪些被关闭了。只要这里不对称，后面所有分析都是白费。
4.2 显存爆炸与 loss 不降
显存溢出在 PV-RCNN 训练里非常常见，尤其是选了小的 voxel_size 或大的 num_keypoints 后。我自己的排查顺序是：先看配置里的 point_cloud_range 和 voxel_size 算出的体素网格数量是不是过大；再检查关键点数是不是被设成了一个夸张的值；最后才考虑降低 batch size。这三个方向里，前两个属于算法层优化，第三个属于硬件妥协，优先做前两个能让训练速度也受益。
loss 不下降或下降到一半卡住，常见原因是标签匹配出了问题。例如某一类目标在场景中很少，导致正样本数极少，分类 loss 会被大类别的负样本淹没，表面看起来 loss 一直在降，实际那一类的 AP 完全没起来。对策是检查每个 batch 里正负样本比例，必要时调整匹配阈值或给分类损失增大权重。
还有一类问题表现为某一步 loss 突然变成 NaN。这大概率是回归目标里混入了无穷大值，比如某些 GT 框尺寸异常、角度差值 wrap 出错，或者在计算 IoU 时除以了零。遇到 NaN，不要先怀疑优化器，而是打开数据样本，把 GT 框和预测框逐个打印出来，通常一眼就能看到某个框的长或宽是零。
4.3 测试分数和训练分数对不上
经常有人拿着训练集上表现很好的模型，去跑测试集，分数掉得惊人。除了过拟合，还有一个很常见的原因是评测数据的选择标准不一致。有的评估脚本用的是简单样本子集，有的用中等难度子集，有的用困难子集，每一类难度对应不同遮挡和截断条件，AP 差距可以非常大。看指标前，先确认你当前读的是哪个子集的评估结果。
另一个问题是官方权重和自训练权重的加载方式不同。官方权重通常配合默认 anchor 和默认类别使用，如果你改了类别数量或 anchor 尺寸，加载官方权重必然会出现维度不匹配。很多工程在这种情况下会直接报错，但也有些框架会忽略不匹配的层，静默地保留随机初始化权重，导致分数莫名低下。加载时务必把模型结构里的关键层逐层打印确认。
复现分数不稳定的另一个来源是随机性。GPU 上的某些操作不保证完全可重复，不同设备、不同 batch 顺序、甚至不同 CUDA 版本都会带来微小差异。严谨的做法是固定随机种子，但不要只固定 Python seed，有些框架需要在命令行里额外设置环境变量才能完全对齐。
5. 从跑通到改出更好分数的一些建议
5.1 先复现，再动手改
拿到 PV-RCNN 工程后，我的建议永远都是先不要乱动。配置保持默认，数据路径改成你本地的路径，直接跑通 train 和 test，用公开数据集验证指标和官方结果在一个合理范围内。这一步的意义不是刷数字，而是确认你的环境、依赖、数据预处理和代码逻辑整体上是闭环的。一旦后续改了模型结构，你可以放心地把分数差异归因到自己的改动上，而不是环境问题。
复现过程中我还会额外记录三件事：config 文件的哈希值、checkpoint 保存时的 seed、评估脚本使用的数据集子集类型。这三件事看似琐碎，但当实验做了几十组之后，你会发现这也是最快定位“分数差异来源”的线索。
5.2 按什么顺序调参最稳
如果默认配置能跑通，分数也在合理范围，接下来才开始调参。我的顺序大致是这样的：
- 先检查 anchor 尺寸是否和真实目标分布匹配，这一步错位的代价最高；
- 再调关键点数量和采样半径，这两个参数直接影响细化头的信息量；
- 然后检查数据增强的强度和方式，增强过强会拖慢收敛，增强过弱容易过拟合；
- 最后才是 loss 权重、学习率、NMS 阈值这些偏“软”的参数。
很多新手把时间花在调学习率上，学习率当然重要，但它是在其他配置基本合理的前提下才有意义。如果 anchor 都没对齐，哪怕学习率调出花来，AP 也上不去。我认为一个负责任的实验记录至少要包含下面几列信息，方便后期对比：
| 实验编号 | 改动点 | 训练AP | 测试AP | 显存占用 | 每轮耗时 | 备注 |
|---|---|---|---|---|---|---|
| 01 | 默认配置 | 82.1 | 80.6 | 7.2G | 18分钟 | 基线 |
| 02 | 关键点数量减半 | 80.3 | 78.9 | 5.8G | 14分钟 | 速度更快，精度下降 |
| 03 | 增大采样半径 | 82.7 | 81.2 | 8.0G | 20分钟 | 小幅提升 |
这张表不用写得多漂亮，但它能逼着你每次只改一个变量，而不是同时改五个变量然后对着结果发呆。实验改动的可控性，比实验次数更有价值。
5.3 我踩过几次坑之后留下的习惯
最后分享一个我自己觉得非常有用的习惯：每次写完 train 或 test 代码的改动，我都会先在单帧数据上做一个小批量测试，而不是直接启动完整训练。单帧测试只需要看 forward 能不能跑通、loss 是不是有限值、ground truth 匹配是否正常。这样能在一个短周期内发现大多数维度错误和 NaN 问题，省下的时间和算力远远超过多写这几行测试代码的成本。
另一个习惯是给每个实验单独记录一份配置文件副本，而不是复用同一个文件反复改动。这个习惯帮我在某次实验对比中快速找到了一个隐藏问题：有两次实验用的文件名和基础配置完全一致，但我后来发现其中一次意外改动了 angle 范围，导致模型输出格式变化，让评估分数掉了几个点。如果没有配置文件副本，这个错误可能真的很难定位。
从 train 到 test，PV-RCNN 的代码路径其实没有捷径可读，但它也不像看起来那么庞大。把体素化、关键点聚合、锚框匹配、损失回传、后处理解码这几段主线抓住，再按“先复现、后调参、每次只改一个变量”的节奏推进，你很快就能从读懂代码变成能自己改代码的人。
: 选择题和判断题（题解）)
