企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习
• 预训练
• 微调

本指南围绕仓库 det/docker/README.md 提供的官方 Docker 方案，完整讲解如何为本项目内置的 detectron2 环境构建 GPU 容器镜像、通过docker/docker-compose两种方式启动、复用持久化模型缓存，以及构建部署容器以编译运行 TorchScript C++ 推理示例。读完本文，你将能够在 NVIDIA GPU 主机上复现本项目官方推荐的容器化开发与部署工作流，并理解镜像构建过程中与 CUDA、OpenCV、PyTorch 版本相关的关键设计决策。

1. 容器化方案概览与前置条件

项目在 det/docker 目录下提供了三份容器相关文件：

• Dockerfile：构建用于日常开发与推理的基础容器（detectron2:v0），内置 Python、PyTorch 1.10、torchvision 0.11.1、OpenCV 与 fvcore；
• deploy.Dockerfile：在基础容器之上叠加 libtorchvision 与 OpenCV 开发库，用于编译 tools/deploy 下的 C++ 部署示例；
• docker-compose.yml：声明式封装 GPU 资源、共享内存、X11 转发等运行参数，方便一键启动。

使用前提（以官方文档为准）：

镜像基础为nvidia/cuda:11.1.1-cudnn8-devel-ubuntu18.04，并特意选用 Ubuntu 18.04 系统以避免 OpenCV 兼容性问题（见 Dockerfile 中的注释，对应 upstream issue #3524）。因此整套方案面向 CUDA 11.1 生态，配套的 PyTorch 版本为 1.10、torchvision 为 0.11.1。

2. 使用 docker 命令行构建与启动容器

官方推荐的最直接路径是进入 docker 目录后执行构建。以下命令位于 det/docker/README.md：

cd docker/ # Build: docker build --build-arg USER_ID=$UID -t detectron2:v0 . # Launch (require GPUs): docker run --gpus all -it \ --shm-size=8gb --env="DISPLAY" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ --name=detectron2 detectron2:v0

2.1 关键参数解析

• --build-arg USER_ID=$UID：将宿主机当前用户的 UID 传入构建期，Dockerfile 用它创建非 root 用户appuser并加入sudo组（%sudo ALL=(ALL) NOPASSWD:ALL允许免密提权）。这是保证容器内文件属主与宿主机一致、方便挂载数据卷的关键设计；
• --gpus all：向容器暴露全部 GPU，需要 Docker ≥ 19.03 与 NVIDIA Container Toolkit 支持；
• --shm-size=8gb：将/dev/shm扩到 8GB。PyTorch DataLoader 的多进程数据加载依赖共享内存，默认 64MB 极易触发Bus error或 OOM，这是运行训练/推理 demo 的必备参数；
• --env="DISPLAY"与--volume="/tmp/.X11-unix:/tmp/.X11-unix:rw"：把宿主机的显示环境变量与 X11 socket 传入容器，使 demo/demo.py 的 OpenCV 可视化窗口能够弹出；
• --name=detectron2：为容器命名，后续docker inspect需要用到该名称。

启动后还需要一步授权，让容器访问宿主机 X server 以显示图像：

xhost +local:`docker inspect --format='{{ .Config.Hostname }}' detectron2`

docker inspect会取出容器的 Hostname（即容器 ID），xhost +local:<hostname>仅对该容器来源的本地连接放行 X 访问权限，比xhost +全局放行更安全。

2.2 在容器内验证安装

进入容器后，可以直接复现 Dockerfile 注释中给出的官方冒烟测试命令，用 COCO 官方样例图跑一次 Mask R-CNN 推理：

wget http://images.cocodataset.org/val2017/000000439715.jpg -O input.jpg python3 demo/demo.py \ --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input.jpg --output outputs/ \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl

该命令会自动从 detectron2 模型仓库下载预训练权重并执行推理。若没有 X 环境，可去掉--output直接保存到目录；demo/demo.py 还支持--webcam、--video-input、--confidence-threshold（默认 0.5）与多个--input路径，配合容器内已内置的 OpenCV 可灵活演示。

3. 使用 docker-compose 启动

若已安装 docker-compose ≥ 1.28.0 与 nvidia-docker-toolkit，官方文档给出更简洁的启动方式：

cd docker && USER_ID=$UID docker-compose run detectron2

docker-compose.yml 已把这些参数全部声明化：

• build.args.USER_ID: ${USER_ID:-1000}：从环境变量注入 UID，缺省 1000；
• deploy.resources.reservations.devices：通过capabilities: [gpu]请求 GPU 资源（Compose 的 GPU 支持自 1.28.0 起可用）；
• shm_size: "8gb"、ulimits.memlock: -1、ulimits.stack: 67108864：对齐 PyTorch 训练的内存要求；
• volumes与environment：只读挂载 X11 socket 并透传DISPLAY、NVIDIA_VISIBLE_DEVICES=all；
• 注释中还保留了接入摄像头（/dev/video0）的示例，取消注释即可让容器访问宿主机摄像头做实时推理。

4. 构建部署容器以编译 C++ 推理示例

