1. 初识Detectron2为什么说它是计算机视觉的“瑞士军刀”如果你正在寻找一个功能强大、社区活跃、上手相对容易的计算机视觉框架那Detectron2绝对值得你花时间研究。我最早接触它是在一个工业质检项目里当时需要快速部署一个能同时做缺陷检测目标检测和缺陷区域分割实例分割的模型。试过几个方案后最终Detectron2以其开箱即用的模型库和高度模块化的设计说服了我们团队。简单来说Detectron2是Facebook AI ResearchFAIR基于PyTorch打造的一个目标检测、分割和姿态估计平台。你可以把它理解为一个“模型超市”里面摆满了各种经过预训练的、性能优异的视觉模型比如我们熟知的Faster R-CNN、Mask R-CNN还有像Cascade R-CNN、Panoptic FPN这些更前沿的算法。和它的前身Detectron相比Detectron2不仅仅是换了个PyTorch后端那么简单。它进行了彻底的重构代码更清晰设计更现代。我印象最深的是它的配置系统和数据管道。以前改个模型结构或者数据增强方式经常要深入到代码细节里现在大部分工作通过一个配置文件就能搞定这对快速实验和迭代太友好了。它支持的任务也相当全面从经典的目标检测、实例分割到人体关键点估计、全景分割基本上主流的视觉任务都覆盖了。无论你是想快速跑通一个Demo验证想法还是想基于它进行深入的二次开发Detectron2都能提供很好的支持。接下来我就带你从零开始一步步搭建环境、跑通Demo再到训练自己的模型把这个强大的工具用起来。2. 环境搭建避开那些让我“掉坑”的依赖冲突万事开头难环境配置往往是劝退新手的第一道坎。我在不同机器上部署过不下十次Detectron2总结下来最稳妥的方法还是从源码编译安装。虽然官方也提供了预编译的wheel包仅限Linux但版本匹配要求严格稍有不慎就会遇到“invalid device function”这类令人头疼的CUDA版本错误。所以我强烈建议你跟着我的步骤从零开始构建一个干净的环境。首先我们需要一个Python虚拟环境。这能有效隔离项目依赖避免和系统或其他项目的包产生冲突。我习惯用Conda因为它对Python版本和CUDA工具链的管理非常方便。假设你已经安装好了Conda打开终端执行以下命令创建一个新环境conda create -n detectron2_env python3.8 -y conda activate detectron2_env这里我选择了Python 3.8这是一个在稳定性和库兼容性之间取得很好平衡的版本。Detectron2官方要求Python 3.7所以3.8或3.9都是不错的选择。环境激活后我们安装最核心的依赖——PyTorch和TorchVision。这里有个关键点PyTorch的CUDA版本必须和你系统里安装的CUDA驱动版本兼容。我吃过亏曾经用CUDA 11.7的驱动去装对应CUDA 11.8的PyTorch结果训练时各种诡异错误。最稳妥的方法是去PyTorch官网根据你的CUDA版本选择安装命令。比如如果你的CUDA版本是11.8可以这样安装conda install pytorch torchvision torchaudio pytorch-cuda11.8 -c pytorch -c nvidia如果网络条件不好可以加上清华源加速。安装完成后务必验证一下GPU是否可用import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.version.cuda)如果torch.cuda.is_available()返回True并且打印的CUDA版本符合预期那PyTorch部分就搞定了。接下来是其他依赖。OpenCV用于图像读取和可视化虽然不是必须但跑Demo和看结果离不开它。我推荐安装opencv-python或opencv-contrib-pythonpip install opencv-python然后是pycocotools这是处理COCO数据集格式的工具包Detectron2的许多模型和评估都依赖它。安装时可能会遇到编译问题可以按以下顺序操作pip install cython pip install githttps://github.com/cocodataset/cocoapi.git#subdirectoryPythonAPI如果第二条命令因为网络问题失败你可以先把cocoapi仓库克隆到本地再进入PythonAPI目录执行python setup.py install。至此前期依赖就准备齐全了。这个过程看似繁琐但搭建一次以后的项目都能受益。一个独立、版本清晰的环境是后续所有工作的基石。3. 编译与安装两种方法总有一种适合你依赖搞定后就可以安装Detectron2本体了。主要有两种方式安装预编译包和从源码编译。我两种都试过各有优劣。预编译包最快一行命令搞定但就像刚才说的它对PyTorch和CUDA的版本要求非常严格且可能不包含最新的特性。从源码编译虽然多花几分钟但兼容性最好也能确保你用到最新的代码。方法一安装预编译包仅限Linux求快可选如果你的环境是Linux并且PyTorch和CUDA版本恰好匹配官方提供的wheel包那这是最省事的方法。你需要根据你的PyTorch和CUDA版本从下面的表格中选择对应的安装命令。例如PyTorch 1.10 CUDA 11.3的组合命令如下pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu113/torch1.10/index.html注意预编译包更新不频繁可能无法使用main分支的最新功能。如果你打算基于Detectron2做研究或开发源码编译是更推荐的方式。方法二从源码编译通用、可靠的首选这是我个人最常用的方法也是官方推荐的方式。首先把Detectron2的代码仓库克隆到本地git clone https://github.com/facebookresearch/detectron2.git cd detectron2然后使用pip以“可编辑”模式进行安装。这个-e参数非常有用它会在你的Python环境里创建一个链接指向本地代码目录这样你后续如果修改了Detectron2的源码无需重新安装就能立刻生效对于调试和开发极其方便。pip install -e .执行这条命令后它会开始编译C和CUDA扩展。这个过程需要你的系统有gcc和g版本5.4通常Linux和macOS都自带。如果编译顺利几分钟后就能完成。完成后你可以打开Python解释器输入import detectron2如果没有报错恭喜你安装成功了我踩过的坑有时候你可能会遇到编译错误比如提示“nvcc not found”或者“CUDA_HOME”找不到。这通常是因为PyTorch找不到CUDA。请再次用print(torch.cuda.is_available(), torch.utils.cpp_extension.CUDA_HOME)确认。另一个常见错误是“invalid device function”这几乎可以肯定是CUDA版本不匹配导致的。比如你用CUDA 11.8编译了PyTorch但系统环境变量指向的是CUDA 12.0的运行时。解决方法是统一版本或者使用python -m detectron2.utils.collect_env命令打印出完整的环境信息仔细比对“Detectron2 CUDA Compiler”、“CUDA_HOME”和“PyTorch built with - CUDA”这几个字段的版本号是否一致。4. 五分钟跑通第一个Demo让模型“看见”你的世界环境装好了不跑个Demo验证一下心里总不踏实。Detectron2在demo/目录下提供了一个非常强大的演示脚本demo.py。它支持多种输入源单张图片、多张图片、整个文件夹、网络摄像头甚至视频文件。我们就从最经典的用预训练模型分析一张图片开始。首先你需要准备一张测试图片比如命名为test.jpg放在一个方便访问的路径。然后在终端中进入Detectron2的根目录执行类似下面的命令python demo/demo.py \ --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input path/to/your/test.jpg \ --output ./output/ \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl我来拆解一下这几个参数--config-file: 指定模型配置文件。这里我们用的是在COCO数据集上训练的Mask R-CNN模型主干网络是ResNet-50加上特征金字塔网络FPN。--input: 你的输入图片路径。--output: 指定一个目录处理后的结果图片会保存到这里。--opts MODEL.WEIGHTS: 指定模型权重文件。这里用了一个神奇的detectron2://开头的URL程序会自动从Facebook的服务器下载对应的预训练权重。你也可以提前下载好权重文件然后这里换成本地路径比如MODEL.WEIGHTS ./model_final_f10217.pkl。执行命令后你会看到终端开始下载模型如果第一次运行然后进行推理。整个过程在我的RTX 3090上大概只需要零点几秒。完成后去./output/目录下找到处理后的图片你会看到原图上多了许多彩色的框和掩膜每个检测到的物体都被标注了出来并且有类别标签和置信度分数。想用摄像头实时玩一下更简单把--input参数换成--webcam就行python demo/demo.py --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml --webcam --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl这会打开你的默认摄像头进行实时目标检测和实例分割效果非常酷炫。第一次看到自己摄像头里的东西被实时框出来时还是挺有成就感的。这个Demo成功运行不仅验证了你的安装完全正确也让你直观感受到了Detectron2的能力。接下来我们就要深入一点看看如何用自己的数据来训练模型。5. 准备你的数据让模型认识你的“专属物品”跑通官方Demo只是第一步真正让Detectron2发挥价值的是用它来解决你自己的问题。而这一切的起点就是数据。Detectron2默认支持好几种数据集格式最常用、生态最完善的就是COCO格式。即使你的数据不是COCO格式也强烈建议你转换成COCO格式因为几乎所有工具和代码都围绕它展开。COCO格式的数据集标注是一个巨大的JSON文件结构清晰但内容较多。它主要包含几个部分images图片信息列表、annotations标注信息列表和categories类别信息列表。对于目标检测任务每个标注需要提供bbox边界框格式是[x左上, y左上, 宽度, 高度]和category_id类别ID。对于实例分割还需要提供segmentation字段可以是多边形点集也可以是RLE编码的掩膜。如果你是从零开始标注数据我推荐使用labelme或CVAT这类工具。以labelme为例它标注后生成的是每张图片一个JSON文件。你需要写一个小脚本把这些单独的JSON文件合并、转换成COCO格式的一个大JSON文件。网上有很多现成的转换脚本比如labelme2coco。这里我分享一个简单的思路你需要遍历所有图片的标注为每张图片生成唯一的image_id为每个标注生成唯一的annotation_id并且维护一个全局的category_id映射关系。假设你已经有了一个符合COCO格式的标注文件annotations.json并且图片都放在train2017/文件夹下。接下来你需要告诉Detectron2你的数据集在哪里、长什么样。这通过注册数据集来实现。你需要写一个函数来加载数据并调用DatasetCatalog.register和MetadataCatalog.get。下面是一个最简单的示例from detectron2.data import DatasetCatalog, MetadataCatalog from detectron2.data.datasets import load_coco_json # 1. 注册你的数据集 json_file “/path/to/your/annotations.json” image_root “/path/to/your/images” dataset_name “my_dataset_train” DatasetCatalog.register(dataset_name, lambda: load_coco_json(json_file, image_root, dataset_name)) # 2. 设置数据集的元数据主要是类别名 metadata MetadataCatalog.get(dataset_name) # 设置类别名注意列表长度要和你的类别数一致且顺序要和json文件里的category_id对应 metadata.thing_classes [“cat”, “dog”, “person”] # 替换成你的类别完成注册后你就可以在配置文件中使用my_dataset_train这个名字来引用你的数据集了。数据准备是机器学习项目中最耗时但也最关键的环节标注的质量直接决定了模型性能的上限。多花点时间确保标注的准确性和一致性后续训练会顺利很多。6. 模型训练与调优从“照猫画虎”到“得心应手”数据准备好了我们就可以开始训练自己的模型了。Detectron2提供了一个非常方便的脚本tools/train_net.py以及一个高度封装的DefaultTrainer类。对于大多数标准任务我们只需要准备好配置文件和数据然后启动训练即可。第一步选择合适的配置文件。配置文件是Detectron2的核心设计它用一个YAML文件定义了模型结构、训练参数、数据源等所有设置。我们不需要从头写最好的方法是“站在巨人的肩膀上”。在configs/目录下官方提供了大量针对不同模型和任务的配置文件。比如如果你想用带FPN的Faster R-CNN做目标检测可以复制configs/COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml作为起点。用文本编辑器打开它你需要修改几个关键地方MODEL: WEIGHTS: “detectron2://COCO-Detection/faster_rcnn_R_50_FPN_3x/137849458/model_final_f6e8b1.pkl” # 可以保留这是用COCO预训练的权重有利于加速收敛迁移学习 ROI_HEADS: NUM_CLASSES: 3 # 改成你的数据集的类别数比如我之前的例子有3类猫、狗、人 DATASETS: TRAIN: (“my_dataset_train”,) # 改成你注册的训练集名字 TEST: (“my_dataset_val”,) # 改成你注册的验证集名字用于评估 SOLVER: BASE_LR: 0.00025 # 学习率如果数据集很小可以适当调小比如0.0001 MAX_ITER: 10000 # 最大迭代次数根据你的数据集大小调整 STEPS: (7000, 9000) # 学习率衰减的步数 INPUT: MIN_SIZE_TRAIN: (640, 672, 704, 736, 768, 800) # 训练时图片的缩放尺度可以调小以节省内存第二步启动训练。修改好配置文件假设保存为my_config.yaml后在终端执行python tools/train_net.py --config-file ./my_config.yaml --num-gpus 1这里的--num-gpus 1指定使用1块GPU。如果你有多块GPU可以改成对应的数字Detectron2会自动启用分布式数据并行训练。训练开始后你会在终端看到损失值、学习率等日志信息。默认情况下模型权重和日志会保存在output/目录下。Detectron2还集成了TensorBoard你可以用tensorboard --logdir output来启动可视化界面实时监控训练过程包括损失曲线、学习率、验证集精度等非常方便。训练中的实战技巧学习率策略对于小数据集使用预训练权重时学习率不宜太大。我通常从BASE_LR: 0.00025开始如果训练不稳定损失出现NaN就调小一个数量级试试。数据增强配置文件里的INPUT部分可以配置数据增强。对于小数据增强尤为重要。除了默认的随机水平翻转还可以尝试RandomBrightness、RandomContrast等。但要注意增强不是越多越好要贴合实际场景。早停与模型选择训练脚本会定期在验证集上评估模型并保存表现最好的检查点model_final.pth。但有时候最后一个检查点不一定是最优的。我习惯同时关注验证集的损失和指标如AP当指标连续几个epoch不再提升时可以考虑手动停止训练并选择验证集指标最高的那个检查点。“踩坑”记录有一次我训练时发现损失一直不降排查后发现是类别数NUM_CLASSES没改对。Detectron2的类别数要包含背景类。如果你有3个物体类别这里应该填4背景算第0类。但请注意在thing_classes元数据里你只需要列出你的物体类别名比如[“cat”, “dog”, “person”]背景类不需要写进去。这个细节很容易搞错。7. 模型评估与推理看看你的模型“学”得怎么样模型训练完成后我们需要客观地评估它的性能。Detectron2内置了对COCO标准评估指标的支持使用起来非常简单。如果你在配置文件的DATASETS.TEST中指定了验证集那么训练过程中就会自动评估。你也可以在训练结束后使用专门的评估脚本python tools/train_net.py --config-file ./my_config.yaml --eval-only MODEL.WEIGHTS ./output/model_final.pth这条命令会加载你训练好的最终模型model_final.pth在测试集上运行一遍并打印出详细的评估结果包括大家熟悉的AP平均精度、AP50、AP75等。对于目标检测AP是综合衡量指标对于实例分割还会输出Mask AP。这些数字能告诉你模型在全局上的表现。但光看数字还不够直观。我们还需要可视化推理结果看看模型在具体图片上哪里做得好哪里犯了错。Detectron2提供了强大的可视化工具。你可以写一个简单的脚本加载模型并对单张图片进行预测和可视化from detectron2.engine import DefaultPredictor from detectron2.config import get_cfg from detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog import cv2 # 加载配置和模型权重 cfg get_cfg() cfg.merge_from_file(“./my_config.yaml”) cfg.MODEL.WEIGHTS “./output/model_final.pth” # 训练好的模型 cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 # 设置一个置信度阈值过滤掉不可靠的预测 predictor DefaultPredictor(cfg) # 读取并预测 im cv2.imread(“./your_test_image.jpg”) outputs predictor(im) # 可视化 v Visualizer(im[:, :, ::-1], MetadataCatalog.get(cfg.DATASETS.TRAIN[0]), scale1.2) out v.draw_instance_predictions(outputs[“instances”].to(“cpu”)) vis_image out.get_image()[:, :, ::-1] # 保存或显示 cv2.imwrite(“output_result.jpg”, vis_image)这段代码的核心是DefaultPredictor和Visualizer。预测器predictor会返回一个字典里面包含了预测的边界框、类别、得分和分割掩膜如果是分割任务。可视化器Visualizer则能把这些信息漂亮地画在图片上。通过查看这些可视化结果你可以发现一些共性问题比如模型对某一类物体总是漏检可能是训练样本不足或者边界框不准可能是数据标注不够精细从而指导你下一步是补充数据、调整标注还是修改模型参数。8. 进阶技巧与部署让你的模型真正“跑起来”当你有了一个表现不错的模型接下来可能就是考虑如何把它集成到实际应用中去比如一个Web服务、一个移动端APP或者一个边缘设备。这里就涉及到模型的导出和部署。模型导出为通用格式Detectron2的模型默认是PyTorch的.pth格式。为了跨平台部署我们常常需要将其转换为ONNX或TorchScript格式。Detectron2对ONNX导出提供了实验性支持。下面是一个将模型导出为ONNX的示例代码框架import torch from detectron2.modeling import build_model from detectron2.checkpoint import DetectionCheckpointer from detectron2.export import Caffe2Tracer, add_export_config from detectron2.config import get_cfg import onnx cfg get_cfg() # ... (加载你的配置文件) cfg add_export_config(cfg) # 添加导出相关的配置 model build_model(cfg) DetectionCheckpointer(model).load(cfg.MODEL.WEIGHTS) model.eval() # 准备一个示例输入张量 inputs [{“image”: torch.randn(3, 800, 800), “height”: 800, “width”: 800}] # 使用Caffe2Tracer进行跟踪这里名字是Caffe2但同样用于ONNX导出 tracer Caffe2Tracer(cfg, model, inputs) # 导出ONNX torch.onnx.export(tracer.model, (inputs[0][“image”], ), “model.onnx”, opset_version11)导出ONNX后你可以使用ONNX Runtime、TensorRT等推理引擎在不同硬件平台上高效运行。不过要注意导出过程可能会遇到一些算子不支持的问题需要根据报错信息进行调试。简化推理流程在实际部署中我们可能不需要训练时那么复杂的配置。Detectron2的配置系统虽然强大但有时显得笨重。你可以将关键的配置参数如模型路径、类别列表、置信度阈值硬编码到一个更简洁的推理脚本中甚至封装成一个简单的类。这样在部署时只需要加载这个脚本和模型文件即可避免了依赖一整套配置文件。性能优化对于实时性要求高的场景性能是关键。除了使用更快的推理引擎如TensorRT还可以从模型本身入手选择更轻量的模型比如用MobileNetV2代替ResNet作为主干网络。减小输入图像尺寸在配置文件的INPUT.MIN_SIZE_TRAIN和INPUT.MIN_SIZE_TEST中设置更小的值能显著提升速度但可能会损失一些精度。调整置信度阈值MODEL.ROI_HEADS.SCORE_THRESH_TEST设得越高保留的预测框越少后处理越快但召回率可能会降低。需要在速度和精度间做权衡。我在一个安防项目里就将一个Mask R-CNN模型用TensorRT加速后部署到了Jetson AGX Xavier边缘设备上对1080p视频流能做到近实时的行人检测与分割效果非常不错。这个过程虽然有些挑战但看到模型最终在真实场景中稳定运行带来的满足感是无与伦比的。Detectron2就像一个强大的工具箱提供了从研发到落地的各种可能剩下的就靠你的想象力和工程能力去挖掘了。