Caffe2 和 Detectron 这套环境难装是出了名的。很多跟我一样接触过老项目的开发者手里拿着的代码和模型权重还是 Caffe2 时代留下的或者要复现某些只提供了 Caffe2 版本配置的经典检测实验那就绕不开这套环境。我这次完整尝试了一次 Caffe2-Detectron 代码环境构建从方案选型、源码编译、算子集成到最后的验证和排错每一步都踩了坑也总结了方法。这篇文章就是完整的记录适合需要在旧代码基上做目标检测研究、维护历史项目或者单纯想理解 Caffe2 生态怎么运作的人参考。先说清楚这套环境到底要装什么、装起来为什么费劲再看具体怎么落地。1. 为什么这套环境这么难装核心矛盾先说清楚1.1 不只是装个框架那么简单Detectron 是一个目标检测与实例分割框架里面实现了 Faster R-CNN、Mask R-CNN、RetinaNet 等一系列经典模型。它运行在 Caffe2 之上而 Caffe2 是一个静态计算图风格的深度学习框架。这里的关键在于Detectron 使用了大量 Caffe2 官方版本里默认不包含的自定义 GPU 算子最常见的就是 ROIAlign、RoIWarp、PSROIPool 这类跟区域提议相关的算子。所以你以为你只是装一个框架实际上你要做的是把 Caffe2 从源码完整编译一遍并且在编译的时候把 Detectron 需要的那些算子的源码一起打进去让它们链接进同一个运行时。这个过程一旦中间任何一步版本不匹配最终得到的库要么编译失败要么运行时报找不到符号、找不到模块。我第一次尝试时低估了这个复杂度以为跟装 OpenCV 一样 pip 一下就行结果花了一整天反复在编译失败和 import 报错之间打转。后来拆开看才明白问题几乎都集中在三个地方Caffe2 源码与 CUDA 版本、编译器版本的兼容性Detectron 自定义算子是否被正确编译进 Caffe2以及 Python 环境的依赖版本是否被锁死。这三个地方就是整套环境的命门后面所有操作都是围绕它们展开的。1.2 三种搭建路线我为什么选了最折腾的源码编译摆在面前的道路一共有三条我先把它们的差别说清楚方案优点缺点建议现成 Docker 镜像理论上开箱即用镜像体积大可修改性差底层版本被固定想定制算子无从下手只做快速 demo 演示可以考虑预编译 Python 包安装快几乎是历史遗留版本不带 Detectron 自定义算子根本过不了检测那一步不推荐白费功夫源码编译完全可控能集成自定义算子可追踪每一步耗时耗力依赖处理繁琐最终选型也是唯一能真正满足项目的方案Docker 方案看起来很美好但我自己的体会是容器里能跑起来和能改代码是两回事。如果你想在 Detectron 源码里改一个算子、加一个模块或者把模型接到自己的数据流水线上容器会成为一个巨大的黑盒子。而且当时可用的镜像大多年久失修内部的 CUDA 版本和驱动接口也可能跟宿主机不兼容反而不如老老实实源码编译。预编译包则更直接它的问题是根本没有 Detectron 需要的那些自定义算子。Caffe2 后来并入了 PyTorch 主线单独的 Caffe2 预编译包早就停止维护了你装到的版本连modules/detectron这个模块都没有GUP 算子注册也不全所以这条路从一开始就不成立。2. 搭建前的硬性检查清单不做好这些后面全是灾难2.1 硬件、系统与驱动层面的确认先泼一盆冷水Detectron 的算子几乎全部是针对 CUDA 写的CPU-only 的 Caffe2 基本跑不了 Detectron 的实际推理。所以第一道硬性门槛就是你得有一块支持 CUDA 的 N 卡。显存建议至少 8GB 以上跑 Mask R-CNN 推理勉强够用如果要做训练或者跑大 batch16GB 及以上才舒服再往上就是多卡的问题了。系统方面Ubuntu 16.04 和 18.04 是最稳的我这次用的就是 18.04。新一点的 Ubuntu 20.04 或 22.04 也见过有人装上但要么得自己修补 Caffe2 源码里的旧接口要么编译时 GCC 版本过高导致一堆 C 语法报错性价比很低。如果你是 CentOS 系建议先确认所有依赖包的可用性再动手我见过不少人在 CentOS 上卡在 OpenCV 和 protobuf 的编译上。驱动和 CUDA 的搭配直接影响后面所有编译。我这次选了 CUDA 9.2 加 cuDNN 7.x 的组合。为什么不用更新的 CUDA 10 或 11因为 Caffe2 stable 分支的源码在 CUDA 10 上编译需要额外改一些地方而在 CUDA 9.2 下几乎不用做特殊处理。这不是说新版本一定不行而是你要清楚自己是在做一套老环境的构建目标不是追新而是让老代码跑起来。装驱动时用厂商提供的 runfile 或 deb 包统一管理不要混装因为后面 CMake 检测 CUDA 版本时如果发现多个版本会直接陷入选择困难。GCC 版本也要提前确认。当年这个生态验证过的编译器范围是 GCC 5.4 到 7.x我这次用的是 7.5。太高版本会在编译 CUDA 相关代码时出现各种 C 标准问题太低版本又可能不支持某些新语法两头都难受。2.2 Python 环境隔离是后手棋Caffe2 时代的 Python 环境非常脆弱强烈建议用 conda 建立一个完全独立的环境不要碰系统 Python。我这次用的是 Python 3.6这是当年验证最充分的版本。Python 3.5 太老很多依赖包已经不再提供对应轮子Python 3.7 在某些 Caffe2 源码文件里会因为asyncio关键字问题报错需要额外打补丁。3.6 处于一个刚好可以拿到老版本依赖、同时又能用上现代语法特性的平衡点。创建环境时的命令大致是这样conda create -n detectron python3.6 protobuf3.6.1 numpy1.16 conda activate detectron pip install cython six future matplotlib opencv-python pyyaml我特意把protobuf锁定在 3.6.1。为什么这么在意 protobuf 版本因为 Caffe2 源码在编译期会生成一批 protobuf 相关的代码运行时加载 proto 文件时程序的 protobuf 库版本必须和编译期一致。新版 protobuf 会直接拒绝加载旧版生成的二进制描述报出libprotobuf version mismatch之类的错误这个错非常隐蔽光看报错完全想不到是版本匹配问题。2.3 COCO API 与检测数据工具链Detectron 训练和评估依赖 COCO API 的 Python 封装也就是常说的 pycocotools。这个包现在虽然有预编译轮子但老环境里经常还是要手动编译。编译前确认你已经装好了 Cython然后从 COCO API 的仓库拉取 PythonAPI 子目录执行cd PythonAPI python setup.py build_ext --inplace这一步能不能过取决于你的 Python 环境和 Cython 版本。如果报错说缺少 Cython 或 numpy 头文件先回头检查依赖是否齐全。pycocotools 编译不通过是后续很多问题的源头因为 Detectron 在运行时会用pycocotools.coco来加载 COCO 格式的标注少了它训练流程根本启动不起来。3. Caffe2 源码编译全流程每一个参数都决定成败3.1 拉取源码与分支选择Caffe2 源码仓库的主分支后来并入了 PyTorch单独的仓库已经停止活跃开发。但别急我们要的不是最新提交而是当年被大量项目验证过的稳定版。我这次用的做法是拉取仓库后切到v0.8.2或者stable分支。master 分支虽然也存在但里面不少脚本已经和现在的环境脱节甚至目录结构都有变化直接用它会增加很多不必要的麻烦。拉取源码时建议留够磁盘空间完整编译之后整个构建目录加源码会占到 10GB 以上。如果磁盘紧张编译中途遇到No space left on device那是一种非常让人崩溃的体验。3.2 CMake 配置参数详解每个开关我都解释一遍Caffe2 使用 CMake 构建配置阶段是所有问题的集中爆发期。我最终使用的配置思路如下每个参数后面是它的实际意义。cd caffe2 mkdir build cd build cmake .. \ -DUSE_CUDAON \ -DUSE_CUDNNON \ -DUSE_NCCLON \ -DBUILD_PYTHONON \ -DUSE_DETECTRONON \ -DUSE_GLOGON \ -DUSE_GFLAGSON \ -DUSE_OPENCVON \ -DCMAKE_PREFIX_PATH/path/to/conda/envs/detectron \ -DCUDA_ARCH_LIST6.1;7.0USE_CUDA和USE_CUDNN是基础开关不必多说。USE_NCCL决定是否编译多卡通信支持如果只是单卡推理可以不开但我建议直接打开因为后面你可能想换到多卡训练到时候再重新编译一遍成本更高。BUILD_PYTHON必须 ON否则不会生成 Python 绑定Detectron 根本没法调用 Caffe2。USE_GLOG和USE_GFLAGS是日志和命令行解析工具建议都开Caffe2 运行时的大量日志输出依赖它们不开的话排查问题时会少掉很多有用信息。USE_OPENCV也很关键Detectron 的推理脚本要用 OpenCV 读写图片虽然也可以在 Python 层单独处理但最好让底层的图像接口也支持它。USE_DETECTRON是这个配置里的灵魂它会告诉 CMake 把modules/detectron下的算子源码一起编进 Caffe2最终的 .so 库里才会包含 Detectron 需要的那些自定义算子。CMAKE_PREFIX_PATH指向 conda 环境的路径目的是让 CMake 找到正确的 Python 解释器和头文件。这里有个非常隐蔽的坑如果你忘了指定CMake 可能找到系统自带的 Python最后编译出来的 Python 绑定跟你的 conda 环境版本不一致import 的时候直接报错。CUDA_ARCH_LIST是我建议一定要加的参数。如果不指定CMake 默认尝试编译支持所有 GPU 架构的代码不仅编译时间翻倍生成的库体积也巨大。查一下自己显卡的 Compute Capability比如 6.1 对应 Pascal 架构7.0/7.5 对应 Volta/Turing填上之后能省下不少时间。我在第一次尝试时没加这个参数编译了将近两个小时加完之后四十分钟就完了。3.3 编译、安装与 PYTHONPATH 配置CMake 配置没问题之后进入编译阶段。我建议这样执行make -j16-j16表示并行编译具体数字根据 CPU 核数调。如果内存不够大并行度太高会直接把内存吃满然后编译进程被系统杀掉。我试过在 16GB 内存的机器上开-j16一旦遇到大文件编译直接 OOM后来降到-j8才稳。如果内存紧张可以先开-j4跑完再看剩余资源逐步提升。编译完成后最重要的一步是设置环境变量。Caffe2 的 Python 包生成在build目录下它不会自动注册到 Python 的搜索路径里。你需要手动把它加进去export PYTHONPATH/path/to/caffe2/build:$PYTHONPATH export LD_LIBRARY_PATH/path/to/caffe2/build/lib:$LD_LIBRARY_PATH这个环境变量配置是整套环境能否被正常 import 的关键。我见过太多人编译成功之后直接import caffe2失败第一反应是重装实际上是 PYTHONPATH 没设对。为了省去每次手动 export 的麻烦我建议把这两行写进 conda 环境的activate.d脚本中这样每次激活环境都会自动加载。具体做法是在 conda 环境的etc/conda/activate.d目录下新建一个.sh文件内容就是上面两行。3.4 检测运算符编译与 Detectron 自身构建到这里Caffe2 本身编译好了但还差最后一块拼图Detectron 项目的 Python 包和它自己的编译产物。Detectron 的代码里有一部分是 Cython 写的比如跟 ROI 相关的后处理逻辑这些需要单独编译。在 Caffe2 源码目录下先执行一次 Python 包的开发模式安装cd /path/to/caffe2 python setup.py develop然后进入 Detectron 项目目录cd /path/to/detectron python setup.py build develop这一步会把 Detectron 内部的.pyx文件编译成.so模块同时把整个项目链接到当前 Python 环境的 site-packages 中因为用了 develop 模式后续改代码不需要重新安装特别适合调试。这步如果报错十有八九是前面的 pycocotools 或 Cython 依赖没装好回头检查 COCO API 是否编译成功。编译完成后你应该能在 Python 里执行这样的验证from caffe2.python import workspace print(workspace.NumCudaDevices())如果能正确输出你的 GPU 数量说明 Caffe2 编译正确CUDA 识别正常。如果输出 0 或直接报错那问题大概率出在 CUDA 库路径没有被正确加载或者编译时 CUDA 版本和运行时版本不一致。这时不要急着往下走先解决 GPU 识别问题再继续不然到了后面推理阶段所有 GPU 相关算子都会失败。4. 验证环节怎么做才算真正成功4.1 从 import 到 GPU 识别很多人以为编译完、import 不报错就算环境搭好了其实这一关只是起点。我建议按顺序做三步验证。第一步检查 Caffe2 核心模块是否能导入import caffe2 from caffe2.python import core print(core.device_option)能正常打印出 device 相关的对象说明核心绑定没有缺失符号。第二步检查 GPU 算子是否注册完整from caffe2.python import workspace print(workspace.NumCudaDevices())这一步要特别关注输出。如果返回 0说明 Caffe2 没有正常识别 GPU后面的检测算子即便编译进去了也跑不起来。如果报错提到cuda runtime相关的内容优先检查LD_LIBRARY_PATH是否包含 CUDA 的 lib64 目录。第三步尝试初始化一个 GPU workspace 并执行一个简单的张量操作。这里不要用复杂算子开个 GPU 上 3x3 矩阵乘法就行。成功了说明 CUDA 运行时和 Caffe2 的 GPU 执行引擎是通的。4.2 用 Detector 跑通一次单图推理环境验证到这里就可以进入真正的实测了。Detectron 的仓库里带了一批经典的模型配置文件比如 Mask R-CNN 的e2e_mask_rcnn_R-101-FPN_2x.yaml对应的是当年在 COCO 数据集上训练好的模型权重。这些权重以.pkl文件形式提供从官方仓库的模型库下载即可。推理命令大概长这样python tools/infer_simple.py \ --cfg configs/12_2017_baselines/e2e_mask_rcnn_R-101-FPN_2x.yaml \ --output-dir /tmp/detectron-output \ --image-ext jpg \ --wts /path/to/model_final.pkl \ /path/to/test_images注意几个参数--wts指向下载好的权重文件--image-ext指定输入图片格式最后的路径是放待测图片的目录。脚本会把画好框和掩膜的图片输出到--output-dir。这一步能跑通是最让人安心的时刻说明整条链路都是通的Caffe2 加载了含 Detectron 自定义算子的库Python 绑定能调用到 GPU 算子模型权重能正常加载图片在前向推理时没有算子执行错误。我第一次跑通时输出目录里出现带掩膜的图片那种成就感还是很真实的。如果在这一步报错最常见的错误是No module named detectron._C这说明 Detectron 自己的 Cython 扩展编译产物缺失回到 3.4 小节重新执行python setup.py build develop。还有一种是报找不到某个算子的 GPU 实现说明USE_DETECTRON编译开关可能没生效需要回头确认 Caffe2 的 build 里是否真的生成了libcaffe2_detectron_ops_gpu.so这个文件。4.3 最小训练实验验证 backward 与 loss 下降推理通了不代表训练一定能走通。如果你只是做推理可以跳过这一步但如果你要复现实验或者微调模型训练链路的验证就很有必要。我的建议是不要上来就全量训练那样太耗时也没有意义而是挑一个小网络配置比如e2e_faster_rcnn_R-50-FPN_1x.yaml然后改小 batch size拿几张自有图片拼一个微型数据集跑几个 iteration。重点是观察 loss 是否在缓慢下降以及 backward 过程是否报错。如果 loss 一直为 NaN通常说明学习率没有按照配置文件调整或者输入数据的格式有问题。如果报错集中在pycocotools相关说明 COCO API 的封装没弄好回看 2.3 节。训练验证通过后你再做任何模型微调或者代码修改心里就有底了。这套环境的构建才算真正完成了闭环。5. 踩坑实录那些文档不会告诉你的问题5.1 编译阶段的高频报错与处理整个尝试过程中编译阶段的问题最多。我整理了一个速查表方便你对比自己的情况。现象根本原因处理办法CMake 报找不到 Python.hCMAKE_PREFIX_PATH 未指向 conda 环境显式指定 conda 环境的 include 路径编译过程报 C 语法错误GCC 版本过高或过低降到 7.x必要时用 update-alternatives 切换make 过程中 OOM 被杀并行编译任务过多内存不足降低-j并行度或临时增加交换分区生成 .so 时报 undefined referenceprotobuf 版本不匹配确保环境内 protobuf 版本与编译时一致libcaffe2_detectron_ops_gpu.so 不存在USE_DETECTRON 参数未在 CMake 阶段生效清空 build 目录重新 cmake确认参数编译 OOM 这个问题我吃了不少亏。后来我学到的技巧是编译前用free -g看一眼可用内存并行度大概控制在内存总量除以 2GB 左右宁可多编译一会也别被系统杀进程。编译到一半被杀掉再重新开始浪费的时间远大于降低并行度省下的时间。5.2 运行期问题与排查顺序编译期问题集中在 CMake 和 make运行期问题则集中在 import 和算子调用。下面几个是我印象最深的。一个是ImportError: undefined symbol通常会出现在 import caffe2 或 import detectron 的时候。这个报错基本可以确定是 .so 库链接顺序或者版本不对。检查LD_LIBRARY_PATH里有没有多个 CUDA 版本目录如果有把旧版本的路径从末尾移掉让链接器优先找到你期望的版本。另一个是module caffe2 has no attribute python这种问题常见于 PYTHONPATH 覆盖。如果你在环境里装了多个版本的 Caffe2 或者 PyTorch字符串路径顺序会影响 import 结果。用python -c import caffe2; print(caffe2.__file__)看一眼实际加载的路径确认它确实是你在编译时设置的 build 目录。还有一个比较隐蔽的是 GPU 算子全部注册失败但import caffe2不报错。这时候运行任何带 ROI 算子的模型都会在第一次前向时崩掉。排查办法是尝试导入一个只调用简单 GPU 算子的样例如果连简单算子都失败说明 Caffe2 的 GPU 支持根本没有编译进去回头检查 CMake 阶段的 CUDA 配置如果简单算子能跑而 ROI 算子崩才考虑检测算子链接问题。5.3 那一次让我差点放弃的问题最后分享一个让我印象最深的坑。第一次所有编译都成功验证也通过了但推理时发现模型输出的检测框完全乱套坐标明显错位。我不是没怀疑过权重文件但是权重是从官方下载的理论上不该有问题。排查了一整天才发现问题出在 OpenCV 的读取通道上。我的 Python 环境里同时存在两个版本的 OpenCV系统自带的旧版本被优先加载导致图片读取时通道顺序和 Detectron 预期的 RGB 不一致检测结果自然全错。解决办法是在环境变量里强制 Python 优先使用 conda 环境中新装的 OpenCV或者干脆在 Python 里统一用cv2.imread读取后手动转通道。这个问题的排查过程让我意识到老代码环境里出现问题很多时候不是代码本身的问题而是环境里潜藏的各种隐性版本冲突。遇到奇怪现象时先检查运行时加载了哪些动态库再看数据在每一步的形态是否正常往往比守着报错信息死磕更有效。6. 这套环境后续的维护建议环境搭好之后不是一劳永逸的。我建议把这个构建过程中用到的所有版本、参数、环境变量配置整理成一个清单文档放在项目里。不要相信记忆也不要只依赖 shell history因为你不知道哪一次清理环境后这些信息会消失。如果团队里有多个人要复用这套环境最好在验证通过后把整个 conda 环境连同编译产物打包成一个镜像。这样即便换机器也能在十几分钟内恢复一个可用的环境。我第一次搭环境花了两天第二次用打包好的环境加部署脚本四十分钟就能开工。另外在 Caffe2 环境里写代码时尽量不升级任何依赖。哪怕只是一个小小的库版本升级都有可能导致某个 .so 的 ABI 不兼容让原本稳定的环境突然崩掉。锁版本不是保守是这套生态的生存法则。最后再说个小技巧把环境变量写进 conda 激活脚本这件事非常实用。具体操作是在 conda 环境的etc/conda/activate.d目录下创建脚本写入export PYTHONPATH和export LD_LIBRARY_PATH之后每次conda activate detectron都会自动带好配置再也不用跟路径参数较劲。这套环境虽然折腾但当你终于看到模型在图片上画出整齐的检测结果时前面所有编译失败的报错都显得没那么难以接受了。