在 Ubuntu 上用 Python 3.8 + RTX 4090 安装 Detectron2 完整指南

Detectron2 是 Facebook AI Research 发布的下一代目标检测平台，支持 Faster R-CNN、Mask R-CNN 等主流检测/分割算法。本文总结了我在 Python 3.8.10 + RTX 4090 + CUDA 12.4 + PyTorch 2.1.2 环境下安装 Detectron2 的全过程，包括环境检测、安装步骤以及常见问题解决方案。

老 Faster R-CNN	Detectron2
手写训练流程	Trainer 已封装
VOC 定制麻烦	COCO / VOC / 自定义都成熟
CUDA 版本敏感	高度兼容
已停止维护	Meta 官方维护

一、环境检测

在安装之前，我们需要确认硬件、CUDA、Python 和 PyTorch 版本。

1️⃣ GPU 与驱动

nvidia-smi

输出示例：

+-----------------------------------------------------------------------------------------+ | NVIDIA-SMI 550.54.10 Driver Version: 551.61 CUDA Version: 12.4 | | GPU Name Memory-Usage | | 0 NVIDIA GeForce RTX 4090 719MiB / 24564MiB | +-----------------------------------------------------------------------------------------+

✅ GPU ：RTX 4090

✅ CUDA 驱动版本 ：12.4

✅ 显存：24GB

2️⃣ CUDA 编译器

nvcc --version

示例输出：

Cuda compilation tools, release 12.4, V12.4.99

3️⃣ Python 版本

python -V

输出：

Python 3.8.10

创建虚拟环境（Python 3.8）

bash 复制代码

cd /mnt/d/develop
python3.8 -m venv d2env
source d2env/bin/activate

4️⃣ PyTorch 版本

安装 PyTorch 2.1.2 + CUDA 12.1：

bash 复制代码

pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 \ --index-url https://download.pytorch.org/whl/cu121

验证：

bash 复制代码

python -c "import torch; print(torch.__version__); print(torch.version.cuda)"

输出：

bash 复制代码

2.1.2 12.1

✅ PyTorch 与 Detectron2 兼容。

⚠️ 注意：Detectron2 官方支持的最低稳定 PyTorch 版本为 2.0，2.1 属实验性，但通常在 CUDA 12.x 下可用。

二、安装 Detectron2

1️⃣ 安装前准备

先安装构建依赖：

bash 复制代码

pip install opencv-python pycocotools matplotlib tqdm
pip install --upgrade pip setuptools wheel pip install ninja

说明：

wheel：解决 invalid command 'bdist_wheel' 错误
ninja：加快 C++/CUDA 扩展编译速度

2️⃣ 克隆源码

git clone https://github.com/facebookresearch/detectron2.git cd detectron2

3️⃣ 安装（普通模式）

普通模式：

pip install .

✅ 推荐方法，如果不需要开发模式即可使用。

4️⃣ 安装（开发模式 editable）

如果希望修改源码并立即生效：

bash 复制代码

pip install -e . --no-build-isolation

常见问题及解决方案：

问题	解决方法
`ModuleNotFoundError: No module named 'torch'`	确保虚拟环境里已经安装 PyTorch，再用 `--no-build-isolation`
`error: invalid command 'bdist_wheel'`	安装 wheel：`pip install --upgrade pip setuptools wheel`
`UserWarning: Attempted to use ninja ...`	安装 ninja：`pip install ninja`

5️⃣ 验证安装

bash 复制代码

python -c "import detectron2; print(detectron2.__version__)"

如果输出版本号，说明 Detectron2 安装成功。

三、训练注意事项（A0 图纸 / VOC 数据集）

数据集切图
- A0 图纸太大（8K~12K），需切成 patch
- Patch 大小：2048~3072 px
- Overlap ≥ 512 px，保证墙体、门窗完整
Detectron2 配置示例

\configs\PascalVOC-Detection\faster_rcnn_R_50_FPN.yaml

bash 复制代码

_BASE_: "../Base-RCNN-FPN.yaml"
MODEL:
  WEIGHTS: "detectron2://ImageNetPretrained/MSRA/R-50.pkl"
  MASK_ON: False
  RESNETS:
    DEPTH: 50
  ROI_HEADS:
    NUM_CLASSES: 36
INPUT:
  MIN_SIZE_TRAIN: (480, 512, 544, 576, 608, 640, 672, 704, 736, 768, 800)
  MIN_SIZE_TEST: 800
DATASETS:
  TRAIN: ('voc_2007_trainval',)
  TEST: ('voc_2007_test',)
SOLVER:
  STEPS: (12000, 16000)
  MAX_ITER: 10000  # 17.4 epochs
  WARMUP_ITERS: 100

单元素元组必须加逗号 (...)
MAX_ITER 是迭代步数，每步处理 IMS_PER_BATCH 张图

训练迭代计算

数据集 100 张图，IMS_PER_BATCH = 2，MAX_ITER = 10000
每个 epoch ≈ 100 / 2 = 50 iterations
总训练轮数 ≈ 10000 / 50 ≈ 200 epochs
每张图训练次数 = (MAX_ITER × IMS_PER_BATCH) / 数据集大小 = 20000 / 100 = 200 次

3️⃣ backbone 预训练权重

R-50.pkl：ResNet-50 ImageNet 预训练
作用：加速收敛，提高精度
可选：从零训练 cfg.MODEL.WEIGHTS = ""

数据集：

最终目录结构应为：

bash 复制代码

datasets/
└── VOCdevkit/
    └── VOC2007/
        ├── Annotations
        ├── ImageSets
        ├── JPEGImages

注册 VOC 数据集（Detectron2）

Detectron2 已经内置 VOC 注册逻辑，只需要环境变量或路径正确即可。

bash 复制代码

export DETECTRON2_DATASETS=/mnt/d/develop/datasets

四、总结

环境：Python 3.8.10 + CUDA 12.4 + RTX 4090 + PyTorch 2.1.2
Detectron2 安装可行 ✅
常见问题及解决方案总结：
1. ModuleNotFoundError: No module named 'torch' → 先装 PyTorch + --no-build-isolation
2. bdist_wheel 错误 → 安装 wheel
3. ninja 警告 → 安装 ninja
自定义分类个数

更改自己的分类：

训练脚本：

python 复制代码

python tools/train_net.py   --config-file configs/PascalVOC-Detection/faster_rcnn_R_50_FPN.yaml   --num-gpus 1   OUTPUT_DIR output/voc07

代表开始推理了：

评估 VOC 2007 mAP

bash 复制代码

python tools/train_net.py \
  --config-file configs/PascalVOC-Detection/faster_rcnn_R_50_FPN.yaml \
  --num-gpus 1 \
  --eval-only \
  MODEL.WEIGHTS output/voc07/model_final.pth

bbox/AP50: 0.78
bbox/AP:   0.51

VOC 2007 的主指标是 mAP@0.5