BEVFusion(MIT)在Ubuntu 20.04上的环境搭建与关键问题排错指南

1. 环境准备：从零搭建BEVFusion基础环境

在Ubuntu 20.04上配置BEVFusion环境，首先要确保硬件和系统环境满足基本要求。我遇到过不少因为基础环境没配好导致后续各种诡异报错的情况，这里把关键要点梳理清楚。

硬件要求方面，建议至少准备：

• NVIDIA显卡（RTX 3060及以上性能的显卡比较合适）
• 16GB以上内存（处理大型数据集时32GB更稳妥）
• 100GB可用磁盘空间（数据集和中间文件会占用大量空间）

先检查显卡驱动是否正常。在终端运行：

bash复制nvidia-smi

这个命令会显示显卡信息和CUDA版本。我遇到过驱动安装不完整的情况，输出里看不到CUDA版本号。如果遇到这种情况，建议先卸载原有驱动再重新安装。

CUDA安装是个容易踩坑的环节。BEVFusion官方推荐CUDA 11.3，但实测11.1-11.6版本都能工作。关键是要保证：

1. 显卡驱动支持的CUDA版本 ≥ 要安装的CUDA版本
2. PyTorch有对应CUDA版本的预编译包

安装CUDA时有个小技巧：使用runfile方式安装，记得取消勾选驱动安装选项，避免覆盖现有驱动。具体步骤：

bash复制wget https://developer.download.nvidia.com/compute/cuda/11.3.0/local_installers/cuda_11.3.0_465.19.01_linux.run
sudo sh cuda_11.3.0_465.19.01_linux.run

安装完成后，记得在~/.bashrc中添加环境变量：

bash复制export PATH=/usr/local/cuda-11.3/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-11.3/lib64:$LD_LIBRARY_PATH

2. Python环境配置与依赖安装

创建独立的conda环境能避免很多包冲突问题。我习惯用miniconda管理环境：

bash复制conda create -n bevfusion python=3.8 -y
conda activate bevfusion

PyTorch安装要特别注意版本匹配。BEVFusion需要torch==1.10.0，这个版本比较老，直接pip安装可能会出错。推荐使用预编译的wheel：

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

安装mmcv-full时有个大坑：必须指定正确的编译版本。我试过直接pip install mmcv-full，结果运行时各种segmentation fault。正确的安装方式是：

bash复制pip install mmcv-full==1.4.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html

其他依赖包的安装相对简单，但要注意版本锁定：

bash复制pip install mmdet==2.20.0
conda install -c conda-forge openmpi mpi4py
pip install Pillow==8.4.0 tqdm torchpack nuscenes-devkit ninja

版本冲突处理是这部分的难点。比如nuscenes-devkit会强制升级numpy到最新版，而BEVFusion需要numpy==1.19.5。我的解决方法是：

bash复制pip install numpy==1.19.5 --force-reinstall
pip install nuscenes-devkit --no-deps

3. BEVFusion源码编译与修改

从GitHub克隆代码后，有几处关键修改必不可少：

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

第一个必改点是spconv的线程配置。打开mmdet3d/ops/spconv/src/indice_cuda.cu，把所有4096改为256。这个值设置太大会导致显存溢出，特别是对于消费级显卡。

第二个调整点是编译参数。在setup.py中，需要根据显卡算力修改编译选项。比如RTX 3060对应的是sm_86：

python复制'-gencode=arch=compute_86,code=sm_86'

编译时可能会遇到各种C++编译错误。我总结了几种常见情况：

1. 如果报错nvcc not found，检查CUDA环境变量
2. 出现undefined reference错误，可能是gcc版本过高，尝试降级到gcc-7
3. 编译卡在100%不动，可能是虚拟内存不足，可以增加swap空间

成功编译的标志是看到类似这样的输出：

code复制building 'mmdet3d.ops.spconv.sparse_conv_ext' extension
[7/7] c++ -pthread -shared -o build/lib.linux-x86_64-cpython-38/mmdet3d/ops/spconv/sparse_conv_ext.cpython-38-x86_64-linux-gnu.so

4. 数据集准备与训练技巧

nuScenes数据集的准备是个耗时的工作。我建议先用mini版测试流程：

bash复制mkdir -p data/nuscenes
# 下载v1.0-mini数据集后解压到上述目录

数据预处理时需要特别注意路径格式。BEVFusion对路径大小写敏感，必须全部小写：

bash复制python tools/create_data.py nuscenes --root-path ./data/nuscenes --version v1.0-mini --out-dir ./data/nuscenes --extra-tag nuscenes

训练配置方面，显存不足是最常见的问题。除了修改batch_size，还可以：

1. 在config文件中减小input_size
2. 使用梯度累积（修改samples_per_gpu参数）
3. 启用混合精度训练（添加fp16 = dict(loss_scale=512.)到config）

分布式训练启动命令示例：

bash复制torchpack dist-run -np 1 python tools/train.py configs/nuscenes/det/transfusion/secfpn/camera+lidar/swint_v0p075/convfuser.yaml

如果遇到CUDA out of memory错误，可以尝试修改mmdet3d/apis/train.py中的distributed参数为True。这个改动能让PyTorch更好地管理显存。

可视化调试是验证环境是否正常的好方法：

bash复制python tools/visualize.py configs/nuscenes/det/transfusion/secfpn/camera+lidar/swint_v0p075/convfuser.yaml --mode gt --checkpoint latest.pth --out-dir vis_results

整个环境搭建过程中，最耗时的往往是各种依赖包的下载和编译。建议使用国内镜像源加速下载，比如清华源或阿里云源。对于需要重复测试的情况，可以考虑将配置好的环境打包成Docker镜像，方便快速恢复工作状态。