简介这份源码包面向希望上手3D Gaussian Splatting3DGS三维场景重建的研究者与开发者尤其适合在非官方推荐环境下摸索部署的实践者。作者以Python 3.10、CUDA 12.3与PyTorch 2.2.1的组合完成验证内容覆盖软件环境配置、依赖安装、数据下载与格式转换并延伸到预训练数据训练、结果查看以及使用自有图片数据训练的完整流程还涉及视频抽帧等实用技巧。资源包共3个文件以inscode工程配置、html页面与gitignore忽略规则为主压缩包约7KB体量轻便便于快速导入与查阅。目前已有229人学习下载可作为3DGS部署与训练阶段的参考起点帮助读者减少环境踩坑、理清数据准备与训练验证思路。1. 从一组模糊照片到可交互三维场景3DGS 部署训练到底在做什么手里有一批无人机航拍图或者手机环绕拍摄的短视频想快速重建出一个能实时旋转、缩放、查看细节的三维场景传统摄影测量流程往往要经历稀疏重建、稠密点云、网格化、纹理映射一长串步骤中间任何一环参数没调好最后出来的模型不是糊就是破面。3D Gaussian Splatting简称 3DGS这两年在三维重建圈子里热度一直没降过核心原因就一个它把场景表示成一堆带位置、协方差、颜色和不透明度的三维高斯球训练完之后直接光栅化渲染画质接近 NeRF速度却能跑到实时。这份 3DGS 部署与训练指南配套源码包解决的就是从环境搭建到训练出第一个可交互场景的完整链路问题适合有一定 Python 和 CUDA 基础、想在自己数据上跑通 3DGS 的开发者也适合做数字孪生、文物扫描、房产展示这类需要快速出三维资产的技术团队。2. 环境搭建与依赖编译CUDA 版本对不上的血泪经验2.1 为什么 3DGS 的环境比一般 Python 项目难搞3DGS 不是纯 Python 项目它的光栅化核心是用 CUDA 写的扩展模块训练时还要调用 PyTorch 的自动求导和自定义算子。这意味着你的 CUDA 驱动版本、CUDA Toolkit 版本、PyTorch 编译时用的 CUDA 版本、以及本地 nvcc 版本四者必须对齐。常见做法是先用nvidia-smi看驱动支持的最高 CUDA 版本再决定装哪个版本的 PyTorch最后用 conda 装对应版本的 cudatoolkit 和 nvcc。很多人翻车就翻在直接用 pip 装了最新版 PyTorch结果和系统里的 CUDA Toolkit 对不上编译扩展时报一堆undefined symbol或者no kernel image is available for execution on the device。我一般会先锁定一个组合比如 CUDA 11.8 PyTorch 2.1.x Python 3.10这个组合在 3DGS 社区里验证得比较多坑相对少。如果你用的是 40 系显卡CUDA 11.8 及以上都行但要注意 PyTorch 官方 wheel 对 sm_89 架构的支持情况。下面是一套我常用的环境初始化命令按顺序执行基本不会出大问题。# 创建独立环境避免污染主环境 conda create -n gs3d python3.10 -y conda activate gs3d # 安装 CUDA Toolkit 和 nvcc版本要和驱动匹配 conda install -c nvidia/label/cuda-11.8.0 cuda-toolkit -y # 安装 PyTorch注意 cu118 对应 CUDA 11.8 pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118 # 验证 PyTorch 是否能正确识别 CUDA python -c import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())这段命令的逻辑是先建一个干净的 Python 3.10 环境然后用 conda 装 CUDA Toolkit主要是为了拿到 nvcc 编译器再用 PyTorch 官方源装对应 CUDA 版本的 torch。最后那行验证很关键如果输出里torch.version.cuda是 11.8 且torch.cuda.is_available()为 True说明基础环境通了。参数上唯一需要你改的是 CUDA 版本号如果你驱动只支持到 11.6那就把 11.8 换成 11.6PyTorch 也换成 cu116 的 wheel。2.2 编译光栅化扩展与常见报错处理环境通了之后下一步是编译 3DGS 的 CUDA 扩展。源码包里一般会有submodules目录里面放着diff-gaussian-rasterization、simple-knn这些子模块。编译命令本身很简单但报错信息往往很隐晦。常见做法是进入子模块目录用pip install .或者python setup.py install来编译。如果编译时报nvcc not found说明 conda 装的 cuda-toolkit 没进 PATH需要手动把$CONDA_PREFIX/bin加进去。如果报unsupported gpu architecture就要在setup.py里显式指定TORCH_CUDA_ARCH_LIST环境变量比如export TORCH_CUDA_ARCH_LIST8.6对应 30 系显卡8.9对应 40 系。# 进入光栅化子模块目录 cd submodules/diff-gaussian-rasterization # 指定目标显卡架构避免编译出全架构导致时间过长或报错 export TORCH_CUDA_ARCH_LIST8.6 # 编译安装 pip install . --no-build-isolation # 回到项目根目录同样方式编译 simple-knn cd ../simple-knn pip install . --no-build-isolation这里--no-build-isolation的作用是让编译过程复用当前环境里已装好的 PyTorch 和 CUDA 头文件而不是另起一个隔离环境重新拉依赖能省不少时间也避免版本错乱。TORCH_CUDA_ARCH_LIST这个参数值得多说一句如果你不确定自己显卡的算力可以去查 NVIDIA 官方算力表30 系消费卡是 8.640 系是 8.9A100 是 8.0V100 是 7.0。设对了编译出来的扩展才能在你的卡上跑设错了要么编译失败要么运行时报内核镜像不匹配。提示编译完成后可以用python -c import diff_gaussian_rasterization快速验证是否安装成功不报错就说明扩展已就位。3. 数据准备与训练参数从 COLMAP 到第一个高斯模型3.1 用 COLMAP 做稀疏重建并整理目录结构3DGS 训练需要先有相机位姿和稀疏点云这部分通常交给 COLMAP 来做。输入就是你拍的那批照片输出是cameras.bin、images.bin、points3D.bin这几个文件。COLMAP 的图形界面操作比较直观但批量处理时用命令行更稳。常见做法是先用特征提取再做匹配最后做稀疏重建。如果是视频抽帧的图片帧间重叠度高用顺序匹配比穷举匹配快很多。重建完成后把输出整理成 3DGS 要求的目录结构一个input文件夹放原始图片一个sparse/0文件夹放 COLMAP 输出然后整个数据集目录作为训练输入。# 特征提取--ImageReader.single_camera 1 表示所有图片共用内参 colmap feature_extractor \ --database_path ./database.db \ --image_path ./input \ --ImageReader.single_camera 1 # 顺序匹配适合视频抽帧 colmap sequential_matcher --database_path ./database.db # 稀疏重建输出到 sparse 目录 colmap mapper \ --database_path ./database.db \ --image_path ./input \ --output_path ./sparse这三步做完后检查sparse/0下是否有cameras.bin、images.bin、points3D.bin。如果points3D.bin里点数太少比如只有几百个说明匹配质量不行可能是照片重叠度不够或者纹理太弱。这时候要么补拍要么在 COLMAP 里调低匹配阈值。参数上--ImageReader.single_camera 1适用于同一台相机拍的所有照片如果混用了不同设备就要设成 0 让 COLMAP 分别估计内参。3.2 训练命令与关键参数解读数据准备好之后就可以跑训练了。3DGS 的训练脚本一般叫train.py核心参数包括迭代次数、学习率、稠密化阈值等。默认配置在大多数场景下能出不错的结果但如果你想控制训练时长或者提升细节就需要理解几个关键参数。--iterations默认是 30000降到 7000 能快速看效果但细节会差一些。--densify_grad_threshold控制高斯球稠密化的梯度阈值调小会让更多高斯球被分裂模型更细但显存占用更高。--position_lr_init是位置学习率初始值场景尺度大时可以适当调大。# 基础训练命令 python train.py \ -s ./data/your_scene \ -m ./output/your_scene \ --iterations 30000 \ --densify_grad_threshold 0.0002 \ --position_lr_init 0.00016 # 如果显存不够降低分辨率或减少稠密化 python train.py \ -s ./data/your_scene \ -m ./output/your_scene \ --iterations 15000 \ --resolution 2 \ --densify_until_iter 10000-s指定数据集路径-m指定输出路径训练过程中的检查点、日志和最终的高斯模型都会存到-m目录下。--resolution 2表示下采样 2 倍能显著降低显存占用适合显存 8G 以下的卡。--densify_until_iter控制到第多少次迭代停止稠密化提前停止能防止高斯球数量爆炸。训练完成后output/your_scene下会有point_cloud/iteration_30000/point_cloud.ply这个文件这就是最终的高斯模型可以用查看器直接打开。注意训练过程中如果看到 loss 突然变成 NaN大概率是学习率太大或者输入数据里有异常位姿先检查 COLMAP 重建结果是否正常。4. 避坑与排查那些让训练白跑的常见问题4.1 显存溢出与高斯球数量失控现象训练到几千步就报CUDA out of memory或者显存占用一路涨到爆。原因通常是稠密化策略太激进高斯球数量在短时间内翻倍增长而显存没跟上。解决方法是调低--densify_grad_threshold的敏感度调大数值或者用--densify_until_iter提前结束稠密化再或者直接降分辨率训练。我一般会在训练脚本里加一个高斯球数量上限的判断超过阈值就停止分裂。4.2 COLMAP 位姿不准导致模型重影现象训练出来的场景看起来有两层或者边缘模糊重影。原因多半是 COLMAP 的相机位姿估计有偏差尤其是拍摄时运动模糊严重或者光照变化大的场景。解决办法是在 COLMAP 里开启--Mapper.ba_global_function_tolerance调优或者手动剔除重建误差大的图片。另一个常见做法是先用colmap model_analyzer看平均重投影误差超过 1.5 像素就要警惕。4.3 编译扩展时报架构不匹配现象pip install .编译成功但运行时提示no kernel image is available。原因是编译时TORCH_CUDA_ARCH_LIST没设对或者根本没设导致编译了默认架构。解决办法是删掉 build 目录重新编译显式指定自己显卡的算力值。如果用的是云服务器先确认实例的 GPU 型号再设。4.4 训练 loss 不下降或震荡现象loss 曲线一直在高位震荡不收敛。原因可能是学习率设得太大或者输入图片分辨率差异太大。解决办法是把--position_lr_init和--scaling_lr都调小一个数量级试试同时检查图片是否都统一了尺寸。另外如果 COLMAP 输出的稀疏点云里有很多离群点也会干扰训练可以在 COLMAP 里做一次点云滤波。4.5 渲染查看器打不开或黑屏现象训练完用viewer.py或者 SIBR 查看器打开界面黑屏或者报 OpenGL 错误。原因通常是查看器依赖的 OpenGL 版本和显卡驱动不匹配或者远程连接时没有 GPU 直通。解决办法是在本地机器上查看或者用--rendering_mode切换到软件渲染模式。如果是服务器环境确认是否加载了libGL库。5. 进阶技巧用 Python 脚本批量评估与导出训练出模型只是第一步实际项目里往往需要批量跑多个场景还要对结果做量化评估。3DGS 官方提供了render.py和metrics.py两个脚本前者渲染测试视角的图片后者计算 PSNR、SSIM、LPIPS 三个指标。我一般会写一个外层脚本遍历数据集目录自动完成训练、渲染、评估三步最后把指标汇总成 CSV。这样跑几十个场景时不用手动一个个点。import subprocess import os import csv # 数据集根目录每个子目录是一个场景 data_root ./data output_root ./output results [] for scene in os.listdir(data_root): scene_path os.path.join(data_root, scene) if not os.path.isdir(scene_path): continue out_path os.path.join(output_root, scene) # 训练 subprocess.run([ python, train.py, -s, scene_path, -m, out_path, --iterations, 30000, --eval # 开启评估模式划分训练测试集 ], checkTrue) # 渲染测试视角 subprocess.run([ python, render.py, -m, out_path, --eval ], checkTrue) # 计算指标 subprocess.run([ python, metrics.py, -m, out_path ], checkTrue) # 读取指标结果假设 metrics.py 输出到 results.json import json with open(os.path.join(out_path, results.json)) as f: metric json.load(f) results.append({ scene: scene, psnr: metric.get(psnr), ssim: metric.get(ssim), lpips: metric.get(lpips) }) # 汇总写入 CSV with open(summary.csv, w, newline) as f: writer csv.DictWriter(f, fieldnames[scene, psnr, ssim, lpips]) writer.writeheader() writer.writerows(results)这段脚本的核心逻辑是串行调度三个官方脚本--eval参数很关键它会让训练时按 7:1 划分训练集和测试集这样metrics.py才有测试视角可算。checkTrue保证任何一步失败就中断避免脏数据混进汇总表。最后输出的summary.csv可以直接丢进 Excel 或者 pandas 做对比分析。参数上唯一要注意的是metrics.py的输出格式不同版本的 3DGS 源码可能输出到不同文件需要根据实际源码调整读取逻辑。另一个实用技巧是导出高斯模型到其他格式。.ply文件虽然通用但有些三维软件不直接支持。常见做法是用plyfile库读取高斯参数然后转成点云或者 mesh 格式。不过要注意高斯球转 mesh 会丢失视角相关的颜色信息只适合做几何参考。如果只是想在网页里展示直接用 3DGS 的 WebGL 查看器加载.ply就行不需要转换。从那以后我每次跑新场景都会先用 7000 步快速训一版看位姿和大致效果确认没问题再上 30000 步完整训练这样能省下大量白跑的时间。希望帮到你。本文还有配套的精品资源点击获取