Detectron2 模型使用指南从配置构建、Checkpoint 加载到输入输出格式全解析【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2在 Detectron2 中模型是一个封装完整的torch.nn.Module它接收一张或多张图片的字典列表作为输入输出损失训练时或检测结果推理时。本指南以 docs/tutorials/models.md 为核心系统讲解如何从 yacs 配置构建模型、加载与保存 checkpoint、调用模型进行训练与推理并逐字段解析内置模型的输入/输出格式同时结合仓库源码揭示底层实现原理。读完本文你将掌握 Detectron2 模型生命周期中的每一个关键环节能够自由地构建、加载、调用甚至拆解模型。从 yacs 配置构建模型Detectron2 的核心设计之一是配置驱动模型。给定一个 yacs 配置对象CfgNode模型及其子模块可以通过build_model、build_backbone、build_roi_heads等工厂函数一键构建from detectron2.modeling import build_model model build_model(cfg) # 返回一个 torch.nn.Modulebuild_model的底层实现位于 detectron2/modeling/meta_arch/build.pydef build_model(cfg): meta_arch cfg.MODEL.META_ARCHITECTURE model META_ARCH_REGISTRY.get(meta_arch)(cfg) model.to(torch.device(cfg.MODEL.DEVICE)) _log_api_usage(modeling.meta_arch. meta_arch) return model其工作机制可以概括为三点注册表Registry分发cfg.MODEL.META_ARCHITECTURE指定了元架构meta-architecture的字符串名称例如GeneralizedRCNN、RetinaNet、SemanticSegmentor、PanopticFPN、FCOS等。META_ARCH_REGISTRY定义于 detectron2/modeling/meta_arch/build.py负责从名称映射到具体的nn.Module类再由obj(cfg)实例化。设备迁移构建完成后模型自动移动到cfg.MODEL.DEVICE指定的设备默认cuda。只构建结构、不加载权重build_model仅初始化网络结构与随机参数权重加载需另走 checkpoint 流程见下一节。各元架构类通过META_ARCH_REGISTRY.register()装饰器注册。以最常用的GeneralizedRCNN见 detectron2/modeling/meta_arch/rcnn.py为例其from_config会依次构建三个核心子模块这也解释了build_backbone、build_roi_heads等函数的用途classmethod def from_config(cls, cfg): backbone build_backbone(cfg) return { backbone: backbone, proposal_generator: build_proposal_generator(cfg, backbone.output_shape()), roi_heads: build_roi_heads(cfg, backbone.output_shape()), input_format: cfg.INPUT.FORMAT, vis_period: cfg.VIS_PERIOD, pixel_mean: cfg.MODEL.PIXEL_MEAN, pixel_std: cfg.MODEL.PIXEL_STD, }也就是说一个标准的 R-CNN 模型由特征提取 backbone、候选区域生成器 proposal_generator与逐区域预测头 roi_heads三部分拼装而成每部分都可通过独立的 build 函数与配置项替换——这正是 Detectron2可组合、可插拔的模块化设计精髓。加载与保存 Checkpoint使用 DetectionCheckpointer构建出的模型参数是随机的训练或推理前需要加载预训练权重。Detectron2 提供了DetectionCheckpointer统一处理加载与保存from detectron2.checkpoint import DetectionCheckpointer # 加载权重文件通常来自 cfg.MODEL.WEIGHTS DetectionCheckpointer(model).load(file_path_or_url) # 保存权重到 output/model_999.pth checkpointer DetectionCheckpointer(model, save_diroutput) checkpointer.save(model_999)DetectionCheckpointer定义于 detectron2/checkpoint/detection_checkpoint.py继承自 fvcore 的Checkpointer并在此基础之上增加了两项关键能力兼容多种权重来源既能加载 PyTorch 原生.pth格式也能加载模型动物园中的.pkl文件并自动对旧版 Caffe2 / Detectron1 模型执行名称对齐与转换align_and_update_state_dicts分布式正确性在DistributedDataParallel训练中确保只有主进程实际读取 checkpoint其他 worker 通过广播同步模型状态见 detectron2/checkpoint/detection_checkpoint.py。支持的权重格式从_load_file的实现detectron2/checkpoint/detection_checkpoint.py可以看出DetectionCheckpointer.load根据文件扩展名与内容分派处理逻辑格式说明.pkl若包含model与__author__字段视为 Detectron2 模型动物园格式否则按 Caffe2/Detectron1 格式处理blobs键、剔除_momentum结尾的键并启用名称匹配启发式转换.pythpycls 项目权重须包含model_state字段.pth默认标准 PyTorch 权重URL 查询参数matching_heuristicsTrue可显式启用名称匹配转换此外模型权重文件可以使用标准 Python 工具自由操作.pth文件可用torch.load/torch.save.pkl文件可用pickle.dump/pickle.load。加载时还有两个实用细节缺失的pixel_mean/pixel_std缓冲会被宽容处理它们本来就会从配置重新初始化旧 checkpoint 中遗留的anchor_generator.cell_anchors意外键也会被忽略避免兼容性报错。使用模型模型本身是一个普通的torch.nn.Module通过outputs model(inputs)调用其中inputs是list[dict]每个 dict 对应一张图片。dict 中需要哪些键取决于模型类型以及模型处于训练还是推理模式。训练模式必须在 EventStorage 上下文中训练时所有内置模型都要求在EventStorage上下文内运行训练统计信息各类 loss会被写入该存储from detectron2.utils.events import EventStorage with EventStorage() as storage: losses model(inputs)此时模型输出一个dict[str - ScalarTensor]包含所有子任务的损失项。GeneralizedRCNN.forwarddetectron2/modeling/meta_arch/rcnn.py会合并 proposal generator 与 roi_heads 两部分的损失训练中的可视化vis_period也依赖get_event_storage()读取当前迭代号与写入图片。推理模式DefaultPredictor 或手动调用如果你只是想用现成模型做简单推理DefaultPredictor是最省事的封装。它定义于 detectron2/engine/defaults.py相比直接使用模型额外完成了以下工作从cfg.MODEL.WEIGHTS加载权重并切换model.eval()始终接收 BGR 顺序的np.ndarray图片按cfg.INPUT.FORMAT做颜色通道转换按cfg.INPUT.{MIN,MAX}_SIZE_TEST应用ResizeShortestEdge预处理接收单张图片、输出单个预测结果而非 batch。典型用法pred DefaultPredictor(cfg) outputs pred(cv2.imread(input.jpg)) # 传入 BGR 单图返回单个预测 dictDefaultPredictor.__call__内部将预处理后的图片包装为{image: image, height: height, width: width}再交给模型其中height/width取原图尺寸。你也可以绕过封装直接进行底层推理model.eval() with torch.no_grad(): outputs model(inputs)这条路径揭示了推理的完整内部流程见GeneralizedRCNN.inferencedetectron2/modeling/meta_arch/rcnn.pypreprocess_image做像素归一化与 padding 组批 → backbone 提特征 → proposal_generator 生成候选框 → roi_heads 逐区域预测 →_postprocess将结果缩放回期望分辨率。其中后处理由 detectron2/modeling/postprocessing.py 的detector_postprocess完成按比例缩放pred_boxes、裁剪出图、过滤空框、将 ROI 掩码还原到原图分辨率、按比例缩放关键点坐标。模型输入格式详解内置模型统一接收list[dict]作为输入每个 dict 描述一张图片。你可以实现任意自定义输入格式的自定义模型但内置模型遵循以下标准格式与DatasetMapper的输出一一对应详见 detectron2/data/dataset_mapper.py 的文档说明。键类型与说明imageTensor形状(C, H, W)。通道含义由cfg.INPUT.FORMAT定义RGB或BGR图像归一化减均值除方差在模型内部基于cfg.MODEL.PIXEL_MEAN/cfg.MODEL.PIXEL_STD完成height,width推理时期望的输出高度与宽度不必等于image字段的实际尺寸。例如预处理已将图片 resize但你希望输出落在原始分辨率上提供该键后模型会输出该分辨率的结果比再缩放一次更高效、更精确instances训练用的 Instances 对象包含以下字段gt_boxesBoxes 对象N 个框、gt_classeslong 型TensorN 个标签取值[0, num_categories)、gt_masksPolygonMasks 或 BitMasks 对象N 个掩码、gt_keypointsKeypoints 对象N 组关键点sem_segTensor[int]形状(H, W)语义分割训练用的 ground truth像素值从 0 开始的类别标签proposals仅 Fast R-CNN 风格模型使用Instances 对象字段包括proposal_boxesBoxes 对象P 个候选框、objectness_logitsTensorP 个分数几点重要补充内置模型推理只需image键width/height可选全景分割训练目前没有标准输入格式因为此类模型使用自定义数据加载器产生的自定义格式底层归一化在preprocess_image中实现detectron2/modeling/meta_arch/rcnn.py先执行(x - pixel_mean) / pixel_std再用ImageList.from_tensors按 backbone 的size_divisibility做 padding 组批。与数据加载器的衔接默认的 DatasetMapperdetectron2/data/dataset_mapper.py的输出正是上述格式的单个 dict它负责读图、应用增广、把标注转为Instances等张量结构。数据加载器完成 batching 后得到list[dict]恰好是内置模型直接支持的输入形态——这就是数据管线 → 模型之间的契约。模型输出格式详解内置模型的输出同样遵循标准格式训练模式输出dict[str - ScalarTensor]键为各损失项名称值为标量张量推理模式输出list[dict]每张图片一个 dict根据任务类型可能包含以下字段字段说明instancesInstances 对象含pred_boxesBoxesN 个检测框、scoresTensorN 个置信度、pred_classesTensorN 个标签取值[0, num_categories)、pred_masksTensor形状(N, H, W)、pred_keypointsTensor形状(N, num_keypoint, 3)最后一维为(x, y, score)score 大于 0sem_segTensor形状(num_categories, H, W)语义分割预测proposalsInstances 对象含proposal_boxesN 个框、objectness_logitsN 个分数panoptic_seg元组(pred, segments_info)pred为(H, W)张量每个像素值为 segment idpanoptic_seg的segments_info语义需要特别注意若segments_info存在其中的每个 dict 描述pred中的一个 segment id字段为idsegment id、isthingthing 还是 stuff、category_id该 segment 的类别 id若某像素的 id 未出现在segments_info中则视为 void 标签定义见全景分割原始论文若segments_info为None则pred中所有像素值必须≥ -1值为-1的像素是 void 标签其余像素的类别 id 由category_id pixel // metadata.label_divisor计算得到。部分执行模型获取中间张量有时你需要拿到模型内部的中间张量例如某层输入、后处理之前的输出。由于模型中通常有数百个中间张量不存在一个给我第 X 个中间结果的通用 API你可以从以下三种方案中选择方案一重写一个子模型按照 write-models 教程重写某个模型组件比如某个预测头让它与现有组件行为一致、但额外返回你需要的输出。这种方法最正规适合需要长期复用的场景。方案二部分执行模型正常构建模型但不用它的forward()而是用自定义代码逐步调用各子模块。例如下面的代码在 mask head 之前取出 mask 特征images ImageList.from_tensors(...) # 预处理后的输入张量 model build_model(cfg) model.eval() features model.backbone(images.tensor) proposals, _ model.proposal_generator(images, features) instances, _ model.roi_heads(images, features, proposals) mask_features [features[f] for f in model.roi_heads.in_features] mask_features model.roi_heads.mask_pooler(mask_features, [x.pred_boxes for x in instances])这种写法完全绕开了GeneralizedRCNN.forward的内部编排直接复现了 detectron2/modeling/meta_arch/rcnn.py 中inference的调用链因此可以插入任意自定义逻辑截取中间结果。方案三使用 forward hooksPyTorch 的 forward hooks 可以帮助你捕获某个模块的输入或输出如果 hooks 拿到的张量不完全是你想要的还可以与方案二部分执行配合用 hooks 获取其他中间张量。无论选择哪种方案都需要阅读现有模型的文档乃至源码理解其内部逻辑才能正确写出获取内部张量的代码。小结Detectron2 的模型使用链路清晰而规整build_model(cfg)依据配置组装模型 →DetectionCheckpointer加载权重 → 在EventStorage下训练或在torch.no_grad()下推理 → 按照标准的list[dict]输入/输出契约与数据管线对接。理解这套契约尤其是输入输出格式与height/width的分辨率语义是进行二次开发、接入自定义数据与调试中间结果的前提。相关的完整 API 细节可进一步查阅 checkpoint 模块文档、engine 模块文档、structures 模块文档 与 data 模块文档。【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考