UniScene AutoDL 环境部署完全指南 (二)：虚拟环境的建立与注意事项

UniScene AutoDL 环境部署完全指南 (二)：虚拟环境的建立与注意事项

适用环境: AutoDL (Miniconda, CUDA 12.1, Python 3.9)

0. 前置准备与注意事项

1. 实例状态：必须确保 AutoDL 实例处于“开机”状态。严禁使用“无卡模式”进行环境配置，因为 CUDA 扩展的编译（如lidar_gen）依赖于对物理 GPU 架构的检测。
2. 镜像选择：推荐选择Miniconda / Python 3.9 / CUDA 12.1的基础镜像。
3. 存储规划：AutoDL 系统盘（/root）空间有限，所有数据集与模型权重必须存储在数据盘（/root/autodl-tmp），并通过软链接映射。

AutoDL 默认环境可能存在 GCC 版本与 CUDA 12.1 不兼容，或gcc与g++版本不一致（Split Brain）的问题，这会导致驱动调用失败或 C++ 扩展编译错误。我们需要强制统一使用GCC-11。

在终端执行以下命令：

# 更新软件源并安装 GCC-11 完整工具链sudoapt-getupdatesudoapt-getinstall-ygcc-11 g++-11 build-essential# 使用 update-alternatives 建立版本管理组，并将 GCC-11 优先级设为最高 (100)sudoupdate-alternatives--install/usr/bin/gcc gcc /usr/bin/gcc-11100sudoupdate-alternatives--install/usr/bin/g++ g++ /usr/bin/g++-11100# 验证编译器版本（预期输出应为 11.x.x）gcc--versiong++--version

1. 核心策略与背景

在云端算力容器中部署涉及自定义 CUDA 算子和老旧可视化库的科研项目时，常面临以下三大挑战：

1. 网络受限：官方源连接超时。

2. 二进制不兼容：Pip 引入的numpy携带的 OpenMP 库劫持了 PyTorch 所需的底层 MKL 库。

3. 构建标准冲突：新版pip(v25+) 强制执行 PEP 660 标准，导致旧版setup.py无法进行 Editable 安装。

本指南采用“基座锁定 + 编译规避 + 依赖清洗”的策略，确保环境的确定性。

2. 基础环境构建与网络配置

2.1 镜像源配置

为规避网络问题，需将 Conda 与 Pip 均指向国内高性能镜像站。

# 1. 重置并配置 Conda 源 (清华源优先，官方源兜底)conda config --remove-key channels2>/dev/null conda config--addchannels defaults conda config--addchannels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config--addchannels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/ conda config--addchannels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config--addchannels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config--setshow_channel_urlsyes# 2. 配置 Pip 源 (阿里云源/清华源)pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip configsetglobal.extra-index-url https://pypi.org/simple pip configsetglobal.trusted-host pypi.tuna.tsinghua.edu.cn

2.2 核心计算层锁定

关键操作：必须通过 Conda 显式安装底层数学库，防止后续openmim安装过程破坏环境。

# 创建虚拟环境conda create-nuniscenepython=3.9-yconda activate uniscene# 安装 PyTorch 核心组件 (指定 CUDA 12.1)condainstallpytorch=2.5.1 torchvision pytorch-cuda=12.1-cpytorch-cnvidia-y# [防御性安装] 强制锁定 MKL 和 OpenMP，解决 "undefined symbol: iJIT_NotifyEvent"# 1.激活 uniscene 环境后，执行以下命令安装缺失的依赖condainstall-cconda-forge ittapi-y# 2.安装numpycondainstallnumpy==1.20.1# # 或者尝试省略1/2直接执行以下指令（暂时未验证）# conda install mkl mkl-include intel-openmp numpy=1.20.1 -y

3. 应用框架与依赖管理

3.1 安装 MMLab 生态

pipinstall-Uopenmim miminstallmmcv==2.1.0

3.1补充 MMCV 扩展编译修正 (关键步骤)

问题描述：
由于 PyTorch 2.5.1 版本较新，OpenMIM 官方仓库尚未发布对应的 MMCV 2.1.0 预编译包（Wheel）。默认的mim install命令在未找到预编译包时，会自动回退至源码安装模式，但默认不开启 CUDA 算子编译。这会导致后续运行出现ModuleNotFoundError: No module named 'mmcv._ext'错误。

解决方案：
必须从源码安装并禁用构建隔离，强制进行包含 CUDA 扩展的源码编译。

