1. 项目概述Gaussian Splatting在玩什么搞过三维重建或者NeRF的朋友最近应该被3DGS3D Gaussian Splatting高斯泼溅刷屏了。这玩意儿从2023年火到现在核心思路很直接用一堆带颜色和透明度的3D高斯函数去表达一个场景再配合一套可微分的光栅化流程把图像从任意视角渲染出来。相比传统NeRF那种逐点查询体渲染的方式3DGS在训练速度和渲染质量上的优势非常明显尤其是实时渲染这一块普通消费级显卡就能跑出流畅的交互帧率。不过想亲手把3DGS跑起来环境搭建是绕不开的第一道坎。这个项目涉及CUDA、PyTorch、COLMAP、C扩展编译一整套链路任何一个环节版本不匹配都可能让你卡在某个报错里出不来。尤其对于第一次接触这类项目的新手来说光是“环境搭建”这四个字里就藏着不少暗坑。这篇文章是我自己从零开始搭建3DGS环境、跑通官方Demo、再拿自己的数据做重建的完整记录。不仅会把每一步操作写清楚还会解释为什么这样选型、哪些地方容易踩坑、遇到了报错要怎么排查。不管你是想复现官方结果还是准备拿自己的照片试试水照着这篇文章走一遍应该能省下不少折腾时间。2. 环境搭建前的思路拆解先把依赖关系理清楚2.1 这套技术到底依赖哪些核心组件3DGS不是那种“装个包就能跑”的纯Python项目它的核心渲染器是用CUDA和C写的扩展模块必须本地编译。这就决定了整个环境搭建的复杂度不仅要有Python环境还要有CUDA工具链而且CUDA和PyTorch版本必须互相匹配否则编译直接失败。整个依赖链条大致是这样的Python环境项目基于Python编写官方推荐用虚拟环境管理避免污染系统环境。PyTorch作为深度学习框架负责网络训练和自动求导。PyTorch内部依赖CUDA运行时。CUDA工具链包括nvcc编译器和CUDA Runtime Library。用于编译项目自带的CUDA扩展。C编译器在Windows上是Visual Studio的MSVC在Linux上是GCC。用于编译C部分代码。COLMAP用于从多张图片中恢复相机位姿和稀疏点云。3DGS需要它作为前置数据处理工具。项目本体从GitHub克隆的gaussian-splatting仓库包含训练、渲染、网络结构定义和可微分光栅化器。理解了这套依赖关系你就能明白为什么环境搭建容易出问题——任何一个组件的版本不对整个链条就断了。提示最省心的方式不是“用最新版本”而是“用作者验证过能跑的版本组合”。在这方面Linux环境通常比Windows省心不少很多坑我在后面会详细说。2.2 方案选型Linux还是WindowsGPU怎么选先说结论建议优先用LinuxUbuntu 20.04或22.04做开发环境。原因有三点第一COLMAP在Linux上的安装方式更丰富既可以用conda直接装也可以自己编译还可以下载现成的appimage。Windows上虽然也有GUI版本但命令行调用和自动化脚本的兼容性差点意思。第二CUDA扩展的编译在Linux上更顺畅。Windows用户需要额外安装Visual Studio并且必须确保VS版本、CUDA版本、PyTorch版本三者兼容这个组合问题的排查难度比Linux高不少。第三不定期拿服务器训练的话服务器基本都是Linux本地先把这套流程跑通迁移起来没有心理负担。当然Windows也不是完全不能跑官方仓库在Windows上是有成功案例的只是需要额外处理Visual Studio环境变量、CUDA_HOME配置等细节。如果你的机器只有Windows也不用灰心后面的实操部分我也会单独说明Windows下的注意事项。GPU方面训练3DGS的显存需求不算太夸张。官方推荐的场景分辨率下约4K到8K级别的输入图片单卡显存在12GB以上会比较从容。如果显存只有8GB可以通过调整图片分辨率、缩小训练迭代次数来跑但效果会打折扣。另外NVIDIA显卡是必须的因为CUDA扩展不支持AMD或Intel显卡。2.3 版本组合的“黄金搭配”参考根据我实际测试和社区里的大量反馈下面这套版本组合是目前稳定性最高的搭配之一组件推荐版本说明Ubuntu20.04 / 22.04 LTS20.04更稳22.04也能用Python3.8 / 3.9 / 3.103.9是我用得最顺的CUDA11.8PyTorch支持最成熟的版本之一PyTorch2.0.0 cu118官方在2.0版本上测试较多COLMAP3.8建议源码编译或conda装最新版GCC7.5 / 9.4Ubuntu自带版本即可不要盲目上CUDA 12.x或者PyTorch 2.1除非你确定官方仓库的submodulediff-gaussian-rasterization和simple-knn在新版本下能正常编译。很多时候问题就出在“我用了最新的CUDA”上结果编译的时候一堆内部API变了网上连报错都搜不到几条。3. 核心细节解析与实操要点逐层拆解关键环节3.1 第一步准备基础环境以Ubuntu为例拿到一台干净的Ubuntu机器后先把系统自带的Python环境确认一下python3 --version pip3 --version如果Python版本低于3.8建议先升级或安装新版本。这里我推荐直接用conda管理环境一劳永逸wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh source ~/.bashrc安装完conda后创建一个独立的虚拟环境conda create -n gaussian_splatting python3.9 conda activate gaussian_splatting这时候你的环境就相当于一个“隔离房间”了后面装什么都不会影响系统自带的Python。这个习惯极其重要尤其是当你的机器上还有别的深度学习项目时避免互相踩版本。3.2 第二步安装CUDA和PyTorch版本必须匹配很多新手在这一步就开始踩坑了。记住一个核心原则PyTorch的CUDA版本和本机安装的CUDA版本不一定非要完全一致但必须互相兼容。确切说PyTorch是自带CUDA runtime的只要本机的NVIDIA驱动足够新哪怕你只装了CUDA 11.8的toolkit也能跑PyTorch的cu118版本。但我个人的建议是保持两者一致始终是最省心的。安装CUDA 11.8的步骤wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run安装过程中注意不要选择安装驱动前提是NVIDIA驱动已经就位只安装CUDA Toolkit即可。安装完成后配置环境变量export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH接着安装匹配的PyTorchpip install torch2.0.0 torchvision0.15.0 --index-url https://download.pytorch.org/whl/cu118装完后用下面这段代码验证CUDA是否可用import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果输出True和你的显卡型号说明PyTorch层没问题了。注意LD_LIBRARY_PATH这个环境变量在后续编译CUDA扩展时很关键如果缺失会报找不到libcudart.so之类的错误。3.3 第三步安装COLMAP处理图片全靠它COLMAP是3DGS训练流程中的前置依赖作用是从一组普通照片里恢复出每张照片对应的相机内外参数同时生成场景的稀疏点云。这个点云在训练时会作为3D高斯的初始位置所以COLMAP的安装质量直接影响后续训练效果。Linux下安装COLMAP我用的是conda方案简单省事conda install -c conda-forge colmap但这个方案偶尔会出现版本太老或者预编译包不兼容的问题。如果conda装好后执行colmap -h报错可以考虑源码编译。源码编译稍微麻烦一点需要先安装一堆依赖sudo apt-get install -y \ git cmake build-essential \ libboost-program-options-dev libboost-filesystem-dev \ libboost-graph-dev libboost-system-dev \ libeigen3-dev libflann-dev libfreeimage-dev \ libmetis-dev libgoogle-glog-dev libgtest-dev \ libsqlite3-dev libglew-dev libqt5opengl5-dev \ libcgal-dev libceres-dev然后克隆源码并编译git clone https://github.com/colmap/colmap.git cd colmap mkdir build cd build cmake .. -DCMAKE_CUDA_ARCHITECTURESnative make -j$(nproc) sudo make install编译时间取决于机器性能一般十几分钟到半小时不等。装好后验证colmap -h看到帮助信息输出就说明安装成功了。3.4 第四步克隆3DGS项目并安装子模块官方仓库地址是graphdeco-inria/gaussian-splatting克隆时注意一定要加上--recursive参数否则子模块是空的git clone https://github.com/graphdeco-inria/gaussian-splatting.git --recursive cd gaussian-splatting项目根目录下有三个关键组成部分train.py训练入口脚本render.py渲染脚本用训练好的模型生成新视角图像submodules/diff-gaussian-rasterization核心的CUDA光栅化器也就是整个项目性能的关键所在submodules/simple-knn用于计算每个高斯点的KNN邻居同样包含CUDA扩展这两个子模块都需要本地编译。不过3DGS官方提供了一个environment.yml文件可以直接用conda创建环境conda env create --file environment.yml conda activate gaussian_splattingenvironment.yml里已经写好了PyTorch和CUDA的版本如果你用的是干净机器直接用这个文件是最省心的。但如果你像我一样已经手动创建了环境也可以继续用已有的环境只需手动安装剩余依赖pip install plyfile tqdm接着编译子模块。官方仓库里其实已经提供了编译命令手动进到对应目录执行也行cd submodules/diff-gaussian-rasterization pip install . cd ../simple-knn pip install .如果编译成功你会看到类似Successfully installed diff-gaussian-rasterization的输出。这一步是环境搭建里最容易出问题的后面第5章我会集中讲报错排查。4. 实操过程与核心环节实现从训练到渲染的完整链路4.1 下载官方测试数据快速验证环境环境搭好了先别急着自己的数据用官方提供的预处理数据集验证整个流程是否通畅。官方数据集地址在项目的README.md里有链接比如经典的truck、garden这些场景。下载后解压到项目目录下比如mkdir -p data/ # 解压下载的数据集到 data/truck 目录数据集的结构大致是这样的data/truck/ ├── images/ # 原始图片 ├── sparse/ # COLMAP输出的稀疏重建结果 │ └── 0/ │ ├── cameras.bin │ ├── images.bin │ └── points3D.bin ├── train_test_split.json # 训练和测试划分 └── ...可以看出官方数据集已经帮你跑好了COLMAP直接就能训练。4.2 训练模型理解关键参数的含义训练命令非常简单python train.py -s data/truck -m output/truck其中-s指定数据集的路径-m指定模型输出目录。训练过程中屏幕上会不断输出loss值、PSNR等指标同时每隔一段迭代就保存一个.ply点云模型文件。如果一切顺利训练过程中你还能看到当前重建场景的实时可视化窗口。默认是用OpenCV的窗口来显示渲染结果和深度图按下回车键可以继续训练。这里有几个核心参数值得琢磨一下--iterations总训练轮数默认是30,000。增加迭代可以让模型更精细但会显著增加训练时间。--save_iterations指定在哪些迭代节点保存模型。默认会在7,000、30,000等节点保存。--resolution渲染分辨率倍数。默认是1.0如果显存不足可以设成2.0即每边分辨率减半。--sh_degree球谐函数的阶数默认是3。阶数越高颜色表现越丰富。训练完成后输出目录下会生成point_cloud.ply、cameras.json等文件。其中point_cloud.ply就是最终的场景模型它是由几十万到上百万个3D高斯点组成的每个点包含了位置、颜色、旋转、缩放、透明度等属性。4.3 自己采集数据COLMAP全流程实操自己拍照片做重建才是3DGS真正有趣的地方。流程不复杂但有几个细节要注意。第一步拍摄。围绕目标物体或场景从不同角度密集拍摄照片。建议保证相邻照片之间有足够的重叠度60%以上拍摄时保持光照稳定避免运动模糊。数量上一个简单物体大概50-100张大型场景可能需要200-400张。第二步用COLMAP重建相机位姿。这是最关键的步骤。先创建一个项目目录比如my_data/把照片放在my_data/images/下。接着依次执行三个命令colmap feature_extractor --database_path my_data/database.db --image_path my_data/images这一步是特征提取会在每张图里找关键点和描述子。colmap exhaustive_matcher --database_path my_data/database.db这一步是特征匹配找出哪些图片之间有共同的特征点。如果图片数量特别多比如500张以上可以考虑用sequential_matcher替代exhaustive_matcher速度更快但匹配质量略有下降。mkdir -p my_data/sparse colmap mapper --database_path my_data/database.db --image_path my_data/images --output_path my_data/sparse这一步是稀疏重建输出相机参数和稀疏点云。如果输出目录下出现了0/子文件夹里面有cameras.bin、images.bin、points3D.bin三个文件说明COLMAP处理成功。三个文件分别是相机内参、图像位姿、三维点云的信息。第三步数据整理。为了让3DGS训练脚本能正确读取需要把数据组织成和官方数据集一样的结构my_data/ ├── images/ # 原始图片 └── sparse/ └── 0/ # COLMAP输出还有一个特殊情况官方仓库里提供了一个convert.py脚本可以帮你自动把COLMAP的文本格式.txt转成二进制格式.bin。如果你不想自己跑COLMAP命令行的每一步直接运行python convert.py -s my_data它会自动完成特征提取、匹配、稀疏重建以及格式转换的全流程。4.4 用训练好的模型渲染新视角训练完成后渲染很简单python render.py -s data/truck -m output/truck渲染脚本会读取模型输出目录下的配置文件生成每个测试视角的渲染图像存放在output/truck/test_preds等目录下。除了RGB图通常会一并输出深度图和法线图。这里要说一下3DGS和传统网格重建的本质区别。传统三维重建比如用COLMAP生成的点云出来的是一堆散点不连续、没色彩细腻度。3DGS生成的则是一个“可微分场景表示”它不是一个网格而是大量带光学属性的三维高斯分布。你可以像玩游戏一样实时旋转这个场景体验大场景漫游的快感。如果配上实时渲染的GUI工具交互帧率轻松上百。4.5 性能调优如何在有限显存下训练如果你的显卡只有8GB显存场景分辨率又比较高训练时很容易OOM显存溢出。我实测有效的几个思路缩小输入分辨率是最直接的手段。在训练命令中加入--resolution 2相当于把图片边长缩小一半显存占用会降到原来的四分之一左右。代价是重建质量会有所下降但如果只是做验证性实验完全够用。减少最大迭代数也能缓解。把--iterations从30,000降到15,000显存压力小很多而且很多简单场景在15,000次迭代时已经收敛得很不错了。直接用官方数据集里的低分辨率版本练手等流程完全跑通后再上自己的高分辨率数据。5. 常见问题与排查技巧实录5.1 子模块编译失败的几种典型情形编译diff-gaussian-rasterization时最常见的报错是找不到CUDA相关的头文件或库。错误信息里通常会出现fatal error: cuda_runtime.h: No such file or directory原因基本就是CUDA_HOME环境变量没有配置或者/usr/local/cuda符号链接没有指向已安装的CUDA版本。解决方法是export CUDA_HOME/usr/local/cuda-11.8 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH重新加载环境变量后再执行pip install .。还有一种情况报错信息里出现了undefined symbol或GLIBCXX字样这往往说明系统的GCC版本和PyTorch编译时使用的GCC版本不一致。这时候可以试试用conda安装一个较新的GCC环境conda install -c conda-forge gcc_linux-64 gxx_linux-64然后再重新编译。5.2 训练时维度不对的报错训练刚开始就报RuntimeError: The size of tensor a (X) must match the size of tensor b (Y)多半是COLMAP产生的点云数量不够或者输入图片尺寸不一致。我的经验是回看COLMAP输出结果看看sparse/0下三个.bin文件是否正常生成尤其points3D.bin的文件大小是否合理。如果点云文件太小几十KB说明COLMAP稀疏重建失败了需要重新检查图片质量。5.3 显存不足的临时解决方案训练过程中出现CUDA out of memory第一反应是检查其他进程有没有占显存nvidia-smi如果有其他训练任务在跑先释放显存。如果只有自己这个任务就按4.5节说的方法降低分辨率。这里有一个很实用的技巧改用更小的测试场景先跑通全流程比如官方数据集里较小的场景用来验证环境成功后再上大场景效率最高。5.4 COLMAP无特征点的坑自己拍照跑COLMAP时如果匹配结果一直不好最常见的原因是图片纹理太单一。比如拍一面白墙或者面无表情的合影特征点少得可怜导致重建失败。解决办法有给场景增加一些有纹理的物体比如纸箱、海报或者在拍摄时加入一些物品作为“锚点”。如果拍的是纯色物体且无法添加纹理就只能用更依赖深度传感器或其他方式的方案了不在3DGS的常规流程里。5.5 Windows环境下的特殊处理Windows用户如果想跑3DGS有几个点必须提前准备安装Visual Studio 2019或2022确保C桌面开发组件齐全。VS版本必须与CUDA版本兼容CUDA 11.8建议VS 2019CUDA 12.x建议VS 2022。在系统环境变量中手动设置CUDA_HOME路径指向CUDA安装目录。用x64 Native Tools Command Prompt来跑pip install确保编译时能找到MSVC编译器。Windows下踩坑概率最高的就是VS和CUDA版本匹配如果报错信息里出现了cl.exe相关的字样基本都是这个原因。5.6 训练产出的模型为什么有“雾感”很多新手第一次训练完渲染出来的图像看起来像隔着一层薄雾颜色发白。这大概率是因为背景部分没有完全被高斯覆盖或者在采集照片时背景有大量天空区域。COLMAP重建这类场景时远景部分本来就稀疏3DGS在高斯初始化时不够充分就会出现这种朦胧感。处理办法拍摄时尽量避免大面积的纯天空背景训练时把--sh_degree调低比如1或者2减少球谐函数阶数有时能缓解背景着色过度平滑的问题。如果场景本身有大量背景区域可以考虑在后处理时加一个掩码只重建前景物体。6. 优质数据集来源与效果评估标准6.1 公开数据集推荐除了官方仓库里的几个场景以下几类公开资源也值得尝试一些高校和研究所公开的Mip-NeRF数据集涵盖了多点视角高分辨率图片可直接用COLMAP重新处理。基于NeRF的合成场景数据集比如Blender风格的多物体场景适合理解3DGS在合成数据上的表现。倾斜摄影测量数据集无人机或手机拍摄的城市场景配合COLMAP效果好。不过要注意3DGS的输入是“一组多视角图片”不一定非要用官方格式。只要有images/和sparse/0/两个基本目录trainer就能启动。6.2 重建质量怎么评估训练结束后官方脚本会输出每个测试视角的PSNR值。PSNR虽然是一个传统指标但高不代表视觉效果好。更直观的评估方式渲染一张测试视角的图片对比真实照片看细节是否清晰、背景是否干净。实时交互模式下转动视角看是否有“空间撕裂”、重影或闪烁。这通常是高斯初始化不足或者训练不充分导致的。算力充足的情况下把训练迭代数从30,000加到50,000甚至100,000很多材质反射和细节会显著变好。代价是训练时间成倍增加。7. 总结与最终建议从我实际搭建3DGS环境到跑通全流程的经历来看最大的感受是环境搭建这件事一半靠版本匹配一半靠耐心调试。它不像普通Python库那样“装完即用”需要你对底层依赖链有一定的理解。如果你打算认真玩这个方向我的建议是初期直接用官方提供的数据集和训练脚本跑通流程不要一上来就折腾自己的数据。把Linux环境弄好遇到编译问题能省一半心。养成记录报错的习惯即便是常见报错不同环境下的细微差异也可能导致完全不同的解决方案。最后再分享一个小技巧。训练前把--iterations临时调低比如5,000快速跑一遍确认数据预处理和训练链路没问题再完整训练。我曾经在COLMAP数据格式转换这一步没处理干净直接跑到第9,000次迭代才发现白白浪费了几个小时。先小成本验证再全量投入既稳妥又高效。