3D Gaussian Splatting这阵子的热度一直没下来一句话概括给你一个场景的一组照片它能快速重建出一片支持实时渲染的三维高斯点云训练完可以直接在那个窗口里自由旋转视角看效果。很多人被官方的渲染效果吸引结果实际操作时卡在环境配置这一关。我自己前前后后在不同机器上配过七八次Windows和Linux都折腾过踩了不少坑。这篇东西就写给想快速跑通官方代码的读者尽量把每一步讲清楚包括为什么要这么配以及那些文档里不会写的避坑点。1. 配置前必须搞清楚的几件事1.1 项目本质与运行链路先说清楚这个项目跑起来到底需要什么。3D Gaussian Splatting官方仓库是graphdeco-inria/gaussian-splatting核心思路是用一组多视角照片先通过COLMAP做相机位姿估计再用可微的高斯光栅化做优化渲染最后得到一份可交互浏览的3D场景模型。为什么环境配置容易把人整崩溃因为它的依赖链条很长需要CUDA Toolkit、PyTorch、COLMAP、submodule里的diff-gaussian-rasterization和simple-knn这两个扩展模块Windows下还得配Visual Studio的MSVC编译器Linux下对GCC版本也有要求。这中间任何一个环节版本不对编译就挂。我见过太多人卡在“diff-gaussian-rasterization找不到”或者“编译时报错MSVC版本不对”。所以配环境之前一定要先理解你机器上要装哪些东西版本之间怎么匹配才能按顺序一步步来。1.2 硬件和系统的底线要求显卡必须支持CUDA这点没有商量余地。NVIDIA的RTX系列、GTX 10系以上都行但显存大小直接决定你能跑什么规模的数据。官方推荐24GB显存训练完整场景实际用下来8GB跑小场景、低迭代数也能出结果只是有些效果细节会妥协。系统方面Windows 10/11和Ubuntu 20.04/22.04是社区里用最多的。Windows下好处是驱动和CUDA的安装图形化操作直观坏处是MSVC编译偶尔出莫名其妙的坑Linux下编译相对顺利但驱动安装对新手不太友好。我自己的倾向是如果机器上已经装了COLMAP和CUDA相关的图形界面工具用Windows如果是新机器、纯服务器环境Ubuntu更省心。显存这块再强调一句训练过程中的峰值显存大约是把静态场景分成高斯基元后逐帧光栅化需要的开销场景越大、图像分辨率越高显存占用越大。如果你只有8GB建议把输入图片resize到1.6k以内迭代次数降到15k还是能看个大概效果的。1.3 版本组合的“黄金套餐”官方README其实给了推荐版本但我实际测下来最稳的一套组合是这样的组件推荐版本备选方案Python3.93.8或3.10也勉强可行但别用3.11CUDA Toolkit11.812.1/12.4需要改编译参数PyTorch2.0.1 / 2.1.0必须匹配CUDA版本Visual StudioVS2022含C桌面开发VS2019需要改工具集版本GCCLinux9.4及以上版本过低会报GLIBCXX错误为什么Python不能太新因为diff-gaussian-rasterization这个扩展模块是用C写的靠PyTorch的C扩展机制编译高版本Python环境里的ABI兼容性容易出问题。我自己在Python 3.10下编译通过过但PyTorch版本、MSVC版本必须跟它匹配一换就得重新试。2. 工具链与依赖分析为什么是它们2.1 Anaconda和Miniconda该选谁官方README建议用Miniconda但我个人建议如果你机器上没有现成的Python环境管理工具直接装Anaconda也挺好因为它自带了conda、Python、常用科学计算包新手省事。但如果你已经在用系统Python或者公司有统一环境规范Miniconda更轻量。核心原因是conda能创建隔离的虚拟环境。3DGS的依赖比较“娇气”跟其他深度学习项目的包很容易冲突。比如你之前装过PyTorch 1.x现在要PyTorch 2.x直接用pip升级可能把系统里其他项目搞崩。用conda建一个干净的env把3DGS的依赖全部锁在这个环境里出问题随时删掉重来不污染其他项目。检查是否已经有conda环境Windows下打开Anaconda PromptLinux下直接终端输入conda --version看输出。没装的话去官网下载对应系统的安装包一路默认安装即可。装完记得重新打开终端让环境变量生效。2.2 CUDA Toolkit和显卡驱动的关系很多人把显卡驱动和CUDA Toolkit混为一谈。简单类比显卡驱动是操作系统能识别显卡的“基础通道”CUDA Toolkit是给开发者用的“开发SDK”里面包含了编译器nvcc、CUDA运行时库、cuDNN等。你要编译和运行3DGS两者都需要。Windows上最容易出现的坑是驱动是最新的但没装CUDA Toolkit或者装了但环境变量没配好导致编译找不到nvcc。安装CUDA Toolkit时建议选自定义安装勾选CUDA、Development、Runtime这些核心组件其他不需要的组件可以不装。安装完成后验证一下Windows下打开cmd输入nvcc --versionLinux下同理。能输出版本号说明CUDA Toolkit装好了。如果提示找不到nvcc检查环境变量里有没有C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\binWindowsLinux下默认在/usr/local/cuda/bin。2.3 Visual Studio的MSVC编译器是硬门槛Windows下编译diff-gaussian-rasterization本质是用MSVC编译C代码然后通过PyTorch加载成Python扩展。所以你必须安装Visual Studio且必须勾选“使用C的桌面开发”工作负载里面那套MSVC工具链和Windows SDK都会被带上。VS2022和VS2019都行但要注意工具集版本。如果你用VS2019又装了个比较新的Windows SDK编译时可能报一堆晦涩的MSB错误。我自己用的VS2022 CUDA 11.8 PyTorch 2.0.1这套组合跑通过建议按这个来。Linux用户不用装Visual Studio但需要有C编译器和CUDA相关的工具链核心就是GCC和GUbuntu上一般默认装了。关键是版本如果GCC版本低于9编译ext模块的时候会报GLIBCXX或者OpenMP相关错误需要先升级编译器。3. 实操从零到一跑通3DGS3.1 下载源码这个坑必须提前避开官方仓库地址是https://github.com/graphdeco-inria/gaussian-splatting下载方式不是直接点Code按钮下载zip那样会缺少submodule。必须用git克隆并带--recursive参数git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting.git为什么必须带--recursive因为仓库里用了Git submodule来管理diff-gaussian-rasterization和simple-knn这两个模块在third_party目录下如果不拉下来后面编译一定会报找不到文件。如果你已经不小心用了git clone没有--recursive进目录执行git submodule update --init --recursive同样能补救。这个坑我在帮朋友排查时遇到过至少三次只要有一个人直接下载了zip包后面必然报错。3.2 创建conda虚拟环境并安装依赖进入项目根目录后先创建虚拟环境名字随意但Python版本建议用3.9conda create -n gaussian_splatting python3.9 -y conda activate gaussian_splatting然后安装PyTorch。这一步的关键是必须安装对应CUDA版本的PyTorch不能用默认的CPU版本。以CUDA 11.8为例pip install torch2.0.1 torchvision0.15.2 --index-url https://download.pytorch.org/whl/cu118这里需要解释一下为什么指定index-url。PyTorch官方默认推送的是CPU版本如果你直接pip install torch装出来的是不能用CUDA的后面跑训练会一直报CUDA unavailable。指定--index-url就是为了明确告诉pip去下载带CUDA支持的wheel包。版本号2.0.1和CUDA 11.8是经过社区大量验证的稳定组合不建议随意改。3.3 安装其他Python依赖官方提供了一个requirements.txt直接安装即可pip install -r requirements.txt里面包含submodules模块、open3d、pycolmap等依赖。但需要注意requirements.txt可能需要看git版本有些旧版本的requirements写法比较粗糙如果报错提示找不到某个包先看一下是不是Python版本问题。如果网络不好pip下载慢可以加清华镜像源加速pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple3.4 编译扩展模块最容易翻车的地方diff-gaussian-rasterization和simple-knn不是预编译的需要在本地编译成Python扩展。这一步是环境配置的核心难点Windows和Linux处理方式略有不同。Windows下不要直接双击运行正常cmd要打开“x64 Native Tools Command Prompt for VS 2022”这个终端会自动加载MSVC和Windows SDK的环境变量。创建好conda环境后在项目根目录下执行conda activate gaussian_splatting set DISTUTILS_USE_SDK1 python setup.py installset DISTUTILS_USE_SDK1这个命令很关键。它的作用是让Python的setuptools在编译时使用Visual Studio的SDK环境而不是尝试自己找一个编译器环境能避免很多“找不到C编译器”的报错。Linux下要简单一些conda activate gaussian_splatting pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn编译过程通常会输出一堆编译信息看到“Successfully installed”才表示成功。如果中途报错九成是CUDA路径没配好。确认一下系统环境变量里CUDA_HOMEWindows下是set CUDA_HOMEC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8Linux下是export CUDA_HOME/usr/local/cuda如果编译报“No such file or directory”这种错误大概率是CUDA_HOME设置了但路不对逐级检查一下。编译成功后最直接的验证方式是python -c import diff_gaussian_rasterization; print(diff_gaussian_rasterization.__file__)能打印出路径说明模块装好了。没报错才是真正的成功。3.5 准备数据COLMAP位姿估计的坑官方支持两种数据来源一是你自己采集的图片二是下载公开数据集如Mip-NeRF 360、Tanks Temples等。自己采集图片的话需要先用COLMAP做相机位姿估计官方脚本convert.py能自动调用COLMAP完成这件事。采集图片时注意几点图片分辨率控制在1.6k~2k左右太高的分辨率会显著增加显存占用和优化时间。场景光照尽量稳定避免过度曝光和过暗因为3DGS对初始化质量比较敏感。图片数量不用太多80~150张足够一个小场景但角度要覆盖全面避免有场景死角。拍摄时尽量保持相邻图片有60%~70%的重叠率COLMAP才能提取到足够的特征点。Windows用户需要单独安装COLMAP并加入环境变量Linux用户用apt安装也行。装好后测试一下colmap -h能输出版本信息说明COLMAP可用。有的小伙伴下载了COLMAP最新版但convert.py脚本里的调用接口变动导致报错建议用3.6~3.8版本。3.6 训练、渲染与评估一条龙数据准备好之后训练命令很简单python train.py -s data/your_scene -m output/your_scene其中-s指定数据路径-m指定输出路径。训练过程中会看到每100步打印一次PSNR等指标整个训练默认3万次迭代8GB显存大概需要1~3小时24GB显存会快不少。训练完成后生成的点云模型和参数文件在output目录下。执行渲染和指标评估python render.py -m output/your_scene python metrics.py -m output/your_scenerender.py会生成每个视角的渲染图metrics.py会计算PSNR、SSIM、LPIPS这三大评估指标。想看可视化效果Windows下可以用项目自带的SIBR_viewerLinux下需要自己编译SIBR_viewers稍微麻烦一点但如果你只是想确认效果用render.py渲染出来的jpg图片就够了。4. 常见问题与排查技巧实录这一部分是我最想写的因为配置环境时遇到的绝大多数问题都是重复出现的如果把常见报错和解决思路整理成表能帮大家省下大量排查时间。4.1 高频报错速查表报错信息可能原因解决方案fatal error: cuda_runtime_api.h: No such file or directoryCUDA Toolkit未安装或路径未配置检查nvcc --version确认CUDA_HOMEerror: command C:\Program Files\Microsoft Visual Studio\2022\...\cl.exe failedMSVC的C工具链未完整安装VS Installer里勾选“使用C的桌面开发”No module named diff_gaussian_rasterizationsubmodule未拉取或未编译git submodule update --init --recursive再重新setup.py installGLIBCXX_3.4.30 not foundGCC版本过旧升级GCC到9.4以上RuntimeError: CUDA out of memory显存不足降低图片分辨率、减少迭代次数、关闭其他GPU进程Exit code 0xc0000409通常是编译的PyTorch与MSVC兼容问题更换PyTorch版本至2.0.x或者更新VS2022补丁OSError: no file named run_colmap foundCOLMAP未安装或未加入PATH安装COLMAP或检查环境变量4.2 训练过程中实际遇到的三个经典坑**坑一submodule为空目录。**一位朋友下载了zip包解压进third_party/diff-gaussian-rasterization一看里面空空如也。这种问题一旦遇到问卷可能查不到答案因为没人会想到你是这样下载代码的。按上文git submodule update --init --recursive补救就好。**坑二Windows下直接双击setup_win.bat报错。**官方其实提供了一个setup_win.bat但它是个简单的封装依赖当前终端环境。如果你双击运行的是普通cmdMSVC环境变量没加载进去就会编译失败。一定要在x64 Native Tools Command Prompt里执行或者先手动set DISTUTILS_USE_SDK1。**坑三训练时PSNR和SSIM一直很低。**如果数据准备阶段COLMAP没跑好相机位姿估计不准训练出来的3DGS效果一定差。这时候看渲染图会发现物体是糊的有重影。解决办法是重新拍摄照片或者调整COLMAP参数重点是保证图像序列有足够的特征点和重叠度。4.3 显存不足与训练速度的取舍心得如果你只有8GB显存又想跑自己的场景我的实际经验是图片resize到1600最长边不超过1600像素。训练轮次从默认的30k降到15k但要把保存间隔改小比如每500步保存一次这样即使中途显存爆了还能从最近的checkpoint恢复。用residual高斯策略不开的情况下效果会下降一些但速度提升很明显。日志里如果显示statistics buffer size过大说明场景分割粒度太细CPU内存也可能吃紧。关闭TensorBoard的可视化省一部分内存。Linux下可以用nvidia-smi查看当前GPU占用如果其他用户/进程占了显存就找管理员协调或者改用小模型。4.4 环境配置的“最终手段”完全重来环境这个东西有时候你排查很久也找不到原因大概率是某个隐性的版本冲突。比如我之前遇到过一次Windows下PyTorch 2.1 CUDA 12.1 VS2022的组合编译能过但训练到几百步就崩最后测试三个多小时把PyTorch降回2.0.1就稳定了。所以遇到疑难杂症别死磕果断删掉conda环境重来conda deactivate conda env remove -n gaussian_splatting conda create -n gaussian_splatting python3.9 -y然后按文章里的顺序重新来一遍。整个过程熟练之后大概半个多小时比盲目排查几小时高效得多。另外有一个小技巧把用到的版本写在一个环境配置文件里environment.yml下次复现环境只需要inputname: gaussian_splatting channels: - conda-forge dependencies: - python3.9 - pip - pip: - torch2.0.1 - torchvision0.15.2然后conda env create -f environment.yml一步到位。配置环境这件事本质上就是一套版本的组合拳。5. 后续还能怎么玩环境跑通只是第一步。3DGS这个方向现在衍生出了很多玩法动态场景重建、自动驾驶多视角数据渲染、基于高斯的生成式模型、还有把3DGS用到SLAM里的。官方仓库只是最基础的一版里面很多细节参数比如sh_degree、densification_interval、opacity阈值都值得慢慢调。配置过程虽然繁琐但一旦跑通你会对整个深度学习和图形学的交叉工作流有更直观的理解。我个人的体会是3DGS的环境配置本质上是一个工程化的“版本管理问题”只要掌握了“先锁定版本组合再按顺序安装、编译、验证”这套思路后面遇到再新的项目也不慌。最后再分享一个小习惯每次配置环境前先写一个简单的版本清单把操作系统、显卡驱动、CUDA、Python、PyTorch、编译器版本全部记下来拍个照或者存个md文件。这样出了问题能主动缩小排查范围。我自己后来配任何深度学习项目都会先用这种方式做前置检查少走了很多弯路。