最近把一台新配的机器从零搭成了能跑MMYOLO训练的环境折腾了整整三个晚上。白天在公司用现成镜像习惯了换了台裸机才意识到环境配置这个环节才是目标检测项目里最容易被低估的坑。MMYOLO不是单一框架它是PyTorch、MMEngine、MMCV、MMDetection、MMYOLO五层依赖叠起来的一条链路任何一层版本对不上后面全崩。这套东西的安装难度不在敲命令而在版本矩阵的匹配。本篇是我在Windows和Linux两套系统上反复踩坑后梳理出的完整路径从选版本、装依赖到跑通推理和训练一条命令一条命令说清楚顺便把最折磨人的几个报错和排查逻辑也一并交代了。1. 装这个框架前先搞清楚它到底依赖什么1.1 MMYOLO和它背后的MM家族MMYOLO是OpenMMLab项目里的YOLO系列工具箱基于PyTorch实现支持YOLOv5、YOLOv6、YOLOv8、RTMDet等一串主流检测模型。很多人一开始以为它就是一个普通pip包装完就能用实际上它的定位是上层应用下面还压着三层基础库PyTorch深度学习计算的底层引擎负责张量运算和自动求导。MMEngineOpenMMLab所有项目的统一训练/推理引擎负责Runner、Hook、日志、权重管理这些通用能力。MMCV提供计算机视觉领域的基础算子其中包含大量C/CUDA编译的扩展算子是环境配置里最容易出事的角色。MMDetectionOpenMMLab的通用检测库MMYOLO很多数据流程和检测头的实现直接复用了它的组件。MMYOLO本身主要负责模型结构、数据增强、训练策略这些YOLO专属逻辑但它运行的前提是下面几层全都要装对。这个叠加态结构决定了它的安装不能简单pip install mmyolo了事——依赖之间的版本咬合特别紧尤其是MMCV和PyTorch/CUDA版本必须严格匹配。1.2 为什么版本矩阵这么容易出问题拿MMCV举例它分为mmcv和mmcv-lib两套安装方式。普通pip install mmcv装的版本CPU/GPU算子可能不完整训练时跑到某个自定义算子突然报undefined symbol。而mmcv-lib是预编译版本它的下载地址里必须指定CUDA版本和PyTorch版本比如cu118/torch2.0这就是一套组合索引。如果你的PyTorch是2.0配CUDA 11.8结果MMCV下了 cu117 的预编译包安装时往往不报错但一跑模型就崩。PyTorch、MMCV、MMDetection三者的版本匹配关系在OpenMMLab官方文档里有对照表但实际项目里经常有人clone了一个别人的项目里面requirements.txt锁的版本和自己机器上的CUDA不一致这就引发了连环报错。所以环境配置的第一步不是急着敲conda create而是先明确你的硬件和驱动能支持哪套CUDA然后倒推出整条技术栈的版本组合。2. 版本选型把你机器的底子摸清楚2.1 光看显卡驱动决定CUDA上限安装CUDA之前必须先搞清楚显卡驱动支持的CUDA版本上限是多少。注意这里说的是上限驱动向后兼容老的驱动跑不了新的CUDA runtime。Linux下用nvidia-smi查看右上角的 CUDA Version 就是当前驱动能支持的最高CUDA版本。Windows下在NVIDIA控制面板-系统信息里也能看到。很多教程一上来就让你装CUDA 11.8或者12.1但如果你的驱动版本停在470.x那连CUDA 11.4都跑不了。一个非常常见的误区是电脑里装了CUDA 11.8的toolkit就以为能跑CUDA 11.8的程序。实际上PyTorch在运行时会调用驱动层的CUDA runtime驱动不够新程序一样起不来报错通常长这样CUDA error: no kernel image is available for execution on the device还有一种情况是电脑里同时装了多个CUDA版本nvidia-smi显示的CUDA Version其实只是驱动支持的版本不是当前环境默认的toolkit版本很容易造成误判。稳妥的做法是nvcc -V查看当前PATH里生效的toolkit版本两个命令搭配着看。2.2 一套经过验证的版本组合我自己的实践下来以下这套组合在兼容性和性能上比较平衡也符合MMYOLO官方要求的依赖区间PythonPyTorchCUDA Toolkittorchvisionmmcv-lib3.81.13.111.70.14.12.0.13.92.0.111.80.15.22.0.13.102.1.012.10.16.02.1.0更推荐的是中间那套Python 3.9 PyTorch 2.0.1 CUDA 11.8。原因很简单PyTorch 2.0引入了torch.compile加速能力MMYOLO在RTMDet系列的训练脚本里对这块有优化CUDA 11.8也是对老显卡兼容性最好的版本GTX 10系、20系、30系、40系都能跑。如果你的显卡是RTX 4090这类新卡建议直接看第三套因为新卡的驱动通常已经支持CUDA 12.x了。选择Python 3.9而不是3.10/3.11的原因在于编译兼容性。MMCV里有一部分算子需要从源码编译Python 3.11刚出的时候很多依赖库的C扩展还没有预编译包会触发源码编译导致时间剧增和报错。虽然现在新版已经跟上来了但为了稳妥3.9是最不折腾的选择。2.3 版本对应关系的查询方法版本匹配信息不是背下来的要学会自己查。核心是看OpenMMLab官方的安装文档里的版本对照表。查询路径我整理一下打开MMYOLO官方文档的安装页找到版本对应关系一节里面有MMEngine、MMCV、MMDetection、MMYOLO各自的版本要求区间。查看MMCV文档里的get_started/installation页里面有预编译包列表https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html你需要确认自己的CUDA和PyTorch组合在这个列表里是否存在。mim install mmcv2.1.0时mim会自动检测当前PyTorch版本和CUDA版本选择对应的预编译包这比手动pip install靠谱得多。表格化的版本矩阵其实就是一张可行域你要做的不是选最新而是选一个所有依赖都有预编译交汇点的组合。这套思路在后续配置其他OpenMMLab项目比如MMDetection、MMSegmentation、MMPose时完全通用。3. 全流程安装从空环境到跑通的每一行命令3.1 建一个干净的环境别污染基础环境首先使用conda创建独立环境这一步强烈建议不要省。很多人在base环境里直接装装完发现以前的项目跑不了了新项目也各种看不懂的冲突。独立环境至少能保证出了问题直接删环境重来不会影响其他项目。conda create -n mmyolo python3.9 -y conda activate mmyolo如果你的conda下载依赖太慢可以考虑配置国内镜像源这一步属于常规操作。重点提醒conda装python时不要图省事用conda install python3.9因为conda可能会顺带更新一堆包在后续pip安装时造成不一致。进入环境后先升级pip和setuptools这两个工具的版本如果太老很容易在编译MMCV时报一些莫名其妙的错误python -m pip install --upgrade pip setuptools wheel3.2 安装PyTorch所有问题的源头PyTorch的安装务必要用官方指定源不要用默认的PyPI源。原因很简单PyPI上默认的PyTorch是CPU版本哪怕你的机器是GPUtorch.cuda.is_available()也会返回False。而且这个坑很难排查因为你装的时候根本不会报错。pip install torch2.0.1 torchvision0.15.2 --index-url https://download.pytorch.org/whl/cu118装完后立刻验证GPU是否可用python -c import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))如果输出2.0.1 True NVIDIA GeForce ...说明PyTorch、CUDA、GPU三者已经打通了。如果返回False先别急着往下装先把这一步解决不然后面所有工作都是白费的。以我自己的经验这一步最常见的坑是明明装的是cu118版本但torch.cuda.is_available()返回False。排查路径是先看torch.__version__里有没有cu118后缀没有的话说明装成了CPU版本有后缀但False那么检查驱动是否支持CUDA 11.8或者你机器上的显卡是否被系统正确识别了。3.3 安装MM系列依赖库MM系列依赖库安装的现代方式是使用OpenMMLab的工具mim它能够自动分析并匹配版本pip install -U openmim mim install mmengine mim install mmcv2.0.0,2.1.0 mim install mmdet3.0.0,4.0.0mim在处理MMCV安装时会读取当前Python环境里PyTorch的版本和CUDA版本然后从OpenMMLab的预编译索引里选择一个最合适的mmcv-lib包。这比自己手动拼-f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html这种URL要方便得多也能少踩很多坑。注意我特意在mmcv和mmdet上加了版本范围约束。MMYOLO 0.6.0这个版本要求MMCV大于等于2.0.0且小于2.1.0MMDetection大于等于3.0.0且小于4.0.0。如果不加范围限制mim会装最新的MMCV 2.1.x或MMDetection 4.x那和MMYOLO 0.6.0的接口就不兼容了运行时会报AttributeError: module mmdet has no attribute xxx这样的错误。3.4 安装MMYOLO本体安装MMYOLO本体我推荐源码安装而不是pip install mmyolo。源码安装好处是第一代码路径就是你的工作目录改模型结构、调配置可以直接生效第二pip默认装的稳定版可能滞后源码版上可能已经修了一些bug。git clone https://github.com/open-mmlab/mmyolo.git cd mmyolo pip install -e .如果你的网络环境访问GitHub不理想可以先把压缩包下载下来再用unzip解压或者使用国内镜像源加速git clone这类属于常规手段。装完以后-e .是editable模式改了代码立刻生效不用重复安装。依赖装完建议用下面这行命令做一次快速体检python -c import mmengine; print(mmengine, mmengine.__version__) python -c import mmcv; print(mmcv, mmcv.__version__) python -c import mmdet; print(mmdet, mmdet.__version__) python -c import mmyolo; print(mmyolo, mmyolo.__version__)如果这四行都能正常输出版本号说明所有依赖的Python层面已经就绪。但这只是第一关真正考验的是CUDA算子能否验证通过mim check mmcv运行后会输出一堆检查项主要是验证MMCV里的CUDA扩展是否能正常导入和运行。看到 No broken installation found 之类的结果才说明MMCV这层真正健康。我在第一次装完时mmcv导入正常但mim check直接报了缺失_ext模块的问题这种属于安装时选了CPU版本后面不得不全部重来。4. 环境验证不跑一次推理都不算真正装好4.1 跑通一张图片的推理装完环境后第一件事找一张真实的图片跑通推理我一般用MMYOLO自带的demo图片python demo/demo.py demo/demo.jpg \ configs/yolov5/yolov5_s-v61_syncbn_fast_8xb16-300e_coco.py \ yolov5_s-v61_syncbn_fast_8xb16-300e_coco_20220918_105700-f09696e6.pth第一次跑的时候模型权重需要下载到checkpoints目录下如果网络不理想可以用mim工具先下mim download mmyolo \ --config yolov5_s-v61_syncbn_fast_8xb16-300e_coco \ --dest ./checkpoints然后执行demo.py。命令跑完以后应该会显示检测结果图片里面的人和几只动物会被画上框并保存一张带标注的输出图。这一步的意义在于验证整条数据链路——图片解码、数据预处理、模型前向、后处理、可视化——是否全部正常。任何一层有问题都会在这一步暴露。4.2 用一小段训练流程验证完整闭环推理通过之后建议再跑一个极小的训练片段确认反向传播和优化器流程也正常python tools/train.py configs/yolov5/yolov5_s-v61_syncbn_fast_8xb16-300e_coco.py \ --cfg-options max_epochs1 train_dataloader.batch_size2这里的--cfg-options是MMEngine提供的命令行覆盖配置的机制把300轮的训练计划改成1轮、batch size改成2目的就是快速走一遍训练的所有环节。命令跑起来后观察日志里是否有loss值在下降以及显存占用是否正常增长。我见过不少环境推理是好的但训练在DistributedSampler初始化阶段就崩了。所以训练流程验证不要省。如果这时发现某个OP报 Not compiled with CUDA support大概率还是MMCV的安装方式和PyTorch不匹配。这时候不要试图修补直接把当前环境删了重装更省时间——这也就是为什么一开始坚持用独立conda环境的关键原因。4.3 用TensorBoard实时看指标MMEngine默认会在训练过程中把日志写到work_dirs目录里面包含JSON日志和TensorBoard事件文件。你可以在另一个终端里启动可视化tensorboard --logdir work_dirs观察曲线是否正常同时对后续调参也有帮助。这一步虽然不是环境验证的必需环节但提前把可视化链路确认好后面正式训练的时候能省不少心。5. 排坑实录安装过程中最常遇到的几类问题5.1 mmcv编译时被系统杀掉有段时间很多人选择源码编译安装MMCV执行pip install mmcv2.0.1 --no-binary mmcv后编译进程在CPU高负载运行数分钟后被内核杀掉终端显示Killed。这个问题的根源通常是编译过程中使用了所有CPU核心内存占用飙升到超出系统物理内存。解决方法是限制编译并行度MAX_JOBS4 pip install mmcv2.0.1 --no-binary mmcvMAX_JOBS控制的是编译时的并行任务数4意味着同一时间最多编4个编译单元内存紧张就调到2。不过我现在的建议是优先用mim install mmcv装预编译包源码编译只是没有对应预编译包的降级方案不要一上来就编译给自己找罪受。5.2 libGL.so.1缺失最容易忽略的系统依赖另一个高频报错是OSError: libGL.so.1: cannot open shared object file: No such file or directory这种情况常见于最小化安装的Linux服务器或Docker容器里系统缺少OpenCV依赖的动态库。解决办法是安装系统库# Ubuntu/Debian apt-get update apt-get install -y libgl1 libglib2.0-0如果是CentOS/RHEL命令对应的是yum install mesa-libGL glib2。这类问题在文档里往往没人提但几乎每个用OpenCV做图像处理的框架都会遇到属于通用坑。5.3 CUDA摄像头级别的花式报错运行推理时出现RuntimeError: CUDA error: invalid device ordinal表示代码尝试访问的GPU编号不存在。常见原因有两个一是单卡机器上代码或配置里写了device_ids[0,1]二是进程并发时环境变量CUDA_VISIBLE_DEVICES设置了不存在的设备号。检查方式是用nvidia-smi看当前有几张卡并用echo $CUDA_VISIBLE_DEVICES查看当前环境变量。还有一种报错AssertionError: Torch not compiled with CUDA enabled这个就很直白了说明你PyTorch装成了CPU版本要回到第3.2节重新安装GPU版。5.4 多次重装后环境变脏环境配置过程中反复安装非常常见最典型的脏环境表现是pip list里看到多个版本号相近的包Python import时的路径居然不是 pip show 对应的目录。这是因为pip的缓存机制和旧版本残留的.egg-link文件在作怪。我的建议是排查超过20分钟没头绪直接放弃修复删除conda环境重来conda deactivate conda remove -n mmyolo --all conda create -n mmyolo python3.9 -y环境配置本身就是重复劳动与其在脏环境里浪费时间不如重来一遍。这个经验可能反直觉但确实是我踩过多次坑后悟出来的最实在的效率提升手段。5.5 显存不够的隐藏原因最后说一个训练阶段才出现的问题明明官方文档写了YOLOv5s可以在11G显存的卡上训练你用的是24G显存的3090结果训练时依旧OOM。排查后发现问题出在训练config里的batch_size是按8卡配置的单卡训练时实际占用的显存远超预期。解决方案很简单在训练命令里覆盖batch sizepython tools/train.py ... --cfg-options train_dataloader.batch_size4另外数据加载线程数persistent_workers和num_workers也会影响内存和显存峰值遇到OOM时可以一并调小。最后说点实在话这套环境配置我已经在不同机器上完整走过不下五次了从Ubuntu 18.04到22.04从GTX 1080 Ti到RTX 4090经验就是版本选型阶段多花半小时后面安装和调试能省一个晚上。我个人的习惯是先把torch.cuda.is_available()和mim check mmcv这两关跑过才继续装上层框架千万不要图省事一口气把全链路装完再去调试那样报错时根本分不清是哪一层出了问题。另一个小技巧足够朴素但很有用把每一步安装命令都记到一个笔记文件里包括日期和机器型号。下次装新机器时直接照着跑遇到问题也方便复盘是哪一步和环境相关。如果你也踩过其他没见过的MMYOLO环境报错建议先别急着重装把完整堆栈贴到社区里大概率有人遇到过很多时候比自己死磕快得多。