从零部署MIT BEVFusion的终极避坑手册：Ubuntu 20.04环境全攻略

在自动驾驶和计算机视觉领域，BEVFusion凭借其统一鸟瞰图表示下的多任务多传感器融合能力，已成为2023年最受关注的开源项目之一。但许多研究者在复现过程中发现，从环境配置到模型运行的每一步都暗藏玄机——CUDA版本冲突、PyTorch兼容性问题、预训练模型下载失败、数据集路径错误等问题层出不穷。本文将基于数十次真实部署经验，带你避开所有已知陷阱，用最短时间完成从裸机到完整运行的部署流程。

1. 系统准备与环境检查

部署BEVFusion前，Ubuntu 20.04系统需要满足以下基础条件：

• NVIDIA驱动 ：推荐使用470.161.03以上版本
• CUDA Toolkit ：必须为11.3版本（与PyTorch 1.10严格对应）
• cuDNN ：建议8.2.1版本
• Python ：3.8.x（官方推荐版本）

验证驱动和CUDA是否正常安装：

nvidia-smi  # 应显示驱动版本和GPU信息
nvcc --version  # 应显示CUDA 11.3

注意：如果系统已安装其他CUDA版本，可通过 sudo update-alternatives --config cuda 切换版本，或使用conda环境隔离。

2. 关键依赖安装与配置

2.1 OpenMPI编译安装

BEVFusion依赖MPI进行分布式训练，必须手动编译指定版本：

wget https://download.open-mpi.org/release/open-mpi/v4.1/openmpi-4.1.4.tar.gz
tar -xzvf openmpi-4.1.4.tar.gz
cd openmpi-4.1.4
./configure --prefix=/usr/local/openmpi --with-cuda
make -j$(nproc)
sudo make install

在 ~/.bashrc 中添加环境变量：

export MPI_HOME=/usr/local/openmpi
export PATH=${MPI_HOME}/bin:$PATH
export LD_LIBRARY_PATH=${MPI_HOME}/lib:$LD_LIBRARY_PATH
export OMPI_MCA_opal_cuda_support=true

验证安装：

cd examples
make
mpirun -np 4 hello_c  # 应无报错输出

2.2 Python虚拟环境搭建

使用conda创建隔离环境：

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

安装指定版本的PyTorch和TorchVision：

pip install torch==1.10.0+cu113 torchvision==0.11.0+cu113 -f https://download.pytorch.org/whl/torch_stable.html

3. BEVFusion专用依赖安装

3.1 MMDetection3D生态链

必须严格按照版本对应关系安装：

包名	版本	备注
mmcv-full	1.4.0	需指定CUDA和PyTorch版本
mmdet	2.20.0	不可使用v3.x系列
mmseg	0.20.2	可选，语义分割需要
spconv	2.1.21	需从源码编译

安装命令：

pip install mmcv-full==1.4.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html
pip install mmdet==2.20.0
conda install -c conda-forge mpi4py openmpi

3.2 其他关键依赖

pip install Pillow==8.4.0 tqdm torchpack nuscenes-devkit ninja
pip install numpy==1.19.5 numba==0.48.0 shapely==1.8.0

提示：numpy 1.20+会导致与PyTorch 1.10的兼容性问题，必须锁定1.19.x版本

4. BEVFusion源码部署

4.1 获取与修改源码

克隆官方仓库：

git clone https://github.com/mit-han-lab/bevfusion.git
cd bevfusion

必须修改的关键文件：

1. spconv编译参数 ： 修改 mmdet3d/ops/spconv/src/indice_cuda.cu ：

   // 将所有的4096改为256
   const int kernelVolume = 256;  // 原为4096
   

2. 预训练模型下载脚本 ： 修改 download_pretrained.sh 为：

   wget https://hanlab18.mit.edu/projects/bevfusion/files/pretrained_updated/bevfusion-det.pth
   wget https://hanlab18.mit.edu/projects/bevfusion/files/pretrained_updated/bevfusion-seg.pth
   

4.2 编译安装

设置CUDA_HOME环境变量：

export CUDA_HOME=/usr/local/cuda  # 绝对路径，不能包含$CUDA_HOME

编译安装：

python setup.py develop

5. 常见报错与解决方案

5.1 预训练模型404错误

现象 ：下载预训练模型时返回404
原因 ：官方URL已变更
解决 ：使用更新后的下载地址：

wget https://hanlab18.mit.edu/projects/bevfusion/files/pretrained_updated/bevfusion-det.pth

5.2 CUDA路径错误

报错 ：`No such file or directory: '/usr/local/cuda/bin/nvcc'
解决 ：

# 确保~/.bashrc中有且仅有：
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH

5.3 循环导入错误

报错 ： ImportError: cannot import name 'feature_decorator_ext'
解决 ：

1. 注释 mmdet3d/ops/__init__.py 中的：

   # from .feature_decorator import feature_decorator
   

2. 注释 mmdet3d/models/backbones/__init__.py 中的：

   # from .radar_encoder import *
   

5.4 数据集路径错误

报错 ： FileNotFoundError: data/nuscenes//nuscenes_infos_train.pkl
解决 ： 修改 tools/data_converter/nuscenes_converter.py ：

info_path = osp.join(info_prefix, '{}_infos_train.pkl'.format(info_prefix))
info_val_path = osp.join(info_prefix, '{}_infos_val.pkl'.format(info_prefix))

6. 完整验证流程

完成所有安装后，运行以下命令验证：

# 下载示例数据
wget https://hanlab18.mit.edu/projects/bevfusion/files/demo.zip
unzip demo.zip

# 运行检测demo
python tools/test.py configs/bevfusion/bevfusion_lidar-cam_voxel0075_second_secfpn_8xb4-cyclic-20e_nus-3d.py \
    checkpoints/bevfusion-det.pth \
    --show-dir results \
    --eval bbox

预期输出应包含检测结果可视化，无任何报错信息。我在AWS g4dn.xlarge实例上实测，完整部署过程约需2小时（含编译时间），关键是要严格遵循版本对应关系。遇到问题时，建议先检查所有环境变量是否设置正确，这是90%错误的根源。