简介资源为3D高斯溅射3DGS部署与训练指南的配套项目源码面向希望快速上手三维场景重建的开发者、研究者和进阶学员。作者在Python 3.10、CUDA 12.3与PyTorch 2.2.1组合下完成了非官方推荐环境的搭建验证内容涵盖软件环境配置、依赖安装、数据集下载与格式转换、预训练数据使用、训练结果查看、自定义图片训练以及视频抽帧等实用技巧并附有调试和优化建议帮助读者避开环境兼容性陷阱。压缩包共3个文件以说明性html为核心配合inscode配置与gitignore忽略规则总大小仅7KB轻量精炼便于快速下载比对。目前已有225人学习使用内容直指部署中的常见问题适合缺乏官方配置示例的初学者按步骤实践也适合已有基础者快速补全自定义数据训练流程。整体来看资源用真实运行经验补充了官方文档未覆盖的环节能显著缩短3DGS落地周期。1. 3DGS是什么为什么2024年之后新视角合成都在谈它3DGS3D Gaussian Splatting3D高斯溅射是当前新视角合成领域最值得投入的方向。它把场景表示成几百万个带颜色、透明度、旋转和尺度的高斯椭球通过光栅化直接投影到图像平面绕开了NeRF那条“每条光线采样几百个点再体渲染”的慢路径。训练速度从NeRF的按天计算缩到按小时计渲染帧率在消费级显卡上就能跑到三位数这让它成为实景重建、SLAM、自动驾驶仿真、电商展示里最常被提到的技术方案。这篇指南面向的是拿到源码但没跑通、或者跑通了但效果不理想的人。我会从环境准备、数据制作、训练参数、排查手段到部署导出按一条能复现的路径讲完。适合的人群包括刚入门的CV研究生、做三维重建的工程师、以及想在嵌入式设备上试试实时渲染的开发者。如果你只是想知道“3DGS能不能用”答案是能而且它已经不止于论文demo阶段。2. 环境准备从零到跑通最小demo的三个checkpoint2.1 硬件与系统先确认你手里的机器够不够格3DGS对硬件的要求比大多数人想象的“宽”也“窄”。窄在显存宽在显卡型号。训练时每个高斯点都要保存位置、协方差、颜色、透明度等属性一个常规场景大概会生成几百万个高斯点优化过程还会动态克隆和分裂显存占用基本在6GB到12GB之间浮动。如果你只有4GB显存建议把图片分辨率降到1/2甚至1/3再训练或者直接放弃当前场景换一个目标更小的数据集。常见做法是训练用NVIDIA显卡显存8GB起步建议12GB以上推理部署可以放宽到4GB因为推理时不需要存梯度。AMD显卡不是不能用但PyTorch对ROCm的支持在部分发行版上仍有坑不推荐新手起步踩。CPU方面没有太高要求但如果你的CPU核心数低于8COLMAP那个环节会比较痛苦。内存建议32GB因为COLMAP的特征提取和匹配会吃不少内存。系统上首选Ubuntu 20.04或22.04NVIDIA驱动在Ubuntu上维护得最省事。Windows也可以跑源码里也给了Windows的编译指引但你要有心理准备去处理Visual Studio和CUDA的版本对齐问题。许多人上来就纠结“ubuntu22 3dgs”能不能跑答案是可以但22.04的GCC版本更高编译时可能会碰到一些第三方库的警告后面避坑章节我会专门写一条。2.2 创建conda环境与安装PyTorch版本对齐是第一步拿到源码后不要急着pip install -r requirements.txt。先建一个干净的conda环境把Python锁在3.8或3.9然后单独装PyTorch。版本对齐很关键源码的C扩展是用CUDA编译的PyTorch的CUDA版本和显卡驱动必须匹配。最稳妥的方式是用conda安装PyTorch而不是pipconda会把cudatoolkit一并装好省去后续的“缺libcudart.so”类报错。conda create -n 3dgs python3.9 -y conda activate 3dgs conda install pytorch1.13.1 torchvision0.14.1 pytorch-cuda11.7 -c pytorch -c nvidia -y这里把PyTorch锁在1.13.1是因为源码里的diff-gaussian-rasterization是在这个版本下写的后续如果Electron版本升级一般也兼容但没必要在起步阶段给自己加不确定因素。安装完后先验证CUDA可用python -c import torch; print(torch.cuda.is_available(), torch.version.cuda)如果输出是True 11.7说明环境没问题。如果是False先别往下走去检查NVIDIA驱动是不是被系统更新顶掉了或者conda环境里装的是不是CPU版PyTorch。2.3 安装子模块diff-gaussian-rasterization和simple-knn源码目录下通常有两个要单独编译的C/CUDA扩展一个是diff-gaussian-rasterization可微光栅化器一个是simple-knn用于初始化时做KNN搜索。这一步是新手最容易卡住的地方因为编译失败的错误信息不一定友好。pip install submodules/diff-gaussian-rasterization pip install submodules/simple-knn如果编译报错先排查三件事一是CUDA_HOME有没有设置没有的话在~/.bashrc里加export CUDA_HOME/usr/local/cuda二是GCC版本Ubuntu 22.04默认GCC 11如果报兼容性错误可以临时切到GCC 9三是确认显卡驱动版本nvidia-smi里显示的CUDA Version只是驱动支持的上限不是实际安装的CUDA工具版本。编译失败后重新装之前建议先pip uninstall这两个包避免旧编译残留。2.4 跑通官方demo数据集下载与训练命令官方提供了一组预处理好的场景数据比如Truck、Garden、Bicycle等。下载后目录结构是images/加一个cameras.json或COLMAP的sparse文件。训练一个demo场景的命令是python train.py -s data/truck -m output/truck这是从零开始训练的命令。-s指定数据目录-m指定输出目录。启动后你会看到类似“Computing weights...”和“Optimizing...”的日志。第一次跑的时候建议选Truck这个场景它大小适中训练一张800x800的图像大概需要五万步时间在20-40分钟之间取决于显卡。Garden场景更大新手起步别选它。跑完之后的产物在output/truck/下里面有point_cloud/每多少步保存一次的点云、train/和test/渲染出来的图片、cameras.json、cfg_args等文件。用官方viewer打开output/truck/point_cloud/iteration_30000/point_cloud.ply能看到一个完整的可旋转场景这就是训练结果的直观验证。3. 数据准备从视频到COLMAP稀疏重建的完整闭环3.1 采集建议环绕、重叠和光照的三个基本原则3DGS训练数据其实就是一组对同一场景从不同视角拍摄的照片。视频可以连拍也可以单反或手机都行。采集质量直接决定重建上限后面再怎么调参数也补不回来。三个原则第一是环绕让相机从多个角度覆盖场景不要只在一个弧线上移动第二是重叠相邻两帧之间的视角变化控制在10度以内重合度不低于60%-80%第三是光照固定光照条件下采集避免阴影随着时间漂移这会直接导致模型学到“多个场景的加权平均”。视频方式通常抽帧后用常见做法是用FFmpeg按固定帧率抽帧。图片数量控制在一个范围内官方场景一般在100到300张之间别贪多。超过500张训练时间会显著拉长而且重叠度过高反而会引入冗余约束。下面是一个抽帧命令ffmpeg -i video.mp4 -vf fps2 -qscale:v 2 data/input/%04d.jpgfps2表示每秒抽两帧你可以根据视频速度调整。如果视频里镜头移动很快每秒2帧可能抽出来的相邻帧视角变化过大如果移动很慢每秒1帧就够了。抽完检查一遍凡是模糊的、被遮挡的、构图大跳变的帧直接删掉别让它们进COLMAP。3.2 COLMAP流程为什么不需要自己装完整版3DGS源码里的convert.py会自动调用COLMAP做稀疏重建和相机位姿估计。COLMAP是一个开源的SfMStructure from Motion工具它从多张图片中恢复相机内外参和稀疏点云。这一步本质上是给后续的高斯初始化提供一个起点。源码里整体会执行特征提取、特征匹配、稀疏重建和相机参数转存。Ubuntu下安装COLMAP可以用apt也可以直接下载官方编译好的二进制包。更省事的做法是在源码仓库的environment.yml或requirements.txt注释里找提示官方经常推荐直接把COLMAP加进系统PATH因为convert.py是通过命令行调用colmap的。建议先手动验证一下colmap -h如果输出帮助信息说明COLMAP可用。然后运行预处理python convert.py -s data/my_scene --resize--resize参数会把图片缩放至原图的1/2后再做重建和训练。这步有两个作用一是降显存二是减少COLMAP匹配时间。最后convert.py会在data/my_scene/下生成distorted和undistorted两个目录训练时用的是undistorted里面的sparse/0和images。你可以留意一下distorted目录里除了图片还有一个sparse文件夹那是COLMAP的原始输出。3.3 图片数量不够或视角太乱时的表现很多人换自己的数据来训练时效果远不如官方demo。原因大概率不是代码问题而是数据问题。如果重建出来的场景出现“玻璃一样”的重影、某些区域糊成一片先回头检查图像本身。COLMAP重建失败的典型表现是稀疏点云数量极少比如只有几百个点、相机位姿输出有大量“估计失败”的状态。此时应该减少图片数量、增加重叠度、重新拍摄而不是盲目调训练参数。一个实用的检查方法是在跑train.py前先打开COLMAP输出的sparse/0/points3D.ply看一眼。如果点云形状能大致看出场景结构说明COLMAP这一步是通过的。如果点云是一团散沙后面的训练大概率也是废的。想象一下3DGS要优化几百万个高斯初始化点云就歪了后续再怎么克隆、分裂也是在一个错误的地基上修修补补。数据质量不行后面每调一次训练参数就多浪费一次时间。4. 训练配置与监控从默认参数开始再看懂loss和保存点4.1 训练命令的完整形态与输出目录运行训练之前先把参数过一遍。train.py支持很多参数有用的是-r控制图片分辨率--iterations控制训练总步数-s和-m指定数据和输出目录。下面这条命令可以视为一个中等配置python train.py -s data/my_scene/undistorted -m output/my_scene -r 2 --iterations 30000 --save_iterations 7000 30000-r 2表示把图片分辨率降到原来的1/2再训练。--save_iterations后面跟的就是要额外保存点云的迭代步数。默认会在7000、30000、60000等几个节点保存指定之后就会多存对应迭代步的模型。节省显存还可以直接改图片尺寸但改-r是最简单的方式缺点是图像分辨率低会限制重建精细程度。启动后输出目录里会不断生成中间结果。point_cloud/iteration_7000/下的point_cloud.ply就是那个步数下的高斯点云可以用viewer加载来看训练进度。train/和test/里则是每个保存节点渲染出来的图像可以和真实图对比。瓶颈往往出现在这一步很多人只盯着终端里的loss数值忘记了视觉检查。4.2 核心参数在哪里改配置文件里没有的东西3DGS的训练参数不是写在配置文件里的而是在train.py里用argparse定义的。与质量直接相关的主要有这几个position_lr_init位置学习率初始值、position_lr_final位置学习率最终值、position_lr_max_steps位置学习率衰减到的最大步数、densification_interval每隔多少步进行密化、densify_grad_threshold密化触发阈值、opacity_reset_interval透明度重置间隔。大多数人直接跑默认参数就够了。如果你重建的场景特别大或特别小需要调整的是--densify_grad_threshold这个阈值。默认的0.0002是官方在Truck这类中等场景上调出来的值。场景细节稀疏、多以大面积连续表面为主时可以试着降低这个阈值让高斯更早开始分裂场景本来就纹理密集阈值太高会导致过密化反而增加渲染时间且容易过拟合。另一个值得关注的是--sh_degree默认是3表示每个高斯用3阶球谐函数表示视角相关颜色。对大部分场景来说3阶够用调低到2可以省显存、减少颜色拟合的平滑度但效果会单薄一些。如果是室内场景、光源变化不大2阶其实是一个性价比不错的选项。4.3 用TensorBoard或裸眼读日志判断训练状态训练过程中终端会输出每个迭代步的loss、耗时和渲染数据。不要在loss还没降下来的时候就打断训练更不要一看到loss剧烈波动就关掉。正确做法是记下初始loss、训练到2000步左右的loss、以及跑到1万步时的趋势用来判断收敛区间。官方仓库也提供了一个简单的TensorBoard脚本train.py在运行时如果没有额外指定--tensorboard不会自动生成事件文件你也可以手动pip install tensorboard后自行接入。但多数情况下检查中间节点保存的渲染图比盯着loss曲线更有效。loss降到一定程度后视觉上不再有可感知的进步说明已经收敛继续跑只是浪费电。一个经验值如果30000步后测试视角渲染的图像和真实图像的边缘仍有明显重影大概率是COLMAP相机位姿有小幅漂移而不是模型容量不足。这时候回头检查数据比继续加训50000步更值得。5. 避坑指南部署训练3DGS常见的五个坑5.1 训练能启动但loss直接变成NaN现象train.py正常启动但训练日志里loss和PSNR显示为nan或者PSNR一路掉到负数。原因最常见的是初始化时高斯点云中包含异常值比如COLMAP输出的稀疏点云里有坐标接近无穷大的点或者图像中存在超出浮点表达范围的像素值。另一个原因是学习率过高让梯度更新冲过了有效区域。解决第一步打开sparse/0/points3D.ply统计点云坐标范围过滤掉异常离群点再训练第二步降低位置学习率初始值到1.6e-4以下第三步把图片统一缩放后重新跑COLMAP。这个坑在自采数据里出现频率最高官方demo因为数据预处理过反而不会暴露。5.2 显存明明够却报CUDA out of memory现象PyTorch报CUDA out of memory但nvidia-smi显示显存还有剩余。原因PyTorch默认会给CUDA预留一块缓存nvidia-smi里的“Free Memory”看起来很多实际可用显存可能已经所剩无几。另外densification步骤会临时创建大量张量峰值显存比常态高出一截。解决给train.py加--memory_limit或者在代码里用torch.cuda.set_per_process_memory_fraction限制PyTorch内存占用比例。更直接的方案是降分辨率-r 4把图片缩到1/4显存占用能降到1/4甚至更低。还有一招数据集对应的sparse目录里如果存在images.bin或cameras.bin尝试删除后重新用convert.py跑一次有时旧缓存会让数据加载阶段多占不少显存。5.3 Ubuntu22.04编译diff-gaussian-rasterization失败现象pip install submodules/diff-gaussian-rasterization时编译报错提示/usr/include下的某些头文件找不到或者CUDA某些库无法链接。原因Ubuntu 22.04默认的GCC是GCC 11而源码里的CUDA扩展可能在GCC 9这种更老的版本下编写的。GCC 11的C标准兼容性和CUDA工具包版本不匹配时会出现模板实例化失败或头文件路径冲突。解决先用ls /usr/local/ | grep cuda确认CUDA安装路径。然后看~/.bashrc里有没有export CUDA_HOME/usr/local/cuda。如果还不行装GCC 9并临时切换默认版本sudo apt install gcc-9 g-9然后在编译时显式指定CCgcc-9 CXXg-9。编译通过后再切回GCC 11也不影响已经装好的包。5.4 训练结果在相机视角内清晰但换个视角就糊现象训练时PSNR很高渲染训练集图像效果很好但一旦移动到训练视角之外的视角画面明显模糊或变形。原因这是典型的“过度拟合训练视角”的表现。3DGS的高斯分布被优化成一个只能解释固定视角的模型泛化性不足。通常与图像覆盖度不够、相机位姿回归误差大有关而不是模型过度的容量问题。解决回到数据采集层面。检查图像是否真的覆盖了整个场景视角间重叠是否足够。一个可操作的验证方法是用COLMAP的model_converter导出相机轨迹并在查看器里看一看相机位置的分布形状。相机轨迹如果呈线性排列而不是环绕分布就是采集方式问题。5.5 训练速度快但重建细节感不强现象场景整体能看但边缘线、纹理细节有一种“油画感”或“涂抹感”不够锐利。原因一是输入图像分辨率本来就低二是训练过程中高斯数量过早饱和densify_grad_threshold太高导致细节处没有触发分裂。三是球谐阶数不够视角变化剧烈时颜色表现力不足。解决在分辨率允许范围内把-r降到1保留原始分辨率。把--densify_grad_threshold下调到0.0001左右。另外训练日志里注意观察总高斯数量变化如果在3万步之前就停止增长大概率是密化机制提前触顶。可以调高--densify_until_iter默认值是15000让它持续密化更久一些。6. 部署与导出从PLY到Web/嵌入式设备的最后一公里训练完成后output目录下的point_cloud.ply是可直接用于渲染的模型。但要让别的系统用起来还需要做两件事一是把PLY转成更紧凑的格式二是在目标平台上实现光栅化渲染。官方仓库的SIBR viewer用的是自己的格式但它也支持直接加载PLY。如果你想在浏览器里展示常见做法是使用开源项目中的WebGL渲染器。它接受一个经过转换的splat文件通常是一个二进制紧凑格式只保留必要属性位置、协方差、颜色、透明度。转换脚本思路如下python convert_ply_to_splat.py input.ply output.splat简单实现逻辑是逐行读取PLY提取每个高斯点的中心坐标、三个尺度值、旋转四元数、球谐系数和透明度按预定二进制布局写入。关键的参数是视锥剔除的阈值和透明度阈值一般把透明度低于0.01的高斯点直接丢弃能减少10%-20%的文件大小而不影响视觉。在Jetson这类边缘设备上部署有两种路线。一种是跑完整的PyTorch模型加在线渲染loop优点是灵活、可以实时更新场景缺点是显存和CPU开销大更适合原型验证。另一种是用C/CUDA重写光栅化内核把模型固化成资源文件运行时只做纯渲染这也是产品化的路径。如果你只是做技术验证第一种足够如果目标是把3DGS塞进实时交互应用第二种值得投入。性能调优方面几个经得住验证的方向是控制高斯总数通过训练阶段的阈值参数限制分裂上限把球谐阶数从3降为2或1推理计算量下降明显在渲染阶段做LOD分层远距离用低密度高斯近距离用完整精度。3DGS在嵌入式设备上的瓶颈往往不是模型大小而是光栅化时逐高斯的像素覆盖判断这个环节做粗粒度剔除比盲目优化shader更有效。有个习惯我现在一直保留任何场景训练完我都会先用viewer把模型完整转一圈确认无悬浮物、无空洞再考虑导出。导出后再用目标设备实拍画面做对比两个画面并排看差得远就回炉调参。3DGS这套流程最大的特点就是反馈链路短从数据到可交互的3D画面中间没有太多黑匣子每一步的产物都能直接看到这也是我建议你从零跑一遍、别只做“拿来调用”的原因。自己跑通一次全流程后面换数据、换平台、做产品化才有据可依。希望帮到你。本文还有配套的精品资源点击获取