Ubuntu24.04 上以RTX4050为代表的新版本CUDA--从0部署Mini-Splatting 遇到的问题与解决方案

Ubuntu 24.04 上从 0 部署 Mini-Splatting 遇到的问题与解决方案

摘要

本文记录了在 Ubuntu 24.04 系统上部署 Mini-Splatting 的完整过程。针对 RTX 4050 Laptop GPU、系统 CUDA 版本较新、项目依赖本地 CUDA/C++ 扩展等实际情况，本文没有直接复现官方较旧的 CUDA 11.6 环境，而是采用 Python 3.8、PyTorch 2.0.1 + CUDA 11.8、Conda CUDA 11.8 编译工具链和 GCC 9 的组合完成部署。部署过程中重点解决了系统 CUDA 与 Conda CUDA 冲突、nvcc 路径错误、完整 CUDA Toolkit 安装触发异常依赖解算以及本地扩展编译等问题。最终，simple-knn、diff-gaussian-rasterization 和 diff-gaussian-rasterization_ms 均成功编译并导入，Mini-Splatting 核心环境部署完成。

1. 项目背景

Mini-Splatting 是基于 3D Gaussian Splatting 的轻量化表示方法，其项目代码中包含多个本地 CUDA/C++ 扩展。因此，该项目的部署难点不只是安装 Python 依赖，还包括正确配置 PyTorch、CUDA 编译器、系统编译器以及 GPU 架构参数。

本次部署环境为 Ubuntu 24.04，显卡为 NVIDIA GeForce RTX 4050 Laptop GPU。由于 RTX 4050 属于 Ada Lovelace 架构，实际部署时选择 CUDA 11.8 作为编译和运行环境，而不是直接使用官方 README 中较旧的 CUDA 11.6 环境。

2. 硬件与软件环境

本次最终成功部署的环境如下：

操作系统：Ubuntu 24.04
GPU：NVIDIA GeForce RTX 4050 Laptop GPU
NVIDIA Driver：595.71.05
nvidia-smi 显示 CUDA Version：13.2
Conda 环境名：mini_splatting
Python：3.8.20
PyTorch：2.0.1+cu118
PyTorch CUDA：11.8
Conda nvcc：CUDA 11.8，V11.8.89
GCC：gcc-9 9.5.0
G++：g++-9 9.5.0
NumPy：1.24.4

需要特别说明的是，nvidia-smi 中显示的 CUDA Version: 13.2 表示当前 NVIDIA 驱动最高支持的 CUDA 运行时版本，并不意味着项目编译时必须使用 CUDA 13.2。实际编译 CUDA 扩展时，应以 which nvcc 和 nvcc --version 的输出为准。

3. 初始环境验证

首先检查显卡、驱动和 GCC 编译器：

nvidia-smi
gcc-9 --version
g++-9 --version

验证结果表明，系统可以正常识别 RTX 4050 Laptop GPU，NVIDIA 驱动正常，gcc-9 和 g++-9 已正确安装。因此，基础硬件环境和系统编译器满足后续部署要求。

4. 创建 Conda 环境

创建独立 Conda 环境，避免污染系统 Python 和其他深度学习项目环境：

conda create -n mini_splatting python=3.8 -y
conda activate mini_splatting

python -m pip install --upgrade pip setuptools wheel

验证 Python 与 pip 路径：

which python
python --version
which pip
pip --version

实际输出如下：

/home/ddsm/Installation/anaconda3/envs/mini_splatting/bin/python
Python 3.8.20
/home/ddsm/Installation/anaconda3/envs/mini_splatting/bin/pip
pip 25.0.1

说明当前终端已经切换到 mini_splatting 环境。

5. 安装 PyTorch 2.0.1 + CUDA 11.8

由于 RTX 4050 属于较新的 Ada Lovelace 架构，本次没有采用官方 README 中较旧的 PyTorch 1.12.1 + CUDA 11.6 组合，而是采用 PyTorch 2.0.1 + CUDA 11.8：

pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 \
  --index-url https://download.pytorch.org/whl/cu118

安装完成后验证 PyTorch 是否能够正确调用 GPU：

python - <<'PY'
import torch

print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
    x = torch.randn(3, 3).cuda()
    print("cuda tensor ok:", x.device, x.shape)
PY

实际输出如下：

torch: 2.0.1+cu118
torch cuda: 11.8
cuda available: True
gpu: NVIDIA GeForce RTX 4050 Laptop GPU
cuda tensor ok: cuda:0 torch.Size([3, 3])

该结果说明 PyTorch CUDA 运行环境已经配置成功。

6. 安装 CUDA 11.8 编译工具链

