NeRF-SLAM从零环境搭建：CUDA、PyTorch与GTSAM编译避坑

简介：面向希望深入理解并动手复现NeRF-SLAM的研究者与三维重建开发者，这份文档聚焦神经辐射场与SLAM结合的稠密建图方案，着力解决复现中概念密集、模块耦合强、排错路径不清等问题。资源包为1个docx文件，约11.01MB，正文以图文、公式和模块说明组织，兼具复现范文、模板与素材参考价值，便于按主题查阅。内容梳理跟踪阶段的带协方差稠密SLAM、光流估计与Droid SLAM改进，并拆解稠密光束法平差层中舒尔补、乔尔斯基分解以及相机位姿和逆深度求解；映射部分覆盖概率体素神经辐射场、哈希编码加速、映射损失与深度监督，结合有噪声深度和姿态下的收敛表现说明设计动机。文档还记录作者复现时遇到的问题与解决方案，可帮助读者建立从原理到工程实现的完整认知，快速定位关键公式、模块关系与调试思路。已有2327人学习。

1. 一台能跑 nerf-slam 的机器，先别急着 clone

上周有人问我 nerf-slam 复现文档里最难的一步是什么，我说不是跑数据集，是让它编译通过。这台机器上 CUDA 是该有的，Python 也是该有的，但cmake --version一敲出来是 3.16，instant-ngp 直接告诉你版本不够；好不容易把 CMake 换到 3.22，GTSAM 又因为系统 Boost 停在 1.65 而拒绝配置。nerf-slam 这套三维重建方案把 Droid-SLAM 的位姿跟踪和 Instant-NGP 的哈希编码辐射场缝在一起，输入只要连续单目 RGB 就能出稠密建图，效果确实漂亮，但它对工具链版本的要求比一般视觉 SLAM 项目苛刻得多——CMake、CUDA、Boost、GTSAM Python 包装四样里有一样对不上，编译就会停在半路。这篇东西适合手里有 8G 以上显存的 N 卡、准备把这套环境从零装一遍的人。

2. 环境盘底：CUDA 11.3、torch 1.12.1+cu113 与 CMake 3.22 的版本账

装 nerf-slam 之前我一般会先在一张纸上写清楚要装哪几个东西、各自什么版本，因为这套仓库的子模块互相咬得很紧：instant-ngp 要 CMake 3.22 以上，GTSAM 的 Python 包装要能找到 Boost 和 pybind11，torch 版本又决定了你能不能直接用官方编译好的 cu113 轮子。先动手 clone 再回头补版本，通常的结果是删掉 build 目录重来三遍。

2.1 显卡驱动、CUDA 与 torch 1.12.1+cu113 的对应关系

torch 1.12.1 的 cu113 轮子意味着它编译时链接的是 CUDA 11.3 运行时，本机驱动只要不低于 CUDA 11.3 要求的下限（470 系列往上比较稳）就能跑，不需要本机装一模一样的 CUDA Toolkit。这一点很容易误解：很多人以为必须nvcc --version显示 11.3，其实只有你要自己编译 CUDA 扩展时才需要完整 Toolkit，装 PyTorch 轮子只需要驱动支持。

我一般会按下面这张表核对，四项里有一项对不上就先解决它，别往下走：

显存这块也提前说一句：Instant-NGP 的 hash 编码本身不轻，加上 Droid-SLAM 的光流相关体积，8G 能跑小场景，12G 以上才谈得上舒服。装环境阶段用nvidia-smi隔几秒刷一次，能提前发现驱动和卡状态的问题，省得后面把显存不足误判成代码 bug。

2.2 克隆仓库与子模块递归拉取

nerf-slam 的仓库把 instant-ngp、gtsam、Droid-SLAM 都做成了子模块，普通git clone拉下来的thirdparty/目录是空的，后面 cmake 一定会报找不到路径。所以第一条命令就得带递归参数：

# 递归拉取主仓库和所有子模块，--recurse-submodules 不能省 git clone https://github.com/ToniRV/NeRF-SLAM.git --recurse-submodules cd NeRF-SLAM # 兜底：如果中途网络断了，子模块可能只拉了一半，这条会补齐 git submodule update --init --recursive

