简介spconv.zip 是一份面向三维点云深度学习场景的预编译资源内含 spconv1.2.1 完整库文件用于解决传统卷积网络难以直接处理非结构化三维点云的问题。它面向使用 PyTorch 开发目标检测、语义分割等三维视觉任务的工程师与研究者省去源码编译步骤可直接安装调用。压缩包共收录 5130 个文件总大小约 46.31MB类型以 C/CUDA 实现.cu、.cpp、.h、.hpp、Python 脚本、HTML 文档及 cmake 构建配置为主同时包含少量示例数据与镜像文件可支撑库的安装、调试与二次开发。已有 1086 人学习下载说明该预编译版本在点云处理需求中有一定关注度和实用价值。解压后既能获得预编译的 so/a 库直接使用也可查看配套源码、文档和示例深入理解体素化、空洞卷积等关键机制便于在自动驾驶、机器人导航等项目中做针对性修改与部署。1. spconv.zip 到底解决什么问题一张 10 万点的点云图让普通卷积直接算不动拿到这个 zip 包的人十有八九是冲着点云卷积来的。一帧 10 万点的激光雷达点云按 200×200×16 体素网格离散之后真正被点击中的格子往往只有 3000 到 6000 个占用率不到 2%。这时候如果还拿普通 3D 卷积从第一层开始滑窗每一层都在海量空格子上做乘加特征图一铺开计算量直接指数膨胀。spconv.zip 这个代码包的本质就是给点云建一张“哪些格子有东西”的索引表只对有效体素做卷积让高分辨率点云也能塞进显存训练。它解决的问题不是省一点算力而是把“点云是否能训得动”这个前提问题解决掉。适合做激光雷达检测、三维语义分割、工业料盘点云分析的人如果你手里是几万到几十万点的帧数据先把这个方案跑通比调任何魔改网络都值。2. 稀疏卷积在做什么体素网格、索引表和有效点的稀疏计算2.1 普通卷积为什么处理不了点云先算一笔账。假设输入是 200×200×16 的体素栅格卷积核是 3×3×3普通 3D 卷积在每个位置都要读周围 27 个格子做乘加。表面看格子总量只有两万多乘加不过几十万次可到了网络中间通道从 16 涨到 64 甚至 128特征图再继续下采样乘加次数就是千万级起步显存也跟着翻倍。更糟的是点云占用率低得离谱一帧扫描数据映射到网格里占用率常年只有 1%2%。换句话说普通 3D 卷积每做 100 次计算98 次以上是在跟空气打交道。还有一层隐性限制普通 3D 卷积输出体素的位置由输入尺寸、padding 和 kernel 决定跟“点到底落在哪”没关系。稀疏卷积完全相反输出格的位置由输入有哪些有效格、卷积核覆盖哪些邻域共同决定。这个特性带来的直接好处是计算量只随有效体素数走与分辨率的立方关系被解耦。你可以把小目标所在的局部区域体素网格拉到 512 分辨率而不必担心显存瞬间被打爆这在普通 3D 卷积里想都不敢想。2.2 数据表示坐标字典 特征矩阵要实现只算有效体素得先有一套能表达“哪里有点”的数据结构。常见实现采用双数组方案一个坐标表一行存一个有效体素的位置同一帧输入里坐标必须唯一另一个特征矩阵与坐标表按行对应每一行是该体素编码后的特征向量。坐标表在带 batch 训练时通常每行包含 4 个整数batch 内帧序号 x/y/z 三维格坐标所以形状是 [N, 4]特征矩阵是 [N, C]。决定能不能跳空计算的还有第三张表工程里叫它规则化表rule book。它记录对于卷积核的每一个偏移位置输入里哪些有效体素命中、分别写到输出的哪个格子。这张表在一次前向里只需要构建一次后面层可以继续复用映射结果。也正因为这张表的存在稀疏卷积算子表现出很强的数据结构耦合性——点云坐标稍有抖动规则化表可能就要重新排一遍计算路径每次都不同。这个特性是第四章参数联动和第五章一堆坑的共同根源理解它比理解卷积公式本身更重要。2.3 关键算子稀疏卷积和子流形卷积选哪个并不是所有层都应该用同一种稀疏卷积。常用算子分两类普通稀疏卷积输出体素位置由输入体素膨胀得到输出数量明显多于输入适合做空间下采样子流形卷积输出位置严格等于输入位置稀疏度保持不变只在已有激活点上做特征提取。这两者的工程意义差别很大。网络浅层做空间压缩时用带 stride 的普通稀疏卷积把体素尺寸逐层翻倍深层做特征抽象时用子流形卷积避免特征向空格扩散导致计算量失去控制。我一般这样搭第一层子流形卷积保持原始点语义第二层接一个 stride2 的普通稀疏卷积让体素半径扩大之后再用一组子流形卷积堆叠感受野最后用稀疏最大池化收口。这套组合对大目标和小目标都相对友好。但要注意子流形卷积不会“新增”信息堆太深时特征沿固定激活路径循环感受野扩张非常有限远距离稀疏目标容易学不到上下文。稀疏卷积与子流形卷积按 2:1 交替是最稳的结构选择。2.4 为什么常见实现偏爱 COO 风格坐标表稀疏矩阵有 CSR、CSC、COO 等多种存储格式CSR 在 CPU 科学计算里非常常见但 GPU 稀疏卷积几乎都偏向 COO显式存坐标线程块直接按坐标索引而不是依赖行偏移扫描。原因有三个。其一GPU 卷积算子要求每个线程块快速判断“我负责的输出体素由哪些输入体素贡献”COO 可以预先排序再生成邻接关系访存局部性更好其二点云天然是不规则采样CSR 的连续行假设在这里作用不大反而多一层间接跳转其三多帧 batch 时不同样本的坐标表直接拼接即可CSR 还要重算行偏移。理解这个差异对数据预处理很有指导意义。如果你的点云是按扫描线逐行产生的可以在送进网络前先按坐标排序再做体素化虽然算子内部也会排序但你在外面排好能省掉一部分规则化表的构建时间。这算是个不太明显但能实打实省几秒每 epoch 的小技巧。3. 跑通最小流程点云转稀疏张量并完成一次前向推理3.1 点云体素化坐标映射与去重动手第一步把原始 XYZ 点云变成整数体素坐标。这里最容易犯错的是直接拿连续坐标当格子坐标那样每个点落一个格稀疏结构完全失去意义。常见做法是先定体素尺寸 voxel_size再把坐标除以它取整同时把超出网格范围的点直接滤掉import numpy as np # points: (N, 3)单位米假设已经转到以传感器为中心的坐标系 voxel_size np.array([0.1, 0.1, 0.2]) # x/y/z 方向的体素边长 grid_size np.array([501, 501, 11]) # 各方向格子数上限 coords np.floor(points / voxel_size).astype(np.int32) mask np.all((coords 0) (coords grid_size), axis1) coords coords[mask] feats feats[mask] # 对应的原始特征比如 xyz 反射强度这段代码做了三件事把连续坐标缩放到整数格丢掉边界外的点避免后续越界保留与坐标对应的特征。voxel_size 的选取在第 4 章细讲这里先用 0.1m 起步。需要注意 z 方向的体素往往比 x/y 大因为激光雷达垂直分辨率本身就比水平低取更小反而引入噪声。同一个体素格子可能落进多个原始点而子流形卷积要求坐标唯一所以必须做去重合并。合并方式影响后续任务表现做检测时通常取格内所有点的平均特征或按反射强度加权平均直接丢弃点会丢失密度信息对远距离目标尤其不利。unique_coords, inverse_idx np.unique(coords, axis0, return_inverseTrue) num_voxels unique_coords.shape[0] feats_sum np.zeros((num_voxels, feats.shape[1]), dtypenp.float32) np.add.at(feats_sum, inverse_idx, feats) counts np.bincount(inverse_idx).astype(np.float32) feats_avg feats_sum / counts[:, None]这段里 np.add.at 是必须的不能写成feats_sum[inverse_idx] feats。后者在同一个格子被多个点命中时会重复覆盖结果完全不可控算是点云预处理里非常隐蔽的翻车点。除法那行是归一化这样每个体素的特征表示的是平均点特征而不是累加和避免高密度区域主导整个网络。3.2 构建稀疏张量并送入网络拿到唯一坐标和聚合特征后把它封装成稀疏张量。多数实现要求坐标带上 batch 索引单帧就是给坐标表第一列填 0多帧时把各帧的结果直接拼起来即可。下面的示例以常见的封装风格为例导入名以你实际解压出来的包为准import torch batch_idx np.zeros((num_voxels, 1), dtypenp.int32) sp_coords np.concatenate([batch_idx, unique_coords], axis1) # (M, 4) sp_feats feats_avg.astype(np.float32) x SparseConvTensor( featurestorch.from_numpy(sp_feats), indicestorch.from_numpy(sp_coords), spatial_shapegrid_size.tolist(), batch_size1 )封装之后x 可以像普通 Tensor 一样在网络里传递。前向之前我会做一个轻量自检打印 indices 的最大最小值确认都在 spatial_shape 以内检查 features 里有没有 NaN。这两个检查能筛掉大量“网络结构没问题但数据进不去”的假报警。许多初学者遇到莫名其妙的维度报错一查全是坐标里混进了负数。3.3 一个最小稀疏网络与输出还原下面用三层结构演示稀疏网络的最小写法子流形卷积保持点数普通稀疏卷积做下采样稀疏池化继续压空间尺寸。import torch.nn as nn import torch.nn.functional as F class DemoNet(nn.Module): def __init__(self, in_ch4, mid_ch32, out_ch16): super().__init__() # 子流形卷积输出稀疏度与输入一致 self.subm SubMConv(in_ch, mid_ch, kernel_size3, indice_keysub0) # 普通稀疏卷积stride2 做空间下采样 self.conv SparseConv(mid_ch, mid_ch, kernel_size3, stride2, indice_keysub0) # 稀疏最大池化继续扩大感受野 self.pool SparseMaxPool(kernel_size3, stride2) def forward(self, x): out self.subm(x) out F.relu(out) out self.conv(out) out self.pool(out) return out注意 indice_key 的用法subm 和 conv 共用同一个 key规则化表可以复用一次省掉重复构建时间。如果希望各层独立建表就不要写同一个 key。这里用F.relu直接作用于稀疏张量算子内部会保留坐标表不变只对特征做激活所以不用担心破坏稀疏结构。跑完前向之后输出坐标落在降采样后的网格尺度。想还原到物理坐标要把体素尺寸按 stride 乘积乘回去但如果你后面接的是检测头强烈建议保持“降采样后网格坐标”不还原直接在这个坐标系里算 anchor 和损失最后输出时再做一次坐标变换省掉中间多次单位换算的麻烦。3.4 观察稀疏度变化网络是变快了还是白算了第一次跑通前向先别看精度。在小数据集上把每一层输出的有效体素数打出来观察稀疏度是怎么流动的。健康的曲线应该是子流形层维持输入稀疏度stride2 卷积把有效体素数降到约 1/8池化后再降 1/8。如果某层输出不降反升通常是 kernel 或 padding 把空邻域也标记成了有效点优化效果被暗中抵消。def print_sparsity(x, name): total np.prod(x.spatial_shape) eff x.indices.shape[0] print(f{name}: effective{eff}, sparsity{eff / total*100:.4f}%)把这段插到每个算子之后比任何 profile 工具都直观。它还能帮你发现“输出坐标超出 spatial_shape”这类反向传播不会报错、只会偷偷丢点的问题。如果输出稀疏度比输入还高优先检查 kernel 和 dilation 设置。4. 关键参数配置voxel_size、stride 与稀疏率联动4.1 voxel_size 定了稀疏率也就定了体素尺寸是稀疏卷积里最敏感的全局参数。同样的点云voxel_size 从 0.05m 改成 0.2m有效体素数量可能差一个数量级感受野覆盖的物理范围随之变化目标的可分辨程度也完全不同。车前 30 米、高度 3 米的目标0.1m 网格还能保留几十个有效体素的覆盖0.2m 可能只剩几个点。所以 voxel_size 不是随便拍的。我一般先统计目标真实包围盒内点云的分布确保目标最小维度上不少于 3 个格子然后再反推 voxel_size。点云噪声大、位置抖动明显时稍微加大体素反而能平滑坐标抖动追求小目标召回时就要缩小体素同时接受计算量上升。数据侧参数和网络侧参数要联动着定常见框架在 GPU 内核里对坐标做向量化加载网格尺寸是 8 的倍数时能减少边界判断所以建议先把 grid_size 整成 8 的倍数再设定网络中的 pool stride 乘积能整除它。这个顺序别反否则后期会为“全连接层输入尺寸差一格”这种问题熬夜。4.2 stride 和 kernel 按“稀疏率预算”控制网络设计时最容易忽略的是输出稀疏率预算。假设输入有效体素数 10000一个紧凑稀疏网络的中间层输出体素数大致按“除以 8 再除以 8”规划。stride 每加大一档输出稀疏度就减一次kernel 加大则会让有效格向邻域扩散。两者作用相反如果调参时只看单个量会出现“增大了 kernel 想提升感受野结果计算量暴涨、精度反降”的典型翻车。我习惯给每个下采样块预设一个稀疏率上限比如“本块输出有效体素数不超过输入的一半”vox_in x.indices.shape[0] vox_out_est np.ceil(vox_in / (stride ** 3)) * 4 # 4 是 kernel 扩散的经验系数 assert vox_out_est vox_in, 该层输出可能比输入还要密这个 assert 的意义不是阻止你设计网络而是把“稀疏度失控”这种隐蔽问题提前暴露在配置阶段。如果触发了优先减小 kernel 或改回子流形卷积而不是硬着头皮加网络深度。4.3 批处理与显存的联动参数不要以为稀疏卷积省显存就可以随便加大 batch。同一批数据里各帧有效体素数可能差异极大城市道路帧可能有 8 万个有效格子高速空旷帧只有 2 万个。如果按固定帧数组 batch显存占用会剧烈波动训练中期突然 OOM 的成因往往就在这里。常见做法是按“每批总有效体素数”来组 batch比如设上限 20 万超过就丢弃或重新采样。这个参数的地位不亚于学习率建议单独记录在实验配置里。显存突刺的另一来源是反向传播稀疏卷积前向通常访存规律、占用可控但反推时要保存中间邻域特征并映射回输入坐标显存往往是前向的好几倍。我用前三步估算先在小 batch 下量前向显存batch 上限再按这个值的 3 倍预算而不是常见的 1.5 倍。参数作用主要影响经验取值voxel_size决定体素粒度有效体素数、目标可分辨度目标最小维度不少于 3 格grid_size定义网格边界坐标越界比例、显存上限整成 8 的倍数kernel_size决定邻域范围有效格扩散程度优先 3扩散明显时回退stride控制下采样率输出稀疏度每块输出约为输入的一半每批有效体素上限控制显存波动训练稳定性按前向显存的 3 倍预算5. 排查手记稀疏张量形状、梯度回传与显存突刺5.1 症状输出坐标错位检测框全部偏向一侧现象训练指标看着正常一旦把检测框画出来整体朝 X 方向偏移好几个体素而且偏移量固定。 原因最常见的是拿子流形卷积的输出坐标当成输入坐标用。子流形卷积输出坐标与输入坐标一一对应表面看“没变”但网络一旦经过 stride2 的下采样坐标就已经落在新网格尺度上。继续用原始 spatial_shape 或原始体素尺寸去还原物理坐标偏移就必然出现。 解决每个带 stride 的层后重新记录一次 spatial_shape。我的做法是维护一个坐标换算器输入时记录 voxel_size每过一个 stride2 层就把它乘 2最终只在输出端做一次物理坐标还原。中间层一律保持统一体素坐标系不做多次换算减少出错面。5.2 症状训练十几轮后显存突然翻倍再 OOM现象loss 稳定下降某一天高峰显存从 9G 跳到 18G直接 OOM而且不是每轮都发生。 原因稀疏卷积的规则化表是动态构建的。如果某个 batch 恰好点特别密集或者随机裁剪把大量点挤进有限区域有效体素数会突然激增规则化表规模同比例放大反向传播的邻域缓存也随之膨胀。平时算得好好的遇到密集帧就炸这是显存突刺的典型形态。 解决按 4.3 的方式按总有效体素数组 batch上限保留 20% 余量。数据增强里加一个“裁剪后有效体素计数”的断言超过阈值就重新采样。不要只靠降低 batch 一条路batch 降太多训练稳定性会变差性价比很低。5.3 症状稀疏卷积加速比不如预期GPU 利用率掉到 40%现象显存确实省了但每轮训练时间没缩短多少甚至更慢GPU 利用率大幅下降。 原因稀疏算子的耗时由规则化表构建和线程调度决定。有效体素数太少时线程块根本打不满 GPU瓶颈从计算量变成内存带宽和索引访存。换句话说稀疏卷积在“有效密度低到一定程度”时才划算密度一旦偏高它比稠密 3D 卷积还要慢。 解决用同一份数据分别跑稠密 3D 卷积和稀疏卷积的前向耗时找到交叉点。我见过小部件点云只有 2000 个有效体素稠密卷积反而快 20%。正确的工程结构往往不是无脑全稀疏而是前 12 层用稠密处理或体素编码把空间压缩一轮之后再切进稀疏网络让稀疏算子处理它最擅长的中高层特征。5.4 症状模型导出后推理结果与训练不一致现象训练和验证都好导出成推理格式后第一个 batch 输出就偏置信度整体下降但幅度不算离谱。 原因不同后端对稀疏算子的边界处理规则不同。训练框架里坐标超出 spatial_shape 的行会被静默丢弃某些推理后端会保留越界坐标或对越界体素做填充。单层差异看不出来多层堆叠后被放大成稳定的精度损失。 解决导出前把 spatial_shape 写死禁止动态尺寸。转换后立刻做 5 个样本的对拍同一组点云分别跑原始模型和导出模型逐个输出比较误差阈值设 1e-4。发现问题先查坐标过滤逻辑再看精度损失这样能省掉一整天的上线回归。6. 走向工程化三个不显眼但很省时间的习惯第一个习惯是固定坐标系。所有点云输入前统一转换到以传感器或约定锚点为原点的坐标系预处理全在这个坐标系里完成。稀疏卷积的规则化表对坐标数值非常敏感坐标系抖动等于每帧都在变相建表实验还难以复现。固定坐标系之后训练和推理的输入分布一致很多奇怪的偶发问题会自己消失。第二个习惯是断点回归测试。每次改完配置或数据增强把上一轮最好的权重拿出来跑一组固定 50 帧的样本对比输出特征图差异。如果差异突然变大问题大概率出在坐标编码或规则化表而不是梯度不收敛。这个习惯帮我挡下过不少“配置没问题”的假象。第三个习惯是混合精度的提前验证。很多人上来就开 AMPloss 一震荡就怀疑学习率其实是稀疏卷积的反向算子对低精度索引支持不完整部分梯度被悄悄截断。建议先全精度跑通小数据再开 AMP 对比前几轮 loss 曲线两条曲线走势一致再切正式训练。这几年我换过几种点云方案最后留下来的习惯就两条把坐标当一等公民看待把稀疏度当计算预算看待。前者能解决八成调试问题后者能解决八成性能问题。希望这篇笔记能帮你在稀疏卷积这条路上少踩几个坑。本文还有配套的精品资源点击获取