虽然 PyTorch 的 cu118 包已经包含 CUDA 运行时，但 Mini-Splatting 需要编译本地 CUDA/C++ 扩展，因此仍然需要 nvcc 编译器。

一开始尝试安装完整 CUDA Toolkit：

conda install -c nvidia/label/cuda-11.8.0 cuda-toolkit -y

但该命令存在两个问题：

1. 计划下载约 3.54 GB 的包，体积较大；
2. Conda 解算结果异常，计划将 Python 从 3.8.20 cpython 降级为 3.8.5 graalpy。

因此，放弃安装完整 CUDA Toolkit，改为安装最小 CUDA 编译组件：

conda install -c nvidia/label/cuda-11.8.0 --override-channels \
  cuda-nvcc=11.8.89 \
  cuda-cudart-dev=11.8.89 \
  cuda-cccl=11.8.89 \
  cuda-driver-dev=11.8.89 \
  -y

该命令只下载约 53 MB 的必要组件，包括 cuda-nvcc、cuda-cudart-dev、cuda-cccl 和 cuda-driver-dev，避免了完整 Toolkit 带来的大规模依赖解算问题。

7. 修正 nvcc 路径冲突

安装最小 CUDA 组件后，直接执行：

nvcc --version

一开始仍然显示系统 CUDA 12.8：

Cuda compilation tools, release 12.8, V12.8.93

进一步检查发现，系统中存在两个 nvcc：

type -a nvcc

输出显示：

nvcc 是 /usr/local/cuda-12.8/bin/nvcc
nvcc 是 /home/ddsm/Installation/anaconda3/envs/mini_splatting/bin/nvcc

这说明 Conda 环境中的 CUDA 11.8 已经安装成功，但 PATH 优先级不正确。解决方法是显式设置环境变量：

export CUDA_HOME="$CONDA_PREFIX"
export CUDA_PATH="$CONDA_PREFIX"

export PATH="$CONDA_PREFIX/bin:$PATH"
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$CONDA_PREFIX/lib64:$LD_LIBRARY_PATH"

export CC=/usr/bin/gcc-9
export CXX=/usr/bin/g++-9
export CUDAHOSTCXX=/usr/bin/g++-9

export TORCH_CUDA_ARCH_LIST="8.9"
export NVCC_PREPEND_FLAGS="-U__SIZEOF_INT128__"

hash -r

再次验证：

which nvcc
nvcc --version

输出变为：

/home/ddsm/Installation/anaconda3/envs/mini_splatting/bin/nvcc
Cuda compilation tools, release 11.8, V11.8.89

至此，编译工具链已经正确切换到 Conda 环境中的 CUDA 11.8。

8. 保存环境变量脚本

为了避免每次打开新终端都手动设置环境变量，创建启动脚本：

mkdir -p ~/Scripts

cat > ~/Scripts/env_mini_splatting.sh <<'EOF'
conda activate mini_splatting

export CUDA_HOME="$CONDA_PREFIX"
export CUDA_PATH="$CONDA_PREFIX"

export PATH="$CONDA_PREFIX/bin:$PATH"
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$CONDA_PREFIX/lib64:$LD_LIBRARY_PATH"

export CC=/usr/bin/gcc-9
export CXX=/usr/bin/g++-9
export CUDAHOSTCXX=/usr/bin/g++-9

export TORCH_CUDA_ARCH_LIST="8.9"
export NVCC_PREPEND_FLAGS="-U__SIZEOF_INT128__"

hash -r
EOF

以后进入 Mini-Splatting 环境时执行：

source ~/Scripts/env_mini_splatting.sh

9. 克隆 Mini-Splatting 仓库

进入下载目录并克隆仓库：

cd ~/DownLoad
git clone --recursive https://github.com/fatPeter/mini-splatting.git

如果仓库已经存在，则进入仓库后初始化子模块：

cd ~/DownLoad/Mini-splatting/mini-splatting
git submodule update --init --recursive

检查项目结构：

pwd
ls
ls submodules

实际项目路径为：

/home/ddsm/DownLoad/Mini-splatting/mini-splatting

submodules 目录下包含：

diff-gaussian-rasterization
diff-gaussian-rasterization_ms
simple-knn

这三个子模块正是后续需要编译的 CUDA/C++ 扩展。

10. 安装基础 Python 依赖

进入项目目录，并加载环境变量：

cd ~/DownLoad/Mini-splatting/mini-splatting
source ~/Scripts/env_mini_splatting.sh

安装基础依赖：

pip install "numpy<2" tqdm plyfile

验证依赖：

python - <<'PY'
import numpy
import tqdm
import plyfile

print("numpy:", numpy.__version__)
print("tqdm ok")
print("plyfile ok")
PY

