简介面向开发者与3D重建研究者的3DGS部署训练源码资料包整理作者在Python 3.10CUDA 12.3PyTorch 2.2.1环境下的实战过程帮助读者绕开官方推荐配置限制掌握3D Gaussian Splatting的部署、训练与数据处理链路。压缩包共3个文件以HTML说明页、.inscode配置入口和.gitignore工程管理文件为主整体仅7KB体积轻量但信息密度高。目前已有200人学习适合刚接触3DGS的开发者作为“踩坑笔记”对照使用也可用于教学演示或个人项目验证。从环境配置到训练落地内容具体涉及NVIDIA GPU下的CUDA环境配置、NumPy/OpenCV等依赖的逐项安装、预训练数据的调用与结果查看、自备图片数据的训练流程以及视频抽帧、数据转换等实用技巧能够帮助读者规避版本兼容性和数据格式相关的常见问题。对希望快速上手3DGS并开展自定义实验的研究者来说可提供从环境准备到训练调优的完整参照将方法直接落地到实际项目中。 这段时间我把 3DGS3D Gaussian Splatting的部署和训练在本地完整跑通了一遍从源码克隆、环境编译到用自己的照片数据集训练出可实时渲染的三维场景中间踩了不少文档里根本不会写的坑。3DGS 这两年确实火核心思路是用一堆带透明度和协方差的 3D 高斯分布来表示场景再通过可微光栅化完成实时渲染效果上跟 NeRF 接近但训练速度和推理效率都要快得多。如果你正准备把 3DGS 用在自己的数据集上或者想在公司内网搭一套可复现的源码环境这篇指南应该能帮你省下至少两天的折腾时间。我不打算讲太多炫技的前沿理论只把源码部署和数据准备这两关讲透再把训练过程中的参数选择、报错排查和调优经验串成一套可以直接照做的流程。适合的人群很明确已经会一点 PyTorch想上手 3DGS但不想花一周去跟 CUDA 版本和 COLMAP 相爱相杀的同学。1. 项目定位与代码仓选型部署 3DGS 第一件事是选对仓库。官方实现是 graphdeco-inria/gaussian-splatting这也是大多数论文对比的 baseline代码结构清晰训练、渲染、指标评估三块都齐适合做深度学习与图形学交叉方向的学习和研究。社区里也有很多派生版本比如 nerfstudio 里的 splatfacto、gsplat 这种偏底层重写的实现各有优势但对第一次上手的人来说我强烈建议先用官方仓库。原因很简单你遇到问题去搜索时绝大多数解决方案都是针对官方仓库描述的版本对得上坑才填得上。社区仓库的优点是迭代快、接口灵活、能直接接自定义数据管线缺点是版本更新太频繁经常出现今天 clone 下来还能编明天就编译不过的情况。我见过太多人一上来就追新仓库结果 debug 了三天最后默默回退到官方版本。所以这篇所有命令都基于官方仓库后面再单独聊什么时候值得切换到社区实现。1.1 官方仓库还是社区仓库这里要强调一个容易误判的地方官方仓库不是 pip install 就完事的它自带两个需要本地编译的 CUDA 扩展——diff-gaussian-rasterization 和 simple-knn。这也是整个部署过程中最容易翻车的部分。源码层面至少要理解到这个程度训练时要把 3D 高斯分布“铺”到 2D 图像平面这个投影和光栅化过程必须可微PyTorch 原生实现太慢所以作者用 CUDA 写了一个并行光栅化器让每个像素能并行累积高斯分布的颜色与不透明度。理解这一点之后你看到“编译 CUDA 扩展报错”就不会慌因为问题通常集中在 CUDA 版本、显卡算力和编译器配置这三件事上。1.2 源码目录速览克隆下来之后核心目录大概长这样arguments/所有命令行参数的定义训练、渲染、网络结构相关参数都在这。scene/场景管理包括数据集读取、高斯模型初始化、相机参数封装。gaussian_renderer/渲染主流程调用光栅化器前向传播在这完成。utils/图像、图形、相机、通用工具函数。train.py训练入口自适应密度控制逻辑在train()里不断循环。render.py/metrics.py推理渲染和指标评估。这个结构属于典型的“小而精”科研项目模板没有复杂业务分层读起来不累。我建议你训练之前先花半天把 train.py 和 scene/gaussian_model.py 过一遍后面调参时你会感谢自己这个习惯。很多参数真实作用在哪一行代码直接看源码比看任何文档都准。2. 部署三步走环境、依赖与本地编译部署 3DGS 本质上是在解决三件事驱动和 CUDA 能不能对上、Python 依赖能不能装上、两个 C 扩展能不能编译通过。我一开始也觉得这东西麻烦实际拆开看每一步都不复杂但顺序错了就会连环报错。2.1 CUDA/PyTorch 版本怎么搭配我这台机器是 Ubuntu 22.04、RTX 4090、驱动 545最后跑稳的搭配如下组件版本操作系统Ubuntu 22.04显卡驱动545.xCUDA Toolkit11.8conda 安装Python3.9PyTorch2.0.1 cu118这套组合在最近两年被验证了很多次稳定性很高。有一个容易混淆的点系统装的是显卡驱动PyTorch 自带的是自己的 CUDA 运行库两者不需要严格一致关键是要保证驱动版本足够新能兼容 PyTorch 用的 CUDA 版本。如果用 CUDA 12.x 和更新的 PyTorch 理论上也能跑但注意环境文件里的 cuda-toolkit 版本要和 PyTorch 构建版本对齐否则编译扩展时经常出现nvcc找不到或 ABI 不匹配的问题。2.2 conda 环境与 Python 依赖官方仓库的 environment.yml 能装大部分依赖但有两个常见问题conda 下载太慢以及 PyTorch 装出来是 CPU 版。我习惯先建环境再手动装关键依赖每一步都可控conda create -n gaussian_splatting python3.9 -y conda activate gaussian_splatting conda install -c nvidia cuda-toolkit11.8 -y pip install torch2.0.1cu118 torchvision0.15.2cu118 --extra-index-url https://download.pytorch.org/whl/cu118 pip install plyfile tqdm submodules/diff-gaussian-rasterization submodules/simple-knn这里直接通过 pip 把两个子模块一起装了比传统pip install -e .少很多后顾之忧。装完跑一下自检python -c import torch; print(torch.cuda.is_available()); print(torch.version.cuda) python -c import diff_gaussian_rasterization; print(rasterizer ok)如果第一行输出 True、第二行正常打印部署基本就完成了。2.3 两个 C 扩展必须编译通过编译失败最常见的三个原因CUDA_HOME没有指向你要用的 CUDA Toolkit 路径导致 nvcc 用错版本。系统缺少基础编译工具比如 g、make需要先执行sudo apt install build-essential。GPU 架构不匹配。如果你用 RTX 40 系列默认编译参数可能没包含对应的 SM 版本需要在扩展目录的setup.py里把arch列表改成显卡算力。我自己踩过的比较典型的问题是 conda 环境里同时存在多个 CUDA toolkitnvcc 和 PyTorch 内部用的 CUDA 不一致。最后我把 conda 环境里的 CUDA 路径显式 export 到CUDA_HOME才解决。经验是不要在同一环境里混装多个 CUDA 版本这是给自己挖坑。3. 数据准备COLMAP 重建决定训练上限3DGS 训练不是直接读照片就完事它需要先从图片里用 COLMAP 跑出稀疏点云和相机位姿作为高斯的初始位置和观测视角。这一步说是预处理其实直接决定了训练结果的上限。照片质量不行后面调再多参数也救不回来。3.1 拍摄照片时的采集要点我拍照时主要盯三件事重叠率、光照变化、固定曝光。相邻照片重叠率尽量在 60%-80%太低了特征点匹配会失败。场景里不要出现大面积高光、镜面反射或者玻璃窗这对 SfM 是灾难级噪声。尽量固定曝光和白平衡如果照片亮度忽明忽暗训练出来的高斯颜色会发灰PSNR 很难超过 18。也有人用视频抽帧代替拍照可行但抽帧太密会导致视角几乎完全相同反而让 COLMAP 匹配失效。我建议连续帧之间至少间隔 2-3 个关键视角让画面有明显位移。3.2 用官方脚本一键生成 SfM 数据官方仓库提供一个convert.py脚本会自动把data/xxx/input下的图片处理成 COLMAP 能识别的目录结构python convert.py -s data/your_scene它会自动完成特征提取、匹配、稀疏重建并在data/your_scene下生成sparse/0、images、distorted等目录。这里有个很多人都会踩的坑脚本要求输入图片放在data/your_scene/input而 train.py 的-s参数指向的是data/your_scene两者不要搞混。3.3 手动跑 COLMAP 的命令流如果你对 COLMAP 的默认参数不放心也可以手动跑mkdir -p data/your_scene/images colmap feature_extractor --database_path data/your_scene/colmap/database.db --image_path data/your_scene/images colmap exhaustive_matcher --database_path data/your_scene/colmap/database.db mkdir -p data/your_scene/colmap/sparse colmap mapper --database_path data/your_scene/colmap/database.db --image_path data/your_scene/images --output_path data/your_scene/colmap/sparse跑完把生成的sparse/0放到 train.py 期望的位置即可。判断重建质量的标准很直接稀疏点云越均匀、越密集3DGS 初始化高斯的底子越好。如果重建出来的点云断裂严重或者相机位姿明显漂移最简单的解决办法是回头补拍照片而不是硬调参数。3.4 数据目录结构说明最终有效的数据目录结构如下data/your_scene/ ├── input/ │ ├── 00001.jpg │ └── ... ├── images/ │ └── (convert.py 生成的同名图片) ├── sparse/ │ └── 0/ │ ├── cameras.bin │ ├── images.bin │ └── points3D.bin └── distorted/sparse/0里存着相机内参、每张图的外参和稀疏点云是训练真正读入的数据。这个目录结构熟悉之后切换场景就很简单把不同场景的目录名换一下就能复用同一套训练流程。4. 训练实操命令行、损失函数与自适应密度控制4.1 启动训练的完整命令部署和数据都准备好后训练本身只有一行命令python train.py -s data/your_scene -m output/your_scene如果你只想先验证数据链路通不通可以缩短迭代python train.py -s data/your_scene -m output/your_scene --iterations 5000 --test_iterations 5000 --save_iterations 5000--test_iterations表示每多少步做一次测试渲染--save_iterations表示在哪些迭代步保存模型。输出会在output/your_scene/point_cloud/iteration_5000/下生成 PLY 点云文件这个就是最终产物。4.2 核心参数的含义与调试方向3DGS 的命令行参数集中在arguments/__init__.py我列一下最值得关注的一组参数默认值作用--iterations30000总训练步数常规场景 30k 足够--sh_degree3球谐阶数越高视角相关效果越强显存越大--densify_grad_threshold0.0002高斯点梯度阈值超过则触发分裂或克隆--densify_until_iter15000自适应密度控制在第 15000 步后关闭--opacity_reset_interval3000每 3000 步重置不透明度防止局部过度累积--lambda_dssim0.2DSSIM 损失权重--position_lr_init0.00016高斯位置学习率初始值训练开始后高斯点数量会经历一次明显的“爆发式增长”。我用一个 8 万稀疏点云的场景跑5000 步时点数量涨到约 40 万之后被剪枝和重分配最后收敛在 25 万左右。这个变化是自适应密度控制在正常工作不是 bug。显存紧张时可以把--sh_degree降到 2视觉效果差别不大但显存和训练时间都能明显下降。4.3 训练输出日志与指标解读训练过程中会打印每个测试迭代的 PSNR并在输出目录生成测试图片和深度图。很多人只盯着 PSNR忽略深度图但深度图能直接反映高斯几何是否合理排查伪影时特别有用。我判断训练是否正常有三个经验指标前 1000 步 PSNR 快速上升到 20 以上说明相机位姿和初始化基本正确。3000 步以后 PSNR 增长放缓但每 3000 步仍有小幅上涨属于正常。如果 PSNR 到了 30但新视角图仍然闪烁问题多半出在球谐阶数或深度排序上不是单纯加迭代次数能解决的。5. 常见问题与调优实录5.1 高频部署报错速查表错误表现原因解决方向No module named diff_gaussian_rasterizationC 扩展没有编译成功检查 CUDA_HOME重新 pip install 扩展nvcc fatal: Unsupported gpu architecture显卡架构不匹配在扩展 setup.py 里加入对应 arch 编号比如 89 对应 RTX 40 系训练时显存直接 OOM图像分辨率或高斯数量过高降低 sh_degree、减小输入图像尺寸COLMAP 匹配到很少的点图片重叠率不够或反光严重重新采集照片增加连续视角重叠输出 PLY 但渲染全黑相机参数和图片没配对检查 sparse/0 目录里的相机内参是否和图片一致5.2 训练后 PSNR 低的排查思路PSNR 低的时候不要第一时间怀疑训练参数先按顺序排查照片有没有对齐、场景里有没有动态物体或大范围遮挡、曝光是否统一。我做过一个室内小物件PSNR 始终只有 16 左右找了一圈发现是拍照时窗外阳光移动导致不同照片的光照不一致。重新拍摄后 PSNR 直接到 27。这个例子很能说明问题预处理阶段对训练结果的影响比后期调参大得多。5.3 渲染伪影与远近排序问题3DGS 光栅化本质是把所有高斯点按深度排序后做 alpha 混合所以“远→近绘制”的顺序非常关键。如果渲染图里出现远处物体边缘被近处高斯污染或者半透明物体出现奇怪的“泡泡感”多半和排序有关。我踩过的另一种情况是场景中远处区域比如天空或背景高斯点数量不够只能用稀疏的大高斯点表达远看还行镜头稍微靠近一点就有明显的“果冻状”抖动。解决办法是适当延长--densify_until_iter到 20000 步让远处区域有更多机会补充细节。缺点是训练时间会拉长但画面质量提升值得。6. 进阶把 3DGS 接入更复杂的渲染管线6.1 从训练好的 PLY 到自研渲染器训练结束后得到的point_cloud.ply里存了每个高斯点的位置、协方差、颜色和球谐系数。如果你要在自己的渲染器里使用不能像普通点云一样直接画点必须用 3DGS 的光栅化或射线追踪方式渲染每一帧。需要先想清楚输出目标只做静态场景展示官方 render.py 或社区的实时 viewer 足够。要接进 Web 前端需要把高斯参数转成浏览器端能解析的格式社区有很多 three.js 实现。要对接自己的图像信号处理链或后处理必须把深度图、alpha 图一起导出不能只导出 RGB。有人会在找资料时看到很多和管线集成相关的缩写或封装名称核心诉求其实都一样不要让渲染停在“出一张图”而是把深度、alpha、法线这些中间结果暴露出来给后面的处理链路用。6.2 硬件加速下的远→近混合绘制思路如果场景规模很大比如城市级数字孪生纯 3DGS 全量渲染的压力会非常大。我最近在看一种思路近处区域用传统网格或体素渲染保证清晰度远处区域用 3DGS 的非结构化高斯表示负责连续性和实时性中间用一段距离衰减的融合带连接两套数据。具体做法上如果你的渲染器支持硬件光栅化可以把近处场景的高斯点光栅化成常规三角形网格远处高斯点按远→近顺序做 alpha 混合最后用深度缓存合成。过渡带不要硬切我会按距离衰减设置一个权重 mask一般从 5 米到 15 米具体看场景尺度。这里最大的难点就是排序问题两套数据在同一像素上的深度关系必须一致否则会出现明显的接缝和闪烁。这个方法做起来需要对 rasterizer 做不少改动适合已经跑通官方训练、想往工程落地的同学继续研究。6.3 后续可以做的扩展方向如果你已经能把官方代码跑通我建议按难度依次尝试先换一个完全不同尺度的场景比如从室内小物件换到室外街道感受密度控制和球谐阶数在不同尺度下的表现再把训练好的模型接进实时渲染框架体验部署环节的工程坑最后可以换 splatfacto 或 gsplat 做横向对比看看同一份数据在不同实现下的效果和时间差别。最后分享一个我自己的习惯3DGS 部署训练最大的门槛其实不是代码而是环境一致性。源码版本、COLMAP 版本、CUDA 版本这三个只要有一个对不上后面就会出现各种玄学报错。我在排查问题时做过最有用的一件事就是把全链路版本号用文本记下来换机器时照着复现。这个习惯看似土实际帮我省掉的 debug 时间是最多的。本文还有配套的精品资源点击获取