企业官网建设流程全解析

Detectron2 quick_schedules 回归测试配置完全指南：用分钟级任务守护模型性能

【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2

本篇以 Detectron2 仓库中 configs/quick_schedules/README.md 为主线，系统讲解其沉淀的"快速回归测试配置"（quick schedules for performance/accuracy regression tracking）设计思想与实战用法。Detectron2 在 configs/quick_schedules 目录下维护了一批可运行的配置，把完整 COCO 训练（动辄数天）压缩为 40 次迭代、数十分钟级（甚至单机 2 卡）的验收任务。读完本文，你将掌握三种测试（instance/instant test、inference accuracy test、training accuracy test）各自的使用场景、配置构成与命令行运行方式，并能结合 dev 下的脚本把这些任务嵌入自己的开发与 CI 流程。

一、quick_schedules 是什么：为什么要"快速"？

Detectron2 是一个用于物体检测、分割等视觉识别任务的平台，仓库本身演进活跃，涉及大量网络结构、CUDA 算子与训练逻辑的修改。如果在每次改动后都用完整配置（例如 configs/Base-RCNN-FPN.yaml 默认MAX_ITER: 90000、SOLVER.IMS_PER_BATCH: 16的全量训练）来验证，成本完全不可接受。于是项目将"回归跟踪"需求沉淀为一组特殊配置，正如 configs/quick_schedules/README.md 开篇所言：

These are quick configs for performance or accuracy regression tracking purposes.

这些配置不追求在 benchmark 上刷 SOTA，而是扮演"冒烟测试 + 精度基线校验"的角色，按用途分为三类，全部集中在 configs/quick_schedules 目录下（共 27 个 YAML 文件）：

README 对三类文件的官方定义原文如下，它们是理解全文的总纲：

• *instance_test.yaml: can train on 2 GPUs. They are used to test whether the training can successfully finish. They are not expected to produce reasonable training results.
• *inference_acc_test.yaml: They should be run using--eval-only. They run inference using pre-trained models and verify the results are as expected.
• *training_acc_test.yaml: They should be trained on 8 GPUs. They finish in about an hour and verify the training accuracy is within the normal range.

注：README 中写作*instance_test.yaml，而实际文件名后缀统一为*instant_test.yaml（如 mask_rcnn_R_50_FPN_instant_test.yaml），二者指向同一类配置，以实际文件名为准。

二、快速测试的核心工程技巧：BASE继承 + 覆写

几乎所有 quick_schedules 配置都大量复用正式模型配置，再通过 YAML 的_BASE_继承与键覆写"缩小问题规模"。这套机制来自 detectron2/config 的 LazyConfig/yacs 配置系统，好处是：

• 网络结构定义（backbone、FPN、RPN、head）与正式模型完全一致，测试的结构真实性有保障；
• 仅覆写数据集、迭代数与学习率等与时间成本强相关的字段，改动最小、可读性最强；
• 当正式基配置变化时，测试配置自动跟随，长期维护成本低。

2.1 基准基配置 configs/Base-RCNN-FPN.yaml

以 Mask R-CNN FPN 系列的 instant/inference/training 测试为例，它们都以_BASE_: "../Base-RCNN-FPN.yaml"为根，该文件定义了一整套标准的 ResNet+FPN 两阶段检测器默认值，关键字段包括：

MODEL: META_ARCHITECTURE: "GeneralizedRCNN" RESNETS: OUT_FEATURES: ["res2", "res3", "res4", "res5"] FPN: IN_FEATURES: ["res2", "res3", "res4", "res5"] RPN: PRE_NMS_TOPK_TRAIN: 2000 POST_NMS_TOPK_TRAIN: 1000 ROI_HEADS: NAME: "StandardROIHeads" ROI_BOX_HEAD: NAME: "FastRCNNConvFCHead" NUM_FC: 2 POOLER_RESOLUTION: 7 ROI_MASK_HEAD: NAME: "MaskRCNNConvUpsampleHead" NUM_CONV: 4 POOLER_RESOLUTION: 14 DATASETS: TRAIN: ("coco_2017_train",) TEST: ("coco_2017_val",) SOLVER: IMS_PER_BATCH: 16 BASE_LR: 0.02 STEPS: (60000, 80000) MAX_ITER: 90000 INPUT: MIN_SIZE_TRAIN: (640, 672, 704, 736, 768, 800) VERSION: 2

这是"默认值模板"：9 万次迭代、batch 16、单尺度 800 训练。quick_schedules 要做的就是把SOLVER.MAX_ITER压到几十到几千、把数据集换成迷你子集。

2.2 内置迷你数据集*_100：把 val 集缩小 100 倍