--recurse-submodules的作用是克隆完成后立刻对每个子模块执行一次 init 和 update；第二条命令是保险，子模块下载中断时它会把缺的部分补上，已经完整的子模块会跳过。判断有没有拉全，看thirdparty/instant-ngp和thirdparty/gtsam里有没有实际的源码文件，只有.git文件说明还是空壳。这一步失败最常见的原因就是网络抖动，重跑git submodule update --init --recursive比删仓库重来划算。

2.3 虚拟环境与两份 requirements 的安装顺序

仓库里有两份依赖清单，一份在根目录，一份在thirdparty/gtsam/python/下，作用完全不同：前者是 nerf-slam 主程序要用的（包含光流、可视化、数据集读取那一套），后者是 GTSAM Python 包装自己的依赖。两份都要装，而且顺序有讲究——先装 torch，再装根目录 requirements，最后装 gtsam 那份，否则某些包会顺着依赖把 CPU 版 torch 又装一遍。

# 建独立虚拟环境，避免和系统 Python 的包打架 python3 -m venv ~/envs/nerfslam source ~/envs/nerfslam/bin/activate python -V # 确认是 3.8 或 3.9 # 先装 torch，--extra-index-url 指向 PyTorch 官方 cu113 轮子源 pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 \ --extra-index-url https://download.pytorch.org/whl/cu113 # 再装主仓库依赖 pip install -r requirements.txt # 最后装 gtsam 子模块的 Python 依赖 pip install -r ./thirdparty/gtsam/python/requirements.txt

--extra-index-url是追加索引而不是替换默认索引，所以 pip 仍然会去 PyPI 找其他包，只是 torch 这类带+cu113本地版本号的包从这个源拿。装完务必验证一次torch.cuda.is_available()，返回 False 说明驱动或轮子版本不匹配，这时候继续往下编译 ngp 只是在给自己挖坑。

提示：pip install torch不带版本号时会装最新版，最新版的 CUDA 运行时和后面的 GTSAM、pybind11 组合没验证过，别图省事。

3. 编译 instant-ngp：CMake 3.22 的选择与 GLEW 缺失的处理

instant-ngp 是 nerf-slam 里负责哈希编码辐射场的那部分，编译它需要 CMake 3.22 以上和一套 OpenGL 相关的开发库。这一章的坑集中在两个地方：CMake 版本太低导致 configure 直接退出，以及 GLEW 找不到导致链接阶段失败。前者是版本问题，后者是系统库问题，处理方式完全不同。

3.1 CMake 升到 3.22 的三条路与取舍

系统包管理器里的 CMake 往往停在 3.16 甚至更低，Ubuntu 20.04 的 apt 源就是 3.16.3，够不着 instant-ngp 的门槛。升级有三条路：apt 加第三方源、pip 装、官方预编译包解压。我一般选第三条，因为不动系统包、可回退、也不需要 root 权限覆盖/usr/bin/cmake。

# 下载官方预编译包，3.22 是 instant-ngp 的最低要求 wget https://cmake.org/files/v3.22/cmake-3.22.0-rc2-linux-x86_64.tar.gz --no-check-certificate # 解压后可以直接用，也可以把 bin 目录塞进 PATH tar -zxvf cmake-3.22.0-rc2-linux-x86_64.tar.gz export PATH=$PWD/cmake-3.22.0-rc2-linux-x86_64/bin:$PATH # 刷新 shell 的命令哈希缓存，否则 cmake 还指向 /usr/bin 下那个旧版本 hash -r cmake --version

hash -r这一步看起来多余，实际是最容易被忽略的：bash 会缓存命令路径，PATH 改了但cmake还解析到旧位置，cmake --version显示的还是 3.16，于是你以为没生效又去折腾一遍。如果想让改动持久，把 export 那行写进~/.bashrc。

这里还有个版本选择的问题值得说：3.22.0-rc2是候选发布版，能用但不建议长期用；正式版3.22.x或者原文提到的3.26.3更稳。从源码编译的方式（./bootstrap && make && sudo make install）我也试过，慢、容易因为缺 OpenSSL 开发包中断，除非你机器上完全没有现成包，否则不推荐。原文里 3.9 那段是历史遗留的折腾记录，对 instant-ngp 没用，可以跳过。

