Detectron2 工具脚本全指南从训练、评估到性能分析与结果可视化【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2本指南以 detectron2 仓库 tools/ 目录下的官方示例脚本为核心系统讲解 train_net.py、plain_train_net.py、benchmark.py、analyze_model.py、visualize_json_results.py 与 visualize_data.py 六个脚本的定位、用法与底层实现。读完本文你将能够通过命令行完成训练内置模型、纯训练循环改造、训练/推理/数据加载速度基准测试、模型 FLOPs 与参数量分析、推理结果与标注数据可视化等完整工作流并理解每个脚本背后的源码级原理。tools 目录概览为什么需要这些脚本根据 tools/README.md 的定位tools/目录存放的是一组演示 detectron2 特性的示例脚本。它们是官方刻意设计的库的用法范例而不是生产级的应用代码——这一点从 train_net.py 的文件头注释可以直接读出为了让一个脚本支持训练很多模型这个脚本包含了一些与内置模型强相关的逻辑因此可能不适合你自己的项目……我们建议你把 detectron2 当作一个库来使用并把本文件当作如何使用这个库的示例。这一设计理念贯穿全部六个脚本内置脚本负责覆盖标准工作流自定义研究需求则通过改写脚本或直接调用 detectron2 API 实现。下表给出六个脚本的一站式速览脚本核心职责典型调用方式train_net.py基于DefaultTrainer训练/评估内置模型python train_net.py --config-file cfg.yamlplain_train_net.py手写训练循环替代Trainer更易魔改同上但训练逻辑完全可见benchmark.py基准测试训练/推理/数据加载速度python benchmark.py --config-file cfg.yaml --task trainanalyze_model.py分析模型 FLOPs、参数、激活量python analyze_model.py --tasks flop --config-file cfg.yamlvisualize_json_results.py可视化 COCO/LVIS 评测 JSON 结果python visualize_json_results.py --input x.json --output dir/ --dataset coco_2017_valvisualize_data.py可视化原始标注或增强后的训练数据python visualize_data.py --config-file cfg.yaml --source annotation下面逐一对每个脚本展开深入讲解。train_net.py内置模型的训练与评估入口train_net.py 是官方推荐的训练脚本其详细命令行用法记录在仓库根目录的 GETTING_STARTED.md 中该文档与tools/README.md相互引用是组合阅读的入口。通用命令行参数default_argument_parser所有训练类脚本train_net、plain_train_net、benchmark、analyze_model都复用 detectron2/engine/defaults.py 中定义的default_argument_parser因此参数体系完全一致--config-file FILE配置文件路径YAML 或 Python LazyConfig--resume尝试从输出目录中的 checkpoint 断点续训--eval-only仅执行评估不训练--num-gpus N每台机器使用的 GPU 数量默认 1--num-machines N机器总数默认 1--machine-rank R当前机器在集群中的编号多机训练时每台机器唯一--dist-url URLPyTorch 分布式初始化地址默认tcp://127.0.0.1:portopts行尾追加的任意配置覆盖项格式为空格分隔的PATH.KEY VALUEYAML 配置或path.keyvaluePython LazyConfig。其中--dist-url的默认端口采用确定性算法2**15 2**14 hash(uid) % 2**14生成这是为了在多卡训练遗留孤儿进程时用户能通过端口被占用这一现象直接感知问题。标准训练流程先按 datasets/README.md 准备好数据集然后进入tools/目录执行示例为 8 卡训练 Mask R-CNNcd tools/ ./train_net.py --num-gpus 8 \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml仓库中的 configs/ 配置默认按 8 卡训练设计。如果只有 1 张 GPU需要按线性缩放法则同步调整批量大小与学习率相关理论依据见论文Accurate, Large Minibatch SGD: Training ImageNet in 1 Hour例如./train_net.py \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \ --num-gpus 1 SOLVER.IMS_PER_BATCH 2 SOLVER.BASE_LR 0.0025仅评估已有权重时使用--eval-only./train_net.py \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \ --eval-only MODEL.WEIGHTS /path/to/checkpoint_file脚本内部的调用链从源码看train_net.py的执行链非常清晰见 tools/train_net.pysetup(args)通过get_cfg()读取默认配置merge_from_file合并 YAMLmerge_from_list合并命令行 opts最后cfg.freeze()冻结并由default_setup完成日志、环境信息输出与配置备份Trainer(DefaultTrainer)子类只重写了两个类方法build_evaluator按数据集的evaluator_type元数据分派评估器和test_with_TTA测试时增强main()中若为--eval-only则构建模型、DetectionCheckpointer.resume_or_load载入权重并调用Trainer.test否则实例化 Trainer、resume_or_load后trainer.train()invoke_main()最后通过launch()启动分布式训练。其中build_evaluator是一个值得关注的hacky 但实用的分发逻辑tools/train_net.py它读取MetadataCatalog.get(dataset_name).evaluator_type据此自动组装SemSegEvaluator、COCOEvaluator、COCOPanopticEvaluator、CityscapesInstanceEvaluator、PascalVOCDetectionEvaluator、LVISEvaluator等并把多个评估器用DatasetEvaluators组合起来。对于自有数据集官方建议直接在脚本里手动创建评估器绕开这段 if-else。DefaultTrainer本身detectron2/engine/defaults.py封装了标准工作流按固定顺序构造 model → optimizer → data_loader注册IterationTimer、LRScheduler、PreciseBN、PeriodicCheckpointer、EvalHook、PeriodicWriter等默认 hooks并实现auto_scale_workers——当实际 GPU 数与配置中的SOLVER.REFERENCE_WORLD_SIZE不一致时自动按比例缩放IMS_PER_BATCH、BASE_LR、MAX_ITER、WARMUP_ITERS、STEPS等超参这也是官方默认配置能无缝适配不同卡数的机制之一。plain_train_net.py手写训练循环的极简魔改版tools/plain_train_net.py 与train_net.py功能对齐同样能训练所有内置配置但不依赖Trainer类而是把训练循环原原本本写在do_train里。文件头注释明确了两者的取舍它支持的默认特性更少但抽象层级也更低因此对想加自定义逻辑的黑客更友好。训练循环源码拆解do_traintools/plain_train_net.py完整展示了 detectron2 一次迭代的核心五步loss_dict model(data) # 1. 前向得到各损失 losses sum(loss_dict.values()) loss_dict_reduced {k: v.item() for k, v in comm.reduce_dict(loss_dict).items()} optimizer.zero_grad() # 2. 清梯度 losses.backward() # 3. 反传 optimizer.step() # 4. 更新参数 scheduler.step() # 5. 学习率调度其余骨架包括DetectionCheckpointerPeriodicCheckpointer管理断点通过checkpointer.resume_or_load(cfg.MODEL.WEIGHTS, resumeresume)返回的iteration决定start_iterdefault_writers注册CommonMetricPrinter、JSONWriter、TensorboardXWriter三个事件写入器按cfg.TEST.EVAL_PERIOD周期性调用do_test做中间评估EventStorage统一记录 loss、lr 等标量指标。do_testtools/plain_train_net.py则遍历cfg.DATASETS.TEST中的每个数据集用build_detection_test_loader建加载器、inference_on_dataset跑评估并把结果以 CSV 格式打印。与 train_net.py 的取舍对比维度train_net.pyplain_train_net.py训练主体DefaultTrainerhooks 机制手写for循环精确计时accurate timing支持不支持注释明确说明Precise BN支持不支持中间评估结果写入 EventStorage支持不支持自定义逻辑侵入点重写 Trainer 方法直接在循环里改适用人群标准工作流使用者研究者、教学演示、深度魔改官方在DefaultTrainer的文档注释里也给出同样的建议路径新研究项目优先尝试重写DefaultTrainer方法其次用只做最简 SGD 的SimpleTrainer加 hooks最后才参考plain_train_net.py自写循环。benchmark.py训练 / 推理 / 数据加载速度基准tools/benchmark.py 的用途是对给定配置基准测试训练速度、推理速度或数据加载速度。注意该脚本额外依赖psutil用于内存监控运行前需pip install psutil。用法与三种任务python benchmark.py --config-file config.yaml --task train/eval/data [optional DDP flags]--task是必选参数tools/benchmark.py可选值实际上有四个--task train测训练速度。内部将DATALOADER.NUM_WORKERS强制改为 2预取 100 个 batch 构造无限迭代的 dummy 数据以AMPTrainer若SOLVER.AMP.ENABLED或SimpleTrainer跑 400 步期间通过TorchProfiler保存 TensorBoard 性能分析。文件注释特别提醒训练速度并不代表最终精度R-CNN 类模型的训练开销随数据内容与模型质量变化--task eval测单卡推理速度。脚本断言--num-gpus 1 --num-machines 1强制NUM_WORKERS0预取 100 个 batch 后先跑 5 次 warmup再计时 300 次前向输出多少 iter 耗时多少秒--task data数据加载基准。用DataLoaderBenchmark先跑一轮 250 iter 10 warmup 的分布式基准再追加 10 轮 250 iter同时通过RAM_msg()打印每轮的 RAM 占用--task data_advanced数据加载深度剖析。在主进程上依次执行benchmark_dataset、benchmark_mapper、benchmark_workers、benchmark_IPC四类细粒度测试多卡时还会执行两轮benchmark_distributed以观察卡间差异。底层实现DataLoaderBenchmarkdata任务的核心是 detectron2/data/benchmark.py 中的DataLoaderBenchmark类它把一个标准数据加载流水线拆成四个可单独计时的环节benchmark_dataset只从DatasetFromList中取原始样本不含 mapper测数据本身读取耗时benchmark_mapper单进程内完成取样本 mapper 预处理测单进程 mapper 速度benchmark_workers把num_workers分别设为 0、1 和配置值测多进程 DataLoader 的真实吞吐benchmark_IPC用_EmptyMapDataset让每个 worker 只返回[0]剔除进程间通信IPC开销——PyTorch 多进程 IPC 只对张量做了优化大的 numpy 数组或其他数据结构可能带来显著 IPC 开销这一项用于量化该开销benchmark_distributed在每个分布式 worker 上分别计时并汇总所有 GPU 的结果同时打印 DataLoader 启动时间首个 iter。计时统一走iter_benchmark带 warmup 与max_time_seconds上限输出格式为avgX.X it/s加 p1/p5/p95/p99 百分位耗时。benchmark.py还支持 YAML 与 Python LazyConfig 两种配置对.py配置直接把cfg.dataloader.train的_target_替换为DataLoaderBenchmark后instantiate。analyze_model.pyFLOPs、参数量与激活量分析tools/analyze_model.py 用于量化模型的计算开销与存储规模运行python analyze_model.py --help可查看完整用法脚本的 epilog 里还内置了两个示例。四种分析任务--tasks为必选参数可同时传入多个空格分隔--tasks parameter只统计参数量无需数据和权重输出按模块深度为 5 的parameter_count_table--tasks flop统计 FLOPs。FLOPs 与输入数据相关需要加载数据与权重--tasks activation统计激活量单位百万同样依赖数据与权重--tasks structure直接打印模型结构str(model)。配套参数-n/--num-inputs默认 100控制用于统计的输入样本数。脚本要求--num-gpus 1assert args.num_gpus 1因为单卡即可完成静态分析。官方示例# 只统计参数量 ./analyze_model.py --tasks parameter \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml # FLOPs 依赖输入与权重需要指定权重 ./analyze_model.py --num-inputs 100 --tasks flop \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \ MODEL.WEIGHTS /path/to/model.pkl源码级原理分析逻辑由 detectron2/utils/analysis.py 支撑FlopCountAnalysis继承自 fvcore 的实现并通过TracingAdapter把 detectron2 的list[dict]输入适配为可 trace 的张量输入定义了一个_IGNORED_OPS集合约 20 个算子把 add、mul、sigmoid、softmax、batch_norm、max_pool2d、NMS 等元素级/归约类操作排除在统计之外避免噪音脚本对每个输入样本统计后做Counter累加最终输出按算子类型的平均 GFlops与总 GFlops 的均值 ± 标准差do_flop的注释提醒检测模型的 FLOPs 通常依赖输入内容box/mask head 的开销随 proposal 数与检出目标数变化因此单一样本统计未必准确官方建议对多个输入取平均——这正是--num-inputs参数存在的意义。visualize_json_results.py可视化 COCO / LVIS 评测结果tools/visualize_json_results.py 用于把COCOEvaluator或LVISEvaluator导出的 JSON 预测结果可视化成图片。用法python visualize_json_results.py --input x.json --output dir/ --dataset coco_2017_val参数说明对应脚本main()中的 argparse 定义--input必填模型产出的 JSON 文件路径--output必填输出目录不存在会自动创建--dataset数据集名称默认coco_2017_val--conf-threshold置信度阈值默认 0.5低于该值的预测会被过滤。使用前提是--dataset必须是已注册的内置数据集如coco_2017_val因为脚本依赖DatasetCatalog获取图像路径、MetadataCatalog获取类别元数据。README 明确指出如果使用非内置数据集就需要自己写脚本或修改本脚本。实现细节读取 JSON 后按image_id分组pred_by_imagecreate_instancestools/visualize_json_results.py把预测记录转成Instances按conf_threshold过滤分数将bbox从 COCO 的XYWH_ABS格式转换为XYXY_ABS并做类别 id 映射类别映射有两个分支COCO 用metadata.thing_dataset_id_to_contiguous_idLVIS 结果格式与 COCO 相同但映射规则不同采用ds_id - 1因为 LVIS 的 category id 从 1 开始其他数据集直接抛ValueError输出图像为左右拼接左半是draw_instance_predictions绘制的预测结果右半是draw_dataset_dict绘制的 GT 标注便于直接对比。visualize_data.py可视化标注数据与增强数据tools/visualize_data.py 用于可视化两种数据形态原始标注GT与经过预处理的训练数据DataLoader 输出。用法python visualize_data.py --config-file config.yaml --source annotation/dataloader --output-dir dir/ [--show]参数说明--source必填二选一。annotation可视化数据集原始标注dataloader可视化经过 mapper 预处理/增强后的实际训练数据--config-file配置文件路径--source annotation时非必需因为可直接读cfg.DATASETS.TRAIN对应的注册数据集--output-dir输出目录默认./--show是否用 OpenCV 窗口即时显示而不是存盘末尾opts与训练脚本相同的PATH.KEY VALUE配置覆盖。两种数据源的行为差异--source dataloader通过build_detection_train_loader(cfg)构建训练 DataLoader逐 batch 取出张量permute(1,2,0)转回 HWC、convert_image_to_rgb按cfg.INPUT.FORMAT转换色彩空间再用Visualizer.overlay_instances把gt_boxes、gt_masks、gt_keypoints叠加到图上。注意 README 的明确提示dataloader 是无限迭代器脚本不会自行终止需要用户手动中断CtrlC——这是验证数据增强效果的常用手段--source annotation直接读取DatasetCatalog.get(k)的原始 dict 列表若cfg.MODEL.KEYPOINT_ON还会先调用filter_images_with_few_keypoints(dicts, 1)过滤掉关键点过少的图片然后Visualizer.draw_dataset_dict绘制 GT 并逐张保存。组合使用一套完整的研究工作流综合以上六个脚本可以串起一条完整的 detectron2 研发流水线数据核查用visualize_data.py --source annotation检查标注质量用--source dataloader目检增强管线训练标准场景用 train_net.py参考 GETTING_STARTED.md 与 configs 内置配置研究型改动则复制 plain_train_net.py 自写循环或按 tools/lazyconfig_train_net.py 的模式改用 Python LazyConfig性能体检benchmark.py --task data_advanced定位数据加载瓶颈--task train/eval估算训练与推理速度analyze_model.py --tasks flop activation parameter摸清模型计算量与规模结果审查评估结束后用visualize_json_results.py把 JSON 结果与 GT 并排可视化直观发现漏检、误检与分割质量问题。如果这些内置脚本满足不了需求官方在 GETTING_STARTED.md 和 tools/README.md 中给出的最终建议是一致的把 detectron2 当作库参考这些脚本自行编写符合项目数据与逻辑的训练、评估与可视化代码——这六个脚本就是最好的起步模板。【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考