快速测试能跑得动，第二个关键是 Detectron2 内置注册了一批只有 100 张图的小型 COCO 子集。在 detectron2/data/datasets/builtin.py 中可以查到它们的注册信息，例如：

"coco_2017_val_100": ("coco/val2017", "coco/annotations/instances_val2017_100.json"), "keypoints_coco_2017_val_100": ("coco/val2017", "coco/annotations/person_keypoints_val2017_100.json"), "coco_2017_val_100_panoptic": (...),

这些数据集名形如<数据集>_2017_val_100，即从 val2017 全量标注里抽取 100 张图的子集标注（instances/person_keypoints/panoptic 对应版本），图片仍需从coco/val2017目录读取。语义分割的 quick test 则使用coco_2017_val_panoptic_stuffonly（仅 stuff 类别），Panoptic 测试使用coco_2017_val_100_panoptic_separated。正式评测中EXPECTED_RESULTS的期望精度正是针对这些迷你子集标定的（inference/training 两类测试的期望值都在 100 张子集上测得，详见下文）。

三、*instant_test.yaml：训练冒烟测试（2 卡）

适用目标：修改了训练相关代码（dataloader、loss、checkpoint、分布式逻辑、head 前向等）后，想确认"训练能不能完整走完一个最小周期而不崩"。此类任务不期望产生合理精度的模型，正如 README 所说 "They are not expected to produce reasonable training results."

3.1 一个典型实例的完整配置

以 configs/quick_schedules/mask_rcnn_R_50_FPN_instant_test.yaml 为例（全文仅 15 行）：

_BASE_: "../Base-RCNN-FPN.yaml" MODEL: WEIGHTS: "detectron2://ImageNetPretrained/MSRA/R-50.pkl" MASK_ON: True DATASETS: TRAIN: ("coco_2017_val_100",) TEST: ("coco_2017_val_100",) SOLVER: BASE_LR: 0.005 STEPS: (30,) MAX_ITER: 40 IMS_PER_BATCH: 4 DATALOADER: NUM_WORKERS: 2

对照 Base 模板，它做了四处关键覆写，每一处都服务于"把成本降到最低"：

• 权重：MODEL.WEIGHTS指向detectron2://协议的 ImageNet 预训练 R-50（R-50.pkl），省去从随机初始化带来的收敛不稳定风险（注意这是预训练 Backbone，不是完整模型权重）；
• 数据集：TRAIN/TEST 都换成coco_2017_val_100，训练仅接触 100 张图；
• 迭代数：MAX_ITER: 40（是 Base 的 9 万次迭代的 1/2250），STEPS: (30,)表示在 30 次迭代处衰减一次 LR；
• batch/worker：IMS_PER_BATCH: 4、NUM_WORKERS: 2，配合 2 卡即可运行的轻量 dataloader 配置。

40 次迭代 × batch 4 = 全流程只消费约 160 张样本，2 张 V100 上通常几分钟内即可跑完 epoch 式的完整生命周期（包含 checkpoint 保存、周期性评估、LR schedule 触发等）。

3.2 各架构的 instant 测试布局

quick_schedules 目录下共有 10 个*instant_test.yaml，基本覆盖了 Detectron2 的主要 meta-architecture，形成一张冒烟测试矩阵：

值得留意两类特殊变体：

Fast R-CNN 的 external proposals。见 fast_rcnn_R_50_FPN_instant_test.yaml，它额外声明了PROPOSAL_FILES_TRAIN/PROPOSAL_FILES_TEST，直接服用由 RPN 全量模型预生成的coco_2017_val_box_proposals_*.pkl，从而绕开 RPN 训练、只验证检测头的训练路径。

GCV 变体与梯度裁剪。mask_rcnn_R_50_C4_GCV_instant_test.yaml 专门覆盖 Gradient Clip by Value（CLIP_TYPE: "value"、CLIP_VALUE: 1.0）的训练路径，用于验证带梯度裁剪训练的稳定性。

3.3 如何运行：dev/run_instant_tests.sh

项目在 dev/run_instant_tests.sh 提供了批量执行入口，脚本核心逻辑如下：

BIN="python tools/train_net.py" OUTPUT="instant_test_output" NUM_GPUS=2 CFG_LIST=( "${@:1}" ) # 支持传入自定义配置列表 if [ ${#CFG_LIST[@]} -eq 0 ]; then CFG_LIST=( ./configs/quick_schedules/*instant_test.yaml ) # 默认跑全部 instant test fi for cfg in "${CFG_LIST[@]}"; do $BIN --num-gpus $NUM_GPUS --config-file "$cfg" \ SOLVER.IMS_PER_BATCH $(($NUM_GPUS * 2)) \ OUTPUT_DIR "$OUTPUT" rm -rf "$OUTPUT" # 每次跑完即清理输出 done