3.2 cmake 配置 instant-ngp 与 GLEW 报错

配置阶段用-B指定构建目录，把产物和源码分开，后面重建直接删目录就行：

# 在 nerf-slam 根目录执行，-B build_ngp 指定构建目录 cmake ./thirdparty/instant-ngp -B build_ngp

正常情况这条命令会打印一堆依赖探测结果然后生成 Makefile。如果看到下面这行，说明系统缺 GLEW 的开发头文件，不是 CMake 的问题：

# 典型报错 # Could NOT find GLEW (missing: GLEW_INCLUDE_DIRS GLEW_LIBRARIES) sudo apt install libglew-dev

GLEW 是 OpenGL 的扩展加载库，instant-ngp 的交互式查看器要用它；libglew-dev提供头文件和.so符号链接，缺了它 configure 阶段就判定依赖不全。同类问题还会出现在 GLFW 上，报错形如Could NOT find glfw3，对应包是libglfw3-dev。装完不用重新 clone，直接重跑同一条cmake ./thirdparty/instant-ngp -B build_ngp即可，CMake 会重新走一遍探测。

3.3 编译参数 RelWithDebInfo 与 -j 并发度

配置通过后进入编译。instant-ngp 的编译时间跟 CPU 核数强相关，编辑部级的机器十几分钟，四核虚拟机一小时也正常：

# RelWithDebInfo 带优化又保留调试符号，崩了能看栈 cmake --build build_ngp --config RelWithDebInfo -j$(nproc)

--config RelWithDebInfo是给多配置生成器用的，单配置生成器（Unix Makefiles）也会把它映射成-O2 -g，效果是比 Release 慢一点点，但 segfault 时能拿到可读的调用栈，调 NeRF 这种数值敏感的代码时很值。-j$(nproc)用满核数，内存小于 16G 的机器建议改成-j4，并行编译多个 CUDA 相关翻译单元时内存飙得很快，OOM killer 把 cc1plus 杀掉的表现就是一句没头没尾的internal compiler error。

编译成功的标志是build_ngp目录下出现可执行文件和依赖库。这一步没过后面的 GTSAM 就别急着弄，先确认 ngp 能独立编过，问题范围才收得住。

4. 编译 GTSAM 与 Python 包装：Boost 1.73 从源码装一遍

GTSAM 是 DBA 层的底层依赖，nerf-slam 要把位姿和逆深度的优化交给它，所以必须编出 Python 包装（-DGTSAM_BUILD_PYTHON=1），否则 import 一跑就断。这一步的拦路虎是 Boost：GTSAM 要求 1.65 以上，很多系统自带的就是 1.65 边缘版本，而 pybind11 又要靠 Boost.Python 的头文件，版本不齐就配置不过。

4.1 GTSAM_BUILD_PYTHON=1 到底打开了什么

# 在 nerf-slam 根目录执行，开启 Python wrapper cmake ./thirdparty/gtsam -DGTSAM_BUILD_PYTHON=1 -B build_gtsam

-DGTSAM_BUILD_PYTHON=1打开的是 GTSAM 的 pybind11 绑定模块，它会额外编译一个gtsam*.so供 Python 直接 import。这个选项一开，CMake 就会去找 Boost.Python 组件、pybind11、以及当前 Python 解释器的头文件，任何一个缺失都会在 configure 阶段报错。所以这一步必须在已经激活虚拟环境的前提下做，否则它探测到的是系统 Python，编出来的.so装不进你的 venv。

如果报的是下面这条，直接进 4.2：

# 典型报错 # Could NOT find Boost (missing: Boost_INCLUDE_DIR serialization system filesystem # thread program_options date_time timer chrono regex) (Required is at least version "1.65")

报错里那一长串组件名说明 CMake 连 Boost 的根目录都没定位到，不是缺某一个库，是整个 Boost 没装或版本太老。

4.2 Boost 1.73 源码编译与 --prefix 的取舍

发行版自带的 Boost 版本往往卡在及格线上，而且组件不一定全，最省事的做法是源码编一份 1.73。Boost 的构建系统分两步：bootstrap.sh生成b2，再用b2编译安装。