# 1. 卸载可能已被错误安装的精简版 (mmcv-lite)pip uninstall mmcv-y# 2. 克隆指定版本 (v2.1.0)# -b v2.1.0: 指定分支/标签# --depth 1: 只克隆最近一次提交，下载更快cdthird_partygitclone-bv2.1.0 https://github.com/open-mmlab/mmcv.git--depth1# 3. 进入源码目录cdmmcv# 4.为安全起见，请清理之前的构建产物。rm-rfbuild/ dist/ *.egg-info/# 5. 强制启用 CUDA 算子编译# --no-build-isolation: 强制使用当前环境已安装的 PyTorch 进行链接pipinstallmmcv==2.1.0 --no-build-isolation-v

验证安装：
执行以下指令，若能成功导入_ext模块依赖的算子，则说明环境构建正确。

python .dev_scripts/check_installation.py

3.2 Python 依赖与兼容性补丁

pipinstallpoetry poetry config virtualenvs.createfalsepoetryinstall--no-root# [关键补丁] 降级 setuptools 以兼容 Mayavi 和 Gym 的构建脚本pipinstallsetuptools==65.5.0

4. CUDA 算子编译

AutoDL 默认 GCC 版本过高（GCC 13），且新版 Pip 对 Editable 模式检查严格。需执行以下环境变量配置及清理操作。

4.1 设置编译环境（一般服务器直接符合条件，不用执行）

# 强制指定系统 GCC 11.4 (兼容 CUDA 12.1)exportCC=/usr/bin/gccexportCXX=/usr/bin/g++

4.2 编译 Lidar Gen (解决 build_editable 挂钩错误)

若直接安装报错missing build_editable hook，需清理残留元数据后重试。

cd./lidar_gen/# 清理构建残留，防止 pip 误判构建后端rm-rfbuild/ dist/ *.egg-info/# 使用禁用构建隔离pipinstall-e.--no-build-isolation-vcd../

4.3 编译其他组件

# 编译 Gaussian Rasterizationcd./video_gen/gs_render/diff-gaussian-rasterization/rm-rfbuild/ dist/ *.egg-info/ pipinstall./ --no-build-isolation-vcd../../../# 编译 Chamfer Distancecdthird_party/chamferdist python3 setup.pyinstallcd../../

4.3.1 代码适配修正 (Critical)

在实际运行data_process/generate_occ.py时，原项目代码与当前版本的chamferdist库存在接口不兼容问题。ChamferDistance封装类默认仅返回损失值（Scalar/Tensor），而生成脚本需要获取最近邻索引（Indices）。

请修改data_process/generate_occ.py中约第 490 行的代码逻辑：

修改前 (错误写法)：

importchamfer# ...d1,d2,idx1,idx2=chamfer.forward(x,y)

修改后 (正确写法)：

# 引入底层 KNN 函数以获取索引fromchamferdist.chamferimportknn_points# ... (在调用处)# 1. 计算 x 到 y 的最近邻 (Forward)# K=1 表示只查找最近的一个点out_x_y=knn_points(x,y,K=1)d1=out_x_y.dists[...,0]# (Batch, N)idx1=out_x_y.idx[...,0]# (Batch, N)# 2. 计算 y 到 x 的最近邻 (Backward)out_y_x=knn_points(y,x,K=1)d2=out_y_x.dists[...,0]# (Batch, M)idx2=out_y_x.idx[...,0]# (Batch, M)

4.4 编译 Neural Kernel Surface Reconstruction (NKSR)

NKSR 是用于将点云重建为网格（Mesh）的核心组件。由于其包含复杂的 CUDA 模板代码，编译过程对内存消耗极大，在多核服务器上极易因并发编译导致内存溢出（OOM）从而中断进程。

4.4.1 编译策略：限制并发数

为防止编译过程中系统崩溃，必须通过MAX_JOBS环境变量严格限制并行编译的任务数。请根据您的显存和系统内存规格选择合适的并发参数。

资源阈值参考表：

注：您可以通过nvidia-smi查看显存大小，或执行以下指令快速确认：

python-c"import torch; print(f'GPU Memory: {torch.cuda.get_device_properties(0).total_memory // 1024**3} GB')"

4.4.2 执行编译安装

请在third_party目录下克隆仓库，并执行以下防崩溃指令。该指令集成了架构指定、并发限制及日志记录功能。

# 1. 准备源码cdthird_partygitclone https://github.com/nv-tlabs/nksr.gitcdnksr# 2. 执行编译 (针对本地环境优化)# 说明：# MAX_JOBS=1: 强制单线程编译，杜绝内存溢出# TORCH_CUDA_ARCH_LIST: 覆盖主流显卡架构 (7.5=T4, 8.0=A100, 8.6=30系, 9.0=40系/H100)# --no-build-isolation: 使用当前已配置好的 PyTorch 环境# tee nksr_build.log: 记录详细编译日志以便排错# A100 专属最快编译命令（40GB 显存随便开）MAX_JOBS=4\TORCH_CUDA_ARCH_LIST="8.0"\rm-rfbuild/ dist/ *.egg-info/ pipinstall--no-build-isolation package/# 安装 PyG 核心组件,利用 PyG 官方预编译包安装 torch-scatter 等组件，替代耗时的源码编译。虽然链接是 2.5.0，但实测兼容 2.5.1。pipinstalltorch-scatter torch-sparse torch-cluster torch-spline-conv\-fhttps://data.pyg.org/whl/torch-2.5.0+cu121.html\--no-build-isolation