输出如下：

numpy: 1.24.4
tqdm ok
plyfile ok

这里将 NumPy 固定在 2.0 以下，是为了避免旧版 CUDA 扩展和部分深度学习代码在 NumPy 2.x 下出现兼容性问题。

11. 编译 simple-knn

首先编译 simple-knn：

pip install -v --no-cache-dir --no-build-isolation submodules/simple-knn

编译过程中可以看到关键信息：

/home/ddsm/Installation/anaconda3/envs/mini_splatting/bin/nvcc
-gencode=arch=compute_89,code=sm_89
-ccbin /usr/bin/gcc-9

其中：

• nvcc 来自 Conda 环境中的 CUDA 11.8；
• compute_89, sm_89 对应 RTX 4050 的 Ada Lovelace 架构；
• -ccbin /usr/bin/gcc-9 表明宿主编译器为 GCC 9。

编译完成后验证导入：

python - <<'PY'
import simple_knn
print("simple_knn import ok")
PY

输出：

simple_knn import ok

说明第一个 CUDA 扩展已经编译成功。

12. 编译 diff-gaussian-rasterization

继续编译标准 Gaussian Rasterization 扩展：

pip install -v --no-cache-dir --no-build-isolation submodules/diff-gaussian-rasterization

验证导入：

python - <<'PY'
import diff_gaussian_rasterization
print("diff_gaussian_rasterization import ok")
PY

输出：

diff_gaussian_rasterization import ok

说明第二个扩展安装成功。

13. 编译 diff-gaussian-rasterization_ms

最后编译 Mini-Splatting 所需的多尺度 rasterization 扩展：

pip install -v --no-cache-dir --no-build-isolation submodules/diff-gaussian-rasterization_ms

验证导入：

python - <<'PY'
import diff_gaussian_rasterization_ms
print("diff_gaussian_rasterization_ms import ok")
PY

若没有报错，则说明第三个扩展安装成功。

14. 最终环境验证

全部依赖和扩展安装完成后，执行总验证：

python - <<'PY'
import torch
import numpy
import simple_knn
import diff_gaussian_rasterization
import diff_gaussian_rasterization_ms

print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("numpy:", numpy.__version__)
print("simple_knn ok")
print("diff_gaussian_rasterization ok")
print("diff_gaussian_rasterization_ms ok")

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
PY

最终输出如下：

torch: 2.0.1+cu118
torch cuda: 11.8
cuda available: True
numpy: 1.24.4
simple_knn ok
diff_gaussian_rasterization ok
diff_gaussian_rasterization_ms ok
gpu: NVIDIA GeForce RTX 4050 Laptop GPU

该结果说明：

PyTorch CUDA 可用：通过
CUDA 11.8 nvcc 编译链：通过
simple-knn：通过
diff-gaussian-rasterization：通过
diff-gaussian-rasterization_ms：通过
RTX 4050 sm_89 编译：通过

至此，Mini-Splatting 的核心运行环境已经部署完成。

15. 常见问题与解决方案

15.1 nvidia-smi 显示 CUDA 13.2，是否需要安装 CUDA 13.2？

不需要。nvidia-smi 显示的是当前驱动最高支持的 CUDA 版本，不代表项目必须使用该版本编译。对于本项目，应重点关注：

which nvcc
nvcc --version
python -c "import torch; print(torch.version.cuda)"

本次实际使用的是 PyTorch CUDA 11.8 和 Conda CUDA 11.8 编译器。

15.2 为什么不使用官方 CUDA 11.6 环境？

官方环境较旧，适合复现作者当时的测试条件。但本次机器使用 RTX 4050 Laptop GPU，该显卡属于 Ada Lovelace 架构。为了更好支持 sm_89 架构，本次采用 PyTorch 2.0.1 + CUDA 11.8 的组合。

15.3 为什么不安装完整 cuda-toolkit？

完整 cuda-toolkit 会引入大量组件，例如 Nsight、Profiler、完整 CUDA 库等。在本次环境中，它还触发了异常依赖解算，计划将 Python 从 CPython 3.8.20 降级为 GraalPy 3.8.5。因此，最终采用最小安装方案，只安装编译扩展必需的 CUDA 组件。

15.4 为什么要使用 gcc-9 和 g+±9？

Ubuntu 24.04 默认 GCC 版本较新，而 CUDA 编译器对宿主编译器版本较敏感。使用 gcc-9/g++-9 可以降低 CUDA 扩展编译时出现兼容性错误的概率。

15.5 为什么设置 TORCH_CUDA_ARCH_LIST="8.9"？

RTX 4050 属于 Ada Lovelace 架构，对应计算能力为 8.9。设置：