# 下载并解压源码 wget https://boostorg.jfrog.io/artifactory/main/release/1.73.0/source/boost_1_73_0.tar.bz2 --no-check-certificate tar xvf boost_1_73_0.tar.bz2 cd boost_1_73_0 # 生成 b2，同时指定 Python 版本，避免多 Python 环境时认错 ./bootstrap.sh --with-python=python3 # 完整安装，--buildtype=complete 保证所有需要的组件都编出来 sudo ./b2 --buildtype=complete install -j$(nproc)

几个参数值得解释。--with-python=python3用来锁定 Python 版本，机器上同时有 3.8 和 3.10 时，Boost.Python 编到哪个版本决定了 GTSAM 的包装能不能 import，写死更保险。--buildtype=complete会编译 Boost 的全部组件，包括报错里点名的那七八个，代价是时间长；如果你只想省时间，可以用--with-system --with-filesystem --with-serialization --with-thread --with-program_options --with-date_time --with-timer --with-chrono --with-regex精确指定。

关于安装路径：默认装到/usr/local/lib和/usr/local/include，CMake 的默认搜索路径包含这两个位置，所以不需要额外配环境变量，这是最省心的选择。如果加了--prefix=/opt/boost，那就得在之后每次 cmake 时补-DBOOST_ROOT=/opt/boost，还得往LD_LIBRARY_PATH里加路径，多出来的每一步都是潜在故障点。我的习惯是宁可装到默认路径，也不要为了「整洁」给自己加配置负担。

装完刷新一下动态库缓存，让系统认得新库：

sudo ldconfig ls /usr/local/lib | grep boost_python # 应该能看到对应版本的 .so

4.3 回到 GTSAM 重新配置并验证 import

Boost 装好之后，删掉之前失败的 build 目录重来，因为 CMake 会缓存「找不到 Boost」这个结论，不清理的话它不会重新探测：

rm -rf build_gtsam cmake ./thirdparty/gtsam -DGTSAM_BUILD_PYTHON=1 -B build_gtsam cmake --build build_gtsam -j$(nproc) sudo cmake --build build_gtsam --target install

--target install会把编好的库和 Python 模块装到/usr/local/lib/python3.x/site-packages或 GTSAM 指定的位置。装完之后在虚拟环境里验证：

# 确认能导入，且版本号打得出来 python -c "import gtsam; print(gtsam.__version__)"

如果这里抛ModuleNotFoundError，先别怀疑编译失败，八成是模块装进了系统 site-packages 而 venv 看不到。用python -c "import sys; print(sys.path)"对比一下安装路径，把 GTSAM 的安装目录补进PYTHONPATH即可，export PYTHONPATH=/usr/local/lib/python3.8/site-packages:$PYTHONPATH是常见写法，路径按实际版本号改。

5. 避坑与排查：五个把我按在椅子上的现场

装这套环境，报错信息大多不长，但指向性差。下面五条是我和身边的人真实卡过的，按「现象 → 原因 → 解决」记一遍，遇到时能少走弯路。

子模块目录是空的，cmake 报路径不存在。现象是cmake ./thirdparty/instant-ngp提示The source directory ... does not exist，ls thirdparty/instant-ngp只有一个.git文件。原因是 clone 时没带--recurse-submodules，或者子模块下载中途网络断了。解决是回到仓库根目录执行git submodule update --init --recursive，如果反复失败，删掉thirdparty/instant-ngp目录再执行一次，比整个仓库重 clone 快得多。

CMake 显示已经是 3.22，instant-ngp 仍然报版本不够。现象是cmake --version明明是 3.22，configure 却输出CMake 3.22 or higher is required。原因是 shell 命令哈希缓存还指向旧的/usr/bin/cmake，或者 PATH 顺序里/usr/bin在前面。解决是先hash -r，再which -a cmake确认解析顺序，必要时把新版本路径放到 PATH 最前面，或者干脆用alias cmake=/opt/cmake-3.22/bin/cmake显式指定。

Boost 装完，GTSAM 依旧报同样的找不到。现象是ls /usr/local/lib能看到libboost_python38.so，但重新 cmake 还是那条Could NOT find Boost。原因是build_gtsam目录里缓存了上一次的探测结果，CMakeCache.txt 里Boost_INCLUDE_DIR-NOTFOUND一直没被覆盖。解决是rm -rf build_gtsam后重新 configure，这也是为什么我习惯失败就删构建目录，比在缓存里做手术省事。

