做计算机视觉这一行的人多半都在某台机器上被Detectron2的安装过程教育过。这个库本身写得很好用但它的依赖链条长得离谱PyTorch、torchvision、CUDA 编译器、gcc 版本、OpenCV、pycocotools、一堆 C/CUDA 扩展要现场编译任何一环错位你看到的报错都可能跟真正的原因隔着十万八千里。用Docker装 Detectron2 不是图新鲜而是把环境这件事一次性固化下来让后面所有的时间都花在模型上而不是环境上。这篇内容适合三类人第一次要跑 Detectron2 的新手、已经跑通但环境被自己搞乱想重做一遍的老手、以及需要把环境交给团队里其他人复现的工程同学。下面全部是我自己在几台不同配置的机器上反复折腾之后总结出来的完整路径包含镜像选型的取舍、Dockerfile 的写法、启动参数的门道以及那些官方文档里不会写的报错与修复方式。1. 为什么我宁愿用 Docker 装 Detectron2也不在宿主机上折腾1.1 这条依赖链到底有多长先把要装的东西数一遍你就能理解为什么宿主机直装的成功率不高。Detectron2 的运行时依赖包括 PyTorch 和 torchvision这两者的版本必须严格配对、Python 版本、CUDA 运行时和驱动、cuDNN编译期依赖包括 gcc/g官方建议 7.5 以上实际用 9 以上更稳、ninja 构建工具、Python 头文件功能依赖包括 OpenCV、pycocotools、fvcore、iopath、Pillow、numpy、scipy。这还没算上你自己后续要装的其他视觉库它们之间往往还会互相拉扯。关键在于这些依赖不是装上了就行而是存在一张隐式的兼容矩阵。PyTorch 的每个 minor 版本都绑定一个特定的 torchvision 版本绑错了不会报错只会在某个深夜的推理阶段返回一堆诡异的数值结果CUDA 的 major 版本决定了你能用哪些架构的显卡gcc 版本和 PyTorch 的 ABI 之间还有一层关系尤其当你从源码编译扩展的时候。宿主机直装最大的问题不是难装而是不可回滚。你为了装 A 项目升级了 PyTorchB 项目就废了你把 gcc 从 9 换到 11系统里其他编译出来的东西可能就开始抱怨。很多人最后的宿主机上堆着三四个 conda 环境、两套 CUDA、一堆LD_LIBRARY_PATH导出自己都说不清哪个在生效。Docker 的价值就在这里每次起一个新容器世界就是干净的你爱怎么折腾怎么折腾删掉容器不留一丝痕迹。1.2 一次典型的版本连环事故复盘我印象最深的一次是在一台刚交付的机器上帮人排障。现象是import detectron2成功但只要import detectron2.modeling就抛undefined symbol。当时的第一反应是重装重装完还是一样。接着怀疑 CUDA 版本改来改去花了两个多小时。真实原因最后是这样的那台机器宿主机预装的驱动比较老最高只支持到某个 CUDA 版本而装上去的 PyTorch 是按更高的 CUDA 版本编译的。torch.cuda.is_available()返回False但由于整段代码在 import 阶段并不会真的初始化 CUDA 上下文所以报错来得绕了一大圈落在了一个跟 CUDA 毫不相干的符号链接错误上。这种报错位置和真实原因相距很远的情况在环境问题上极其常见。如果当时用的是容器排查会快得多换一个已知可用的基础镜像问题瞬间就能确认是环境问题还是代码问题。这种可对照、可二分的能力比任何排障技巧都值钱。1.3 Docker 方案解决了什么又解决不了什么需要说清楚边界。Docker 解决的是宿主机环境隔离和依赖版本固化它把我这能跑和你那也能跑之间的大部分差异抹平了。它不会帮你解决显卡驱动问题——驱动仍然装在宿主机上容器只是借用它也不会帮你解决显存不够的问题nvidia-smi在容器里看到的还是同一张卡。还有一个常见的误解以为容器里装 CUDA 就完事了。实际上容器镜像里带的是CUDA 运行时runtime和工具链toolkit不含内核态驱动。驱动版本决定了你能跑哪个上限的 CUDA 版本镜像里的 CUDA 版本不能高于宿主机驱动支持的上限。这条规则搞错了你会遇到容器起来、nvidia-smi正常但torch.cuda.is_available()是 False 的经典现象。2. 宿主机侧的准备驱动、容器运行时与 GPU 透传2.1 先确认驱动能撑到哪个 CUDA 版本动 Docker 之前先在宿主机上把底子摸清楚这步花三十秒能省后面两小时。# 查看驱动与它支持的最高 CUDA 版本 nvidia-smi输出右上角的CUDA Version: xx.x表示驱动支持的最高 CUDA 运行时版本不是已安装的版本。这个数字是你选镜像的天花板。比如显示 12.4那么镜像里用 cu121 或 cu124 都没问题用 cu126 就有风险。老显卡这块要特别注意。从 CUDA 12 开始官方不再支持 Maxwell 和 Pascal 架构算力 5.x、6.0/6.1。如果你手上是这一类老卡哪怕驱动更新到能支持 CUDA 12也必须退回 CUDA 11.8 的镜像否则装上 PyTorch 之后会出现no kernel image is available for execution on the device这种运行期报错。这个错通常在第一次真正把张量搬到 GPU 上做卷积时才出现前面的 import 和模型构建全都正常非常容易误判成代码问题。对应的一个判断依据是 PyTorch 官方预编译包默认启用的架构列表。较新的版本已经逐步移除了对老算力的支持你可以在容器里跑一句python -c import torch; print(torch.cuda.get_arch_list())看看当前构建覆盖了哪些sm_xx跟nvidia-smi里显卡的算力对一下对不上就换镜像。2.2 让容器能看见 GPU有了驱动还需要容器运行时把 GPU 设备透传进去。这一步在新一点的发行版上通常只需要装上对应的工具包并重启服务docker run --gpus all就能生效。不同发行版的安装方式差异较大我这里不展开具体命令思路是添加官方的软件源、安装容器工具包、执行配置命令把 Docker 的默认运行时改过去、重启 Docker 服务。装完之后有一个很容易被忽略的细节用户组。执行 Docker 命令的账号需要属于docker组否则你就得一直加sudo。加了sudo之后又会出现新问题——容器内以 root 身份运行挂载目录里写出来的文件回到宿主机上就变成 root 所有普通账号想删都删不掉。这个坑我在第 7 节会专门讲。2.3 三条命令快速验证透传是否成功在写任何 Dockerfile 之前先用一条命令确认 GPU 透传链路是通的docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi这三条信息必须同时成立才算通路打通容器能正常启动、nvidia-smi在容器内能看到显卡、输出里的驱动版本和宿主机一致。如果这里就失败了后面所有关于 Detectron2 的讨论都没有意义先把这一段修好。3. 镜像选型官方基础镜像、自建还是别人打包好的3.1 三条路线的真实取舍很多人第一反应是去搜一个能直接跑 Detectron2 的镜像拉下来就想用。我不太推荐这条路原因很简单你不知道那个镜像里 PyTorch 是什么版本、CUDA 是什么版本、有没有被人改过 pip 源、编译选项是不是和你显卡匹配。出了问题你没有任何信息去排查只能重来。真正靠谱的选择是在两条路里挑一是以 PyTorch 官方发布的基础镜像为底自己往上叠二是从一张干净的系统镜像开始把包括 PyTorch 在内的所有东西都自己装。我把三种做法的差异列在下面。路线上手成本可控性镜像体积适合场景拉现成的第三方整合镜像最低最低通常很大临时验证想法、跑个 demoPyTorch 官方基础镜像 叠加中等高中等绝大多数工程场景纯系统镜像从零装最高最高可以很小需要极致瘦身或特殊版本组合中间那条路是我最常走的。PyTorch 官方镜像已经把 CUDA、cuDNN、Python 环境和最重要的torch、torchvision配对好了这一层恰好是最容易出错的交给它省心。Detectron2 本身需要编译所以基础镜像必须选devel版本而不是runtime版本——devel 里带nvcc和完整的编译工具链runtime 里没有你在上面编译 CUDA 扩展会直接失败。3.2 我实际用的基础镜像与版本组合具体到标签我倾向选带devel后缀、CUDA 11.8 或 12.1 的那几个稳定标签。选 11.8 的理由是兼容性最广老显卡新显卡都能覆盖选 12.1 的理由是驱动较新的机器上用起来更顺某些新算子编译出来的性能略好。如果你的机器驱动版本比较新、显卡也都在近几年的范围内12.1 是更舒服的选择。PyTorch 版本我一般固定在 2.x 的某个具体小版本不做浮动。原因是 Detectron2 的编译对 PyTorch 的 C 接口有一定依赖大版本跨越时偶尔会遇到需要打补丁的情况固定住可以让你在半年后重建镜像时得到一模一样的结果。torchvision 必须和 PyTorch 严格对应这是硬性的。常见的对应关系大致是这样的torch 2.1 配 torchvision 0.162.2 配 0.172.3 配 0.182.4 配 0.192.5 配 0.20。这组数字建议每次动手前到官方发布说明里核对一遍因为它会随版本更新变化凭记忆填是很容易翻车的。3.3 选定镜像后的版本核对清单基础镜像拉下来之后别急着装 Detectron2先跑一遍核对。把下面这几项记在纸上后面出问题时有对照物。docker run -it --rm --gpus all pytorch/pytorch:2.1.0-cuda11.8-cudnn8-devel bash -c python -c import torch, torchvision; print(\torch\, torch.__version__); print(\tv\, torchvision.__version__); print(\cuda\, torch.version.cuda); print(\avail\, torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else \no gpu\) nvcc --version gcc --version | head -1 这段输出的信息量很大。torch.version.cuda告诉你 PyTorch 编译时用的 CUDA 版本跟nvcc --version应该大体一致允许小版本差异但不该跨 major。gcc版本决定了你后面编译 Detectron2 时的编译器。torch.cuda.is_available()为 True 说明透传成功。4. 从零写一份能复现的 Dockerfile4.1 分层顺序决定了你重建镜像要等多久Dockerfile 的每一行都是一个层层一旦缓存命中就不会重跑。写这个文件的第一原则是变化频率低的放前面变化频率高的放后面。具体到 Detectron2 的场景顺序应该是基础镜像 → 系统包apt→ Python 依赖pip其中 torch 相关已经在基础镜像里了→ 克隆 Detectron2 源码 → 编译安装 → 拷贝你自己的项目代码。项目代码每天都在改放最后系统包几乎不动放最前面。这样你改一行业务代码重建镜像只需要几秒钟。还有个小技巧把 apt 的update和install写在同一个RUN里并在结尾清掉/var/lib/apt/lists。这样既不会因为缓存导致索引过期也能减小镜像体积。4.2 编译期到底需要装哪些系统包Detectron2 编译过程会用到 C 编译器、CMake、以及一些图像库的头文件。除此之外还有几个运行期才暴露的库不在编译阶段报错但跑起来就给你脸色看其中最典型的是 OpenCV 的动态链接库。下面这份清单是我反复试出来比较全的一组RUN apt-get update apt-get install -y --no-install-recommends \ build-essential \ ninja-build \ cmake \ git \ curl \ wget \ libgl1 \ libglib2.0-0 \ libsm6 \ libxext6 \ libxrender1 \ libgomp1 \ rm -rf /var/lib/apt/lists/*libgl1和libglib2.0-0这两个是ImportError: libGL.so.1: cannot open shared object file的解药。这个报错在无图形界面的容器里出现频率极高因为很多视觉库依赖 OpenCV 的完整版而完整版又依赖系统图形库。如果你确定只用 headless 版本也可以完全不装这两个包改成安装opencv-python-headless。但要注意两条路只能选一条混装会导致 OpenCV 版本冲突症状是某些函数莫名其妙地不可用。ninja-build建议装上。Detectron2 的编译支持用 ninja 加速能明显缩短源码编译的时间尤其是在需要重新编译自定义算子的迭代过程中。4.3 装 Detectron2 的两种方式与选择理由Detectron2 有两种装法pip install从 PyPI 拿包或者克隆源码后pip install -e .以开发模式安装。我几乎总是选后者理由有三个。第一开发模式下你改源码立刻生效调试模型结构时非常方便第二某些情况下你需要针对自己的显卡架构重新编译源码在手边才好操作第三PyPI 上的包版本更新节奏和 GitHub 主干不完全同步如果你要用的某个功能是新加的只有源码里有。开发模式安装对应的命令是RUN git clone --depth 1 --branch v0.6 https://github.com/facebookresearch/detectron2.git /opt/detectron2 \ cd /opt/detectron2 \ pip install --no-cache-dir -e .--depth 1只拉最新一次提交能把克隆时间从几分钟压到十几秒。--branch指定 tag这是保证可复现的关键——不加的话你每次重建都可能拿到不一样的代码。如果网络条件不理想克隆这一步可能会卡住。一个稳妥的做法是提前在宿主机上把源码准备好然后在 Dockerfile 里用COPY拷进去避免构建过程中依赖外网。4.4 一份完整的、我实际在用的 Dockerfile把上面这些拼起来完整版本长这样FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-devel ENV DEBIAN_FRONTENDnoninteractive \ TZAsia/Shanghai \ PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 RUN apt-get update apt-get install -y --no-install-recommends \ build-essential ninja-build cmake git curl wget \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 \ rm -rf /var/lib/apt/lists/* # 锁住 numpy 在 2.0 以下避免部分依赖编译失败 RUN pip install --no-cache-dir numpy2 \ opencv-python-headless \ pycocotools \ scipy \ scikit-image \ tensorboard \ jupyterlab COPY --chown1000:1000 detectron2 /opt/detectron2 RUN cd /opt/detectron2 pip install --no-cache-dir -e . WORKDIR /workspace几点说明。把源码用COPY拷进去而不是在构建时克隆好处是构建完全离线、速度稳定代价是你需要自己维护那份源码。PYTHONUNBUFFERED1让日志实时输出训练时看进度条不会卡住。WORKDIR设成/workspace跟后面挂载的项目目录对应上进去就是工作区。提示numpy2这个约束不是迷信。numpy 2.0 发布后一批依赖它在编译期检查类型的包出现了兼容问题pycocotools 和一些视觉库都在受影响范围内。在确定整条链路都适配之前锁在 1.x 是最省事的选择。5. 启动容器挂载、共享内存与开发方式5.1 数据目录和 pip 缓存的挂载策略镜像建好只是开始怎么起容器才决定了日常使用爽不爽。核心原则是容器是一次性的数据和缓存要落在宿主机上。数据目录必须挂载否则容器一删标注数据、模型权重全没了。挂载的时候注意权限用-v /path/on/host:/workspace/data这种形式并保证宿主机目录的所有者 uid 和容器内运行的 uid 一致否则会出现读得到写不进或者写进去删不掉的尴尬。pip 缓存也值得挂载。你在容器里临时装个包调试如果不挂缓存下次重建容器又得重新下载。挂一个~/.cache/pip进去速度会快很多。同理~/.cache/torch里放着预训练权重的下载缓存挂出来之后就不用每个新容器都重新下载几个 G 的权重了。5.2 shm-size一个不设置就会半夜炸的参数这是我踩过最隐蔽的坑之一。Docker 默认给容器的/dev/shm只有 64MB。Detectron2 的数据加载用多进程 worker进程间通信走共享内存一旦 worker 数量上去或者单张图比较大就会在训练跑到第几十个 iteration 的时候抛出RuntimeError: DataLoader worker (pid xxx) is killed by signal: Bus error。这个错误的迷惑性在于它不发生在启动时而是在训练进行到一半的时候出现很容易被误判成数据有问题或者内存泄漏。实际上就是共享内存不够。解决办法是在docker run时加--shm-size8g具体值根据你的 worker 数量和图像尺寸来定。我的经验值是粗略估算需要的内存量约等于 worker 数量乘以单 batch 数据体积再乘个安全系数。如果不确定先给 8G跑起来再看df -h /dev/shm。另一种做法是把宿主机的一个目录挂到/dev/shm上但这样会绕过内存直接落盘性能反而下降不推荐在训练场景里用。5.3 三种开发方式的适用场景进入容器的开发方式有三种我按使用频率排一下。直接docker exec进 bash。最简单适合写脚本、跑单次推理、看日志。缺点是终端一断进程就没了长训练不适合。在容器里跑 JupyterLab。适合探索性工作比如调可视化、看数据分布、试不同的预处理参数。启动时映射端口-p 8888:8888记得加--ip0.0.0.0和 token 或者密码别裸奔在公网上。在容器里跑 SSH 服务。适合把容器当成一台远程开发机用配合本地编辑器的远程开发功能体验最好。缺点是需要在镜像里多装一个 sshd镜像大一点。三种方式可以共存我在自己的镜像里通常把 Jupyter 装好日常用 exec 进 bash需要长时间跑训练的时候用nohup或者tmux挂在后台。5.4 一条可直接抄的命令与 compose 版本综合上面所有考虑我日常用的启动命令是这样的docker run -itd \ --name d2-dev \ --gpus all \ --shm-size8g \ -v $(pwd):/workspace \ -v ~/.cache/pip:/root/.cache/pip \ -v ~/.cache/torch:/root/.cache/torch \ -v /data/datasets:/workspace/datasets:ro \ -p 8888:8888 \ -w /workspace \ d2:cuda118 \ bash-itd是后台常驻随时docker exec -it d2-dev bash进去。datasets目录用:ro只读挂载防止误操作把原始数据改了——这个习惯一旦养成能避免很多数据被脚本覆盖的悲剧。如果你更喜欢 compose把它翻译过去是一一对应的services: d2: build: . image: d2:cuda118 container_name: d2-dev shm_size: 8gb working_dir: /workspace volumes: - .:/workspace - ~/.cache/pip:/root/.cache/pip - ~/.cache/torch:/root/.cache/torch - /data/datasets:/workspace/datasets:ro ports: - 8888:8888 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] command: bash tty: truedeploy.resources.reservations.devices这一段是新版本 compose 里声明 GPU 的方式和--gpus all等价。6. 验证安装是否真的成功而不是仅仅 import 通过6.1 三层验证法import detectron2成功说明不了任何问题。Detectron2 的顶层__init__很轻几乎不碰 CUDA。真正的坑都在下面两层。我把验证分成三层逐层往上。第一层版本矩阵。写一个小脚本把关键版本全打出来存成文件留着以后出问题第一时间对比import torch, torchvision, detectron2, numpy, cv2 print(torch , torch.__version__) print(torchvision, torchvision.__version__) print(cuda build , torch.version.cuda) print(cudnn , torch.backends.cudnn.version()) print(detectron2 , detectron2.__version__) print(numpy , numpy.__version__) print(opencv , cv2.__version__) print(gpu , torch.cuda.get_device_name(0)) print(arch list , torch.cuda.get_arch_list())第二层自定义算子。Detectron2 里有若干用 C/CUDA 写的扩展比如 ROIAlign、NMS 的加速实现。这些只有在真正调用时才加载。跑一句from detectron2 import _C如果能导入成功说明 C 扩展编译链路是通的。这一步过了绝大部分编译类问题就排除了。第三层端到端跑通。用官方提供的最小推理脚本加载一个预训练模型对一张图做前向。这一层能暴露算子实现在特定显卡上是否可用的问题就是前面提到的no kernel image。6.2 跑一遍官方测试集是值得的如果时间允许我建议跑一下官方的单元测试。不用全跑挑核心的几个模块就行cd /opt/detectron2 python -m pytest tests/test_model_e2e.py -x -q python -m pytest tests/test_roi_align.py -x -qtest_model_e2e.py会构建一个完整的小模型并跑前向反向是最有价值的冒烟测试。它能同时验证 PyTorch、CUDA、自定义算子、以及模型的组装逻辑。我第一次在某个新卡上跑通 Detectron2就是靠这个测试发现问题的——单算子调用都正常但组合起来在某个特定 shape 下会挂。6.3 一个最小可用的推理 demo验证完之后写一个能真正跑出结果的小脚本作为环境可用的最终凭证import torch, cv2 from detectron2 import model_zoo from detectron2.config import get_cfg from detectron2.engine import DefaultPredictor cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file( COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url( COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml) cfg.MODEL.DEVICE cuda if torch.cuda.is_available() else cpu cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 predictor DefaultPredictor(cfg) img cv2.imread(/workspace/datasets/demo.jpg) out predictor(img) inst out[instances].to(cpu) print(检测到目标数:, len(inst)) print(类别:, inst.pred_classes.tolist()) print(得分:, [round(s, 3) for s in inst.scores.tolist()])这段代码第一次跑会去下载权重所以要确保网络通畅或者提前把权重文件放到缓存目录里。跑出结果就说明整条链路是通的。7. 我在实际使用中踩到的坑与修复路径7.1 undefined symbol 报错的排查链路这是最常见也最容易被误判的一类错误。完整报错通常长这样ImportError: /opt/detectron2/detectron2/_C.cpython-310-x86_64-linux-gnu.so: undefined symbol: _ZN3c10...。排查顺序我是这样走的。第一步确认 torch 和 detectron2 是不是在同一个 Python 环境里。听起来很傻但真的有相当比例的情况是因为在两个环境里各装了一半。用python -c import torch; print(torch.__file__)和python -c import detectron2; print(detectron2.__file__)确认路径一致。第二步看是不是编译缓存的问题。Detectron2 编译产物在build/目录下如果你在编译过程中途换过 torch 版本又没清理就会残留旧的.so。清理后重编rm -rf build/ pip install -e .。第三步确认 torch 版本和编译时用的一致。这个信息在.so里可以用ldd看它链接了哪个libtorch。如果链接路径指向一个已经不存在的目录那就是版本切换的残留。7.2 显卡架构不匹配的隐蔽表现前面提过no kernel image is available这里补充一下它的几个变种。有时候报错信息更隐晦是CUDA error: invalid device function或者干脆结果全是零。判断方法是用torch.cuda.get_arch_list()打印出当前构建支持的架构列表再跟nvidia-smi里的算力对比。如果确实不匹配两个选择换一个 CUDA 版本更高的镜像新架构需要新的 CUDA 才支持或者反过来如果显卡太老就退到 CUDA 11.8。这属于选型阶段的错误容器里是修不了的。还有一种情况是显卡本身支持但编译时TORCH_CUDA_ARCH_LIST环境变量设窄了导致只编了部分架构。这种情况重新设置变量后重编即可export TORCH_CUDA_ARCH_LIST7.5;8.0;8.6 cd /opt/detectron2 rm -rf build/ pip install -e .7.3 容器里产生的文件宿主机上删不掉这是用 Docker 做开发的经典烦恼。容器里默认以 root 运行产出的日志、模型文件、缓存目录的所有者是 root退出容器回到宿主机普通账号想清理会提示权限不足只能sudo rm -rf。解决方案有三种按推荐程度排第一种启动时指定用户-u $(id -u):$(id -g)。缺点是如果镜像里没有对应 uid 的用户某些依赖会找不到 home 目录需要额外设置HOME环境变量。用的时候一般这样写-u $(id -u):$(id -g) -e HOME/tmp。第二种在 Dockerfile 里创建一个和宿主机同 uid 的用户并用USER指令切过去。这是最干净的做法但需要在构建时知道宿主机的 uid团队里各人 uid 不同的话就不太通用。第三种跑完之后统一改权限。简单粗暴但容易忘。我自己偏向第一种虽然要处理HOME的小问题但切换成本最低。7.4 内存 OOM 和显存 OOM 要分开看训练突然挂掉很多人第一反应是显存不够其实两者要分开判断。显存 OOM 的报错里会明确写CUDA out of memory并附带显存分配失败的信息。这种情况调小 batch size、开启梯度累积、或者用torch.cuda.empty_cache()缓解。而宿主机内存 OOM 的表现完全不同——进程被系统直接杀掉日志戛然而止没有任何 Python 层的错误堆栈。这种情况常见于数据预处理特别重的时候比如在线做大量图像增强、或者一次把很大的数据集读进内存。看dmesg能看到内核的 OOM killer 记录。区分方法很简单训练中途挂掉且没有 traceback先看dmesg有明确 traceback看报错内容。这个判断顺序能省下大量瞎调参数的时间。7.5 numpy 版本引发的连锁故障numpy 2.0 那次升级掀起的波澜在视觉栈里影响面相当大。症状五花八门有的是AttributeError: module numpy has no attribute float有的是某些编译扩展直接 import 失败还有的是 pycocotools 在解析标注文件时崩溃。处理方式就是锁版本。在 Dockerfile 里显式写numpy2并且放在其他 Python 依赖之前安装这样 pip 在解析依赖时就不会为了满足某个包而把 numpy 升上去。如果在已有容器里遇到这个问题直接pip install numpy2 --force-reinstall重装一遍通常就恢复了。同类的问题还有setuptools版本。新版 setuptools 对某些老式setup.py的兼容性变差会导致pip install -e .失败。遇到编译阶段莫名的AttributeError时pip install setuptools70是一个值得一试的手段。8. 镜像瘦身与团队分发8.1 多阶段构建能砍掉多少开发用的镜像和部署用的镜像需求不一样。开发镜像要带编译器、要能改代码、体积大点无所谓部署镜像只需要推理能力编译工具链全都可以扔掉。用多阶段构建可以做到既方便开发又不臃肿。思路是在第一阶段用 devel 镜像编译好 Detectron2产出.so和安装好的包第二阶段用 runtime 镜像只把编译产物和 Python 依赖拷过去。这样能砍掉一大块体积主要是编译工具链和头文件。不过要提醒一句多阶段构建会显著增加 Dockerfile 的复杂度而且一旦某天你需要在部署镜像里临时调试编译问题会非常难受。我的建议是开发阶段别折腾多阶段等整套流程稳定了、要交付给别人用了再考虑做瘦身版本。8.2 离线分发save 与 load很多场景下目标机器没法连外网或者内网拉镜像速度极慢。这时候需要把镜像导出成文件带走。# 导出并压缩体积通常能压到原来的四成左右 docker save d2:cuda118 | gzip d2-cuda118.tar.gz # 目标机器上导入 gunzip -c d2-cuda118.tar.gz | docker load导出之前记得先docker image prune清一下悬空镜像docker save会把所有层都打进去包括那些已经被新版本覆盖的中间层。另外导出前最好先确认镜像里没有敏感的配置信息比如私有的源地址、访问凭据之类。单机分发用save/load够了多机场景建议还是搭一个内网镜像仓库用push/pull更省事也能享受到层缓存的好处。8.3 版本锁定做到什么程度才够可复现这件事做到什么程度取决于你的场景。如果只是自己用把 PyTorch 和 Detectron2 的 tag 固定住基本就够了。如果要把环境交给别人用建议再进一步把所有 pip 依赖冻结成requirements.txt并且在 Dockerfile 里用pip install -r而不是逐条pip install。这样依赖关系清晰可查也能避免 pip 的依赖解析在不同时间点给出不同结果。我的习惯是在镜像构建成功之后进容器跑一句pip freeze requirements.lock把结果保存到项目里。下次有人问你当时用的什么版本直接给他这个文件。Detectron2 本身因为是-e安装的会在 freeze 里显示成一个本地路径这个记得手工处理掉。说说我自己的做法。我现在的习惯是每接手一个新机器第一件事不是装环境而是把那个已经验证过的镜像docker load进去用一条docker run把环境拉起来先跑通那个最小推理 demo。环境这件事只要有一份经过验证的快照后面所有问题都不再是环境问题。这个顺序反过来做很容易在环境上耗掉一整周而模型的事一点没推进。另外分享一个小技巧我在容器里永远会挂一个/workspace/notes目录把每次遇到的报错原文和解决方案记进去。Detectron2 这套栈的报错重复率很高记过一次下次直接搜自己的笔记比搜别处快得多。这个习惯坚持了半年多排查时间大概缩短了一半。 做计算机视觉这一行的人多半都在某台机器上被Detectron2的安装过程教育过。这个库本身写得很好用但它的依赖链条长得离谱PyTorch、torchvision、CUDA 编译器、gcc 版本、OpenCV、pycocotools、一堆 C/CUDA 扩展要现场编译任何一环错位你看到的报错都可能跟真正的原因隔着十万八千里。用Docker装 Detectron2 不是图新鲜而是把环境这件事一次性固化下来让后面所有的时间都花在模型上而不是环境上。这篇内容适合三类人第一次要跑 Detectron2 的新手、已经跑通但环境被自己搞乱想重做一遍的老手、以及需要把环境交给团队里其他人复现的工程同学。下面全部是我自己在几台不同配置的机器上反复折腾之后总结出来的完整路径包含镜像选型的取舍、Dockerfile 的写法、启动参数的门道以及那些官方文档里不会写的报错与修复方式。1. 为什么我宁愿用 Docker 装 Detectron2也不在宿主机上折腾1.1 这条依赖链到底有多长先把要装的东西数一遍你就能理解为什么宿主机直装的成功率不高。Detectron2 的运行时依赖包括 PyTorch 和 torchvision这两者的版本必须严格配对、Python 版本、CUDA 运行时和驱动、cuDNN编译期依赖包括 gcc/g官方建议 7.5 以上实际用 9 以上更稳、ninja 构建工具、Python 头文件功能依赖包括 OpenCV、pycocotools、fvcore、iopath、Pillow、numpy、scipy。这还没算上你自己后续要装的其他视觉库它们之间往往还会互相拉扯。关键在于这些依赖不是装上了就行而是存在一张隐式的兼容矩阵。PyTorch 的每个 minor 版本都绑定一个特定的 torchvision 版本绑错了不会报错只会在某个深夜的推理阶段返回一堆诡异的数值结果CUDA 的 major 版本决定了你能用哪些架构的显卡gcc 版本和 PyTorch 的 ABI 之间还有一层关系尤其当你从源码编译扩展的时候。宿主机直装最大的问题不是难装而是不可回滚。你为了装 A 项目升级了 PyTorchB 项目就废了你把 gcc 从 9 换到 11系统里其他编译出来的东西可能就开始抱怨。很多人最后的宿主机上堆着三四个 conda 环境、两套 CUDA、一堆LD_LIBRARY_PATH导出自己都说不清哪个在生效。Docker 的价值就在这里每次起一个新容器世界就是干净的你爱怎么折腾怎么折腾删掉容器不留一丝痕迹。1.2 一次典型的版本连环事故复盘我印象最深的一次是在一台刚交付的机器上帮人排障。现象是import detectron2成功但只要import detectron2.modeling就抛undefined symbol。当时的第一反应是重装重装完还是一样。接着怀疑 CUDA 版本改来改去花了两个多小时。真实原因最后是这样的那台机器宿主机预装的驱动比较老最高只支持到某个 CUDA 版本而装上去的 PyTorch 是按更高的 CUDA 版本编译的。torch.cuda.is_available()返回False但由于整段代码在 import 阶段并不会真的初始化 CUDA 上下文所以报错来得绕了一大圈落在了一个跟 CUDA 毫不相干的符号链接错误上。这种报错位置和真实原因相距很远的情况在环境问题上极其常见。如果当时用的是容器排查会快得多换一个已知可用的基础镜像问题瞬间就能确认是环境问题还是代码问题。这种可对照、可二分的能力比任何排障技巧都值钱。1.3 Docker 方案解决了什么又解决不了什么需要说清楚边界。Docker 解决的是宿主机环境隔离和依赖版本固化它把我这能跑和你那也能跑之间的大部分差异抹平了。它不会帮你解决显卡驱动问题——驱动仍然装在宿主机上容器只是借用它也不会帮你解决显存不够的问题nvidia-smi在容器里看到的还是同一张卡。还有一个常见的误解以为容器里装 CUDA 就完事了。实际上容器镜像里带的是CUDA 运行时runtime和工具链toolkit不含内核态驱动。驱动版本决定了你能跑哪个上限的 CUDA 版本镜像里的 CUDA 版本不能高于宿主机驱动支持的上限。这条规则搞错了你会遇到容器起来、nvidia-smi正常但torch.cuda.is_available()是 False 的经典现象。2. 宿主机侧的准备驱动、容器运行时与 GPU 透传2.1 先确认驱动能撑到哪个 CUDA 版本动 Docker 之前先在宿主机上把底子摸清楚这步花三十秒能省后面两小时。# 查看驱动与它支持的最高 CUDA 版本 nvidia-smi输出右上角的CUDA Version: xx.x表示驱动支持的最高 CUDA 运行时版本不是已安装的版本。这个数字是你选镜像的天花板。比如显示 12.4那么镜像里用 cu121 或 cu124 都没问题用 cu126 就有风险。老显卡这块要特别注意。从 CUDA 12 开始官方不再支持 Maxwell 和 Pascal 架构算力 5.x、6.0/6.1。如果你手上是这一类老卡哪怕驱动更新到能支持 CUDA 12也必须退回 CUDA 11.8 的镜像否则装上 PyTorch 之后会出现no kernel image is available for execution on the device这种运行期报错。这个错通常在第一次真正把张量搬到 GPU 上做卷积时才出现前面的 import 和模型构建全都正常非常容易误判成代码问题。对应的一个判断依据是 PyTorch 官方预编译包默认启用的架构列表。较新的版本已经逐步移除了对老算力的支持你可以在容器里跑一句python -c import torch; print(torch.cuda.get_arch_list())看看当前构建覆盖了哪些sm_xx跟nvidia-smi里显卡的算力对一下对不上就换镜像。2.2 让容器能看见 GPU有了驱动还需要容器运行时把 GPU 设备透传进去。这一步在新一点的发行版上通常只需要装上对应的工具包并重启服务docker run --gpus all就能生效。不同发行版的安装方式差异较大我这里不展开具体命令思路是添加官方的软件源、安装容器工具包、执行配置命令把 Docker 的默认运行时改过去、重启 Docker 服务。装完之后有一个很容易被忽略的细节用户组。执行 Docker 命令的账号需要属于docker组否则你就得一直加sudo。加了sudo之后又会出现新问题——容器内以 root 身份运行挂载目录里写出来的文件回到宿主机上就变成 root 所有普通账号想删都删不掉。这个坑我在第 7 节会专门讲。2.3 三条命令快速验证透传是否成功在写任何 Dockerfile 之前先用一条命令确认 GPU 透传链路是通的docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi这三条信息必须同时成立才算通路打通容器能正常启动、nvidia-smi在容器内能看到显卡、输出里的驱动版本和宿主机一致。如果这里就失败了后面所有关于 Detectron2 的讨论都没有意义先把这一段修好。3. 镜像选型官方基础镜像、自建还是别人打包好的3.1 三条路线的真实取舍很多人第一反应是去搜一个能直接跑 Detectron2 的镜像拉下来就想用。我不太推荐这条路原因很简单你不知道那个镜像里 PyTorch 是什么版本、CUDA 是什么版本、有没有被人改过 pip 源、编译选项是不是和你显卡匹配。出了问题你没有任何信息去排查只能重来。真正靠谱的选择是在两条路里挑一是以 PyTorch 官方发布的基础镜像为底自己往上叠二是从一张干净的系统镜像开始把包括 PyTorch 在内的所有东西都自己装。我把三种做法的差异列在下面。路线上手成本可控性镜像体积适合场景拉现成的第三方整合镜像最低最低通常很大临时验证想法、跑个 demoPyTorch 官方基础镜像 叠加中等高中等绝大多数工程场景纯系统镜像从零装最高最高可以很小需要极致瘦身或特殊版本组合中间那条路是我最常走的。PyTorch 官方镜像已经把 CUDA、cuDNN、Python 环境和最重要的torch、torchvision配对好了这一层恰好是最容易出错的交给它省心。Detectron2 本身需要编译所以基础镜像必须选devel版本而不是runtime版本——devel 里带nvcc和完整的编译工具链runtime 里没有你在上面编译 CUDA 扩展会直接失败。3.2 我实际用的基础镜像与版本组合具体到标签我倾向选带devel后缀、CUDA 11.8 或 12.1 的那几个稳定标签。选 11.8 的理由是兼容性最广老显卡新显卡都能覆盖选 12.1 的理由是驱动较新的机器上用起来更顺某些新算子编译出来的性能略好。如果你的机器驱动版本比较新、显卡也都在近几年的范围内12.1 是更舒服的选择。PyTorch 版本我一般固定在 2.x 的某个具体小版本不做浮动。原因是 Detectron2 的编译对 PyTorch 的 C 接口有一定依赖大版本跨越时偶尔会遇到需要打补丁的情况固定住可以让你在半年后重建镜像时得到一模一样的结果。torchvision 必须和 PyTorch 严格对应这是硬性的。常见的对应关系大致是这样的torch 2.1 配 torchvision 0.162.2 配 0.172.3 配 0.182.4 配 0.192.5 配 0.20。这组数字建议每次动手前到官方发布说明里核对一遍因为它会随版本更新变化凭记忆填是很容易翻车的。3.3 选定镜像后的版本核对清单基础镜像拉下来之后别急着装 Detectron2先跑一遍核对。把下面这几项记在纸上后面出问题时有对照物。docker run -it --rm --gpus all pytorch/pytorch:2.1.0-cuda11.8-cudnn8-devel bash -c python -c import torch, torchvision; print(\torch\, torch.__version__); print(\tv\, torchvision.__version__); print(\cuda\, torch.version.cuda); print(\avail\, torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else \no gpu\) nvcc --version gcc --version | head -1 这段输出的信息量很大。torch.version.cuda告诉你 PyTorch 编译时用的 CUDA 版本跟nvcc --version应该大体一致允许小版本差异但不该跨 major。gcc版本决定了你后面编译 Detectron2 时的编译器。torch.cuda.is_available()为 True 说明透传成功。4. 从零写一份能复现的 Dockerfile4.1 分层顺序决定了你重建镜像要等多久Dockerfile 的每一行都是一个层层一旦缓存命中就不会重跑。写这个文件的第一原则是变化频率低的放前面变化频率高的放后面。具体到 Detectron2 的场景顺序应该是基础镜像 → 系统包apt→ Python 依赖pip其中 torch 相关已经在基础镜像里了→ 克隆 Detectron2 源码 → 编译安装 → 拷贝你自己的项目代码。项目代码每天都在改放最后系统包几乎不动放最前面。这样你改一行业务代码重建镜像只需要几秒钟。还有个小技巧把 apt 的update和install写在同一个RUN里并在结尾清掉/var/lib/apt/lists。这样既不会因为缓存导致索引过期也能减小镜像体积。4.2 编译期到底需要装哪些系统包Detectron2 编译过程会用到 C 编译器、CMake、以及一些图像库的头文件。除此之外还有几个运行期才暴露的库不在编译阶段报错但跑起来就给你脸色看其中最典型的是 OpenCV 的动态链接库。下面这份清单是我反复试出来比较全的一组RUN apt-get update apt-get install -y --no-install-recommends \ build-essential \ ninja-build \ cmake \ git \ curl \ wget \ libgl1 \ libglib2.0-0 \ libsm6 \ libxext6 \ libxrender1 \ libgomp1 \ rm -rf /var/lib/apt/lists/*libgl1和libglib2.0-0这两个是ImportError: libGL.so.1: cannot open shared object file的解药。这个报错在无图形界面的容器里出现频率极高因为很多视觉库依赖 OpenCV 的完整版而完整版又依赖系统图形库。如果你确定只用 headless 版本也可以完全不装这两个包改成安装opencv-python-headless。但要注意两条路只能选一条混装会导致 OpenCV 版本冲突症状是某些函数莫名其妙地不可用。ninja-build建议装上。Detectron2 的编译支持用 ninja 加速能明显缩短源码编译的时间尤其是在需要重新编译自定义算子的迭代过程中。4.3 装 Detectron2 的两种方式与选择理由Detectron2 有两种装法pip install从 PyPI 拿包或者克隆源码后pip install -e .以开发模式安装。我几乎总是选后者理由有三个。第一开发模式下你改源码立刻生效调试模型结构时非常方便第二某些情况下你需要针对自己的显卡架构重新编译源码在手边才好操作第三PyPI 上的包版本更新节奏和 GitHub 主干不完全同步如果你要用的某个功能是新加的只有源码里有。开发模式安装对应的命令是RUN git clone --depth 1 --branch v0.6 https://github.com/facebookresearch/detectron2.git /opt/detectron2 \ cd /opt/detectron2 \ pip install --no-cache-dir -e .--depth 1只拉最新一次提交能把克隆时间从几分钟压到十几秒。--branch指定 tag这是保证可复现的关键——不加的话你每次重建都可能拿到不一样的代码。如果网络条件不理想克隆这一步可能会卡住。一个稳妥的做法是提前在宿主机上把源码准备好然后在 Dockerfile 里用COPY拷进去避免构建过程中依赖外网。4.4 一份完整的、我实际在用的 Dockerfile把上面这些拼起来完整版本长这样FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-devel ENV DEBIAN_FRONTENDnoninteractive \ TZAsia/Shanghai \ PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 RUN apt-get update apt-get install -y --no-install-recommends \ build-essential ninja-build cmake git curl wget \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 \ rm -rf /var/lib/apt/lists/* # 锁住 numpy 在 2.0 以下避免部分依赖编译失败 RUN pip install --no-cache-dir numpy2 \ opencv-python-headless \ pycocotools \ scipy \ scikit-image \ tensorboard \ jupyterlab COPY --chown1000:1000 detectron2 /opt/detectron2 RUN cd /opt/detectron2 pip install --no-cache-dir -e . WORKDIR /workspace几点说明。把源码用COPY拷进去而不是在构建时克隆好处是构建完全离线、速度稳定代价是你需要自己维护那份源码。PYTHONUNBUFFERED1让日志实时输出训练时看进度条不会卡住。WORKDIR设成/workspace跟后面挂载的项目目录对应上进去就是工作区。提示numpy2这个约束不是迷信。numpy 2.0 发布后一批依赖它在编译期检查类型的包出现了兼容问题pycocotools 和一些视觉库都在受影响范围内。在确定整条链路都适配之前锁在 1.x 是最省事的选择。5. 启动容器挂载、共享内存与开发方式5.1 数据目录和 pip 缓存的挂载策略镜像建好只是开始怎么起容器才决定了日常使用爽不爽。核心原则是容器是一次性的数据和缓存要落在宿主机上。数据目录必须挂载否则容器一删标注数据、模型权重全没了。挂载的时候注意权限用-v /path/on/host:/workspace/data这种形式并保证宿主机目录的所有者 uid 和容器内运行的 uid 一致否则会出现读得到写不进或者写进去删不掉的尴尬。pip 缓存也值得挂载。你在容器里临时装个包调试如果不挂缓存下次重建容器又得重新下载。挂一个~/.cache/pip进去速度会快很多。同理~/.cache/torch里放着预训练权重的下载缓存挂出来之后就不用每个新容器都重新下载几个 G 的权重了。5.2 shm-size一个不设置就会半夜炸的参数这是我踩过最隐蔽的坑之一。Docker 默认给容器的/dev/shm只有 64MB。Detectron2 的数据加载用多进程 worker进程间通信走共享内存一旦 worker 数量上去或者单张图比较大就会在训练跑到第几十个 iteration 的时候抛出RuntimeError: DataLoader worker (pid xxx) is killed by signal: Bus error。这个错误的迷惑性在于它不发生在启动时而是在训练进行到一半的时候出现很容易被误判成数据有问题或者内存泄漏。实际上就是共享内存不够。解决办法是在docker run时加--shm-size8g具体值根据你的 worker 数量和图像尺寸来定。我的经验值是粗略估算需要的内存量约等于 worker 数量乘以单 batch 数据体积再乘个安全系数。如果不确定先给 8G跑起来再看df -h /dev/shm。另一种做法是把宿主机的一个目录挂到/dev/shm上但这样会绕过内存直接落盘性能反而下降不推荐在训练场景里用。5.3 三种开发方式的适用场景进入容器的开发方式有三种我按使用频率排一下。直接docker exec进 bash。最简单适合写脚本、跑单次推理、看日志。缺点是终端一断进程就没了长训练不适合。在容器里跑 JupyterLab。适合探索性工作比如调可视化、看数据分布、试不同的预处理参数。启动时映射端口-p 8888:8888记得加--ip0.0.0.0和 token 或者密码别裸奔在公网上。在容器里跑 SSH 服务。适合把容器当成一台远程开发机用配合本地编辑器的远程开发功能体验最好。缺点是需要在镜像里多装一个 sshd镜像大一点。三种方式可以共存我在自己的镜像里通常把 Jupyter 装好日常用 exec 进 bash需要长时间跑训练的时候用nohup或者tmux挂在后台。5.4 一条可直接抄的命令与 compose 版本综合上面所有考虑我日常用的启动命令是这样的docker run -itd \ --name d2-dev \ --gpus all \ --shm-size8g \ -v $(pwd):/workspace \ -v ~/.cache/pip:/root/.cache/pip \ -v ~/.cache/torch:/root/.cache/torch \ -v /data/datasets:/workspace/datasets:ro \ -p 8888:8888 \ -w /workspace \ d2:cuda118 \ bash-itd是后台常驻随时docker exec -it d2-dev bash进去。datasets目录用:ro只读挂载防止误操作把原始数据改了——这个习惯一旦养成能避免很多数据被脚本覆盖的悲剧。如果你更喜欢 compose把它翻译过去是一一对应的services: d2: build: . image: d2:cuda118 container_name: d2-dev shm_size: 8gb working_dir: /workspace volumes: - .:/workspace - ~/.cache/pip:/root/.cache/pip - ~/.cache/torch:/root/.cache/torch - /data/datasets:/workspace/datasets:ro ports: - 8888:8888 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] command: bash tty: truedeploy.resources.reservations.devices这一段是新版本 compose 里声明 GPU 的方式和--gpus all等价。6. 验证安装是否真的成功而不是仅仅 import 通过6.1 三层验证法import detectron2成功说明不了任何问题。Detectron2 的顶层__init__很轻几乎不碰 CUDA。真正的坑都在下面两层。我把验证分成三层逐层往上。第一层版本矩阵。写一个小脚本把关键版本全打出来存成文件留着以后出问题第一时间对比import torch, torchvision, detectron2, numpy, cv2 print(torch , torch.__version__) print(torchvision, torchvision.__version__) print(cuda build , torch.version.cuda) print(cudnn , torch.backends.cudnn.version()) print(detectron2 , detectron2.__version__) print(numpy , numpy.__version__) print(opencv , cv2.__version__) print(gpu , torch.cuda.get_device_name(0)) print(arch list , torch.cuda.get_arch_list())第二层自定义算子。Detectron2 里有若干用 C/CUDA 写的扩展比如 ROIAlign、NMS 的加速实现。这些只有在真正调用时才加载。跑一句from detectron2 import _C如果能导入成功说明 C 扩展编译链路是通的。这一步过了绝大部分编译类问题就排除了。第三层端到端跑通。用官方提供的最小推理脚本加载一个预训练模型对一张图做前向。这一层能暴露算子实现在特定显卡上是否可用的问题就是前面提到的no kernel image。6.2 跑一遍官方测试集是值得的如果时间允许我建议跑一下官方的单元测试。不用全跑挑核心的几个模块就行cd /opt/detectron2 python -m pytest tests/test_model_e2e.py -x -q python -m pytest tests/test_roi_align.py -x -qtest_model_e2e.py会构建一个完整的小模型并跑前向反向是最有价值的冒烟测试。它能同时验证 PyTorch、CUDA、自定义算子、以及模型的组装逻辑。我第一次在某个新卡上跑通 Detectron2就是靠这个测试发现问题的——单算子调用都正常但组合起来在某个特定 shape 下会挂。6.3 一个最小可用的推理 demo验证完之后写一个能真正跑出结果的小脚本作为环境可用的最终凭证import torch, cv2 from detectron2 import model_zoo from detectron2.config import get_cfg from detectron2.engine import DefaultPredictor cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file( COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url( COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml) cfg.MODEL.DEVICE cuda if torch.cuda.is_available() else cpu cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 predictor DefaultPredictor(cfg) img cv2.imread(/workspace/datasets/demo.jpg) out predictor(img) inst out[instances].to(cpu) print(检测到目标数:, len(inst)) print(类别:, inst.pred_classes.tolist()) print(得分:, [round(s, 3) for s in inst.scores.tolist()])这段代码第一次跑会去下载权重所以要确保网络通畅或者提前把权重文件放到缓存目录里。跑出结果就说明整条链路是通的。7. 我在实际使用中踩到的坑与修复路径7.1 undefined symbol 报错的排查链路这是最常见也最容易被误判的一类错误。完整报错通常长这样ImportError: /opt/detectron2/detectron2/_C.cpython-310-x86_64-linux-gnu.so: undefined symbol: _ZN3c10...。排查顺序我是这样走的。第一步确认 torch 和 detectron2 是不是在同一个 Python 环境里。听起来很傻但真的有相当比例的情况是因为在两个环境里各装了一半。用python -c import torch; print(torch.__file__)和python -c import detectron2; print(detectron2.__file__)确认路径一致。第二步看是不是编译缓存的问题。Detectron2 编译产物在build/目录下如果你在编译过程中途换过 torch 版本又没清理就会残留旧的.so。清理后重编rm -rf build/ pip install -e .。第三步确认 torch 版本和编译时用的一致。这个信息在.so里可以用ldd看它链接了哪个libtorch。如果链接路径指向一个已经不存在的目录那就是版本切换的残留。7.2 显卡架构不匹配的隐蔽表现前面提过no kernel image is available这里补充一下它的几个变种。有时候报错信息更隐晦是CUDA error: invalid device function或者干脆结果全是零。判断方法是用torch.cuda.get_arch_list()打印出当前构建支持的架构列表再跟nvidia-smi里的算力对比。如果确实不匹配两个选择换一个 CUDA 版本更高的镜像新架构需要新的 CUDA 才支持或者反过来如果显卡太老就退到 CUDA 11.8。这属于选型阶段的错误容器里是修不了的。还有一种情况是显卡本身支持但编译时TORCH_CUDA_ARCH_LIST环境变量设窄了导致只编了部分架构。这种情况重新设置变量后重编即可export TORCH_CUDA_ARCH_LIST7.5;8.0;8.6 cd /opt/detectron2 rm -rf build/ pip install -e .7.3 容器里产生的文件宿主机上删不掉这是用 Docker 做开发的经典烦恼。容器里默认以 root 运行产出的日志、模型文件、缓存目录的所有者是 root退出容器回到宿主机普通账号想清理会提示权限不足只能sudo rm -rf。解决方案有三种按推荐程度排第一种启动时指定用户-u $(id -u):$(id -g)。缺点是如果镜像里没有对应 uid 的用户某些依赖会找不到 home 目录需要额外设置HOME环境变量。用的时候一般这样写-u $(id -u):$(id -g) -e HOME/tmp。第二种在 Dockerfile 里创建一个和宿主机同 uid 的用户并用USER指令切过去。这是最干净的做法但需要在构建时知道宿主机的 uid团队里各人 uid 不同的话就不太通用。第三种跑完之后统一改权限。简单粗暴但容易忘。我自己偏向第一种虽然要处理HOME的小问题但切换成本最低。7.4 内存 OOM 和显存 OOM 要分开看训练突然挂掉很多人第一反应是显存不够其实两者要分开判断。显存 OOM 的报错里会明确写CUDA out of memory并附带显存分配失败的信息。这种情况调小 batch size、开启梯度累积、或者用torch.cuda.empty_cache()缓解。而宿主机内存 OOM 的表现完全不同——进程被系统直接杀掉日志戛然而止没有任何 Python 层的错误堆栈。这种情况常见于数据预处理特别重的时候比如在线做大量图像增强、或者一次把很大的数据集读进内存。看dmesg能看到内核的 OOM killer 记录。区分方法很简单训练中途挂掉且没有 traceback先看dmesg有明确 traceback看报错内容。这个判断顺序能省下大量瞎调参数的时间。7.5 numpy 版本引发的连锁故障numpy 2.0 那次升级掀起的波澜在视觉栈里影响面相当大。症状五花八门有的是AttributeError: module numpy has no attribute float有的是某些编译扩展直接 import 失败还有的是 pycocotools 在解析标注文件时崩溃。处理方式就是锁版本。在 Dockerfile 里显式写numpy2并且放在其他 Python 依赖之前安装这样 pip 在解析依赖时就不会为了满足某个包而把 numpy 升上去。如果在已有容器里遇到这个问题直接pip install numpy2 --force-reinstall重装一遍通常就恢复了。同类的问题还有setuptools版本。新版 setuptools 对某些老式setup.py的兼容性变差会导致pip install -e .失败。遇到编译阶段莫名的AttributeError时pip install setuptools70是一个值得一试的手段。8. 镜像瘦身与团队分发8.1 多阶段构建能砍掉多少开发用的镜像和部署用的镜像需求不一样。开发镜像要带编译器、要能改代码、体积大点无所谓部署镜像只需要推理能力编译工具链全都可以扔掉。用多阶段构建可以做到既方便开发又不臃肿。思路是在第一阶段用 devel 镜像编译好 Detectron2产出.so和安装好的包第二阶段用 runtime 镜像只把编译产物和 Python 依赖拷过去。这样能砍掉一大块体积主要是编译工具链和头文件。不过要提醒一句多阶段构建会显著增加 Dockerfile 的复杂度而且一旦某天你需要在部署镜像里临时调试编译问题会非常难受。我的建议是开发阶段别折腾多阶段等整套流程稳定了、要交付给别人用了再考虑做瘦身版本。8.2 离线分发save 与 load很多场景下目标机器没法连外网或者内网拉镜像速度极慢。这时候需要把镜像导出成文件带走。# 导出并压缩体积通常能压到原来的四成左右 docker save d2:cuda118 | gzip d2-cuda118.tar.gz # 目标机器上导入 gunzip -c d2-cuda118.tar.gz | docker load导出之前记得先docker image prune清一下悬空镜像docker save会把所有层都打进去包括那些已经被新版本覆盖的中间层。另外导出前最好先确认镜像里没有敏感的配置信息比如私有的源地址、访问凭据之类。单机分发用save/load够了多机场景建议还是搭一个内网镜像仓库用push/pull更省事也能享受到层缓存的好处。8.3 版本锁定做到什么程度才够可复现这件事做到什么程度取决于你的场景。如果只是自己用把 PyTorch 和 Detectron2 的 tag 固定住基本就够了。如果要把环境交给别人用建议再进一步把所有 pip 依赖冻结成requirements.txt并且在 Dockerfile 里用pip install -r而不是逐条pip install。这样依赖关系清晰可查也能避免 pip 的依赖解析在不同时间点给出不同结果。我的习惯是在镜像构建成功之后进容器跑一句pip freeze requirements.lock把结果保存到项目里。下次有人问你当时用的什么版本直接给他这个文件。Detectron2 本身因为是-e安装的会在 freeze 里显示成一个本地路径这个记得手工处理掉。说说我自己的做法。我现在的习惯是每接手一个新机器第一件事不是装环境而是把那个已经验证过的镜像docker load进去用一条docker run把环境拉起来先跑通那个最小推理 demo。环境这件事只要有一份经过验证的快照后面所有问题都不再是环境问题。这个顺序反过来做很容易在环境上耗掉一整周而模型的事一点没推进。另外分享一个小技巧我在容器里永远会挂一个/workspace/notes目录把每次遇到的报错原文和解决方案记进去。Detectron2 这套栈的报错重复率很高记过一次下次直接搜自己的笔记比搜别处快得多。这个习惯坚持了半年多排查时间大概缩短了一半。