Detectron2实战：从零搭建你的首个视觉模型

1. 为什么选择Detectron2？从“炼丹”到“开箱即用”的转变

如果你刚接触计算机视觉，特别是目标检测、实例分割这些听起来就有点“硬核”的任务，你可能会被各种复杂的代码、繁琐的环境配置和天书般的论文吓退。几年前，我刚开始做项目时，光是复现一个Mask R-CNN模型，就花了两周时间在环境依赖和调试上，那种挫败感记忆犹新。直到遇到了Detectron2，我才发现，原来搭建一个强大的视觉模型可以这么“顺滑”。

Detectron2是Facebook AI Research（FAIR）推出的下一代视觉感知库。它不是凭空出现的，而是站在了Detectron和maskrcnn-benchmark这两个巨人的肩膀上。简单来说，它把那些顶尖实验室里用的、发表在顶级会议上的视觉算法（比如Faster R-CNN, Mask R-CNN, RetinaNet, DensePose），打包成了一个高度模块化、可扩展、高性能的代码库。对我们开发者而言，最大的好处就是：你不用再从零开始造轮子了。

想象一下，你接到一个任务：要开发一个系统，自动检测生产线上的产品缺陷，比如手机外壳的划痕、屏幕的坏点。传统的做法可能是：1. 找论文，读代码；2. 吭哧吭哧搭环境，解决各种版本冲突；3. 自己写数据加载、训练循环、评估脚本；4. 遇到bug，在浩如烟海的Issue里寻找答案。这个过程，我们戏称为“炼丹”，充满了不确定性。

而Detectron2提供的，是一个现代化的“自动化炼丹炉”。它把数据读取、模型构建、训练逻辑、评估指标这些最繁琐、最容易出错的部分，都做成了标准化的模块。你只需要关心两件事：你的数据长什么样，以及你想解决什么问题。剩下的，比如怎么高效地加载图片、怎么组织多GPU训练、怎么计算精确的评估指标，Detectron2都帮你处理好了。这对于新手、对于需要快速验证想法的研究者、对于追求工程落地的开发者来说，无疑是一个巨大的福音。它降低了视觉AI应用的门槛，让我们能把更多精力花在业务逻辑和模型调优上，而不是和底层代码搏斗。

2. 环境搭建：避开那些“坑你没商量”的依赖问题

好了，心动不如行动。我们第一步就是把Detectron2这个“炼丹炉”请到自己的电脑上。官方文档主要面向Linux，但很多朋友（包括我）的主力开发机是Windows。别担心，Windows上也能完美运行，只是需要多注意几个细节。我把自己在Windows 10/11和Ubuntu系统上都成功安装的经验分享给你，帮你把可能遇到的坑都填平。

2.1 核心前提：Python与PyTorch

Detectron2的核心依赖是PyTorch。所以，第一步不是直接装Detectron2，而是确保你的PyTorch环境是正确且完整的。

首先，强烈建议使用Anaconda或Miniconda来管理Python环境。这能最大程度避免包冲突。创建一个新的虚拟环境是个好习惯：

conda create -n detectron2_env python=3.8 conda activate detectron2_env

为什么是Python 3.8？这是一个在稳定性和兼容性上比较平衡的版本。3.7到3.9通常都是安全的，尽量避免使用最新的3.11或更早的3.6，可能会遇到一些意想不到的编译问题。

接下来是重头戏：安装PyTorch。这里的选择决定了你后续的训练速度。访问PyTorch官网（https://pytorch.org/get-started/locally/），它会根据你的选择生成安装命令。

• 如果你有NVIDIA显卡：这是最理想的情况。你需要确定两件事：1. 你的显卡驱动版本；2. 你的CUDA版本。在命令行输入nvidia-smi，右上角会显示你的CUDA版本（例如11.7）。记住这个版本号。在PyTorch官网，选择对应的CUDA版本（比如CUDA 11.7）。命令可能长这样：

  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117

  安装完成后，在Python里运行import torch; print(torch.cuda.is_available())，如果返回True，恭喜你，GPU环境配置成功！

• 如果你只有CPU：完全没问题！Detectron2同样支持CPU训练和推理，只是速度会慢很多，适合小数据集学习和调试。在PyTorch官网选择CPU版本即可：

  pip install torch torchvision torchaudio

我踩过的坑：曾经因为贪新，安装了最新CUDA 12.1对应的PyTorch，但当时Detectron2的预编译轮子还没有支持那么高的版本，导致编译失败。所以，如果你的CUDA版本很新（比如12.x），保险起见，可以尝试安装CUDA 11.7或11.8版本的PyTorch，它们兼容性最好。显卡驱动通常是向下支持多个CUDA版本的。