import gtsam 成功，但 import torch 之后进程直接崩。现象是单独 import 两个包都没问题，一起用就 segfault 或者报undefined symbol。原因是两套库链接了不同的 C++ ABI 或不同的 Python 版本，常见于系统里同时存在 conda 的 Python 和 pyenv 的 Python，而 Boost 是按另一个解释器编的。解决是统一解释器：确认which python指向虚拟环境内的那个，重编 Boost 时--with-python=指到同一个，然后重装 GTSAM 包装。

编译到一半报internal compiler error或直接被 Killed。现象是编译日志没有语法错误，只有一行c++: internal compiler error: Killed (program cc1plus)或者Killed。原因是并行度太高，多个重模板翻译单元同时展开吃光了内存，OOM killer 开始杀进程。解决是-j降到 4 甚至 2，free -h观察剩余内存，必要时临时加 swap。这条最容易误判成代码问题，尤其是日志里完全没有 error 关键字的时候。

注意：这五条里有三条是缓存和路径问题，不是真的缺依赖。遇到报错先确认「报错的东西是不是真的不在」，再动手装，能省掉一半无效重装。

6. 装完怎么验证：三步冒烟测试与显存观察

环境装到最后一步，最忌讳的是直接上完整数据集。正确做法是先跑一个最小验证链，把「能不能 import」「编译产物在不在」「能不能跑起来」三件事分开确认，出错时才能快速定位是哪一层的问题。

我一般按下面这个顺序走，每一步都有明确的期望输出：

第二步只是看文件存在，第三步才是关键：能 importgtsam不等于能用类，很多失败的包装在 import 时不报错，一构造对象就抛undefined symbol。所以一定要实例化一个最基础的对象试探。

# 一条命令把三项检查串起来，任何一步失败都会中断 set -e python -c "import torch; assert torch.cuda.is_available(), 'CUDA 不可用'; print('torch ok', torch.version.cuda)" python -c "from gtsam import Pose3; print('gtsam ok', Pose3())" [ -d build_ngp ] || { echo "ngp 未构建"; exit 1; } echo "all checks passed"

set -e让脚本在任一命令非零退出时立刻停下，避免前一步失败后继续往下走造成误判。assert torch.cuda.is_available()这一句能挡住「装成了 CPU 版 torch」这个最常见的隐性错误，很多人在后面跑训练时才发现速度慢得离谱，其实从头到尾都没用上卡。

三步都过了，再拿一个小场景跑通一次前向。跑的时候另开一个终端盯着显存：

# 每 2 秒刷一次显存占用，观察是否持续上涨 watch -n 2 nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv

健康的曲线是显存快速上升到某个平台期后小幅波动，如果一路涨到接近上限然后进程被杀，说明场景规模超出了卡的承受范围，先降分辨率或换更短的序列，别急着改代码里的超参。反过来，如果显存几乎不动、GPU 利用率长期为 0，那就是数据没读进去或者计算落在了 CPU 上，回头查 torch 的 CUDA 状态和数据集路径。

这套环境里最容易反复出问题的环节，其实是「装完看起来能跑，但跑出来是错的」。比如 GTSAM 包装虽然能 import，但链接的是错误 Python 版本的 Boost.Python，在优化阶段才会以段错误的形式暴露；又比如 instant-ngp 编译时没开RelWithDebInfo，崩了连调用栈都没有，只能靠猜。从那以后我每次装完这套环境，都强制把上面那张表的三步走一遍，再看三十秒显存曲线，才允许自己开始跑数据。这个习惯帮我挡掉过好几次「看起来装好了」的假象。

这份复现文档里把从 clone、torch 安装、CMake 升级、GLEW 处理到 Boost 源码编译的完整链路都记了下来，包括每一步的报错原文和对应解法，照着走比自己在报错里打转快得多。装的时候把这份记录放在旁边对照，遇到卡住的地方先查表里的现象列，多半能找到对得上的那一条。希望帮到你。

本文还有配套的精品资源，点击获取