{ result: BEVFormer 的环境配置好比一场连续闯关基础依赖装好了、CUDA 也确认过了、分布式训练组件勉强能 import 了正想松口气开始生成训练用的 .pkl 数据集结果 mmcv 直接甩你一脸红字报错。这期要讲的就是我在 BEVFormer 环境配置过程中撞上的第二个大坑——数据集的 .pkl 文件生成时报错 mmcv。从报错信息定位、根因分析、环境重配到最终把数据文件成功跑出来整个过程我都记录在下面。适合正在配置 BEVFormer、已经解决了基础依赖但卡在数据生成环节的读者也适合所有被 mmcv 版本折磨过、想系统搞清楚来龙去脉的人。\n\n## 1. 报错现场与根因定位\n\n### 1.1 那条让你血压飙升的报错长什么样\n\n如果你已经在跑 BEVFormer 官方的数据转换流程大概率会接触到类似下面这条命令\n\nbash\npython tools/data_converter/nuscenes_converter.py \\\n --root-path ./data/nuscenes \\\n --out-dir ./data/nuscenes \\\n --extra-tag nuscenes \\\n --version v1.0-trainval\n\n\n一部分人还没走到这一步在import mmcv阶段就挂了报错信息是ModuleNotFoundError: No module named mmcv。另一部分人更惨明明pip list里能看到 mmcv结果脚本一执行就出现AttributeError: module mmcv has no attribute xxx或者ImportError: libGL.so.1: cannot open shared object file。我当时遇到的正是第二种mmcv 装上了但装的那份 mmcv 跟 BEVFormer 需要的那份完全不是一回事。\n\n这种“装上了却用不了”的报错比“没装”更让人崩溃。因为你会不自觉怀疑是不是命令写错、路径不对、环境没激活浪费大量时间在无关方向排查。实际上报错信息只是在告诉你一个非常朴素的事实当前的 Python 进程里加载到了一个不兼容的 mmcv 版本或错误的 mmcv 实现。\n\n### 1.2 根因BEVFormer 与 mmcv 版本错位\n\nBEVFormer 这个项目比较特殊它大量依赖 OpenMMLab 家族的老接口尤其是 mmcv 1.x 时代的 API 风格。官方代码里很多模块直接调用mmcv.parallel、mmcv.runner、mmcv.Config这些在 2.x 版本里已经改动甚至移除的组件。\n\n我在排查时先把环境里已安装的 mmcv 版本打出来确认\n\nbash\npip show mmcv | grep Version\n\n\n结果看到的是2.1.0。再看 BEVFormer 仓库里的requirements.txt和文档发现它明确要求的是 mmcv-full 1.4 或者 1.6 这个区间至多兼容到 1.x 末代。把 2.x 当成 1.x 用等于让一个旧项目强行对接新框架报错是必然的。\n\n版本错位还会带来连锁反应mmdet3d、mmdet、mmsegmentation 这些配套库全部围绕某个特定 mmcv 版本设计。如果你只改了 mmcv那 mmdet 和 mmdet3d 的版本又对不上接着会冒出第二次、第三次报错。因此mmcv 不是孤立问题它牵动着整条依赖链。\n\n### 1.3 为什么这种老版本问题仍然普遍\n\n有人可能会问都什么年代了老 BEVFormer 为什么还在用旧版 mmcv因为 BEVFormer 的代码核心基于 2022 年前后的空间交叉注意力机制很多自定义算子、数据采样逻辑和训练流程都是对着当时的 mmcv 接口写的。后期 OpenMMLab 升级到 2.x接口变化很大BEVFormer 官方并没有同步做完整迁移这就导致你用新版环境跑旧代码时充满了摩擦。\n\n这种事情在自动驾驶感知、bev 感知这类算法仓库里特别常见。研究型代码不会追求长期兼容作者的目标是把论文效果复现出来环境只在自己的机器上验证过。所以作为使用者我们需要主动把环境锁到作者当年那个“软件快照”上。理解了这一点你就不会再纠结“为什么不能直接用最新版”而是会老老实实把版本固定下来。\n\n## 2. 环境配置关键路径与版本组合选择\n\n### 2.1 一套能真正跑通的版本组合\n\n以下是我在这台 Ubuntu 20.04 CUDA 11.3 RTX 3090 机器上最终验证通过的组合适合大部分想跑 BEVFormer 数据生成和训练的人\n\n| 组件 | 推荐版本 | 说明 |\n| --- | --- | --- |\n| Python | 3.8 | 太高容易出现依赖编译问题 |\n| PyTorch | 1.10.1 | 与 CUDA 11.3 搭配稳定 |\n| torchvision | 0.11.1 | 与 torch 1.10.1 配套 |\n| mmcv-full | 1.4.0 | 推荐直接编译安装 |\n| mmdet | 2.25.1 | 与 mmcv 1.4 一起用 |\n| mmsegmentation | 0.25.0 | 依赖链里的固定一环 |\n| mmdet3d | 1.0.0.dev0 | 按 BEVFormer 仓库指定版本安装 |\n\n这里我想强调的是mmcv 千万不要用最新版也不要直接pip install mmcv更不要顺手把它升级到 2.x。BEVFormer 的很多代码模块是以 1.x 的 API 为基准写的你上 2.x 以后第一眼可能没问题但一旦跑起来各种隐藏的接口参数变化全都会冒出来。\n\n### 2.2 mmcv-full 的安装姿势与坑\n\n在 Python 3.8 的虚拟环境里我的安装步骤是这样。先建环境\n\nbash\nconda create -n bevformer python3.8 -y\nconda activate bevformer\npip install torch1.10.1cu113 torchvision0.11.1cu113 \\\n -f https://download.pytorch.org/whl/torch_stable.html\n\n\n然后安装 mmcv-full。这里最容易出现的分岔路是\n\nbash\n# 错误示范装成纯 Python 包\npip install mmcv\n\n# 正确示范安装带 CUDA 算子编译的完整版\npip install mmcv-full1.4.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html\n\n\n如果你机器上 CUDA 版本比较特殊或者预编译包下载很慢那就直接走源码编译\n\nbash\npip install -r requirements.txt\nMMCV_WITH_OPS1 pip install mmcv-full1.4.0\n\n\n源码编译的好处是保证跟本机 CUDA 版本完全匹配坏处是耗时长可能二十分钟甚至更久。编译过程中如果报CUDA_HOME找不到记得先确认nvcc -V能正常输出并且export CUDA_HOME/usr/local/cuda。\n\n很多人忽略的一点是mmcv-full 和 mmcv 是两套不同的发行包。mmcv 是轻量版只包含基础工具不包含自定义的 CUDA 算子。BEVFormer 里部分 3D 算子会用到这些编译好的 CUDA 组件只装轻量版就会在某个环节突然报AttributeError: module mmcv has no attribute ops。所以在安装时不要只图快该装 full 就装 full。\n\n### 2.3 安装完成后的自检清单\n\n装完以后我建议你不要直接一窝蜂去跑训练先做一轮快速自检。这一步能帮你把“装好了”和“真能用”区分开。\n\nbash\npython -c \import mmcv; print(mmcv.__version__)\\npython -c \import mmcv; print(mmcv.__file__)\\npython -c \import mmdet3d; print(mmdet3d.__version__)\\n\n\n如果第一行输出1.4.0第二行指向的是你当前虚拟环境里的 site-packages第三行也正常那说明基础环境问题不大。还可以进一步测试 mmcv 的编译扩展是否正常\n\nbash\npython -c \from mmcv.ops import nms\\n\n\n这一步很多人会忽略。当我第一次测试时发现mmcv.ops导入失败因为当时安装的 mmcv-full 没有成功编译 CUDA 扩展。后来重新设置了CUDA_HOME再编译才顺利通过。\n\n## 3. 数据 .pkl 生成实操步骤\n\n### 3.1 数据目录与原始资料的准备\n\n环境就绪之后开始处理数据集。BEVFormer 默认使用的数据集是 nuScenes官方数据转换脚本会把原始数据整理成可以直接被训练代码读取的 .pkl 文件。开始前先确认你的目录结构长这样\n\n\ndata/nuscenes/\n├── maps\n├── samples\n├── sweeps\n├── v1.0-trainval\n├── v1.0-test\n├── v1.0-mini\n└── nuScenes_map\n\n\n如果你是从官网下载的数据通常能直接看到这些文件夹。这里有个小坑很多人下载后把目录压缩包直接解压到当前路径导致多出一层嵌套例如data/nuscenes/nuScenes-v1.0/samples。转换脚本扫描data/nuscenes时找不到正确路径就会报错。\n\n### 3.2 生成 pkl 的命令与配置解读\n\n确认目录正常后切换到 BEVFormer 仓库根目录执行\n\nbash\npython tools/data_converter/nuscenes_converter.py \\\n --root-path ./data/nuscenes \\\n --out-dir ./data/nuscenes \\\n --extra-tag nuscenes \\\n --version v1.0-trainval\n\n\n命令本身不复杂但要注意几个参数--root-path指向原始数据的根目录--out-dir是转换结果的输出目录--extra-tag会决定生成的文件名比如nuscenes_infos_train.pkl、nuscenes_infos_val.pkl、nuscenes_infos_test.pkl等--version选择数据版本。\n\n我当时跑在这里时没有立刻进入数据解析而是先在nuscenes_converter.py内部 import 阶段就直接崩溃。报错内容是ModuleNotFoundError: No module named mmcv.ops。这个场景很典型脚本开头会导入大量 OpenMMLab 和检测相关模块而这一步会率先触发 mmcv 的底层环境问题。\n\n### 3.3 脚本执行过程的观察点\n\n如果你也在这一阶段报错重点关注脚本执行时的几个关键输出\n\n- 是否显示loading annotations或loading attribute这类日志\n- Tokyo 数据集较长运行时可能会在一两个小时内别指望秒出\n- 如果脚本中途卡住不动多半是内存或显存不足而不是环境问题。\n\n数据转换过程中会调用 nuscenes-devkit 来读取原始标注。nuscenes-devkit 版本太新可能导致字段解析结构不一致建议固定为1.1.10左右\n\nbash\npip install nuscenes-devkit1.1.10\n\n\n太新的版本理论上兼容性更好但实测下来BEVFormer 这种基于 2022 年代码的仓库用老版本 devkit 更稳。\n\n### 3.4 生成结果验证与内容检查\n\n转换完成后用简单的 Python 脚本验证 .pkl 文件是否包含预期的字段\n\npython\nimport pickle\n\ndata_path ./data/nuscenes/nuscenes_infos_train.pkl\nwith open(data_path, rb) as f:\n infos pickle.load(f)\n\nprint(len(infos[infos]))\nprint(list(infos[infos][0].keys()))\n\n\n正常情况下第一条数据里会包含lidar_path、sweeps、cams、gt_boxes、gt_names这些字段。如果字段缺失多半是因为 nuscenes-devkit 版本差异导致属性名变动或者标注加载不完整。\n\n## 4. 常见问题排查与避坑速查\n\n### 4.1 mmcv 相关报错对照表\n\n我把这次配置中遇到的典型报错整理成了速查表直接照着查就行。\n\n| 报错信息 | 直接原因 | 快速处理 |\n| --- | --- | --- |\n|ModuleNotFoundError: No module named mmcv| 当前环境没安装 mmcv | 装 mmcv-full 1.4.0 |\n|AttributeError: module mmcv has no attribute Dict| 装成了 mmcv 2.x接口变化 | 卸载重装 mmcv-full 1.4.0 |\n|AttributeError: module mmcv has no attribute ops| 只装了轻量版 mmcv没有 CUDA 算子 | 安装完整版 mmcv-full |\n|ImportError: libGL.so.1| 系统缺 OpenGL 相关库 |apt install libgl1 libglib2.0-0|\n|CUDA_HOME is not found| 编译时找不到 CUDA 路径 | 设置export CUDA_HOME/usr/local/cuda|\n|No module named nuscenes| nuscenes-devkit 未安装 |pip install nuscenes-devkit1.1.10|\n\n### 4.2 几条必须牢记的排查原则\n\n环境问题排查有一个黄金法则先确认当前环境再怀疑代码问题。我见过太多人在ImportError时报着“代码明明没问题”的想法去改代码最后发现是虚拟环境没激活或者 shell 里加载了另一个 Python 路径。\n\n建议在转换脚本前插入一个环境检查像这样\n\npython\nimport sys\nimport mmcv\nprint(sys.executable)\nprint(mmcv.__file__)\n\n\n如果sys.executable指向的不是你预期的python那说明 pip 和 python 不对应继续跑下去只会浪费时间。\n\n另一个容易忽略的点是不要在主环境里裸跑实验。我建议单独开一个 conda 环境专门给 BEVFormer 使用。这样做的好处是即使你后面为了其他项目升级了 mmcv 或者 PyTorch也不怕污染 BEVFormer 的环境。\n\n### 4.3 来自重复配置的经验总结\n\n经过这次调错我给自己定下了几条规矩也把它们分享给你\n\n1. 安装任何 OpenMMLab 系项目前先读仓库根目录的requirements.txt和docs/install.md把版本一一对应死。\n2. 安装顺序固定先 PyTorch再 mmcv-full再 mmdet再 mmseg最后 mmdet3d。顺序反了容易隐藏依赖冲突。\n3. 遇到报错先看 ImportError 还是 AttributeError。前者基本是环境缺失后者大概率是版本不匹配。\n4. 生成 .pkl 文件前先跑一次python -m py_compile tools/data_converter/nuscenes_converter.py确认脚本本身没有语法错误再跑完整流程。\n5. 不要贪新不要用 Google Colab 最新环境去硬跑 BEVFormer。Colab 的预装包版本经常把环境搞得乱七八糟。\n\n再多说一个我在实际操作中发现的细节数据转换脚本的日志输出频率不高当它卡在某个阶段时你很难判断是还在正常工作还是已经死掉。最好用ps aux | grep nuscenes_converter查看进程状态并用watch -n 5 nvidia-smi看资源占用。如果 CPU 和内存一直在波动那说明还在处理不需要急着杀进程。\n\n这次踩坑之后我最大的感受是环境配置报错并不可怕可怕的是不知道错在哪里。很多新人第一次遇到 mmcv 相关报错时第一反应是上网搜一段“万能安装命令”贴上去结果越贴越乱。真正有效的做法是把报错信息拆开看它是在 import 阶段报的错还是在使用某个具体函数时报的错是缺了依赖还是版本冲突只要定位到这一点百分之八十的问题都能在五分钟内解决。\n\n比如我现在碰到的所有 mmcv 相关报错几乎都能归结到一个原因环境版本跟代码预期不一致。所以如果你也卡在 .pkl 文件生成这一步无需慌先检查 mmcv 的版本和类型再决定下一步怎么走。按这篇文章的路径走下来你的环境大概率能顺利通过数据生成这一关卡。 }