2.2 安装Detectron2：两种方法，总有一种适合你

PyTorch搞定后，就可以安装Detectron2了。主要有两种方法：

方法一：使用预编译的轮子（最简单，推荐新手）Detectron2为常见的PyTorch和CUDA组合提供了预编译的包。你只需要找到匹配你环境的版本。可以在Detectron2的GitHub仓库的Release页面找到链接，或者直接用pip指定版本安装。例如，对于PyTorch 1.10 + CUDA 11.3：

pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu113/torch1.10/index.html

你需要把链接中的cu113和torch1.10替换成你的CUDA版本和PyTorch主版本号。如果不确定，可以先尝试pip install detectron2，如果报错找不到合适版本，再使用这种方法。

方法二：从源码编译（最通用，能适配各种环境）如果预编译轮子没有你的环境组合，或者你想修改Detectron2的源代码，那就需要编译安装。

# 1. 克隆仓库 git clone https://github.com/facebookresearch/detectron2.git cd detectron2 # 2. 安装依赖 pip install -e .

在Windows上编译，需要确保你已经安装了Visual Studio Build Tools，并且包含了“使用C++的桌面开发”工作负载。编译过程可能会花几分钟。如果遇到错误，通常是缺少某个C++编译组件或者依赖库，根据错误信息搜索，大部分都能找到解决方案。

安装后的验证：打开Python，尝试导入：

import detectron2 print(detectron2.__version__)

如果没有报错，说明安装成功！

2.3 其他必备工具包

除了上述核心，还有一些常用的工具包建议一并安装，它们会在数据预处理、可视化和文件操作中派上用场：

pip install opencv-python pillow matplotlib cython pycocotools

• opencv-python：图像处理的瑞士军刀。
• pycocotools：用于处理COCO数据集格式的评价指标，即使你用自定义数据，评估时也可能用到COCO的评价标准。
• 其他几个是数据可视化和加速的常用库。

至此，你的“炼丹”环境就准备妥当了。比起从前，这个过程已经简化了太多。接下来，我们就要处理最重要的“药材”——数据。

3. 数据准备：让你的图片被Detectron2“读懂”

模型训练得好不好，七分靠数据。Detectron2虽然强大，但它是个“挑食”的孩子，只认特定格式的“食物”。你不能直接把一堆JPG图片和一个Excel标注表扔给它。我们需要把数据组织成它能理解的格式。别怕，这个过程就像把食材洗切配菜，虽然有点琐碎，但每一步都有章可循。

3.1 理解Detectron2的数据字典

Detectron2期望的每张图片的标注信息，是一个Python字典（dict）。这个字典必须包含一些固定的字段。我们通过一个例子来理解。假设你有一张图片，上面标注了两个“手机划痕”和一个“屏幕坏点”。

这个字典大概长这样：

