保姆级避坑指南：在Ubuntu 20.04上从零部署StreamPETR 3D检测模型（含CUDA 11.3、Flash Attention安装）
保姆级避坑指南：在Ubuntu 20.04上从零部署StreamPETR 3D检测模型
当你在深夜的实验室里第三次面对ImportError: libGL.so.1报错时，是否想过放弃这个看似简单的3D检测模型部署？别担心，这份指南将带你穿越CUDA版本地狱、PyTorch兼容性迷宫和mmcv-full安装陷阱。我们将用最硬核的方式，解决那些官方文档从未提及的"玄学"问题。
1. 环境配置：从零搭建铜墙铁壁
1.1 系统级准备：打好地基
在Ubuntu 20.04上，先执行这些看似无关却至关重要的操作：
sudo apt-get update sudo apt-get install -y build-essential libgl1-mesa-glx ffmpeg为什么需要它们？
build-essential包含g++/gcc编译器链，是PyTorch等库编译的基石libgl1-mesa-glx解决OpenGL依赖，避免可视化环节崩溃ffmpeg处理多媒体数据流，某些数据预处理脚本会隐式调用
关键检查点：
g++ --version # 应显示9.4.0或更高 nvidia-smi # 确认驱动已安装且支持CUDA 11.31.2 Conda环境：隔离的艺术
用以下命令创建纯净环境：
conda create -n streampetr python=3.8 -y conda activate streampetr版本锁定策略：
- Python 3.8是PyTorch 1.11的最佳搭档
- 过早或过晚的Python版本会导致ABI兼容性问题
1.3 PyTorch生态：版本精确制导
执行这套"黄金组合"安装命令：
pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 \ --extra-index-url https://download.pytorch.org/whl/cu113常见翻车点：
- 误用
conda install会导致CUDA版本不匹配 - torchvision版本必须严格对应，否则会引发DLL加载错误
验证安装：
import torch print(torch.__version__, torch.cuda.is_available()) # 应输出1.11.0 True2. 依赖库安装：拆解复杂依赖链
2.1 mmcv-full：最棘手的拼图
推荐使用预编译wheel避免源码编译：
wget https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/mmcv_full-1.6.0-cp38-cp38-manylinux1_x86_64.whl pip install mmcv_full-1.6.0-cp38-cp38-manylinux1_x86_64.whl备选方案：
pip install openmim mim install mmcv-full==1.6.0 -v # -v参数显示详细日志2.2 扩展库：隐藏的版本陷阱
按顺序安装这些关键组件：
pip install mmdet==2.28.2 mmsegmentation==0.30.0 git clone https://github.com/open-mmlab/mmdetection3d.git -b v1.0.0rc6 cd mmdetection3d pip install -v -e . # 可编辑模式安装版本兼容矩阵：
| 组件 | 必须版本 | 兼容范围 |
|---|---|---|
| numpy | 1.23.4 | 1.20-1.23 |
| yapf | 0.40.1 | ≤0.40.1 |
| spconv | cu113 | 必须匹配CUDA版本 |
2.3 Flash Attention：加速神器安装指南
优先使用预编译wheel：
wget https://github.com/Dao-AILab/flash-attention/releases/download/v0.2.2/flash_attn-0.2.2+cu113torch1.11.0-cp38-cp38-linux_x86_64.whl pip install flash_attn-0.2.2+cu113torch1.11.0-cp38-cp38-linux_x86_64.whl源码编译方案（当预编译版本不可用时）：
pip install flash-attn==0.2.2 -v --no-build-isolation3. 报错全解析：从现象到本质
3.1 典型错误案例库
案例1：numba初始化失败
from numba.np.ufunc import _internal SystemError: initialization of _internal failed根因：numpy版本过高导致ABI不兼容修复：
pip install numpy==1.23.4 # 必须精确版本案例2：spconv缺失
ModuleNotFoundError: No module named 'spconv'解决方案：
pip install spconv-cu113 # 必须带CUDA后缀案例3：路径导入黑洞
ModuleNotFoundError: No module named 'projects.mmdet3d_plugin'永久修复：
export PYTHONPATH=$PYTHONPATH:`pwd` # 在项目根目录执行3.2 显存管理实战技巧
当遇到CUDA out of memory时，按此顺序调整：
- 修改config文件：
samples_per_gpu=1 # 原值通常为2或4 workers_per_gpu=0 # 调试时设为0- 使用梯度累积模拟更大batch：
optimizer_config = dict(type="GradientCumulativeOptimizerHook", cumulative_iters=2)- 启用AMP混合精度：
fp16 = dict(loss_scale=512.)4. 数据集处理：以nuScenes为例
4.1 数据准备流水线
对于mini数据集：
python tools/create_data_nusc.py \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --extra-tag nuscenes2d \ --version v1.0-mini文件结构检查清单：
data/nuscenes ├── samples ├── sweeps ├── v1.0-mini ├── nuscenes2d_temporal_infos_train.pkl └── nuscenes2d_temporal_infos_val.pkl4.2 常见数据错误
时间戳不同步：检查infos文件中的timestamp字段是否连续标注缺失：验证gt_boxes和gt_names的对应关系
5. 训练与验证：高效工作流
5.1 分布式训练启动器
8卡训练命令：
tools/dist_train.sh \ projects/configs/StreamPETR/stream_petr_r50_flash_704_bs2_seq_24e.py \ 8 \ --work-dir work_dirs/run1/关键参数监控：
- 使用
nvtop观察GPU利用率 - 用
gpustat -i检查显存波动 - 日志中关注
mAP和NDS指标变化
5.2 测试评估技巧
生成可提交结果：
python tools/test.py \ work_dirs/run1/stream_petr_r50_flash_704_bs2_seq_24e.py \ work_dirs/run1/latest.pth \ --eval bbox \ --eval-options 'jsonfile_prefix=./results/submission'可视化调试： 修改visualize.py中：
result_json = "results/submission.bbox.json" version = "v1.0-mini" # 与数据集版本一致