BEVFormer代码复现：从环境配置到数据集链接的完整指南
1. 环境准备：从零搭建BEVFormer开发环境
第一次接触BEVFormer时，我花了两天时间才把环境配好，主要卡在CUDA版本和mmcv的兼容性问题上。为了避免大家走弯路，我把完整的环境配置流程整理出来。建议使用Ubuntu 20.04系统，实测这个版本对各种深度学习框架的支持最稳定。
1.1 基础环境搭建
推荐使用Anaconda管理Python环境，它能有效隔离不同项目的依赖冲突。以下是具体操作步骤：
# 创建名为bevformer的Python3.8环境 conda create -n bevformer python=3.8 -y conda activate bevformer安装PyTorch时要特别注意CUDA版本匹配。我的显卡是RTX 3090，实测以下组合最稳定：
pip install torch==1.10.0+cu113 torchvision==0.11.0+cu113 -f https://download.pytorch.org/whl/torch_stable.html安装完成后务必验证CUDA是否可用：
import torch print(torch.cuda.is_available()) # 应该返回True print(torch.version.cuda) # 应该显示11.31.2 关键依赖安装
BEVFormer依赖OpenMMLab系列工具包，安装顺序很重要。先装mmcv-full再装其他组件：
# 必须指定版本号避免兼容性问题 pip install mmcv-full==1.4.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html接着安装mmdetection和mmsegmentation：
pip install mmdet==2.14.0 pip install mmsegmentation==0.14.1其他必要依赖包括数据集处理工具：
pip install nuscenes-devkit==1.1.10 lyft-dataset-sdk==0.0.8 pip install scikit-image==0.19.0 pandas==1.4.42. 代码获取与编译
2.1 克隆与版本控制
直接从OpenMMLab官方仓库获取mmdetection3d代码：
git clone https://github.com/open-mmlab/mmdetection3d.git cd mmdetection3d git checkout v0.17.1 # 必须使用这个版本编译安装时建议添加--no-deps参数避免依赖冲突：
python setup.py develop --no-deps2.2 解决常见编译问题
编译过程可能会遇到这两个典型问题：
ninja报错：先确保安装了ninja构建工具
pip install ninja版本冲突：如果之前装过其他版本的mmdet3d，务必先卸载干净
pip uninstall mmdet3d -y
我在RTX 4090上测试时发现需要额外安装一个补丁：
pip install --force-reinstall numpy==1.23.5 # 解决最新显卡的兼容性问题3. 数据集准备与处理
3.1 数据集目录结构
BEVFormer主要使用nuScenes数据集，建议按以下结构组织文件：
data/ ├── can_bus/ ├── nuscenes/ │ ├── maps/ │ ├── samples/ │ ├── sweeps/ │ └── v1.0-trainval/Windows用户可以用mklink创建符号链接节省空间：
mklink /j D:\project\data\can_bus E:\datasets\can_bus3.2 数据集预处理
运行预处理脚本前需要设置Python路径：
export PYTHONPATH=./ # 解决"No module named 'tools'"错误然后生成数据集信息文件：
python tools/create_data.py nuscenes \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --version v1.0 \ --canbus ./data/can_bus这个过程大约需要30分钟，建议在服务器上执行。我遇到过一个坑：如果数据集路径包含中文，预处理会失败。
4. 模型训练与调试
4.1 预训练模型下载
官方提供的预训练模型有两个下载渠道：
直接从GitHub下载：
wget https://github.com/zhiqi-li/storage/releases/download/v1.0/r101_dcn_fcos3d_pretrain.pth国内用户建议用百度网盘（链接见文末）
下载后放到ckpts目录下，文件结构应该是：
ckpts/ └── r101_dcn_fcos3d_pretrain.pth4.2 启动训练
使用分布式训练能显著加快速度：
./tools/dist_train.sh configs/bevformer/bevformer_base.py 8这里的8表示使用8块GPU。如果只有单卡，可以用：
python tools/train.py configs/bevformer/bevformer_base.py4.3 调试技巧
在代码中插入断点：
import pdb; pdb.set_trace()查看张量形状时建议使用这个技巧：
def debug_hook(module, input, output): print(f"Shape: {output.shape}") model.layer.register_forward_hook(debug_hook)训练过程中如果出现NaN值，可以尝试调小学习率或添加梯度裁剪：
optimizer = dict( type='AdamW', lr=2e-4, weight_decay=0.01, paramwise_cfg=dict( custom_keys={ 'img_backbone': dict(lr_mult=0.1), }), grad_clip=dict(max_norm=35, norm_type=2) )5. 常见问题解决方案
5.1 CUDA内存不足
如果遇到CUDA out of memory错误，可以尝试：
- 减小batch size：修改config中的
samples_per_gpu - 使用梯度累积：
optimizer_config = dict(type="GradientCumulativeOptimizerHook", cumulative_iters=4) - 启用混合精度训练：
fp16 = dict(loss_scale=512.)
5.2 数据集加载失败
典型错误信息包括：
KeyError: 'gt_bboxes_3d'AssertionError: Invalid sample index
解决方法：
- 确保数据集版本是v1.0-trainval
- 重新运行预处理脚本
- 检查
nuscenes_infos_train.pkl文件是否完整
5.3 模型收敛问题
如果训练loss不下降：
- 检查学习率策略：
lr_config = dict( policy='step', warmup='linear', warmup_iters=500, warmup_ratio=0.001, step=[16, 22] ) - 验证数据增强配置：
train_pipeline = [ dict(type='LoadMultiViewImageFromFiles', to_float32=True), dict(type='PhotoMetricDistortionMultiViewImage'), ... ]
我在实际项目中发现，适当调整BEV特征的维度可以提升小物体检测效果：
bev_h = 200 # 原始值为128 bev_w = 200百度网盘预训练模型下载链接：https://pan.baidu.com/s/1abc123def456ghi (示例链接，请替换为真实地址)