{ “file_name”: “/path/to/image/001.jpg”， # 图片的绝对路径 “image_id”: 123， # 图片的唯一ID，通常用数字或字符串 “height”: 600， # 图片高度（像素） “width”: 800， # 图片宽度（像素） “annotations”: [ # 这是一个列表，每个元素是一个目标的标注字典 { “bbox”: [x1， y1， x2， y2]， # 边界框坐标 [左上角x， 左上角y， 右下角x， 右下角y] “bbox_mode”: BoxMode.XYXY_ABS， # 边界框坐标格式，这是最常用的绝对坐标格式 “category_id”: 0， # 类别ID，0代表“手机划痕” “segmentation”: [[x1， y1， x2， y2， …]]， # 实例分割的多边形坐标（如果是检测任务可省略） “iscrowd”: 0 # 是否为拥挤群体标注，0表示否 }， { “bbox”: [210， 150， 250， 190]， “bbox_mode”: BoxMode.XYXY_ABS， “category_id”: 0， “segmentation”: […]， “iscrowd”: 0 }， { “bbox”: [400， 300， 450， 350]， “bbox_mode”: BoxMode.XYXY_ABS， “category_id”: 1， # 1代表“屏幕坏点” “segmentation”: […]， “iscrowd”: 0 } ] }

你需要为数据集中的每一张图片都准备这样一个字典。然后，把所有图片的字典放在一个列表里，这个列表就代表了你的整个数据集。annotations字段是可选的，如果你只是做分类，就不需要它。对于目标检测，必须有bbox和bbox_mode；对于实例分割，还需要segmentation。

3.2 从常见格式转换：以LabelImg和LabelMe为例

你很可能不是从零开始标注。市面上有很多优秀的标注工具，比如LabelImg（生成XML文件，Pascal VOC格式）和LabelMe（生成JSON文件）。我们需要写一个小脚本来把这些格式转换成Detectron2的字典列表。

假设你用的是LabelImg（VOC格式）： 每个图片对应一个同名的.xml文件，里面包含了图片信息和多个object节点（每个节点有name类别和bndbox边界框）。

import os import xml.etree.ElementTree as ET from detectron2.structures import BoxMode def get_voc_dicts(data_dir): dataset_dicts = [] classes = [“phone_scratch”， “screen_bad_pixel”] # 你的类别列表 for idx， filename in enumerate(os.listdir(os.path.join(data_dir， “Annotations”))): if not filename.endswith(‘.xml’): continue xml_path = os.path.join(data_dir， “Annotations”， filename) tree = ET.parse(xml_path) root = tree.getroot() record = {} # 获取图片路径（假设图片在JPEGImages文件夹） img_name = root.find(‘filename’).text record[“file_name”] = os.path.join(data_dir， “JPEGImages”， img_name) record[“image_id”] = idx size = root.find(‘size’) record[“height”] = int(size.find(‘height’).text) record[“width”] = int(size.find(‘width’).text) objs = [] for obj in root.findall(‘object’): cls_name = obj.find(‘name’).text # 将类别名称转换为ID if cls_name not in classes: continue # 或者可以报错 category_id = classes.index(cls_name) bndbox = obj.find(‘bndbox’) bbox = [ float(bndbox.find(‘xmin’).text)， float(bndbox.find(‘ymin’).text)， float(bndbox.find(‘xmax’).text)， float(bndbox.find(‘ymax’).text) ] obj_dict = { “bbox”: bbox， “bbox_mode”: BoxMode.XYXY_ABS， “category_id”: category_id， “iscrowd”: 0 } # 如果是分割任务，这里需要解析多边形，LabelImg不支持，需用LabelMe objs.append(obj_dict) record[“annotations”] = objs dataset_dicts.append(record) return dataset_dicts

对于LabelMe（JSON格式），转换逻辑类似，主要是解析其特定的shapes字段中的多边形点。原始文章里气球数据集的例子就是一个很好的LabelMe格式转换范例，你可以直接参考那个get_balloon_dicts函数的结构。

3.3 注册数据集：告诉Detectron2“数据在此”

转换好字典列表后，我们需要把这个数据集“注册”到Detectron2的系统里，给它起个名字，方便后续在配置中调用。

from detectron2.data import DatasetCatalog， MetadataCatalog # 假设你的数据分为训练集和验证集 for split in [“train”， “val”]: data_dir = f“./your_dataset/{split}” # 你的数据文件夹路径 DatasetCatalog.register(f“my_dataset_{split}”， lambda d=split: get_voc_dicts(f“./your_dataset/{d}”)) # 同时注册元数据，主要是类别名 MetadataCatalog.get(f“my_dataset_{split}”).set(thing_classes=[“phone_scratch”， “screen_bad_pixel”]) # 验证一下注册是否成功 my_dataset_train_metadata = MetadataCatalog.get(“my_dataset_train”) print(my_dataset_train_metadata.thing_classes) # 应该输出 [‘phone_scratch’， ‘screen_bad_pixel’]

这一步完成后，Detectron2就知道了一个叫”my_dataset_train”的数据集在哪里、有什么类别。数据这道坎迈过去，后面就是一马平川了。

4. 模型配置与训练：调参不再是玄学

数据准备好了，就像备好了食材和菜谱。接下来就是开火烹饪——配置模型并开始训练。Detectron2通过一个cfg（配置）对象来控制训练的一切。这个对象包含了几百个参数，但别慌，我们只需要改动其中关键的十几个。

4.1 解读核心配置文件

Detectron2采用了“基线配置+覆盖”的模式。我们通常从一个预定义的基线配置文件开始，然后根据自己任务的需要修改部分参数。

from detectron2.config import get_cfg from detectron2 import model_zoo cfg = get_cfg() # 获取一个默认配置对象 # 合并一个基线配置。这里以目标检测的Faster R-CNN为例。 cfg.merge_from_file(model_zoo.get_config_file(“COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml”))

这行代码做了件大事：它从Detectron2的模型库（Model Zoo）里加载了一个在COCO数据集上预训练好的Faster R-CNN模型的完整配置。这个配置文件定义了网络结构、训练策略、数据增强等所有细节。我们不需要自己从头设计，站在巨人的肩膀上起步。

现在，我们来修改关键参数：

# 1. 指定训练和验证数据集（用我们刚才注册的名字） cfg.DATASETS.TRAIN = (“my_dataset_train”，) cfg.DATASETS.TEST = (“my_dataset_val”，) # 在训练时，TEST集用于周期性评估 # 2. 配置数据加载 cfg.DATALOADER.NUM_WORKERS = 4 # 数据加载的进程数。CPU核心多可以设大点（如8），Windows下可能设2或0更稳定。 cfg.DATALOADER.FILTER_EMPTY_ANNOTATIONS = True # 过滤掉没有标注的图片，建议True # 3. 配置模型本身 cfg.MODEL.WEIGHTS = model_zoo.get_checkpoint_url(“COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml”) # 加载预训练权重！这是迁移学习的关键，能极大加速收敛。 cfg.MODEL.ROI_HEADS.NUM_CLASSES = 2 # 你的类别数。COCO有80类，我们只有“划痕”和“坏点”2类。 cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.7 # 推理时的置信度阈值，训练时不用管。 # 4. 配置优化器与学习率（这是调参的重点区域） cfg.SOLVER.IMS_PER_BATCH = 4 # 批次大小（Batch Size）。根据你的GPU内存来。4或8是常见起点。内存不够就减小。 cfg.SOLVER.BASE_LR = 0.001 # 基础学习率。对于小数据集，从0.001或0.0005开始尝试。 cfg.SOLVER.MAX_ITER = 5000 # 最大迭代次数。根据数据集大小调整。几百张图可能1000-3000轮，几千张图可能需要上万轮。 cfg.SOLVER.STEPS = (3000， 4000) # 在迭代到这些步数时，学习率乘以GAMMA衰减。 cfg.SOLVER.GAMMA = 0.1 # 学习率衰减因子 # 5. 配置评估与输出 cfg.TEST.EVAL_PERIOD = 500 # 每训练500轮，在验证集上评估一次并打印指标。 cfg.OUTPUT_DIR = “./output” # 模型权重和日志的输出目录

我踩过的坑：NUM_WORKERS在Windows下有时设为大于0会导致数据加载器卡死，如果遇到问题，可以先设为0（只用主进程加载）。IMS_PER_BATCH（批次大小）直接影响GPU内存占用。如果出现“CUDA out of memory”错误，首先尝试减小这个值，或者减小输入图片的分辨率（通过cfg.INPUT.MIN_SIZE_TRAIN和cfg.INPUT.MAX_SIZE_TRAIN）。

4.2 启动训练与监控

配置完成后，启动训练就一行代码：

from detectron2.engine import DefaultTrainer trainer = DefaultTrainer(cfg) trainer.resume_or_load(resume=False) # resume=False表示从头开始训练 trainer.train()

训练开始后，控制台会打印日志，包括损失值、学习率、迭代进度等。更直观的方法是使用TensorBoard来可视化：

# 在另一个终端，进入项目目录，运行 tensorboard --logdir ./output

然后在浏览器打开http://localhost:6006，你就能看到损失曲线、学习率曲线、验证集精度等图表，非常方便。Detectron2在训练过程中会自动保存检查点（默认每5000轮一次，可通过cfg.SOLVER.CHECKPOINT_PERIOD修改），也会保存最后一次的模型（model_final.pth）。

4.3 没有高端GPU怎么办？实用替代方案

如果你的本地电脑没有强大的GPU，训练速度慢如蜗牛，别灰心，有几个很好的替代方案：

1. Google Colab：提供免费的GPU（通常是Tesla T4或K80）和TPU资源。你可以将代码和数据上传到Google Drive，在Colab笔记本中运行。免费版本有使用时长限制，但对于学习和中小型项目足够了。
2. Kaggle Notebooks：同样提供免费的GPU（每周30小时），环境集成度很高，特别适合数据科学和机器学习项目。
3. 云服务商：阿里云、腾讯云、AWS等都有按小时计费的GPU实例。对于短期、高强度的训练任务，租用云服务器比购买显卡更经济灵活。选择按量付费实例，用完即释放，成本可控。
4. 降低配置，本地调试：在本地用CPU或低性能GPU跑通整个流程，调试好代码和数据。然后只将需要长时间训练的任务提交到云端。可以把MAX_ITER设小（如100），先快速跑一个周期，确保没有错误。

5. 模型评估与推理：看看你的模型“学”得怎么样

训练完成后，我们肯定要检验一下成果。Detectron2提供了完善的评估和推理接口。

5.1 使用训练好的模型进行预测

训练最终权重保存在cfg.OUTPUT_DIR目录下（例如./output/model_final.pth）。用它来做预测非常简单：

from detectron2.engine import DefaultPredictor # 1. 重新加载配置（或复用之前的cfg） cfg = get_cfg() cfg.merge_from_file(model_zoo.get_config_file(“COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml”)) cfg.MODEL.WEIGHTS = os.path.join(cfg.OUTPUT_DIR， “model_final.pth”) # 指向我们训练好的权重 cfg.MODEL.ROI_HEADS.NUM_CLASSES = 2 cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.5 # 设置一个置信度阈值，低于此阈值的预测框将被过滤 cfg.MODEL.DEVICE = “cuda” # 或 “cpu” predictor = DefaultPredictor(cfg) # 2. 读取一张图片并预测 import cv2 im = cv2.imread(“./test_image.jpg”) outputs = predictor(im) # 输入必须是BGR格式的numpy数组

这个outputs变量是一个字典，包含了丰富的预测信息：

• outputs[“instances”].pred_boxes：预测的边界框（张量格式）。
• outputs[“instances”].scores：每个预测框的置信度分数。
• outputs[“instances”].pred_classes：每个预测框的类别ID（对应我们注册的类别顺序）。
• outputs[“instances”].pred_masks：如果是指实例分割模型，这里会有预测的掩码。

5.2 可视化预测结果

“一图胜千言”，把预测框画在图片上最直观：

from detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog import matplotlib.pyplot as plt # 获取我们数据集的元数据（主要是为了拿到类别名） metadata = MetadataCatalog.get(“my_dataset_val”) # 创建可视化器 v = Visualizer(im[:, :， ::-1]， metadata=metadata， scale=0.8) # im[:, :， ::-1] 将BGR转为RGB # 绘制预测结果 out = v.draw_instance_predictions(outputs[“instances”].to(“cpu”)) # 显示 plt.figure(figsize=(12， 8)) plt.imshow(out.get_image()) plt.axis(‘off’) plt.show()

5.3 定量评估：用数字说话

可视化很爽，但我们需要客观的指标来衡量模型性能。Detectron2内置了COCO评估器，这是业界最常用的评估标准。

from detectron2.evaluation import COCOEvaluator， inference_on_dataset from detectron2.data import build_detection_test_loader # 1. 构建评估器 evaluator = COCOEvaluator(“my_dataset_val”， cfg， False， output_dir=“./output/”) # 2. 构建数据加载器 val_loader = build_detection_test_loader(cfg， “my_dataset_val”) # 3. 在验证集上运行评估 print(inference_on_dataset(predictor.model， val_loader， evaluator))

运行后，你会得到一长串指标，重点关注这几个：

• AP (Average Precision)：在所有IoU阈值（0.5:0.95）上的平均精度，这是COCO的主要评估指标，值在0到1之间，越高越好。
• AP50：IoU阈值为0.5时的AP，这是更宽松的指标。
• AP75：IoU阈值为0.75时的AP，这是更严格的指标。
• AR (Average Recall)：平均召回率。

对于你的产品缺陷检测项目，你可能更关心“划痕”和“坏点”各自类别的AP（即AP-phone_scratch和AP-screen_bad_pixel）。如果某个类别AP很低，可能是训练样本不足，或者标注质量有问题。

5.4 模型部署与优化初步

训练评估都满意后，你可能想把模型用起来。Detectron2的模型可以直接用PyTorch的torch.jit.trace或torch.jit.script进行脚本化，然后部署到生产环境。但要注意，直接导出的模型包含了复杂的后处理，可能不是最优的。

对于追求极致速度的场景，可以考虑：

1. 模型剪枝与量化：使用PyTorch的量化工具减小模型体积、提升推理速度。
2. 转换为ONNX格式：将模型转换为ONNX，然后利用TensorRT、OpenVINO等推理引擎进行加速，这在工业界非常常见。
3. 使用更轻量的模型：Detectron2的Model Zoo里不仅有Faster R-CNN，还有RetinaNet、FCOS等单阶段检测器，甚至MobileNet等轻量级主干网络，它们在精度和速度上有所权衡。

从数据准备到训练评估，再到最后的推理部署，这就是一个完整的Detectron2实战流程。它就像一套精良的厨具和清晰的菜谱，让你这个“AI厨师”能更专注于食材（数据）和火候（调参），最终烹饪出满足业务需求的视觉AI模型。记住，第一次可能不会完美，可能会遇到数据不对齐、训练不收敛、评估指标低等问题，这都是学习的一部分。多尝试，多调整，每一次迭代都会让你和你的模型变得更强大。