4.4.3 备选方案：手动离线安装 PyG 组件 (网络受限推荐)

若服务器无法连接 PyG 官方源或下载速度过慢，建议采用“本地下载 -> 上传服务器 -> 离线安装”的策略。此方法最为稳妥，可彻底规避服务器端的网络波动。

步骤 1：本地下载 Wheel 包
请在本地电脑（Windows/Mac）访问以下官方仓库地址：
下载链接：https://data.pyg.org/whl/torch-2.5.0+cu121.html

请务必下载文件名包含cp39(Python 3.9) 和linux_x86_64的以下 4 个文件（版本号可能随时间微调，以最新为准）：

1. torch_scatter-2.1.2+pt25cu121-cp39-cp39-linux_x86_64.whl
2. torch_sparse-0.6.18+pt25cu121-cp39-cp39-linux_x86_64.whl
3. torch_cluster-1.6.3+pt25cu121-cp39-cp39-linux_x86_64.whl
4. torch_spline_conv-1.2.2+pt25cu121-cp39-cp39-linux_x86_64.whl

步骤 2：上传至服务器
通过 AutoDL 控制台的 JupyterLab 文件上传功能，或使用 SCP/FileZilla 工具，将上述 4 个.whl文件上传至服务器的任意目录（例如/root/whls）。

步骤 3：执行离线安装
在服务器终端进入上传目录并执行安装：

# 1. 进入存放 whl 文件的目录cd/root/whls# 请根据实际上传路径修改# 2. 批量安装 (使用通配符，禁用构建隔离)pipinstalltorch_scatter-*.whl\torch_sparse-*.whl\torch_cluster-*.whl\torch_spline_conv-*.whl\--no-build-isolation

编译完成后，建议执行python -c "import nksr; print('NKSR installed successfully')"进行验证。

4.5 occupancy_gen/12hz_processing/save_bevlayout_12hz.py问题

运行 BEV 布局脚本时报TypeError: 'MultiPolygon' object is not iterable（在nuscenes/map_expansion/map_api.py第 1823 行附近）

• 原因：nuscenes-devkit 的地图代码与 Shapely 2.x 不兼容（Shapely 2.x 的 MultiPolygon 不再可直接迭代）。

• 解决：

pip uninstall shapely-ypipinstallshapely==1.8.5# 或者 shapely==1.8.5

降级后所有使用NuScenesMap.get_map_mask()的脚本（包括本项目的 BEV 布局生成、Occ3D、UniAD 等）立刻恢复正常。

5. 可视化环境 (Mayavi 与 Xvfb)

5.1 安装 Mayavi

采用“预装二进制依赖”策略，避免耗时的 VTK 源码编译。

# 安装系统依赖sudoapt-getupdate&&sudoapt-getinstall-ylibgl1-mesa-glx xvfb libxcb-cursor0# 安装 Mayavi (先安装4.7.3，若出现build wheel时间过长则推荐安装 4.8.1，该版本也能使用，禁用隔离以使用旧版 setuptools)pipinstallmayavi==4.7.3 --no-build-isolation# pip install mayavi==4.8.1 --no-build-isolation

设置环境变量

# 设置 PYTHONPATH (建议写入 ~/.bashrc 以持久化)exportPYTHONPATH=$(pwd):$PYTHONPATH

5.2 配置虚拟屏幕 (解决 Server active 报错)

若报错Server is already active for display 1，说明存在残留进程或锁文件。

# 1. 清理残留进程和锁文件 (防御性措施)pkill-9Xvfbrm-f/tmp/.X1-lock# 2. 启动 Xvfb (后台运行)Xvfb :1-screen01280x1024x24-authlocalhost&# 3. 注入环境变量exportDISPLAY=:1exportQT_QPA_PLATFORM=offscreenexportQT_API=pyqt5

6. 附录：故障排查手册

验证脚本：
完成部署后，请务必运行以下脚本确认全模块加载正常：

python-c "importtorch,mmcv,lidar_gen,chamferdistfrommayaviimportmlabprint(f'[SUCCESS] PyTorch:{torch.__version__}| CUDA:{torch.cuda.is_available()}')print(f'[SUCCESS] MMCV:{mmcv.__version__}')print('[SUCCESS] All custom ops and visualization tools loaded.')"