人工智能计算机视觉深度学习机器学习【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址https://gitcode.com/GitHub_Trending/de/detectron2点击查看免费下载导读本文以 detectron2 官方 Notes 文档体系docs/notes/index.rst为骨架系统梳理该项目的四大工程主题Mask R-CNN 训练吞吐基准测试benchmarks、与 Detectron/Caffe2/TensorFlow 的兼容性差异compatibility、向后兼容与变更日志changelog、社区贡献规范contributing。阅读本文后你将掌握如何在 8 卡环境下复现官方基准测试、理解 detectron2 与老版 Detectron 在边框约定与 ROIAlign 等底层算子上的具体差异并据此迁移模型、识别历史上易被忽略的静默回归问题以及按官方标准提交代码的完整流程。本文的实操命令与配置均来自当前仓库真实文件源码级结论均标注了对应实现路径可直接对照验证。一、Notes 文档体系概览docs/notes/目录在官方文档中承担项目级工程说明角色index.rst通过 Sphinx toctree 将以下四篇主题文档组织为可导航的知识单元文档主题docs/notes/benchmarks.mdMask R-CNN 训练速度的跨实现基准对比docs/notes/compatibility.md与 Detectron / maskrcnn-benchmark / Caffe2 / TensorFlow 的兼容性说明docs/notes/changelog.md向后兼容策略、配置版本演变与历史静默回归清单docs/notes/contributing.mdIssue / PR 流程、功能取舍标准与贡献规范下文按这四个主题逐一展开并在每个主题中结合仓库源码补充底层实现证据帮助读者从知道是什么进阶到知道为什么。二、训练吞吐基准测试Benchmarks2.1 测试设置与方法学官方基准用于评估一个端到端 R-50-FPN Mask R-CNN 模型在 detectron2 与主流开源实现中的训练吞吐其关键设置如下硬件8 张 NVIDIA V100NVLink 互联软件栈Python 3.7、CUDA 10.1、cuDNN 7.6.5、PyTorch 1.5对照实现分别使用 TensorFlow 1.15.0rc2Keras 2.2.5、MxNet 1.6.0b20190820 等模型端到端 R-50-FPN Mask R-CNN超参数与 Detectron baseline 配置 保持一致——关键点是该配置没有尺度增强INPUT.MIN_SIZE_TRAIN: (800,)固定单尺度短边 800 训练指标取迭代 100500 的平均吞吐img/s以跳过 GPU 预热阶段。文档同时提醒R-CNN 类模型训练过程中的吞吐会随模型预测质量动态变化因此该指标与 Model Zoo 中整轮训练平均速度不可直接比较。这一跳过 warmup、取稳定区间均值的度量思路可以在复现实验时直接沿用以避免初始化阶段的核函数编译、缓存填充干扰读数。2.2 主要结果实现吞吐img/sdetectron2PyTorch62mmdetectionPyTorch53maskrcnn-benchmarkPyTorch53tensorpackTensorFlow50SimpleDetMxNet39DetectronCaffe219matterport/Mask_RCNNTensorFlow14需要强调这是该基准发布时detectron2 release v0.1.2、PyTorch 1.5 时代在特定硬件上的测量结果数字随软件版本、GPU 型号与数据规模变化很大不宜作为当前版本的绝对性能承诺其价值在于同一软硬件约束下的相对对比以及纯 PyTorch 实现也能达到领先的训练吞吐这一设计目标的验证。2.3 各实现复现命令官方文档为每个对照实现给出了精确的复现方式detectron2使用 release v0.1.2运行python tools/train_net.py --config-file configs/Detectron1-Comparisons/mask_rcnn_R_50_FPN_noaug_1x.yaml --num-gpus 8其中--num-gpus 8通过 tools/train_net.py 内部调用 detectron2/engine/launch.py 的分布式启动逻辑将训练分配到 8 张卡上。mmdetectioncommitb0d845f运行./tools/dist_train.sh configs/mask_rcnn/mask_rcnn_r50_caffe_fpn_1x_coco.py 8maskrcnn-benchmarkcommit0ce8f6f先用sed -i s/torch.uint8/torch.bool/g **/*.py; sed -i s/AT_CHECK/TORCH_CHECK/g **/*.cu适配 PyTorch 1.5再运行python -m torch.distributed.launch --nproc_per_node8 tools/train_net.py --config-file configs/e2e_mask_rcnn_R_50_FPN_1x.yaml。文档注明其测得速度高于其 Model Zoo 数据可能源于软件版本差异tensorpackcommitcaafdaexport TF_CUDNN_USE_AUTOTUNE0后运行mpirun -np 8 ./train.py --config DATA.BASEDIR/data/coco TRAINERhorovod BACKBONE.STRIDE_1X1True TRAIN.STEPS_PER_EPOCH50 --load ImageNet-R50-AlignPadding.npzSimpleDetcommit9187a1运行python detection_train.py --config config/mask_r50v1_fpn_1x.pyDetectron运行python tools/train_net.py --cfg configs/12_2017_baselines/e2e_mask_rcnn_R-50-FPN_1x.yaml。文档特别指出其大量算子运行在 CPU 上因此性能受限吞吐仅 19 img/smatterport/Mask_RCNNcommit3deaec需先应用文档附录中的 hyperparameter 对齐 diff核心改动包括GPU_COUNT8、BACKBONEresnet50、STEPS_PER_EPOCH50、TRAIN_ROIS_PER_IMAGE512、合并三阶段训练为单阶段layers3并关闭 validation 回调等然后export TF_CUDNN_USE_AUTOTUNE0并运行python coco.py train --dataset/data/coco/ --modelimagenet。该 diff 也印证了基准对超参数可比性的重视——若不消除实现间超参差异吞吐对比将失去意义。2.4 从配置与源码理解基准背后的模型形态基准使用的 configs/Detectron1-Comparisons/mask_rcnn_R_50_FPN_noaug_1x.yaml 是理解Detectron1 兼容形态的最佳样例它显式回滚了 detectron2 相对 Detectron1 的若干默认变更_BASE_: ../Base-RCNN-FPN.yaml MODEL: WEIGHTS: detectron2://ImageNetPretrained/MSRA/R-50.pkl MASK_ON: True RESNETS: DEPTH: 50 # Detectron1 uses smooth L1 loss with some magic beta values. # The defaults are changed to L1 loss in Detectron2. RPN: SMOOTH_L1_BETA: 0.1111 ROI_BOX_HEAD: SMOOTH_L1_BETA: 1.0 POOLER_SAMPLING_RATIO: 2 POOLER_TYPE: ROIAlign ROI_MASK_HEAD: POOLER_SAMPLING_RATIO: 2 POOLER_TYPE: ROIAlign INPUT: # no scale augmentation MIN_SIZE_TRAIN: (800, )对照 detectron2/config/defaults.py 中的默认值可以清晰看到差异点MODEL.RPN.SMOOTH_L1_BETA与MODEL.ROI_BOX_HEAD.SMOOTH_L1_BETA默认均为0.0即纯 L1 loss而非 smooth L1POOLER_TYPE默认是ROIAlignV2而该基准配置回退为ROIAlign。这些正是下一章兼容性主题中推理结果不一致的根源之一。三、与其他库的兼容性Compatibilitydetectron2 在解决 Detectron 遗留问题的同时刻意不保证与 Detectron 的模型级兼容即使使用完全相同的权重两个代码库推理得到的结果也会不同。官方文档将差异归纳为推理与训练两个层面下面逐一展开并结合源码定位差异实现。3.1 推理层面的主要差异3.1.1 边框宽高的自然约定去掉 1这是最基础也最影响深远的一项角点为 (x1, y1)、(x2, y2) 的边框宽高现在按width x2 - x1、height y2 - y1计算而 Detectron 对宽高各加 1。这一变更最直接地影响了边框回归的编码/解码。在 detectron2/modeling/box_regression.py 的Box2BoxTransform中可以看到新约定的落地src_widths src_boxes[:, 2] - src_boxes[:, 0]、src_heights src_boxes[:, 3] - src_boxes[:, 1]get_deltas解码时同样以widths boxes[:, 2] - boxes[:, 0]为基础计算中心点与 exp 缩放非极大值抑制NMS。影响非常小文档明确标注可忽略。文档同时说明Caffe2 的相关算子已通过额外选项采纳了这一新约定因此detectron2 训练的模型仍可在 Caffe2 中做推理。3.1.2 RPN 使用更简单、量化伪影更少的 anchorDetectron 中的 anchor 被量化且面积不够精确detectron2 的 anchor 与特征网格点中心对齐且不做量化。源码证据在 detectron2/modeling/anchor_generator.py_create_grid_offsets使用torch.arange(offset * stride, grid_width * stride, stepstride, ...)生成网格偏移默认offset0.5即半 stride 偏移构造器注释推荐该值约束0.0 offset 1.0generate_cell_anchors直接由size面积平方根与aspect_ratio代数推导w sqrt(area / a)、h a * w代码注释明确写道这与原始 Faster R-CNN / Detectron 的 anchor 生成方式不同——旧版本以不太自然的方式相对特征网格偏移并引入量化导致不同 aspect ratio 的 anchor 尺寸略有差异。3.1.3 类别标签顺序不同任何形状为(..., num_categories 1, ...)的可训练参数都会受影响detectron2整数标签[0, K-1]对应 K 个目标类别标签K是专门的背景类别Detectron标签0表示背景[1, K]对应 K 个类别。这意味着从 Detectron 迁移权重时分类层以及所有带1维度的层的权重顺序必须重排。数据侧detectron2/data/datasets/coco.py 通过id_map {v: i for i, v in enumerate(cat_ids)}把 COCO 的稀疏类别 id 映射为[0, 80)连续 id 并写入thing_dataset_id_to_contiguous_id元数据保证与0 为背景的约定衔接。3.1.4 ROIAlign 的不同实现半像素对齐新实现与原版有两处关键差异官方已将其移植到 Caffe2所有 ROI 相对 Detectron 平移半个像素以获得更好的图像-特征图对齐。实现见 detectron2/layers/roi_align.pyROIAlign默认alignedTrue类注释解释了其像素模型——给定连续坐标 c邻接像素索引按floor(c - 0.5)与ceil(c - 0.5)计算而旧实现alignedFalse不做 0.5 减法双线性插值时使用了轻微错位的像素。若需启用旧行为可用ROIAlign(alignedFalse)或在配置中将POOLER_TYPE从默认的ROIAlignV2改为ROIAlign这正是 2.4 节基准配置的做法。单元测试 tests/layers/test_roi_align.py 用 5×5 输入同时验证了两种模式的输出未校正结果为[[7.5, 8, ...], ...]加 0.5 校正后为[[4.5, 5.0, ...], ...]可直接对照理解半像素的具体数值含义ROI 不再要求最小尺寸为 1输出上只有微小、可忽略的差异。另外ROIAlign实现要求torchvision 0.7文件头部有显式断言因为新对齐语义依赖 torchvision 的roi_align接口。3.1.5 Mask 推理函数不同paste_mask 更精确detectron2 重写了 paste_mask 函数精度高于 Detectron官方测量显示该改动可为 COCO mask AP 带来约0.5% 绝对值的提升。核心实现位于 detectron2/layers/mask_ops.py新实现paste_masks_in_image通过torch.nn.functional.grid_samplealign_cornersFalse把固定分辨率如 28×28的预测 mask 采样回原图平面支持整图批量粘贴与按GPU_MEM_LIMIT 1GB分块GPU 上更快旧实现paste_mask_in_image_old保留在同一文件中第 155 行起注释明确其因错误的像素建模而具有更大量化误差、已不再使用——它以box[2] - box[0] 1计算采样像素数正是 3.1.1 节去掉 1约定的反面教材。3.2 训练层面的主要差异不影响模型级兼容RPN.POST_NMS_TOPK_TRAIN由 per-batch 改为 per-image修复了 Detectron 的已知 bug但可能导致少数模型如 keypoint 检测精度小幅下降需重新调参才能对齐 Detectron 结果。这一点在 configs/Base-RCNN-FPN.yaml 中有完整注释Detectron1 在默认 batch size 为 2 时每批 2000 个 proposal约合每图 1000 个而 detectron2 直接以 per-image 语义配置POST_NMS_TOPK_TRAIN: 1000对应 detectron2/config/defaults.py 中的默认值 2000/1000 在 FPN 配置下被显式覆盖边框回归默认 loss 从 smooth L1 改为 L1官方观察到这会使 box AP50 略降、但高 IoU 阈值下的 box AP 提升整体 box AP 轻微改善。默认值见 detectron2/config/defaults.pyMODEL.RPN.SMOOTH_L1_BETA 0.0与第 304 行MODEL.ROI_BOX_HEAD.SMOOTH_L1_BETA 0.0需要平滑 L1 时正是通过 2.4 节的SMOOTH_L1_BETA配置开启坐标解释约定COCO 边框与分割标注的坐标被解释为[0, width]/[0, height]连续坐标而关键点标注被解释为[0, width-1]/[0, height-1]的像素索引。该约定直接影响水平翻转增强的实现在 detectron2/data/detection_utils.py 的transform_keypoint_annotations中翻转关键点需要keypoint_hflip_indices把每个关键点交换为其对侧对应点如左眼 ↔ 右眼该索引由create_keypoint_hflip_indices依据数据集元数据生成水平翻转由 detectron2/data/transforms/augmentation_impl.py 的Flip增强默认prob0.5产生HFlipTransform其apply_coords/apply_box等类型化接口负责同步变换标注坐标。3.3 与 Caffe2 的兼容性如 3.1 所述尽管与 Detectron 推理结果不兼容但相关算子新边框约定、新 ROIAlign已在 Caffe2 中实现因此detectron2 训练的模型可以转换为 Caffe2 部署。完整教程见 docs/tutorials/deployment.md配套的转换入口包括 tools/deploy/export_model.py 以及 detectron2/export/ 下的caffe2_export.py、caffe2_modeling.py等模块评估侧可通过 detectron2/evaluation/coco_evaluation.py 的COCOEvaluator对转换结果做 bbox / segm / keypoints 三类任务的指标核对。3.4 与 TensorFlow 的兼容性大多数算子在 TensorFlow 中可用但 resize / ROIAlign / padding 的实现存在微小差异需要处理。官方提供的可行路径是使用 tensorpack Faster R-CNN 的转换脚本运行标准 detectron2 模型具体用法以其仓库文档为准仓库侧可参考 detectron2/export/torchscript.py 等导出工具链作为中间格式的参考。四、向后兼容性与变更日志Changelog4.1 API 稳定性分级策略由于库的研究性质不可避免存在向后不兼容变更。为降低对用户的冲击官方定义了清晰的稳定性分级见 docs/notes/changelog.md稳定 APIAPI 文档中列出的函数/类名、参数及文档化的类属性除非另有说明均视为稳定。若确需破坏会先触发一段合理时长的 deprecation 警告并记录在 Release 日志中内部 API其余函数/类/属性视为内部实现更易变更。但官方意识到部分已被外部项目使用尤其是detectron2/projects内的便捷复用对这类 API 也可能按稳定 API 对待并在时机成熟时提升为稳定实验性项目detectron2/projects下的项目或用detectron2.projects导入的项目全部视为实验性质默认行为可变名称含 default 或被明确文档化为产生默认行为的类/函数其行为可能在新增功能时改变。官方同时给出一个务实建议第三方项目若想跟上 detectron2 的最新进展以库依赖方式跟进比 fork 源码更省心因为 API 变更的频率与范围远小于代码级变更。可在 Release 日志中搜索 incompatible changes 查看具体破坏性变更。4.2 配置版本Config Version演变detectron2 自开源以来配置版本号从未变更普通开源用户无需担心该问题。历史上有两次版本更迭v1将RPN_HEAD.NAME重命名为RPN.HEAD_NAMEv2发布前对大量配置进行了一轮批量重命名。当前配置文件中可见VERSION: 2字段如 configs/Base-RCNN-FPN.yaml配置解析与旧版本迁移逻辑位于 detectron2/config/ 下的config.py、compat.py与defaults.py。4.3 历史静默回归清单Silent Regressions这是最有排查价值的一节以下问题会静默产生错误结果且难以调试官方将其列档备忘时间窗口问题2020-04-01 ~ 2020-05-11当TRAIN_ON_PRED_BOXESTrue时精度异常2020-03-30 ~ 2020-04-01ResNet 主干构建不正确2019-12-19 ~ 2019-12-26使用 aspect ratio grouping 导致精度下降2019-11-09 之前测试时增强TTA不预测最后一个类别如果你复现的历史结果恰好落在这几个窗口应优先怀疑这些已知问题而非自身代码TRAIN_ON_PRED_BOXES对应的训练模式可参考 configs/quick_schedules/mask_rcnn_R_50_FPN_pred_boxes_training_acc_test.yaml 这类准确率回归测试配置。五、参与贡献Contributing5.1 Issue 与 PR 流程Issue官方使用 GitHub Issues 追踪公开 bug 与问题报告时需遵循 issue 模板涉及安全漏洞的披露需走官方的白帽bounty流程而非公开提 issuePR 规模约束对于较大的新功能约 50 行提交 PR 前必须先与维护者在 issue 中讨论动机与方案避免把时间花在可能被拒绝的 PR 上。5.2 功能取舍的五大考量官方并不总是接受新功能评审依据以下因素能否不改动 detectron2 就能实现detectron2 设计为可从外部扩展大量能力如 projects/ 中的各类项目若某个部分扩展性不足应提出更通用的改进诉求受众广度功能是否对大量用户有用有影响力的检测论文、流行数据集、显著加速、广泛使用的工具还是只服务小众场景冷门论文、非主流 trick、非标准数据。新增模型/数据集/新任务默认不会被纳入主干除非社区热度足够此类功能通常放进projects/或在 projects/README.md 中给出链接接口设计是否良好可在 PR 前以 issue 或 draft PR 形式讨论是否给不需要该功能的用户增加心智/实践负担是否会破坏现有 API。5.3 新增功能的两种路径给既有函数/类Func加功能时有两种选择(1) 给Func增加新参数(2) 新写Func_with_new_feature。官方更偏好方案 (2)理由包括不修改或破坏既有代码不给不需要该功能的用户增加负担以及给函数无限加参数在未来层出不穷的研究想法面前不可扩展。这一偏好与 5.2 的第 1、4 条标准一脉相承也解释了仓库中大量以独立模块/项目形态存在的新方法如 projects/PointRend、projects/TridentNet 等。5.4 提交 PR 的检查清单若 PR 包含多个正交改动拆分为多个 PR新增了应被测试的代码需补充测试仓库测试见 tests/例如 ROIAlign 语义验证在 tests/layers/test_roi_align.py需要实验的 PR如新模型/新方法不必更新 Model Zoo但必须在 PR 描述中提供实验结果若 API 有变更同步更新文档Python docstring 遵循 Google 风格Sphinx napoleon 扩展支持代码需通过./dev/linter.sh的 lint 检查脚本位于 dev/linter.sh。5.5 CLA 与 License接受 PR 前需要提交一次 Contributor License AgreementCLA仅需一次即可参与 Facebook 系所有开源项目。贡献即视为同意将贡献内容按仓库根目录 LICENSE 许可授权。六、快速参考与总结围绕 Notes 四篇文档可以提炼出以下可直接使用的工程要点基准复现使用 configs/Detectron1-Comparisons/mask_rcnn_R_50_FPN_noaug_1x.yaml 与python tools/train_net.py --config-file ... --num-gpus 8并参考文档方法取 100500 迭代均值注意该配置同时是回滚 Detectron1 默认行为的活教材SMOOTH_L1_BETA、POOLER_TYPE: ROIAlign、单尺度训练跨库迁移从 Detectron 迁移模型时需处理宽高约定1、anchor 中心对齐、类别标签顺序、ROIAlign 半像素对齐alignedFalse或POOLER_TYPEROIAlign取旧行为与 paste_mask 精度差异Caffe2 部署路径是可行的TensorFlow 需处理 resize/ROIAlign/padding 的微小差异兼容性避坑关注 API 稳定性分级搜索 Release 日志中 incompatible changes配置版本自开源未变当前VERSION: 2留意四个历史静默回归时间窗贡献规范大功能先提 issue 讨论、优先新模块而非改旧接口、Google 风格 docstring、./dev/linter.sh校验、测试与文档同步更新。综上Notes 文档是衔接纯算法研究与工程化落地的重要桥梁基准测试让性能对比有据可依兼容性说明让模型迁移有章可循变更日志让版本演进可追溯贡献规范让社区协作可持续。结合本仓库源码逐项对照读者既能直接复现官方结论也能在面对新旧代码混用时快速定位差异根源。赞分享人工智能计算机视觉深度学习机器学习【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址https://gitcode.com/GitHub_Trending/de/detectron2点击查看免费下载相关推荐Media Downloader跨版本兼容性API变更与向后兼容处理Media Downloader跨版本兼容性API变更与向后兼容处理 在使用Media Downloader时你是否遇到过升级后某些功能突然失效的情况是否桌面应用音视频ffsubsync跨版本兼容性处理API变更与向后兼容策略ffsubsync跨版本兼容性处理API变更与向后兼容策略 你是否曾在升级ffsubsync后遭遇命令失效或字幕同步异常作为一款自动化字幕同步工具ffsu音视频音频处理视频处理CLI如何确保Meson Build System跨版本兼容性API变更与向后兼容终极指南如何确保Meson Build System跨版本兼容性API变更与向后兼容终极指南 Meson Build System作为一款高效的构建系统在不断迭代过构建工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
