保姆级避坑指南在Ubuntu 20.04上从零复现StreamPETR 3D检测器含Flash Attention安装1. 环境配置那些官方文档没告诉你的细节在Ubuntu 20.04上搭建StreamPETR开发环境就像玩俄罗斯方块——看似简单但一个版本错位就会全盘崩溃。我花了三天时间才搞明白为什么官方文档里的简单几步在实际操作中会变成连环坑。CUDA版本选择的玄学虽然官方推荐CUDA 11.3但如果你之前安装过其他版本一定要用nvidia-smi和nvcc --version交叉验证驱动版本和运行时版本是否匹配。我遇到过驱动支持CUDA 11.7但代码需要11.3的情况最终不得不重装驱动。虚拟环境搭建的隐藏陷阱# 这个命令看起来简单但python3.8必须精确指定 conda create -n streampetr python3.8为什么是3.8因为mmcv-full 1.6.0对Python 3.9的支持有问题而PyTorch 1.11.0在3.10上会有兼容性警告。依赖安装顺序的奥妙先装PyTorchCUDA组合包再装mmcv-full建议用预编译whl最后装mmdetection3d这个顺序不能乱否则会出现明明装了mmcv却提示找不到的灵异事件。我推荐使用离线安装方式pip install mmcv_full-1.6.0-cp38-cp38-manylinux1_x86_64.whl2. Flash Attention安装从入门到放弃再到成功Flash Attention是性能优化的关键但它的安装过程堪称渡劫。官方提供了两种安装方式但都有坑离线安装法优点速度快10秒完成缺点需要找到完全匹配的whl文件关键点文件名中的cu113torch1.11.0必须一字不差在线编译安装# 加上-v参数才能看到进度否则你会以为死机了 pip install flash_attn0.2.2 -v这个命令可能会运行1小时以上期间你的CPU会满负荷运转。我在AWS g4dn.xlarge实例上实测编译耗时83分钟。常见报错解决方案报错g not found→sudo apt install build-essential报错CUDA_HOME not set→export CUDA_HOME/usr/local/cuda-11.3报错GLIBCXX版本过低→ 更新gcc到9.0以上版本3. 数据集准备那些让人抓狂的路径问题NuScenes数据集的处理过程就像在迷宫里找出口——每个转角都可能遇到新的路径错误。官方脚本create_data_nusc.py对路径格式极其敏感绝对路径 vs 相对路径使用相对路径时必须确保当前在mmdetection3d目录下绝对路径要完整到/data/nuscenes层级不能只到/data文件结构应该严格遵循data/ └── nuscenes/ ├── samples/ ├── sweeps/ ├── maps/ └── v1.0-mini/经典报错处理# 报错ModuleNotFoundError: No module named tools.data_converter # 解决方案在mmdetection3d目录下执行 export PYTHONPATH$PYTHONPATH:pwd对于mini数据集用户记得修改版本号# 注意最后的v1.0-mini参数 python tools/create_data_nusc.py --version v1.0-mini4. 训练过程中的内存杀手们开始训练后你会发现显存就像沙漠里的水——永远不够用。通过反复实验我总结出这些省显存的技巧配置文件修改优先级把samples_per_gpu降到1将workers_per_gpu设为0减小img_scale尺寸关闭所有可视化选项关键参数对比参数名安全值危险值影响程度samples_per_gpu12★★★★★workers_per_gpu04★★★☆☆seq_len424★★★★☆img_scale(704,256)(1408,512)★★★★★多卡训练的隐藏选项# 使用8卡训练时batch_size会自动乘以8 tools/dist_train.sh config_file.py 8 --work-dir output/注意分布式训练需要先配置好NCCL否则会出现卡死现象。测试NCCL是否正常python -c import torch; torch.distributed.init_process_group(nccl); print(OK)5. 可视化让结果从数字变成画面训练完成后可视化是验证模型效果的最后一关但visualize.py脚本的路径处理方式相当个性。必须修改的三个地方# 1. 结果路径注意没有.json后缀 result_json test/results_nusc # 2. 数据集版本mini版必须修改 version v1.0-mini # 3. 输出目录建议用绝对路径 out_dir /path/to/result_vis可视化效果优化技巧修改render_egoposes参数控制视角调整vis_boxes_range过滤远处物体设置show_frames参数为True生成动态序列常见问题解决方案报错KeyError: boxes_3d→ 检查测试时是否加了--eval bbox参数报错No such file or directory: results_nusc.json→ 确认路径是否包含文件名本身画面空白 → 检查数据集版本是否匹配训练配置6. 那些我踩过的坑实战记录numpy版本灾难报错SystemError: initialization of _internal failed原因numba与numpy 1.24不兼容解决pip install numpy1.23.4spconv安装谜题报错No module named spconv关键点必须安装与CUDA匹配的版本正确命令pip install spconv-cu113yapf版本陷阱报错TypeError: FormatCode() got unexpected keyword argument verify解决pip install yapf0.40.1docker内的libGL问题报错libGL.so.1: cannot open shared object file解决方案apt install ffmpeg是的就是ffmpeg内存泄漏侦探游戏现象训练时显存缓慢增长直至崩溃排查步骤用nvidia-smi -l 1监控显存变化在DataLoader中设置persistent_workersFalse检查自定义算子是否有内存泄漏最后分享一个实用技巧在Docker内开发时先安装这些基础包能避免90%的奇怪报错apt update apt install -y \ build-essential \ ffmpeg \ libsm6 \ libxext6 \ libgl1-mesa-glx \ git-lfs