如何快速上手UniScene?从零搭建CUDA 12.1开发环境的6步完整教程

原创2026-11-13 14:49:351,874 阅读

如何快速上手UniScene?从零搭建CUDA 12.1开发环境的6步完整教程

UniScene 是一个统一的驾驶场景生成框架(CVPR 2025, TPAMI 2026),能够从 BEV 布局一次性生成语义占据(Occupancy)、多视角视频和 LiDAR 点云三种关键数据。本文将从零带你用 6 个步骤搭建 UniScene 的 CUDA 12.1 开发环境,并在最后跑通环境验证,适合新手快速上手。

UniScene 驾驶场景生成效果演示,从BEV布局生成占据、视频与LiDAR点云

UniScene 的整体流程是"占据中心化"的两级生成:先生成语义占据作为元场景表示,再以此为条件分别生成视频与 LiDAR 数据。

UniScene 占据中心化驾驶场景生成框架总览图

项目按三大模块组织,对应三条生成链路,目录结构如下:

模块 目录 功能
占据生成 occupancy_gen/ 基于 VAE + Diffusion Transformer 的语义占据生成
LiDAR 生成 lidar_gen/ 基于 Sparse UNet + 先验引导采样的点云生成
视频生成 video_gen/ 基于 3D 高斯渲染 + Diffusion UNet 的多视角视频生成

UniScene 占据生成模型架构图,Occupancy VAE 与 DiT

三个子模块的详细使用文档分别见 occupancy_gen/README.md、lidar_gen/README.md、video_gen/README.md。

⚠️ 官方推荐环境:Ubuntu 20.04 + NVIDIA A100/A800 + CUDA 12.1 + Python 3.9(见 install.md)

步骤1:安装CUDA 12.1与cuDNN并配置环境变量

环境搭建的核心是 CUDA 12.1 + cuDNN 8.8,版本必须严格对齐,否则后续 CUDA 扩展编译会失败。

  1. 安装 CUDA 12.1 和 cuDNN(官方推荐 cuDNN 8.8.1.3);
  2. 在 ~/.bashrc 或激活脚本中配置环境变量:
CUDA=12.1
CUDNN=8.8.1.3

export CUDA_HOME=/data/cuda/cuda-$CUDA/cuda
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$CUDA_HOME/lib64/stubs:$CUDA_HOME/extras/CUPTI/lib64:/data/cuda/cuda-$CUDA/cudnn/v$CUDNN/lib64:/usr/local/nvidia/lib64:$LD_LIBRARY_PATH
export PATH=$CUDA_HOME/bin:$PATH
export CUDA_TOOLKIT_ROOT_DIR=$CUDA_HOME
export LIBRARY_PATH=$CUDA_HOME/lib64:$LIBRARY_PATH
export CFLAGS="-I$CUDA_HOME/include $CFLAGS"
export LDFLAGS="-L/usr/local/nvidia/lib64 $CFLAGS"

✅ 验证:nvcc --version 应显示 release 12.1。

步骤2:确认GCC版本并安装系统依赖

编译 CUDA 扩展对编译器有要求,官方使用 gcc 9.4.0 测试通过:

# 确认 gcc 版本 >= 9(conda 环境内)
gcc --version

安装可视化所需的系统依赖(xvfb 用于无显示器环境渲染):

sudo apt-get install xvfb

步骤3:创建conda环境并安装PyTorch (CUDA 12.1)

先克隆仓库(含子模块),再创建 Python 3.9 的 conda 环境:

git clone https://gitcode.com/gh_mirrors/un/UniScene-Unified-Occupancy-centric-Driving-Scene-Generation.git --recursive
cd UniScene-Unified-Occupancy-centric-Driving-Scene-Generation

conda create -n uniscene python=3.9
conda activate uniscene
conda install pytorch=2.5.1=py3.9_cuda12.1_cudnn9.1.0_0 torchvision -c pytorch -c nvidia

接着安装 OpenMIM 工具链中的 mmcv(LiDAR 生成模块依赖):

pip install -U openmim
mim install mmcv==2.1.0

步骤4:使用poetry安装Python依赖

