如何快速上手UniScene?从零搭建CUDA 12.1开发环境的6步完整教程
如何快速上手UniScene?从零搭建CUDA 12.1开发环境的6步完整教程
UniScene 是一个统一的驾驶场景生成框架(CVPR 2025, TPAMI 2026),能够从 BEV 布局一次性生成语义占据(Occupancy)、多视角视频和 LiDAR 点云三种关键数据。本文将从零带你用 6 个步骤搭建 UniScene 的 CUDA 12.1 开发环境,并在最后跑通环境验证,适合新手快速上手。
UniScene 的整体流程是"占据中心化"的两级生成:先生成语义占据作为元场景表示,再以此为条件分别生成视频与 LiDAR 数据。
项目按三大模块组织,对应三条生成链路,目录结构如下:
| 模块 | 目录 | 功能 |
|---|---|---|
| 占据生成 | occupancy_gen/ | 基于 VAE + Diffusion Transformer 的语义占据生成 |
| LiDAR 生成 | lidar_gen/ | 基于 Sparse UNet + 先验引导采样的点云生成 |
| 视频生成 | video_gen/ | 基于 3D 高斯渲染 + Diffusion UNet 的多视角视频生成 |
三个子模块的详细使用文档分别见 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 扩展编译会失败。
- 安装
CUDA 12.1和cuDNN(官方推荐 cuDNN8.8.1.3); - 在
~/.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。
最后设置 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,说明可视化链路搭建成功。
搭建完成后的下一步
环境就绪后,按 README.md 继续即可:
- 下载预训练权重:通过
huggingface-cli download获取占据(Occ-VAE / Occ-DiT)、LiDAR(occ2lidar.pth)、视频(video_pretrained.safetensors)三组模型; - 准备数据:将 nuScenes v1.0 Trainval 放入
./data/nuscenes,并可用 data_process/generate_occ.py 生成 GT 占据标签; - 跑通生成链路:先
bash ./occupancy_gen/run_eval_dit.sh生成占据,再用lidar_gen/tools/test.py和video_gen/inference_video.py分别生成点云与视频。
生成链路跑通后,你就能看到类似下面的多视角渲染效果:
常见问题速查(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、视频三位一体的驾驶场景生成。






