做3DGS三维高斯泼溅3D Gaussian Splatting相关方向的人应该都有体会真正劝退你的往往不是算法本身而是环境配置。这套东西不像普通深度学习项目装个requirements.txt就能跑它牵扯到CUDA Toolkit、显卡驱动、PyTorch版本、C子模块本地编译、COLMAP数据准备等多个环节任何一个环节对不上后面就是连环报错。这篇文章是3DGS系列的第一篇专门把算法环境配置这条链路完整走一遍讲清楚每一步在做什么、为什么这么做、踩了坑怎么排查。内容按我实际复现官方开源仓库的经验来写适合刚接触3DGS的新手也适合被环境折腾到想放弃的同学。1. 为什么环境配置是3DGS的第一道坎1.1 3DGS不吃“开箱即用”那一套大多数深度学习项目拿到源码后就是pip install -r requirements.txt python train.py两步走但3DGS不行。这个算法在渲染阶段用了一个自定义的可微光栅化器官方仓库把它做成了两个子模块放在submodules目录下diff-gaussian-rasterization负责核心的光栅化渲染simple-knn负责构建高斯点之间的初始近邻索引。这两个模块不是预编译好的Python包而是C/CUDA源码需要在你自己的机器上重新编译编译过程依赖于CUDA、PyTorch扩展接口和系统gcc工具链。这就带来一个问题不同机器的CUDA版本、PyTorch版本、gcc版本各不相同编译结果也不一样。官方代码并没有为所有环境提供通用轮子所以环境配置阶段就是要把这套本地编译的依赖链跑通。很多人第一次跑3DGS时卡了一个星期往往不是训练逻辑看不懂而是卡在编译阶段的各种报错上。建议先建立正确预期环境配置不是一次性装好所有软件那么简单而是要确保显卡驱动、CUDA Toolkit、PyTorch、编译器、子模块这五层能协同工作。只要有其中一层版本不匹配后面编译就会暴露问题。理解了这一点再去看网上各种零散的报错解决方案会清晰很多。1.2 硬件与软件栈的整体认知先看硬件门槛。3DGS训练时的显存消耗不低官方示例一般在几GB到十几GB之间浮动。实拍场景图片多一点、分辨率高一点显存占用就会明显上升。按目前主流情况建议显卡显存至少6GB起步跑中等规模场景建议12GB以上如果有24GB的卡当然更从容。显存不够虽然不会导致环境配置失败但训练时很容易OOM所以买卡、租卡前先估好自己的场景规模。显卡还有一个隐藏限制是计算能力Compute Capability。3DGS的光栅化CUDA代码用了一些较新的GPU特性老架构显卡无法编译。官方说明要求GPU计算能力不低于6.0对应的是比较老的Pascal架构以后的产品。如果你手头是很多年前的显卡环境配置阶段大概率会看到关于compute capability的报错。软件栈方面最关键的是搞清楚三个东西的区别。第一是显卡驱动这是系统层的东西跑任何GPU程序都需要第二是CUDA Toolkit提供nvcc编译器和CUDA运行时库是编译C/CUDA子模块的工具第三是PyTorch自带的CUDA运行时它是和PyTorch轮子绑定的。很多人看到nvidia-smi里显示的CUDA版本是12.x就以为CUDA Toolkit装好了其实这是两回事后面我会详细说。整体推荐的稳定组合分新旧两套。保守方案Linux系统 CUDA 11.8 Python 3.7/3.8 PyTorch 1.13.1这个组合最接近早期官方文档的默认配置网上资料也最多。新一点的方案CUDA 12.1 Python 3.9/3.10 PyTorch 2.x也能编译通过但遇到报错时排查难度会略高。如果你没有特殊原因我建议按保守方案走省心。2. 动手前先把依赖清单列清楚2.1 官方仓库的整体目录结构拿到源码先别急着clone完就敲命令我习惯先把目录结构看清楚理解每个模块在环境配置中扮演什么角色。官方仓库的顶层内容大致是这样submodules/diff-gaussian-rasterization核心可微光栅化器整个3DGS训练过程最依赖的模块必须本地编译submodules/simple-knn辅助模块用于构建高斯点的近邻关系也需要本地编译SIBR_viewers官方自带的实时可视化查看器不参与训练和渲染主流程环境配置时可以先不管utils/数据加载、相机参数解析、图形学辅助函数等纯Python代码train.py训练入口脚本render.py渲染入口脚本用训练好的模型生成新视角画面convert.py把视频或图片转换为COLMAP格式数据的工具脚本第一次看这个结构时容易忽略一个关键点官方仓库里的submodules不是直接包含在仓库里的而是以git子模块的方式引用的。如果clone仓库时没有加--recursive参数这两个子模块目录会是空的后面编译直接报找不到源码。这算是最常见的低级错误之一我见到的频率非常高。从环境配置的角度看整个流程的核心目标可以抽象成一句话把diff-gaussian-rasterization和simple-knn这两个子模块在当前机器上编译成功并且能被Python正常import。只要这一步通过了其他都是常规操作。2.2 关键依赖项与版本选型逻辑逐个说清楚依赖项选型的理由。CUDA Toolkit建议装11.8或12.1。11.8是官方早期验证过的版本和PyTorch 1.13.1组合最稳定。12.1可以和PyTorch 2.x组合也能跑通。注意不要只看驱动版本驱动新不代表CUDA Toolkit就齐全nvcc是单独装的东西。Python3.7到3.10之间都有人用。官方早期环境文档写的是Python 3.7但3.8、3.9在实际使用中也没问题。3.11以后我测试时遇到个别依赖包没及时适配的情况比如一些旧版本的numpy、plyfile在小版本上有兼容问题建议不要用太新的Python。PyTorch必须装带CUDA支持版本的轮子不要用默认的CPU版本。用pip安装时指定index-url来拉取对应CUDA版本的轮子是最不容易出错的做法。gcc/g编译器Linux系统自带的gcc 9.x或10.x都没问题。如果系统是较新的发行版自带gcc 12或13编译时可能会遇到一些C语法兼容性报错这时候可以手动切换系统gcc版本。其他Python库plyfile用于读写PLY格式的点云和模型文件tqdm显示进度条还有OpenCV相关依赖会在convert.py处理视频时用到。这些通过pip安装即可。COLMAP和FFmpeg这两个是独立于Python生态的系统级工具。COLMAP用于从图片或视频恢复相机参数和稀疏点云FFmpeg用于视频抽帧。严格来说它们不属于Python环境配置但缺了它们convert.py就跑不起来所以也应该在环境阶段装好。把这些依赖列在一张脑图里会更直观。环境配置的先后顺序也很重要先装显卡驱动和CUDA Toolkit再建Python虚拟环境并装PyTorch再编译子模块最后准备数据。顺序乱了排查问题时往往不知道哪一层出了错。3. 一步步完成环境搭建3.1 CUDA与驱动先搞定最底层第一步先检查驱动和CUDA的情况。打开终端分别跑两个命令nvidia-smi nvcc --versionnvidia-smi看到的是显卡驱动信息和驱动支持的CUDA版本号nvcc --version看到的才是CUDA Toolkit编译器的版本。如果nvcc命令提示找不到说明你的系统只有驱动没有安装CUDA Toolkit或者没有配置环境变量。我遇到过一种情况nvidia-smi显示的CUDA版本是12.4看起来挺新但实际装机时只装了显卡驱动CUDA Toolkit完全没装结果编译子模块时找不到nvcc。所以这里一定要明确区分。安装CUDA Toolkit时如果你用的系统比较新直接通过包管理器装比较省事但注意版本可能偏旧。想精确控制版本的话从官方下载runfile安装包手动装。我个人的习惯是装在/usr/local/cuda目录下这样可以同时保留多个版本通过环境变量切换。装完CUDA后需要配置环境变量。在~/.bashrc或~/.zshrc里追加export CUDA_HOME/usr/local/cuda export PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH然后source一下配置文件。CUDA_HOME这个变量非常重要因为后面编译子模块时PyTorch的扩展构建系统会通过它来找nvcc和CUDA头文件。我碰到过有人明明装了CUDA但编译时报CUDA_HOME not set之类的错误就是因为环境变量没配。在动手下一步之前确认这几个条件都满足nvcc --version能看到版本号nvidia-smi能看到显卡且驱动正常echo $CUDA_HOME能输出路径。任何一项不满足都先解决掉再继续。3.2 创建Python虚拟环境并安装PyTorch环境隔离是必须做的直接用系统Python装容易和别的项目打架。我习惯用conda创建虚拟环境conda create -n gs python3.8 -y conda activate gs然后安装基础依赖pip install plyfile tqdm接下来是PyTorch的安装这是整个环境配置里最容易踩坑的地方。如果直接执行pip install torch很多情况下会装到CPU版本后面编译子模块时虽然也能过但训练时发现CUDA不可用那才叫崩溃。所以一定要指定CUDA版本对应的轮子来源pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118这个命令会安装带CUDA 11.8支持的PyTorch。如果你前面装了CUDA 12.1就把cu118改成cu121。装完之后可以验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())这个输出必须看到True代表PyTorch能调用CUDA。经常有人的环境卡在这一步输出是False原因就是装了CPU版PyTorch或者CUDA Toolkit版本和PyTorch轮子不匹配。注意一个细节PyTorch的CUDA版本和系统的CUDA Toolkit版本不需要严格相同PyTorch自带了一整套CUDA运行时库只要显卡驱动够新PyTorch就能跑。但编译子模块时可能同时依赖PyTorch的runtime和系统CUDA Toolkit所以两边版本尽量对齐最省心。3.3 编译两个关键C子模块先clone仓库。这一步一定要带--recursive否则子模块是空的git clone 官方仓库地址 --recursive如果已经clone完了才发现子模块是空的补一条命令git submodule update --init --recursive然后进入子模块目录编译cd submodules/diff-gaussian-rasterization pip install . cd ../simple-knn pip install .编译过程会调用nvcc编译CUDA代码耗时比较长第一次编译可能需要几分钟到十几分钟取决于机器性能。看到Successfully installed diff-gaussian-rasterization这样的输出就说明编译成功了。simple-knn同理。linux下官方还提供了build.shWindows下是build.bat本质上也是调pip install用哪个都可以。我习惯直接pip install看到报错更直观。这里想解释一下为什么这两个模块必须本地编译。diff-gaussian-rasterization里的CUDA kernel是针对GPU架构写的不同显卡的计算能力不同预编译二进制没法通吃。编译时它会根据当前显卡型号生成针对性的机器码这也是为什么换了显卡后需要重新编译一遍。如果编译过程中遇到报错先不要慌大多数情况下是环境变量或者PyTorch版本的问题后面排错章节会专门讲。我记得自己第一次编译时候等进度条的时候屏幕滚过一大堆警告看着吓人其实只要最终能import成功就没事。3.4 验证环境是否可用子模块编译完成后环境其实已经基本成型了。我会建议做一个快速验证而不是直接开训练。打开Python交互环境执行import torch from diff_gaussian_rasterization import GaussianRasterizer from simple_knn._C import distCUDA2 print(torch.cuda.is_available())如果Python能正常import这两个模块且torch.cuda.is_available()为True那么环境配置算是成功了。这一步花不了几分钟但能帮你把训练时报错的概率大幅度降低属于典型的磨刀不误砍柴工。还有一个验证方式是直接尝试打印子模块的函数输出比如传一些随机张量进去。不过这步可做可不做因为就算函数能调用参数不对也会报错正常import成功就够了。环境验证完接下来要做的是准备训练数据。很多人环境装好了就急着跑官方demo结果发现没数据可用或者数据目录结构不对又开始折腾。这里我建议先看完下一节把数据这块准备好再一起跑。4. 数据准备环境搭好之后第一件正事4.1 3DGS喂给模型的数据格式3DGS训练需要的数据包括两部分一组同一场景的多视角图片以及每张图片对应的相机参数。相机参数包括内参焦距、主点和外参位姿这些信息官方仓库默认依赖COLMAP来生成。COLMAP是一个做运动恢复结构SfM的工具它会对一组图片做特征提取、特征匹配、稀疏重建最终输出一个包含相机位姿的稀疏点云。这个输出就是3DGS需要的相机参数来源。具体到目录结构训练脚本train.py会根据你指定的数据根目录来找input/目录存放原始图片或视频images/目录存放COLMAP处理后的图片sparse/0/目录存放COLMAP的稀疏重建结果包括cameras.bin、images.bin、points3D.bin理解这个流程后你会发现3DGS本身不负责从图片估计相机位姿它是直接用COLMAP给好的相机参数开始训练的。所以数据准备的核心工作就是调用COLMAP把一组图片变成带有相机参数的标准结构。4.2 用视频快速生成COLMAP数据如果你手头的素材是视频官方提供的convert.py可以一条命令完成抽帧、COLMAP重建全流程python convert.py -s data/xxx这里-s参数指定数据根目录。脚本的工作流程大致是先用FFmpeg从视频里按一定帧率抽帧保存到input/目录然后调用COLMAP做特征匹配和稀疏重建最终输出sparse目录。实际操作中我对录制视频有几点建议。第一围绕物体缓慢旋转镜头移动速度要慢画面模糊会严重影响特征匹配。第二尽量保证相邻帧之间有足够的重叠区域一般要求至少60%以上。第三光照条件要稳定避免曝光剧烈变化。第四视频时长不用太长几十秒到几分钟足够最终抽帧出来的图片数量控制在几十到两三百张之间就行。图片太少重建不稳定太多训练时间翻倍而且不一定提升质量。convert.py有一些常用参数值得注意。比如--skip_colmap可以在已经有sparse数据时跳过COLMAP重建只做图片整理--no_gpu可以用CPU模式跑COLMAP这步官方脚本会根据命令自动选择一般不太需要手动指定。如果你已经有现成的图片而不是视频直接把图片放进data目录的input文件夹里结构准备好之后也可以跑COLMAP。但要注意图片分辨率不要过高超过一定尺寸时COLMAP的特征提取会非常慢显存和内存占用也高。建议把长边缩到1600像素左右再喂进去速度会快很多。4.3 目录结构到底应该长什么样很多人在数据准备阶段踩坑是因为目录结构理解有偏差。这里给一个标准的参考结构data/ └── scene_name/ ├── input/ │ ├── frame_0001.jpg │ ├── frame_0002.jpg │ └── ... ├── images/ │ ├── frame_0001.jpg │ ├── frame_0002.jpg │ └── ... └── sparse/ └── 0/ ├── cameras.bin ├── images.bin └── points3D.bininput目录放原始视频抽帧出来的图片images目录是COLMAP处理时用的图片sparse/0目录是COLMAP的输出。如果你自己用其他方式生成了COLMAP工程注意database.db的位置也影响脚本能否正确复用。实际操作里convert.py会把第一步抽帧结果放input然后把图片拷贝到images再调用COLMAP把结果写到sparse/0。如果你是从已有COLMAP工程迁移需要手动保证这个结构一致特别是sparse目录下的输出编号必须是0。这种目录设计其实不算复杂但确实很容易被忽略。我帮别人排查过很多次问题最后发现就是sparse目录放错位置train.py找不到cameras.bin直接报路径不存在的错误。如果训练时遇到这类报错先回来检查数据目录结构比改代码靠谱得多。5. 排错实录环境配置阶段的高频大坑5.1 CUDA相关报错与对应解法环境配置阶段最常出问题的地方就是CUDA。我整理几种高频情况现象原因解决办法nvcc命令找不到CUDA Toolkit没装或PATH没配安装CUDA Toolkit配置PATH和CUDA_HOME编译报CUDA_HOME not setPyTorch构建系统找不到CUDA路径在~/.bashrc设置export CUDA_HOME/usr/local/cudatorch.cuda.is_available()为FalsePyTorch装成CPU版用带cu118/cu121的index-url重装PyTorchCUDA driver version is insufficient驱动版本过旧升级显卡驱动或换更低的CUDA Toolkit其他程序占满显存CUDA out of memory显存被占或数据过大nvidia-smi查占用关进程或降低数据分辨率这里需要特别提一个很多新手会困惑的问题为什么nvidia-smi显示CUDA 12.xPyTorch用的CUDA 11.8也能跑因为nvidia-smi里的CUDA版本表示驱动支持的最高CUDA版本而PyTorch自带CUDA运行时只要驱动版本不低于PyTorch所需的CUDA最低版本就能用。理解了这个逻辑就不会被各种CUDA版本号搞晕。我个人的习惯是提前用nvidia-smi确认驱动能支持的目标CUDA版本比如驱动是535.xx系列那CUDA 12.1和11.8都支持随便选一个都行。如果驱动太老比如只支持CUDA 11.4以下那就只能老老实实用PyTorch 1.12或更早版本这属于特殊情况不展开讲了。5.2 编译子模块时的报错编译diff-gaussian-rasterization和simple-knn时报错种类比较集中常见的有这几种。第一种是找不到PyTorch头文件报错里会出现类似fatal error: torch/extension.h: No such file or directory。这几乎可以断定是当前Python环境里PyTorch没装好或者编译时激活了错误的虚拟环境。检查一下conda activate是不是生效了以及python -c import torch能否正常执行。第二种是找不到CUDA头文件报错里出现cuda_runtime.h: No such file or directory。这种情况基本上就是CUDA_HOME没设置对或者CUDA Toolkit没安装完整。检查/usr/local/cuda/include目录下有没有cuda_runtime.h文件没有就说明CUDA Toolkit没装好。第三种是gcc版本过高导致的编译失败报错信息五花八门大多是C语法模板实例化的兼容问题。现代Linux发行版默认gcc可能是13.x而我前面说过9.x或10.x比较稳妥。解决办法是安装并切换系统默认gcc版本sudo apt install gcc-9 g-9 sudo update-alternatives --config gcc sudo update-alternatives --config g切换后再重新编译大概率能过。第四种是编译过程巨慢或者因为多线程编译导致内存吃紧。可以在编译前设置环境变量限制并行任务数export MAX_JOBS4 pip install .这个参数会传给ninja或setup.py的并行编译逻辑能有效降低内存占用。我跑过的很多机器默认并行任务太高编译一个小模块差点把内存吃满设成4就顺畅多了。5.3 Python、PyTorch与显存问题Python版本的坑多数隐藏得很深。比如用Python 3.11装某些旧版本的依赖包时可能会遇到没有对应wheel、只能从源码编译的情况编译过程又会触发新问题。所以如果不是有特殊的包版本需求我建议整个环境的Python版本保持在3.8到3.10之间。还有一个我见过很多次的问题是明明在conda环境里安装了PyTorch但执行train.py时报ModuleNotFoundError原因是启动脚本时没有激活conda环境或者激活了却用的是系统Python。排查方法很简单先执行which python看看用的哪个解释器再执行python -c import torch; print(torch.version)确认环境是否正确。显存问题虽然更多出现在训练阶段但环境配置阶段也可以提前预防。训练前用nvidia-smi看一眼可用显存心里有个数。3DGS默认配置下如果数据场景比较小6GB显存还能凑合如果场景大、图片多很可能需要降低图片分辨率或减少迭代次数。官方代码里有一些命令行参数可以在训练时调整但这不是环境配置的核心等后续文章讲训练细节时再展开。如果训练时直接报CUDA out of memory最直接的应急方法是把数据图片长边缩到1100或1200像素重新跑一次convert.py。这个操作能显著降低显存和内存压力代价只是重建精度稍有下降。对于大多数demo场景来说视觉差异其实不大。6. 最后的个人经验与建议环境配置这件事最怕的就是从一个教程抄命令抄完不知道为什么。我在这里把整套配置流程走下来最终的体会是3DGS的环境并不比很多大型C项目复杂但它的技术栈比较新网上资料相对零散导致很多人卡在某个细节的版本兼容问题上。我自己在调试时有一个习惯准备一个小本子记录每一次报错和对应的解决方法标注好机器配置。因为不同机器、不同系统版本、不同驱动版本之间差异很大换个环境可能又会遇到新问题。记录多了之后再碰到报错基本能快速定位是哪一层出了问题排查效率高很多。另外如果你是在云服务器或远程机器上配置环境一定要确认GPU驱动在系统里是可见的。很多云镜像默认只装了CPU环境nvidia-smi都看不到显卡这种情况下一切后续步骤都无从谈起。我自己就遇到过一次当时排查了半天最后发现是云实例驱动没装装完驱动后整个流程一气呵成。最后再分享一个小技巧配置完成后可以把两个子模块的pip install命令写进一个依赖脚本里以后换机器时先装系统级的CUDA和COLMAP再运行这个脚本十几分钟就能把环境搭起来。环境配置这件事本身没有太多高深的玄机只要把每一层的版本关系理清楚按顺序走绝大部分问题都能解决。