项目使用 poetry 管理依赖,锁文件 poetry.lock 已提供,可保证版本一致:

pip install --no-cache-dir setuptools==65.5.0
pip install poetry
poetry install --no-root

这一步会安装 torch==2.5.1、deepspeed、mmdet3d==1.4.0、open3d 等数十个依赖(完整清单见 pyproject.toml 与 environment.yml)。

💡 若 poetry 安装 mayavi、PyQt5、vtk、setuptools 失败,可手动补装: pip install vtk==9.0.2 PyQt5==5.15.10 PyQt5-sip 和 pip install --no-cache-dir mayavi==4.7.3

步骤5:编译三个CUDA扩展

UniScene 有三个需要本地编译的 CUDA 扩展,顺序安装:

# 1) LiDAR 生成模块(含 pcdet 与 dda 算子)
cd ./lidar_gen/ && pip install -e . -v && cd ../

# 2) 视频生成模块的 3D 高斯光栅化算子
cd ./video_gen/gs_render/diff-gaussian-rasterization/ && pip install ./ && cd ../../../

# 3) Chamfer 距离算子
cd third_party/chamferdist
python3 setup.py install
cd ../../

三个扩展对应的入口文件分别为 lidar_gen/setup.py、video_gen/gs_render/diff-gaussian-rasterization/setup.py 和 third_party/chamferdist/setup.py。

UniScene LiDAR生成模型架构图,Sparse UNet与先验引导采样

最后设置 Python 路径,让各模块可互相导入:

export PYTHONPATH=$(pwd)

步骤6:验证环境与可选的mayavi可视化

1)验证 PyTorch CUDA 12.1 是否就绪:

python -c "import torch; print(torch.__version__, torch.version.cuda); print(torch.cuda.is_available())"

期望输出类似 2.5.1+cu121 12.1 True。

2)(可选)验证 mayavi 3D 可视化。mayavi 在无头服务器上需配合虚拟帧缓冲 Xvfb 使用:

# 终端A:启动虚拟显示
Xvfb :1 -screen 0 1280x1024x24 -auth localhost

# 终端B:设置环境变量并运行测试
export DISPLAY=:1
export QT_QPA_PLATFORM=offscreen
export ETS_TOOLKIT=qt
export QT_API=pyqt5
python3 occupancy_gen/check_mayavi.py

若正常会生成并保存一张 mayavi_test.png,说明可视化链路搭建成功。

UniScene 视频生成模型架构图,3D高斯渲染与Diffusion UNet

搭建完成后的下一步

环境就绪后,按 README.md 继续即可:

  1. 下载预训练权重:通过 huggingface-cli download 获取占据(Occ-VAE / Occ-DiT)、LiDAR(occ2lidar.pth)、视频(video_pretrained.safetensors)三组模型;
  2. 准备数据:将 nuScenes v1.0 Trainval 放入 ./data/nuscenes,并可用 data_process/generate_occ.py 生成 GT 占据标签;
  3. 跑通生成链路:先 bash ./occupancy_gen/run_eval_dit.sh 生成占据,再用 lidar_gen/tools/test.py 和 video_gen/inference_video.py 分别生成点云与视频。

生成链路跑通后,你就能看到类似下面的多视角渲染效果:

UniScene 生成的多视角驾驶场景视频渲染效果,六相机深度彩色视图

UniScene 占据中心场景生成完整演示动图

常见问题速查(FAQ)

问题 排查建议
编译 CUDA 扩展报 nvcc not found 检查 CUDA_HOME、PATH 是否已按步骤1配置
gcc 版本过低编译失败 按步骤2 升级到 gcc ≥ 9
mim install mmcv 报错 确认已 pip install -U openmim,且 torch 为 2.5.1+cu121
mayavi 崩溃 / core dump 参考 install.md 中 mayavi 专节,配合 Xvfb 虚拟帧缓冲

🎉 恭喜!至此 UniScene 的 CUDA 12.1 开发环境已从零搭建完成,接下来只需下载权重和数据,即可体验占据、LiDAR、视频三位一体的驾驶场景生成。

登录后查看全文
UniScene-Unified-Occupancy-centric-Driving-Scene-Generation