在 Ubuntu 20.04 上把 IS-Fusion 环境从零搭起来比我想象中要曲折得多。这个项目本身不复杂真正麻烦的是 CUDA 11.1、PyTorch 1.10.1 和系统驱动三者之间的匹配关系稍微有一个版本对不上编译的时候就会冒出一堆看似莫名其妙、实际上全靠经验才能定位的报错。这篇文章把我从裸机开始部署的全部过程、踩过的坑、排查思路都整理出来了包括为什么非要这个版本组合、哪些地方可以偷懒、哪些命令必须在 root 权限下执行。不管你是第一次接触神经三维重建还是已经在不少环境里折腾过照着这套流程走基本能一次点亮。1. 部署思路和版本选型先把环境地图走通再动手装1.1 IS-Fusion 的依赖链条到底有多长IS-Fusion 本质上是一个基于深度学习的多视角三维重建项目运行链路里既有 Python 端的推理代码又有需要编译的 CUDA 扩展还牵扯到三维点云处理和可视化。这类项目的依赖通常不是“pip install 完事”它至少包含这么几层底层 CUDA 运行时和驱动负责调用 GPU 算力驱动版本必须能支撑 CUDA 11.1。PyTorch 生态PyTorch 1.10.1 在编译时依赖 CUDA 11.1 的算子库torchvision 又依赖 PyTorch 的版本接口。CUDA 扩展IS-Fusion 里用到的部分算子不会都出现在 PyTorch 官方安装包里项目可能需要从源码编译 tiny-cuda-nn 这类高性能 CUDA 扩展。Python 库Open3D、OpenCV、NumPy、trimesh 等分别负责点云读写、图像读取、张量处理和网格处理。关键在于这一整条依赖链每一环都有版本约束它们不是互相独立的。你可以在 PyPI 上装一个最新版 NumPy但那可能会让旧版 PyTorch 直接报错你可以在系统里装一个很新的驱动但未必能和 CUDA 11.1 的编译工具链完美配合。所以我在动手之前把所有版本约束先写在纸上逐个确认兼容范围而不是直接抄 README 的命令。1.2 版本选型的核心原则先看兼容性表再看 README很多人拿到项目第一反应是打开 README按部就班执行。这个思路没错但 README 往往只写了“建议用 CUDA 11.1 PyTorch 1.10.1”不会告诉你这些版本是开发者在某台固定机器上验证过的更不会告诉你为什么 Ubuntu 20.04 是相对稳妥的选择。我当时选型的基本原则是不追新只看兼容矩阵。PyTorch 1.10.1 官方发布的预编译包里有四种 CUDA 变体分别为 CPU、CUDA 10.2、CUDA 11.1、CUDA 11.3。其中 CUDA 11.1 是 IS-Fusion 依赖链里被验证次数最多的版本因为项目源码中的 CMake 编译脚本和扩展模块大多是在这个 CUDA 版本下调整过的。Ubuntu 20.04 的默认 GCC 是 9.4而 CUDA 11.1 对 GCC 的支持范围恰好覆盖了 GCC 6 到 GCC 9这意味着不需要额外切换编译器版本。相比之下Ubuntu 22.04 的默认 GCC 已经是 11直接编译 CUDA 11.1 的代码时会遇到大量不匹配警告有些甚至直接致命。所以如果项目没明确支持新版系统老老实实装 Ubuntu 20.04 反而是节省时间的方式。1.3 硬件上需要做好哪些确认开始之前先用最简单的方式确认手头机器的 GPU 型号并判断其计算能力是否被项目支持。执行下面命令lspci | grep -i nvidia也可以用nvidia-smi不过新系统还没装驱动时这条命令大概率不可用。一般来说IS-Fusion 这类只需 CUDA 11.1 的项目对显卡要求并不算苛刻GTX 10 系列、RTX 20 系列、RTX 30 系列都能跑但不同架构对应的计算能力不同比如 GTX 1080 Ti 是 6.1RTX 2080 Ti 是 7.5RTX 3090 是 8.6。提前知道这个数字很重要后面编译 CUDA 扩展时需要精准设置TORCH_CUDA_ARCH_LIST否则要么编译报错要么编译出来的算子根本无法在当前显卡上执行。还要确认内存和磁盘空间。建议系统盘至少预留 30GB 以上光是 CUDA Toolkit、conda 环境和项目依赖加起来就很容易超过 10GB如果还打算下载数据集做训练空间需求会更大。内存方面16GB 是最低要求32GB 会舒服很多因为三维重建项目在处理点云和稠密网格时经常会出现短暂的高内存占用。2. Ubuntu 20.04 系统准备从装系统到点亮 NVIDIA 驱动2.1 系统安装与 apt 源加速部署环境的第一步是装一个干净的 Ubuntu 20.04。这里建议安装桌面版虽然纯服务器版更轻量但后续如果你想快速查看可视化结果或调试三维渲染桌面环境能省掉不少麻烦。安装过程中选择最小安装即可不需要额外装第三方软件。系统装好之后第一件事是更新 apt 源。默认源在国外下载速度通常很慢可以替换成清华镜像源Ubuntu 20.04 的代号是 focal对应路径如下sudo sed -i shttp://archive.ubuntu.com/ubuntuhttp://mirrors.tuna.tsinghua.edu.cn/ubuntug /etc/apt/sources.list sudo sed -i shttp://security.ubuntu.com/ubuntuhttp://mirrors.tuna.tsinghua.edu.cn/ubuntug /etc/apt/sources.list sudo apt update如果你当初安装时选择的镜像源不是官方源sources.list 里的地址可能已经不同那就手动编辑/etc/apt/sources.list确保里面出现的是mirrors.tuna.tsinghua.edu.cn/ubuntu。更新完成后顺手把基础编译工具装上sudo apt install -y build-essential gcc g make wget git这里有个隐藏坑Ubuntu 20.04 默认自带 GCC 9.4正合适但如果你之前装过build-essential或者通过其他方式升级了 GCC就要检查一下版本避免冲掉 CUDA 11.1 的编译兼容性。2.2 安装 NVIDIA 驱动并禁用 nouveauUbuntu 20.04 默认显卡驱动是开源的 nouveau深度学习根本没法用必须换成 NVIDIA 官方驱动。最推荐的方式不是去官网手动下驱动安装包而是直接用 Ubuntu 自带的 ubuntu-drivers 工具sudo ubuntu-drivers devices执行后系统会列出当前机器可用的 NVIDIA 驱动版本并标注recommended。我当时看到推荐版本是 470果断直接安装sudo apt install -y nvidia-driver-470安装过程中会自动处理一部分 nouveau 禁用逻辑但为了保险我建议手动再写一个 blacklist 文件防止重启后 nouveau 又抢占显卡sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nvidia-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nvidia-nouveau.conf sudo update-initramfs -u sudo reboot重启后如果看到桌面正常说明驱动基本没问题如果黑屏或者卡在登录界面可能是驱动和 display manager 冲突可以在 GRUB 启动项里加nomodeset参数临时绕过再排查驱动安装细节。注意这一步千万别跳过“禁用 nouveau”否则你后面运行nvidia-smi时大概率会看到一个couldnt communicate with the NVIDIA driver的报错问题定位起来很闹心。2.3 验证驱动、gcc 和基础编译环境重启后打开终端查看驱动是否生效nvidia-smi正常情况下会显示类似这样的信息NVIDIA-SMI 470.xx.xx Driver Version: 470.xx.xx CUDA Version: 11.4注意这里的CUDA Version是驱动支持的最高 CUDA 版本不代表系统已经装了 CUDA Toolkit也不代表项目能用 11.4 编译。只要这个数字大于等于 11.1驱动层面就满足要求了。然后再确认一下编译器版本和基本环境gcc --version python3 --versiongcc 9.x 是理想结果。python3 版本不关键因为后面会用 conda 单独创建环境。到这里系统层准备就完整了可以开始处理深度学习环境。3. 安装 CUDA 11.1 和 PyTorch 1.10.13.1 为什么系统要装 CUDA Toolkit而不是全靠 PyTorch不少新手会天真地以为PyTorch 预编译包里已经带了 CUDA 运行时就不需要再单独装 CUDA Toolkit 了。这个想法只对了一半。PyTorch 的 cu111 wheel 确实捆绑了部分 CUDA 动态库但并没有捆绑 nvcc 编译器也没有完整的 CUDA 头文件。当你需要从源码编译 CUDA 扩展时编译器找不到cuda_runtime.h就会直接报错。所以系统层面必须有一个完整的 CUDA Toolkit。我这里选择安装 CUDA 11.1.1下载地址和安装命令如下wget https://developer.download.nvidia.com/compute/cuda/11.1.1/local_installers/cuda_11.1.1_455.32.00_linux.run chmod x cuda_11.1.1_455.32.00_linux.run sudo sh cuda_11.1.1_455.32.00_linux.run --toolkit --silent --no-opengl-libs安装时添加--toolkit参数表示只安装编译器和开发库不重复安装 NVIDIA 驱动--no-opengl-libs可以避免和桌面的 OpenGL 库冲突。安装完成后CUDA 会被放到/usr/local/cuda-11.1然后把相关路径写入 bashrcecho export PATH/usr/local/cuda-11.1/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-11.1/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc验证一下nvcc --version如果能输出版本号系统 CUDA 环境就准备好了。3.2 PyTorch 1.10.1cu111 的安装方式PyTorch 的安装必须用 PyTorch 官方提供的 cu111 预编译包不能直接从默认 PyPI 源安装否则装出来的是最新版或者 CPU 版本。推荐用 conda 创建环境后在环境内部执行conda create -n isfusion python3.8 -y conda activate isfusion pip install torch1.10.1cu111 torchvision0.11.1cu111 torchaudio0.10.1 --extra-index-url https://download.pytorch.org/whl/cu111这里有个重要细节--extra-index-url https://download.pytorch.org/whl/cu111不是装饰它会告诉 pip 去 PyTorch 官方索引里寻找带cu111的包。如果只写pip install torch1.10.1pip 会从 PyPI 搜索一个叫torch的包而 PyPI 上的 1.10.1 大概率是 CPU 版本后面直接浪费你半天时间。PyTorch 1.10.1 对应的 torchvision 版本必须是 0.11.1torchaudio 必须是 0.10.1这三个版本是官方锁定的组合不能混搭。装完先跑一条最关键的验证命令python -c import torch; print(torch.__version__, torch.cuda.is_available())看到1.10.1cu111 True就说明 PyTorch 和 GPU 成功搭上线了。3.3 使用 conda 隔离 Python 环境我没有把 Python 依赖直接装在系统 python3 里而是用了 Miniconda 来隔离。无论是 Anaconda 还是 Miniconda核心价值都一样避免不同项目之间因为包版本不同而互相打架。IS-Fusion 这类源码项目很可能同时需要 numpy、open3d、opencv 等依赖如果直接装在系统环境里升级系统 Python 包时很容易把环境弄崩。装 Minicondawget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh source ~/.bashrc创建环境时我用了 Python 3.8而不是最新版。原因很简单PyTorch 1.10.1 时代官方支持的 Python 版本最高到 3.9而 3.8 是当时生态最稳的版本许多基于 PyTorch 的旧项目对 3.8 的兼容性都验证过。如果你的电脑上已经存在了别的 conda 环境不要偷懒直接conda activate base务必新建独立环境后面一旦依赖崩溃删除重建是最快的恢复方案。提示我个人习惯在项目目录里放一个requirements-lock.txt把完整的 pip 依赖版本列出来方便完全复现实验环境。人为控制版本比依赖项目 README 里的“最新版”靠谱得多。4. IS-Fusion 依赖编译CUDA 扩展是最容易翻车的地方4.1 编译前必设的环境变量和工具链检查IS-Fusion 项目里通常会有几个需要从源码编译的 CUDA 扩展常见的就是 tiny-cuda-nn 这类高性能算子库。这些扩展既没有现成的 pip wheel也无法直接用pip install从网上下载编译好的包必须依靠你本机的 nvcc 编译器现场构建。编译前先确认以下环境变量确保 CUDA 工具链能被正确找到export CUDA_HOME/usr/local/cuda-11.1 export PATH/usr/local/cuda-11.1/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.1/lib64:$LD_LIBRARY_PATH nvcc --version然后把这几行也写进~/.bashrc防止每次开新终端都要手动 export。接下来最关键的变量是TORCH_CUDA_ARCH_LIST它告诉编译器要为哪些 GPU 架构生成算子。如果设置错误编译会报类似Unsupported gpu architecture的错误或者编译成功后在运行时提示算子不支持当前设备。根据你自己的显卡架构来设置export TORCH_CUDA_ARCH_LIST6.1;7.0;7.5;8.6这段的意思是同时编译支持 GTX 10 系、RTX 20 系、RTX 30 系的算子编译时间会长一些但兼容性最好。如果你确定只用一张卡比如 RTX 3090可以把范围缩到8.6能明显加快编译速度。注意如果项目里的 CMakeLists 写死了sm_86之类架构而你设置的范围不包括它会直接编译失败所以不要盲目追求“越小越好”。4.2 CUDA 扩展编译常见报错我在编译过程中遇到的第一个高频报错是fatal error: cuda_runtime.h: No such file or directory看到这个先别慌它基本可以断定是CUDA_HOME没设置或者设置指向了不存在的路径。在编译进程的环境变量里CUDA_HOME是扩展构建脚本用来定位头文件的基准路径。我见过有人把CUDA_HOME设置成/usr/local/cuda但这个软链接在安装 11.1 时可能并不存在或者指向了其他版本这种情况需要检查一下ls -l /usr/local/如果没有/usr/local/cuda-11.1或者/usr/local/cuda指向不对重新执行 CUDA Toolkit 安装时使用的--prefix或者手动创建软链接即可。注意不要只设置PATH不设置LD_LIBRARY_PATH否则编译阶段能过运行时还会在加载动态库这一步继续报错。第二个常见报错是nvcc fatal : Unsupported gpu architecture compute_90这条通常意味着编译脚本检测到的 GPU 架构太新而你安装的 CUDA 11.1 并不认识。CUDA 11.1 发布于 2021 年前后对 RTX 40 系这种新卡支持不完善。如果手头是 RTX 4090最合理的解决方式是设置TORCH_CUDA_ARCH_LIST8.9但需要提前确认 CUDA 11.1 是否支持compute_89/sm_89。如果你没有合适的硬件建议找个旧一点的 GPU或者考虑更换整个项目的 CUDA 环境而不是和编译器硬刚。4.3 运行时报错“libXXX not found”怎么定位编译扩展这一关过了之后运行阶段也会遇到动态库找不到的问题最常见的就是ImportError: libcudnn.so.8: cannot open shared object file: No such file or directory这是因为某些扩展在链接阶段显式依赖了 cuDNN而 PyTorch wheel 自带的 cuDNN 并不一定在系统库搜索路径中。解决方式是到 NVIDIA Developer 网站下载对应 CUDA 11.1 的 cuDNN 8.2 版本解压后把lib64下的文件拷贝到系统库目录sudo cp cudnn-linux-x86_64-8.2.x.x/lib64/* /usr/local/cuda-11.1/lib64/ sudo ldconfig如果不想手动下载也可以试试从 conda 安装 cudnnconda install -c conda-forge cudnn8.2然后把 conda 环境的 lib 目录加入LD_LIBRARY_PATH。这个方案胜在方便但要注意 conda 的 cudnn 版本不能和 PyTorch 内部使用的 cuDNN 版本冲突如果torch.cuda.is_available()为 True 但运行扩展时崩溃大概率就是这里出现了版本冲突。5. 环境验证与常见问题速查5.1 一条命令确认 PyTorch 是否识别 GPU验证环境是否正常不要一上来就猛跑完整 Demo先用最小命令确认关键点python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))输出应该是1.10.1cu111 True NVIDIA GeForce RTX 3090如果torch.cuda.is_available()返回 False可能性只有三种驱动没装好、PyTorch 装成了 CPU 版本、或者 nouveau 还在占用显卡。依次排查即可。接下来再验证关键扩展库能否正常导入python -c import open3d; print(open3d.__version__) python -c import cv2; print(cv2.__version__)如果 Open3D 报错大概率是 NumPy 版本问题。PyTorch 1.10.1 对 NumPy 的兼容范围是numpy1.24而新环境默认可能会装 1.26 甚至更高。遇到类似module numpy has no attribute float这类错误时执行pip install numpy1.24我没有在安装命令里把 numpy 固定为numpy1.21但只要你后面不出兼容性问题建议装上numpy1.21.6这是 PyTorch 1.10.x 时代最常见的搭配。5.2 常见问题速查表下面这堆问题都是我实际部署时碰到或者帮人排查过的高频问题整理成速查表方便你遇到报错时直接对照。现象可能原因解决方案nvidia-smi显示失败nouveau 未禁用或驱动未生效重新安装驱动添加 blacklist 并重启torch.cuda.is_available()返回 FalsePyTorch 装成 CPU 版卸载后用 cu111 wheel 重装cuda_runtime.h找不到CUDA_HOME 未设置设置CUDA_HOME/usr/local/cuda-11.1编译时出现Unsupported gpu architectureTORCH_CUDA_ARCH_LIST 设置错误设置成和自己 GPU 匹配的架构libcudnn.so.8找不到系统缺少 cuDNN 8.x从 NVIDIA 下载 cuDNN 并复制到 CUDA lib64导入 Open3D 时报 numpy 错误numpy 版本太高执行pip install numpy1.24运行过程中显示内存不足数据集较大或默认分辨率过高降低 batch size 或输入分辨率ImportError: libGL.so.1找不到系统缺少 OpenGL 动态库执行sudo apt install -y libgl1 libgl1-mesa-dev第一列就是报错原文或者现象第二列是成因第三列是处理方式。如果你遇到的报错不在表格里还有一个通用排查方法把ImportError后面的.so文件名复制到搜索引擎里搜一遍通常立刻能定位到是哪个系统库缺失。5.3 给新手的最终建议先跑内置 Demo别直接上自己的数据环境配置好之后建议先跑项目自带 Demo而不要第一时间用自己的数据。原因很简单Demo 数据经过项目作者验证输入格式、标定文件、相机参数都是齐全的能快速暴露环境剩余的问题。如果 Demo 能正常跑出结果说明环境基本没问题这时候再换成自己的数据遇到问题就可以判断是环境问题还是数据问题。如果你在运行 Demo 时看到类似这样一段信息Loading configuration from configs/demo.yaml Creating model with device: cuda:0说明 CUDA 已经被正确调用项目正式进入可用状态。此时可以观察显存占用和帧率消耗判断硬件是否能支撑后续实验。最后再补充几句实在话这套环境我前后折腾了差不多两天最后复盘发现绝大多数时间都耗在了版本冲突和手动编译上IS-Fusion 项目本身的代码反而没出什么幺蛾子。建议你遇到奇怪报错时先检查几个最容易出错的位置驱动是否生效、CUDA_HOME 是否指对路径、PyTorch 是否装成 CPU 版、NumPy 是不是过新。这四个位置能覆盖八成问题。还有一个我自己的小习惯每完成一个步骤就拍个屏幕或者把输出存到日志文件里。尤其是nvcc --version和python -c import torch; print(torch.__version__, torch.cuda.is_available())这些关键输出后面排错时翻出来看一眼就能定位是哪一步开始跑偏。环境部署这种活最怕的不是问题多而是问题出现了你却不知道它是从哪个环节冒出来的。