基础容器构建成功后，可按 deploy.Dockerfile 叠加出部署镜像，用于编译和运行 TorchScript 格式的 C++ 示例：

# Build: docker build -t detectron2-deploy:v0 -f deploy.Dockerfile . # Launch: docker run --gpus all -it detectron2-deploy:v0

注意该镜像以FROM detectron2:v0为基础（deploy.Dockerfile），因此必须先完成第 2 节的构建。部署镜像额外完成四件事：

1. 设置CMAKE_PREFIX_PATH指向~/.local/lib/python3.6/site-packages/torch/，让 CMake 找到 libtorch；
2. 安装libopencv-dev（C++ 版 OpenCV）；
3. 从源码编译安装 libtorchvision（torchvision v0.11.1 的 C++ 库），供 TorchScript tracing/scripting 导出模型运行；
4. 进入 tools/deploy 目录执行cmake && make，把 torchscript_mask_rcnn.cpp 编译成tools/deploy/build下的可执行文件。

编译产物对应三种导出方法的完整流程，参见 tools/deploy/README.md。以 tracing 方式为例，先在 Python 侧导出模型：

./export_model.py --config-file ../../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --output ./output --export-method tracing --format torchscript \ MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl \ MODEL.DEVICE cuda

再在部署容器内用 C++ 运行：

./build/torchscript_mask_rcnn output/model.ts input.jpg tracing

scripting与caffe2_tracing两种导出方法命令类似，只需替换--export-method与最后一个运行参数。需要留意 torchscript_mask_rcnn.cpp 中的一个约束：caffe2_tracing 导出模型不包含 padding 逻辑，输入图像宽高必须能被 32 整除（FPN 模型要求），代码中以assert(height % 32 == 0 && width % 32 == 0)强制检查。

5. 使用持久化缓存目录，避免重复下载模型

默认情况下 Dockerfile 通过ENV FVCORE_CACHE="/tmp"把 fvcore 的模型缓存固定到容器内/tmp，容器销毁后缓存即丢失，每次启动都会重新下载权重。官方文档给出的解决方案是把缓存目录挂载到宿主机：

docker run --gpus all -it \ --shm-size=8gb --env="DISPLAY" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ --volume=$HOME/.torch/fvcore_cache:/tmp:rw \ --name=detectron2 detectron2:v0

关键点：宿主机目录$HOME/.torch/fvcore_cache被挂载到容器内的/tmp，正好覆盖FVCORE_CACHE指向的路径（Dockerfile），因此模型权重在多次docker run之间得以复用。注意该缓存同时会承接其他临时文件写入，需确保目录权限与容器内appuser兼容。

6. 在容器内安装新依赖

官方文档区分了“持久修改”与“临时修改”两种方式：

持久修改（修改镜像本身，适用于每次启动都要用到的依赖）：编辑 Dockerfile，在合适位置追加 RUN 指令后重新构建：

RUN sudo apt-get update && sudo apt-get install -y vim

由于基础镜像已创建免密 sudo 用户appuser（Dockerfile），容器内也可直接用sudo安装系统包；修改镜像后需重新执行docker build --build-arg USER_ID=$UID -t detectron2:v0 .使改动生效。

临时修改（不重建镜像，仅在当前容器会话内生效）：直接进入容器执行：

sudo apt-get update && sudo apt-get install -y vim

容器退出后改动即丢失，适合快速验证。

7. 镜像构建的源码级解读与常见坑

结合 Dockerfile 全文，有三个值得关注的设计点：

1. 构建期强制编译 CUDA 算子：ENV FORCE_CUDA="1"（第 30 行）。原因如注释所述——docker build期间无法访问 GPU，若不设置该变量，detectron2 的 setup 会因检测不到 CUDA 而退化为纯 CPU 编译，导致容器内无法使用 GPU；
2. 通过TORCH_CUDA_ARCH_LIST覆盖默认架构：构建期无法探测宿主机 GPU 型号，因此把常见架构（Kepler、Maxwell、Pascal、Volta、Turing 等）全部编入（第 33-34 行）。代价是编译时间明显变长；如果你明确知道自己的 GPU 架构，可修改该 ARG 为单架构（如6.0;7.0）以加快构建，这也与 INSTALL.md 中关于TORCH_CUDA_ARCH_LIST的建议一致；
3. 非 root 运行 +FVCORE_CACHE固定：镜像最终以appuser身份、在detectron2_repo工作目录下运行，模型缓存固定到/tmp，与第 5 节的挂载方案相互配合。

若在容器内遇到 CUDA 相关报错，可参考 INSTALL.md 的常见问题清单，例如用python -m detectron2.utils.collect_env检查 CUDA 版本一致性、核对 GPU 计算能力是否在编译架构列表内等。

8. 完整工作流速查

整套流程覆盖了从“日常推理开发”到“TorchScript C++ 部署”的完整闭环，是复现本项目（Vision Mamba + detectron2）检测/分割能力的推荐容器化路径。

• 人工智能
• 计算机视觉
• 深度学习
• 预训练
• 微调