export TORCH_CUDA_ARCH_LIST="8.9"

可以让 PyTorch CUDA 扩展编译时生成适合当前显卡的目标代码，避免不必要的架构编译，也减少编译失败概率。

15.6 编译过程中出现 warning 是否需要处理？

本次编译过程中出现了若干 warning，例如：

• __CUDACC__ redefined
• Tensor.data<T>() is deprecated
• There are no /usr/bin/g++-9 version bounds defined for CUDA version 11.8

这些 warning 没有导致编译失败。只要最终出现：

Successfully built ...
Successfully installed ...
import ok

就可以认为扩展已经正常安装。

16. 训练脚本入口验证

核心环境部署完成后，可以进一步验证训练脚本入口是否正常：

cd ~/DownLoad/Mini-splatting/mini-splatting/ms
python train.py -h

验证 Mini-Splatting-D：

cd ~/DownLoad/Mini-splatting/mini-splatting/ms_d
python train.py -h

验证 Mini-Splatting-C：

cd ~/DownLoad/Mini-splatting/mini-splatting/ms_c
python run.py -h

如果上述命令能够正常打印参数说明，而不是出现 ModuleNotFoundError 或 CUDA 扩展加载错误，则说明项目入口脚本也可以正常运行。

17. 部署经验总结

本次部署的核心经验如下：

1. 对于包含本地 CUDA/C++ 扩展的项目，不能只关注 PyTorch 是否能调用 GPU，还必须确认 nvcc、CUDA_HOME、gcc/g++ 是否正确。
2. nvidia-smi 显示的 CUDA 版本不等同于编译扩展时使用的 CUDA 版本，真正需要检查的是 which nvcc 和 nvcc --version。
3. 在 Ubuntu 24.04 上部署较早期的 3D Gaussian Splatting 系列项目时，系统默认 GCC 版本往往过新，建议显式指定 gcc-9/g++-9。
4. 对 RTX 40 系列显卡，应注意 CUDA 架构支持问题，建议设置 TORCH_CUDA_ARCH_LIST="8.9"。
5. Conda 安装完整 CUDA Toolkit 时可能触发复杂依赖解算，甚至影响 Python 版本。对于只需编译 PyTorch 扩展的场景，安装最小 CUDA 编译组件通常更稳妥。
6. 不建议直接执行 pip install -r requirements.txt 来一次性安装全部扩展。逐个编译 simple-knn、diff-gaussian-rasterization 和 diff-gaussian-rasterization_ms 更便于定位问题。

18. 最终可复用命令汇总

以下命令适用于本次成功环境，可作为后续复现参考：

conda create -n mini_splatting python=3.8 -y
conda activate mini_splatting

python -m pip install --upgrade pip setuptools wheel

pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 \
  --index-url https://download.pytorch.org/whl/cu118

conda install -c nvidia/label/cuda-11.8.0 --override-channels \
  cuda-nvcc=11.8.89 \
  cuda-cudart-dev=11.8.89 \
  cuda-cccl=11.8.89 \
  cuda-driver-dev=11.8.89 \
  -y

export CUDA_HOME="$CONDA_PREFIX"
export CUDA_PATH="$CONDA_PREFIX"
export PATH="$CONDA_PREFIX/bin:$PATH"
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$CONDA_PREFIX/lib64:$LD_LIBRARY_PATH"

export CC=/usr/bin/gcc-9
export CXX=/usr/bin/g++-9
export CUDAHOSTCXX=/usr/bin/g++-9
export TORCH_CUDA_ARCH_LIST="8.9"
export NVCC_PREPEND_FLAGS="-U__SIZEOF_INT128__"

cd ~/DownLoad/Mini-splatting/mini-splatting

pip install "numpy<2" tqdm plyfile

pip install -v --no-cache-dir --no-build-isolation submodules/simple-knn
pip install -v --no-cache-dir --no-build-isolation submodules/diff-gaussian-rasterization
pip install -v --no-cache-dir --no-build-isolation submodules/diff-gaussian-rasterization_ms

最终验证：

python - <<'PY'
import torch
import numpy
import simple_knn
import diff_gaussian_rasterization
import diff_gaussian_rasterization_ms

print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("numpy:", numpy.__version__)
print("simple_knn ok")
print("diff_gaussian_rasterization ok")
print("diff_gaussian_rasterization_ms ok")

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
PY

若输出中包含：

torch: 2.0.1+cu118
torch cuda: 11.8
cuda available: True
simple_knn ok
diff_gaussian_rasterization ok
diff_gaussian_rasterization_ms ok
gpu: NVIDIA GeForce RTX 4050 Laptop GPU

则说明 Mini-Splatting 核心环境部署成功。