3DGS部署与训练全攻略：从CUDA环境到参数调优的实战笔记

简介面向希望部署与训练3D Gaussian Splatting的开发者与研究者这是一套在非官方推荐环境下验证可运行的完整项目源码重点解决Python 3.10、CUDA 12.3与PyTorch 2.2.1组合下的环境配置、依赖安装、数据下载与格式转换、模型训练及结果查看等环节的实操问题。压缩包共3个文件包含inscode配置、HTML说明文档和gitignore过滤规则整体约7KB结构精简适合快速对照学习。作者不仅给出了从官方预训练数据到自定义图片训练的完整路径还结合视频抽帧、数据预处理等进阶技巧说明如何准备非标准数据集并补充了训练结果查看方式帮助读者少走弯路。目前已有200人学习下载对于刚接触3DGS的初学者、需要环境排错参考的工程人员以及希望将三维重建方法迁移到个人课题的研究者都具有直接参考价值。 最近上手跑了一轮 3DGS 的部署和训练整个流程走下来最大的感受就是官方文档看着简单实操全是坑。3DGS3D Gaussian Splatting作为三维重建方向这几年最热的技术之一论文和示例视频都做得非常漂亮但真正从零开始把源码跑通、把自己的场景数据训出能看的效果中间隔着大量版本兼容、编译报错、参数调优的问题。这篇把我在 3DGS 部署与训练上的完整过程、验证过的参数、踩过的坑一次性记录下来适合正在折腾这个项目源码的算法工程师、三维视觉研究者也适合想把手头设备测一测的 AR/VR 从业者。从我自己的经验看部署阶段的核心是 CUDA 工具链、PyTorch 版本、子模块编译这三件事只要版本矩阵不乱基本半天能跑通。训练阶段的核心则是场景数据质量、稀疏点云结果、密度控制参数这三个环节数据拍得不好后续所有调参都是白费。下面按我自己的实操顺序把每个环节展开讲清楚。1. 项目整体认知与部署方案设计1.1 3DGS到底解决什么问题在拆部署步骤之前先把 3DGS 解决的核心问题讲清楚。传统三维重建基本围绕 NeRF 和点云展开NeRF 的渲染质量高但训练几小时到几天、渲染一张图也要秒级根本没法做实时交互。3DGS 的思路是把场景表示成一大团三维高斯分布点每个点都带自己的位置、协方差、颜色和透明度通过可微光栅化直接往图像平面上投影配合自适应的密度控制既能表达复杂几何又能用 GPU 并行渲染。实际效果就是训练时间从 NeRF 的天级压缩到分钟到小时级渲染速度直接跑到实时帧率。你可以把 3DGS 理解成“会呼吸的点云”普通点云是静态的、不可微的3DGS 里每个点是一个有梯度、能学习形状和颜色的软椭球。场景里的镜面反光、细碎结构靠的是球谐系数SH去拟合视角相关的颜色变化这也是后面训练参数里sh_degree的由来。1.2 硬件与环境版本选型官方的训练代码是 CUDA 深度绑定的别指望纯 CPU 环境能跑。我自己实测普通的小物体场景在 RTX 3080 10GB 上能训但显存会比较紧张场景稍微大一点、图片分辨率再高一点20GB 显存才算舒适。官方仓库里给出的参考配置是 24GB 以上的专业卡实际做项目的话RTX 4090 或者 A5000 往上会比较省心。渲染端倒是不挑任意带 CUDA 的 N 卡都能跑实时查看器。环境版本是最容易翻车的地方先说结论我在多台机器上验证过比较稳的组合组件推荐版本备注操作系统Ubuntu 20.04 / 22.04Windows 也能跑编译坑更多Python3.7 ~ 3.10太新或太旧都可能翻车CUDA11.8 或 12.1必须和 PyTorch 匹配PyTorch2.0.1 / 1.13.1对应 CUDA 版本别用 CPU 版g / MSVCLinux 需 7.0Windows 需 VS2019编译子模块必需为什么强调 CUDA 和 PyTorch 的匹配因为官方仓库里的diff-gaussian-rasterization子模块是直接编译扩展的编译时会调用 PyTorch 自带的 CUDA 扩展机制如果 PyTorch 内置的 CUDA 版本和系统里不一致轻则编译警告重则运行时直接段错误。所以我的建议是先用nvcc --version确认系统 CUDA再按对应版本安装 PyTorch别盲目上最新版。2. 环境部署完整实操2.1 克隆源码与创建环境部署第一步是拉取官方源码。这里有一个非常容易踩的坑3DGS 仓库用到了子模块如果直接git clone不带--recursive后面积木一样的子模块目录是空的编译时直接报找不到头文件。正确做法如下git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting cd gaussian-splatting conda env create --file environment.yml conda activate gaussian_splattingenvironment.yml里会装好基础的 Python 依赖包括 PyTorch、tqdm、plyfile 等。不过要注意的是这个文件里默认的 PyTorch 版本可能和你的 CUDA 不匹配建议在执行之前先手动装 PyTorch再让environment.yml跳过重装。更保险的流程是conda create -n gaussian_splatting python3.8 -y conda activate gaussian_splatting pip install torch2.0.1 torchvision0.15.1 --index-url https://download.pytorch.org/whl/cu118 pip install plyfile tqdm为什么不直接用environment.yml因为我试过几台机器那个文件里钉死的版本和你本机驱动之间多少有点偏差不如手动执行来得干净。装完 PyTorch 后可以用python -c import torch; print(torch.__version__, torch.cuda.is_available())快速验证一下 GPU 是否可见。2.2 编译子模块与验证源码里有三个和 CUDA 强相关的子模块diff-gaussian-rasterization、simple-knn以及用于实时查看器的SIBR_viewers。训练和渲染只需要前两个查看器是额外的不着急装。编译的命令也很直接pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn这一步在 Linux 上通常顺序执行就能过但在 Windows 上坑很多需要先安装 Visual Studio 2019 或 2022并且要勾选“使用 C 的桌面开发”工作负载系统 PATH 里必须能定位到cl.exe如果遇到C1083头文件找不到多半是 Windows SDK 版本没对齐。还有一个小细节diff-gaussian-rasterization的setup.py在构建时会根据CUDA_HOME环境变量查找 CUDA 工具包Windows 下如果没有自动识别手动set CUDA_HOMEC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8再重新编译。编译完成后可以做一个快速验证在官方仓库的scene模块里随便导入一个高斯模型类或者直接跳到训练环节用一个小数据集试跑。我自己的经验是只要diff-gaussian-rasterization能 import 成功部署阶段就已经完成了一大半。3. 数据准备与COLMAP稀疏重建3.1 拍摄数据的采集规范3DGS 训练效果好不好60% 的功劳在数据采集。很多朋友拿着手机随便绕一圈拍个几十张丢进去训练出来的模型一团糊然后以为是代码问题其实大概率是数据不达标。我总结的拍摄规则有三条第一相邻图像的重叠率保证在 60% 到 80% 之间不要跳拍宁多勿少第二尽量避免反光、透明材质和纯色无纹理区域玻璃杯、白墙、镜面金属对 COLMAP 的特征匹配极其不友好第三固定曝光和焦距不要边走边变焦也不要触发自动 HDR不然同一个点在不同帧里的颜色基准都不一样。图像数量方面单个简单物体 50 到 150 张够用房间级的场景建议 300 到 600 张。分辨率建议控制在 1600 到 2000 像素的短边太高的分辨率对 COLMAP 特征提取和后续训练显存都是压力但也不要压得过低否则重建出的几何会丢细节。3.2 COLMAP处理与数据格式转换3DGS 官方不直接吃原始图像它需要先用 COLMAP 做一次稀疏重建得到相机位姿和稀疏点云。手动操作 COLMAP 的图形界面也可以但批量处理强烈建议用命令行。我的常用命令如下colmap feature_extractor --database_path database.db --image_path images --ImageReader.single_camera 1 colmap exhaustive_matcher --database_path database.db mkdir sparse colmap mapper --database_path database.db --image_path images --output_path sparseexhaustive_matcher适合图像数量不超过 500 张的场景数量再大就需要切换成顺序匹配或词汇树匹配否则匹配速度会让人怀疑人生。mapper跑完之后会生成sparse/0目录里面是cameras.bin、images.bin、points3D.bin三个二进制文件。如果sparse/0目录没生成或者只有空文件夹说明特征匹配或三角化失败了建议回头检查图像清晰度和重叠率。拿到稀疏重建结果后用仓库里的convert.py把数据转成训练需要的格式python convert.py -s /path/to/your/dataset这个脚本会从sparse/0里读位姿生成sparse/0下的cameras.bin等数据的副本再在images目录里生成去畸变后的图片版本存在images的副本目录里原始图像不会被覆盖。完成后你还需要确认最终目录结构是否是这样的dataset/ ├── images/ ├── sparse/ │ └── 0/ │ ├── cameras.bin │ ├── images.bin │ └── points3D.bin记得把convert.py跑完后的输出目录和原始目录对上否则训练脚本会提示找不到相机参数文件。4. 训练实操与关键参数解析4.1 训练命令与参数清单数据准备到位后训练就是一个命令的事python train.py -s /path/to/your/dataset -m /path/to/output默认会训练 30000 步迭代在 RTX 4090 上一个 200 张图的小场景大约需要 20 到 40 分钟。官方代码里比较常用的参数我整理了一下参数默认值说明-iimages输入图像子目录名-m无输出目录--iterations30000总迭代数--sh_degree3球谐最大阶数--densify_until_iter15000密度控制截止迭代--densify_from_iter500开始密度控制--densify_grad_threshold0.0002梯度阈值--opacity_reset_interval3000透明度重置间隔--lambda_dssim0.2SSIM 损失权重--start_checkpoint无加载已有模型继续训练这些参数里我实际体验下来最影响最终效果的三个是sh_degree、densify_until_iter和lambda_dssim。sh_degree默认 3对应 16 个球谐系数能表达比较复杂的视角相关高光如果场景里都是漫反射材质降到 2 反而能减少过拟合和闪烁。densify_until_iter控制高斯点分裂/克隆的截止时间超过这个步数后点云数量基本冻结如果发现模型细节不足可以适当往后延到 20000 甚至 25000。4.2 密度控制与学习率为什么这么设3DGS 的密度控制是整个算法的灵魂。简单来说训练过程中每个高斯点会计算位置梯度梯度大说明这个点在移动且还没有被优化好此时有两种处理方式如果点在场景中处于欠重建状态大概率是小尺度高斯就克隆一份如果点是大尺度且覆盖面太广就分裂成两个更小的点。从第 500 次迭代开始每 100 步做一个这样的自适应增密一直到 15000 步停止。这样点云数量会从初始 COLMAP 稀疏点的几千个增长到几万甚至几十万最终精确覆盖场景表面。学习率方面官方实现里最值得关注的是位置学习率它采用了延迟指数衰减策略训练初期位置学习率是 0.00016随着迭代从 0.01 倍开始逐步上升在训练后期指数衰减到 0.0000016。这种设计是为了让模型前期快速找到大致结构后期微调细节而不会震荡。我一开始不懂直接改成一个常数学习率结果 30000 步下来点云分布非常散渲染画面一直在抖。有个容易被忽略的点是--lambda_dssim它让损失函数是 L1 和 SSIM 的加权组合默认 0.2 的 SSIM 权重。SSIM 只管局部结构相似L1 管像素值差异两者配合能让渲染结果既有结构感又不会色彩偏移。实测下来如果场景纹理简单把lambda_dssim降到 0.1 会更快收敛纹理复杂则维持 0.2 更稳。4.3 增量训练与衍生方案训练是一次性的需求吗做项目时经常要在已训好的模型上继续迭代。官方支持--start_checkpoint加载已有的 checkpoint 做增量训练例如python train.py -s /path/to/your/dataset -m /path/to/output --start_checkpoint /path/to/output/point_cloud/iteration_20000/point_cloud.ply增量训练适合两类场景一是原始数据增加了新视角图像需要把新信息并入现有模型二是第一次训练只跑了 10000 步想在保留已有结构的基础上继续补细节。要注意的是加载点云后密度控制会从头开始计数你可能需要把--densify_from_iter调小一点否则加载的模型在前几百步里不会新增点。最近社区里还有很多衍生方案比如 3DGS-ppisp 把渲染分解成近景和远景两个阶段解决了场景深度跨越太大时的质量问题SIGMA 则用硬件混合渲染来做远近视角的过渡。这些都是在官方部署框架基础上做的优化建议先把基础版跑通再按需去研究衍生的渲染管线。5. 常见问题与排查技巧实录5.1 问题速查表把这段时间遇到的高频问题整理成了一张速查表按出现频率排序问题现象直接原因解决办法编译子模块时报错No such file or directory子模块未拉取完整git submodule update --init --recursive训练中CUDA out of memory场景点云过多或图像分辨率过高降低--sh_degree、缩小输入图片、用--iterations减少总步数train.py报找不到cameras.bin目录结构不对或 COLMAP 没跑完确认sparse/0下三个 bin 文件存在渲染结果大片黑色空洞稀疏重建质量差初始点云缺失重新采集数据增加重叠率检查 COLMAP 输出画面闪烁、重影SH 阶数过高或学习率不合适降低sh_degree检查位置学习率训练始终不收敛loss 不降图像间曝光差异太大统一曝光关闭自动白平衡5.2 排查思路与避坑心得遇到问题先别急着改代码。我的排查顺序是先确认 COLMAP 重建是否正常再确认训练日志里 loss 是否持续下降最后才检查渲染结果。很多人一上来就调训练参数结果数据源就是脏的等于白忙。这里分享几个文档里不会写的经验。第一COLMAP 重建完一定要打开稀疏点云看一眼哪怕是用 COLMAP GUI 拉一下视角如果点云稀稀拉拉或者有大片空洞后面 3DGS 怎么训都补不回来。第二训练的初始迭代阶段大概前 1000 步渲染画面会很粗糙这是正常的别在中途停下来判断效果建议至少等 5000 步再去看中间结果。第三如果场景里有大量相似纹理比如草地、砖墙、地毯COLMAP 很容易匹配错位可以考虑在feature_extractor时把--SiftExtraction.max_num_features调大或者用已知相机参数的方式跳过 COLMAP 直接训练。关于显存紧张的问题我有一个实测有效的技巧把训练数据里的images文件夹做一次批量缩放短边压到 1280 或 1600。这个操作对最终渲染质量影响很小但显存占用能下降 30% 以上。很多人舍不得压分辨率其实 3DGS 在 1600px 下已经能出非常细腻的细节再往上多的主要是存储和算力成本。5.3 多场景并行训练的经验补充如果是团队项目需要同时对多个场景做训练我建议每个任务单独开一个 conda 环境或者至少用不同的输出目录。官方代码在保存中间结果时不会自动加时间戳两个任务共用输出目录会互相覆盖。另外如果条件允许可以在训练脚本外面套一层nohup或者用 tmux 管理会话避免 SSH 断连导致训练中断。我试过直接挂后台三天没关机的训练任务跑了 6 个场景没有任何异常稳定性还是可以的。多场景并行还有一个收益点可以把 COLMAP 重建好的数据预先转换好等到要用时直接开训省掉每次重新跑 SIFT 的时间。特别是图像多的数据集COLMAP 特征提取这一步往往比训练本身还耗时。写在最后的实操心得我个人在实际操作中的体会是3DGS 的部署难度其实不高真正的门槛在于“数据采集”和“参数理解”。我第一次跑通官方示例花了整整一天其中大部分时间消耗在 Windows 编译和 CUDA 版本匹配上剩下的时间都浪费在不合格的拍摄数据上。后来改成先拿官方提供的tandt数据集验证环境再拍自己的场景整个流程就顺畅很多。最后再分享一个小技巧训练完成后渲染视频时不要只盯着 PSNR 指标看一定要用 SIBR 查看器或者自带的render.py生成一段新视角视频肉眼观察有没有“气泡感”和“抖动”。数值指标高但在新视角上穿帮的情况我见过太多次了。如果发现穿帮优先检查相机位姿和稀疏点云密度这两个是最基础也是最关键的环节。本文还有配套的精品资源点击获取