要点：

• 默认会遍历./configs/quick_schedules/*instant_test.yaml全部匹配项；也可以把特定配置作为位置参数传入做单测，如bash dev/run_instant_tests.sh configs/quick_schedules/mask_rcnn_R_50_FPN_instant_test.yaml；
• 入口是 tools/train_net.py，会通过--num-gpus调用launch以分布式方式启动（该文件使用default_argument_parser().parse_args()解析--config-file、--num-gpus、--eval-only、--resume、--opts等）；
• 命令行末端的SOLVER.IMS_PER_BATCH ...、OUTPUT_DIR ...属于--opts就地覆写，IMS_PER_BATCH被动态设为2 × 2 = 4，与配置文件保持一致。

读者在 2 卡环境下自行复现冒烟测试，最简单的方式是：

python tools/train_net.py --num-gpus 2 \ --config-file configs/quick_schedules/mask_rcnn_R_50_FPN_instant_test.yaml \ OUTPUT_DIR /tmp/instant_test_output

四、*inference_acc_test.yaml：推理精度回归（--eval-only）

适用目标：验证"预训练权重 + 当前代码"的推理结果与官方预期一致。当改动涉及后处理（NMS）、TTA、精度数值类型、模型导出等推理链路时，用它可以快速捕捉精度漂移。README 明确规定它必须以--eval-only方式运行，不做任何训练。

4.1 期望精度的声明式校验：TEST.EXPECTED_RESULTS

这是此类配置的灵魂。以 mask_rcnn_R_50_FPN_inference_acc_test.yaml 为例，它继承自正式模型 COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml，然后覆写权重与校验断言：

_BASE_: "../COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml" MODEL: WEIGHTS: "detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl" DATASETS: TEST: ("coco_2017_val_100",) TEST: EXPECTED_RESULTS: [["bbox", "AP", 47.34, 0.02], ["segm", "AP", 42.67, 0.02], ["bbox_TTA", "AP", 49.11, 0.02], ["segm_TTA", "AP", 45.04, 0.02]] AUG: ENABLED: True MIN_SIZES: (700, 800) # to save some time FLOAT32_PRECISION: "highest"

可以看到：

• MODEL.WEIGHTS下载官方发布的model_final_f10217.pkl（mask_rcnn_R_50_FPN_3x 在 Model Zoo 的最终权重）；
• TEST.EXPECTED_RESULTS声明一组四元组断言[task, metric, expected_value, tolerance]，这里是 bbox AP 47.34±0.02、segm AP 42.67±0.02，以及开启 TTA 后的bbox_TTA/segm_TTA期望；
• TEST.AUG.ENABLED: True开启 Test-Time Augmentation，且MIN_SIZES: (700, 800)被刻意收窄为两个尺度以节省时间（全量 TTA 通常使用多个尺度）；
• FLOAT32_PRECISION: "highest"固定浮点运算精度，防止不同 GPU/库的数值差异干扰断言。

4.2 底层校验机制：verify_results

EXPECTED_RESULTS如何生效？评测完成后，训练/评测框架 detectron2/engine/defaults.py 中会判断配置里是否有该字段并调用verify_results：

if len(self.cfg.TEST.EXPECTED_RESULTS) and comm.is_main_process(): verify_results(self.cfg, self._last_eval_results)

而verify_results实现在 detectron2/evaluation/testing.py，逻辑非常直接：遍历EXPECTED_RESULTS中的每组(task, metric, expected, tolerance)，从实际评测结果中取出对应指标，逐一比较|actual - expected|是否超过容差；一旦超差或指标缺失/非有限值，就打印 "Result verification failed!" 并以sys.exit(1)退出，从而让外层脚本感知失败：

def verify_results(cfg, results): expected_results = cfg.TEST.EXPECTED_RESULTS ... for task, metric, expected, tolerance in expected_results: actual = results[task].get(metric, None) ... diff = abs(actual - expected) if diff > tolerance: ok = False ... if not ok: logger.error("Result verification failed!") sys.exit(1) else: logger.info("Results verification passed.")

这就是"精度回归自动化断言"的完整闭环：评测结果对比期望值 → 超差即非零退出码 → CI 判定失败。

4.3 其他推理精度测试与运行方式

• keypoint_rcnn_R_50_FPN_inference_acc_test.yaml：基于 COCO-Keypoints/Base-Keypoint-RCNN-FPN.yaml，断言关键点与 bbox 的推理精度；
• retinanet_R_50_FPN_inference_acc_test.yaml、rpn_R_50_FPN_inference_acc_test.yaml、semantic_R_50_FPN_inference_acc_test.yaml 分别覆盖单阶段检测、RPN、语义分割（sem_seg mIoU/mACC 断言）的推理路径；
• panoptic_fpn_R_50_inference_acc_test.yaml 除模型精度外，还配套了一个可视化冒烟测试。

命令行运行（单机建议至少 2 卡；模型权重通过detectron2://自动下载到缓存）：

python tools/train_net.py --eval-only --num-gpus 2 \ --config-file configs/quick_schedules/mask_rcnn_R_50_FPN_inference_acc_test.yaml \ OUTPUT_DIR /tmp/inference_acc_test_output

项目提供的批量入口 dev/run_inference_tests.sh 与 instant 测试脚本结构类似，默认遍历./configs/quick_schedules/*inference_acc_test.yaml，以--eval-only逐项执行；随后它还会调用python demo/demo.py --config-file ./configs/quick_schedules/panoptic_fpn_R_50_inference_acc_test.yaml --input datasets/coco/val2014/COCO_val2014_0000001933* --output $OUTPUT做一次端到端可视化推理检查（需准备 COCO val2014 图片）。

提示：推理精度测试对数值稳定环境有要求——某些 GPU 在 TF32/FP16 混算下可能出现超出 0.02 容差的抖动，这也是配置里显式声明FLOAT32_PRECISION: "highest"的原因。

五、*training_acc_test.yaml：短时训练精度回归（8 卡，约 1 小时）

适用目标：验证改动没有破坏训练本身的正确性——例如梯度流、损失函数、优化器更新都正常，模型经过一段完整训练后，精度应稳定落在历史基线区间。README 要求以8 张 GPU运行，训练约 1 小时即可结束（相对 9 万迭代的全量训练只是零头），然后通过EXPECTED_RESULTS断言训练收敛程度。

5.1 一个典型实例的完整配置

以 mask_rcnn_R_50_FPN_training_acc_test.yaml 为例，它直接继承 Base-RCNN-FPN 并把训练规模压到 6000 迭代：

_BASE_: "../Base-RCNN-FPN.yaml" MODEL: WEIGHTS: "detectron2://ImageNetPretrained/MSRA/R-50.pkl" ROI_HEADS: BATCH_SIZE_PER_IMAGE: 256 MASK_ON: True DATASETS: TRAIN: ("coco_2017_val",) TEST: ("coco_2017_val",) INPUT: MIN_SIZE_TRAIN: (600,) MAX_SIZE_TRAIN: 1000 MIN_SIZE_TEST: 800 MAX_SIZE_TEST: 1000 SOLVER: WARMUP_FACTOR: 0.3333333 WARMUP_ITERS: 100 STEPS: (5500, 5800) MAX_ITER: 6000 TEST: EXPECTED_RESULTS: [["bbox", "AP", 42.5, 1.0], ["segm", "AP", 35.8, 0.8]]

与 instant 测试不同，这里不使用_100子集而是直接用完整coco_2017_val（val 在同时承担训练集角色时相当于一种"准测试集"），通过调整输入尺度来缩短单步时间：训练尺度固定为短边 600（MIN_SIZE_TRAIN: (600,)去掉 Base 的多尺度抖动），测试尺度短边 800。6000 次迭代 + 长短两个 LR 衰减点（5500、5800），在 8 卡 × 每批 16（Base 默认 IMS_PER_BATCH）下约 1 小时跑完，期望 bbox AP ≈ 42.5（容差 ±1.0）、segm AP ≈ 35.8（容差 ±0.8）。容差远大于 inference 测试（0.02），因为短训练天然存在随机波动，验证的是"数量级正确"而非"逐点一致"。

5.2 关键点与 RPN smooth L1 的注释

对回归测试配置而言，训练精度断言受 loss 类型影响极大。在关键点版本 keypoint_rcnn_R_50_FPN_normalized_training_acc_test.yaml 中可以看到两组带注释的覆写，直接反映工程经验：

ROI_BOX_HEAD: SMOOTH_L1_BETA: 1.0 # Keypoint AP degrades when using plain L1 loss RPN: SMOOTH_L1_BETA: 0.2 # Keypoint AP degrades when using plain L1 loss

即关键点任务下若将 Smooth L1 换成普通 L1，关键点 AP 会明显退化——这两条注释把"为什么这个数值必须保持"烙进了配置本身，说明 quick_schedules 也在记录可复现的训练超参数基线。该配置还包含 ROI 头 batch 256、ROI_KEYPOINT_HEAD.NORMALIZE_LOSS_BY_VISIBLE_KEYPOINTS: False等与正式关键点模型一致的超参，并断言 keypoints AP 76.91±1.0。

5.3 语义分割的 mIoU 断言与 stuff-only 训练

语义分割版 semantic_R_50_FPN_training_acc_test.yaml 把META_ARCHITECTURE覆写为"SemanticSegmentor"，训练/测试都使用coco_2017_val_panoptic_stuffonly（panoptic 标注中的 stuff 类别子集），关闭尺度增强以提速：

TEST: EXPECTED_RESULTS: [["sem_seg", "mIoU", 76.51, 1.0], ["sem_seg", "mACC", 83.25, 1.0]] INPUT: MIN_SIZE_TRAIN: (800, ) # no scale augmentation

对语义分割的回归断言同时给出mIoU（76.51±1.0）与mACC（83.25±1.0）两类像素级指标。类似的，Panoptic 版本 panoptic_fpn_R_50_training_acc_test.yaml 使用coco_2017_val_panoptic_separated。

5.4 覆盖范围与运行方式

training_acc_test一族目前共 7 个配置，除上述外还包括 mask_rcnn_R_50_C4_training_acc_test.yaml（C4 backbone 训练路径）与 mask_rcnn_R_50_FPN_pred_boxes_training_acc_test.yaml（覆盖"基于预测框而非 GT 框采样"的特殊训练回归）。

运行命令与 inference 测试相同，但不带--eval-only：

python tools/train_net.py --num-gpus 8 \ --config-file configs/quick_schedules/mask_rcnn_R_50_FPN_training_acc_test.yaml \ OUTPUT_DIR /tmp/training_acc_test_output

注意：请按 README 要求使用 8 卡；若 GPU 数量或每卡显存不同，需要同步调整SOLVER.IMS_PER_BATCH，否则学习率/迭代数与 batch 的默认配套关系会失真，导致精度断言不可复现。

六、三者在 CI / 开发流程中的角色

把这三种测试放到一起看，它们分别守卫开发流程的三个不同阶段，构成一套"金字塔式"回归防线：

1. 最底层（最快）：*instant_test.yaml，2 卡、几分钟——每个 PR 或本地改动后先跑，只有训练生命周期跑通，后续才有意义。它通常直接决定 "does training crash at all?" 这类基本问题；
2. 中层：*inference_acc_test.yaml，单机 2 卡即可，依赖 Model Zoo 预训练权重——验证推理链路（含 TTA、数值精度）对模型输出的保真度，适合在改动postprocessing、evaluation、export相关代码后运行；
3. 顶层（最贵，按需跑）：*training_acc_test.yaml，8 卡约 1 小时——验证训练链路数值正确性，适合在大规模改动 optimizer、loss、backbone 结构后做周期性回归。

三个脚本exit code都可作为 CI 门禁：凡EXPECTED_RESULTS校验失败（detectron2/evaluation/testing.py 返回sys.exit(1)），对应 job 即失败；而dev/run_instant_tests.sh、dev/run_inference_tests.sh默认遍历整个 configs/quick_schedules 目录，新增配置无需改动脚本即可自动纳入回归矩阵。

七、小结与快速参考

• 核心思想：用_BASE_继承正式模型配置，通过覆写MAX_ITER/IMS_PER_BATCH/数据集/输入尺度把训练成本降低数个数量级，从而把"模型回归验证"从几天压缩到几分钟到一小时；
• 数据集基础：依赖detectron2://预训练权重（ImageNet R-50 / Model Zoo final weights）与内置 100 张子集（*_val_100、*_val_100_panoptic_separated），相关注册见 detectron2/data/datasets/builtin.py；
• 断言机制：三类配置中的期望精度统一通过TEST.EXPECTED_RESULTS（格式[task, metric, expected, tolerance]）声明，由 detectron2/engine/defaults.py 在评测/训练结束时触发 verify_results 自动校验；
• 容差设计：inference 测试容差极小（0.02，逐点复现官方推理）；training 测试容差大（±0.8~1.0，容忍短训练随机波动）；instant 测试无精度断言，只看能否跑通；
• 快速上手命令：见 dev/run_instant_tests.sh 与 dev/run_inference_tests.sh，或按上文命令直接通过 tools/train_net.py 指定单配置执行。

当你需要为自己的定制检测/分割模型建立低成本回归体系时，直接复用 configs/quick_schedules 这套模式（继承正式配置 + 迷你数据集 +EXPECTED_RESULTS断言 + shell 批量脚本）即可获得与 Detectron2 官方同款的开发保障。

【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2