Detectron2 上手指南用内置命令行工具完成推理演示、模型训练与评估【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2本文基于 Detectron2 仓库的入门文档 docs/tutorials/getting_started.md 编写系统讲解其内置命令行工具的三大用途用 demo/demo.py 对预训练模型做推理可视化、用 tools/train_net.py 与 tools/plain_train_net.py 完成模型训练与评估以及如何把 Detectron2 作为库集成进自己的项目。读完后你可以直接复现“下载模型权重 → 跑一张图片推理 → 单/多卡训练 → 评估 checkpoint”的完整闭环并能定位到每个命令行参数背后的源码实现。一、三条上手路径总览Detectron2 面向使用者的入口分为三类推理演示demo/demo.py 提供命令行工具可对内置配置对应的模型跑图片、视频、摄像头推理并在 OpenCV 窗口中可视化检测结果训练与评估tools/train_net.py 与 tools/plain_train_net.py 两个脚本可用于训练仓库 configs/ 目录下提供的所有配置也可作为编写自定义训练脚本的参考API 编程在自己的 Python 代码中以库的方式调用 Detectron2 的推理与训练 API更多“在 Detectron2 之上搭建项目”的方式可参考仓库内置的项目示例目录 projects/含 DensePose、DeepLab、TridentNet、ViTDet 等子项目的配置与代码。二、训练前的数据集准备训练与评估都依赖内置数据集。按照 datasets/README.md 的说明数据集被假定存放在环境变量DETECTRON2_DATASETS指定的目录中该目录下应有coco/、lvis/、cityscapes/、VOC20{07,12}/等子目录设置方式为export DETECTRON2_DATASETS/path/to/datasets若不设置默认为当前工作目录下的./datasets以 COCO 为例期望的目录结构为coco/ annotations/ instances_{train,val}2017.json person_keypoints_{train,val}2017.json {train,val}2017/ # 对应 json 中提到的图片文件Panoptic-FPN、LVIS、Cityscapes、Pascal VOC、ADE20k 等数据集的期望结构与对应的准备脚本如 datasets/prepare_panoptic_fpn.py、datasets/prepare_cocofied_lvis.py、datasets/prepare_ade20k_sem_seg.py均在 datasets/README.md 中有完整说明训练前应先阅读该文档。三、用预训练模型做推理演示3.1 基本命令从 MODEL_ZOO.md 中挑选一个模型及其配置文件例如实例分割配置 configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml然后运行cd demo/ python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input1.jpg input2.jpg \ [--other-options] --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl这条命令会执行推理并在 OpenCV 窗口中展示可视化结果。需要特别理解的一点是配置文件本身是为训练设计的其中的MODEL.WEIGHTS指向 ImageNet 预训练权重而非最终检测权重可对照 mask_rcnn_R_50_FPN_3x.yaml 中WEIGHTS: detectron2://ImageNetPretrained/MSRA/R-50.pkl因此评估/推理时必须通过--opts MODEL.WEIGHTS model zoo 中的权重 URI显式覆盖为 model zoo 中训练好的模型。3.2 常用命令行参数从 demo/demo.py 的参数定义demo/demo.py#L39-L73可以确认完整参数列表如下参数作用源码依据--config-file配置文件路径默认指向configs/quick_schedules/mask_rcnn_R_50_FPN_inference_acc_test.yamldemo/demo.py#L41-L46--input一张或多张图片或单个 glob 模式如directory/*.jpgdemo/demo.py#L49-L54--webcam从摄像头读取输入与--input互斥demo/demo.py#L47--video-input视频文件路径demo/demo.py#L48--output图片保存到目录单图则存文件视频/摄像头输出存为视频文件demo/demo.py#L55-L59--confidence-threshold实例预测的最低显示分数默认 0.5demo/demo.py#L61-L66--opts以KEY VALUE键值对方式覆盖任意配置项demo/demo.py#L67-L72几个常见用法摄像头推理把--input files换成--webcam视频推理把--input files换成--video-input video.mp4CPU 推理在--opts之后追加MODEL.DEVICE cpu保存输出图片结果用--output指定目录或单图文件名摄像头/视频结果存为文件。3.3 参数如何生效源码级解读demo/demo.py#L23-L36 中的setup_cfg展示了配置合并顺序先get_cfg()取默认配置再merge_from_file合并 YAML 文件最后merge_from_list(args.opts)应用命令行覆盖因此--opts MODEL.WEIGHTS ...的优先级最高。同时--confidence-threshold会被写入三处测试阈值MODEL.RETINANET.SCORE_THRESH_TEST、MODEL.ROI_HEADS.SCORE_THRESH_TEST与MODEL.PANOPTIC_FPN.COMBINE.INSTANCES_CONFIDENCE_THRESH分别对应单阶段检测器、R-CNN 系列与全景分割模型这解释了为何一个参数能通吃多种内置模型。图像入口侧--input支持 glob当只传入一个参数时会执行glob.glob展开demo/demo.py#L104-L107并断言至少匹配到一个文件每张图经read_image(path, formatBGR)读取与评估流程保持 BGR 一致再交给VisualizationDemo处理。可视化与预测的封装在 demo/predictor.py 中VisualizationDemo.__init__demo/predictor.py#L16-L35内部使用 detectron2/engine/defaults.py 中的DefaultPredictor后者会自动加载cfg.MODEL.WEIGHTS的 checkpoint、按cfg.INPUT.FORMAT做颜色转换、按cfg.INPUT.{MIN,MAX}_SIZE_TEST做缩放run_on_image根据模型输出字典中是否存在panoptic_seg、sem_seg、instances键分别调用Visualizer对应的绘制方法因此同一 demo 工具能渲染全景分割、语义分割与实例/关键点三类预测run_on_video对摄像头与视频文件逐帧取图并绘制--output在视频分支中会优先尝试 x264.mkv不可用时回退 mp4v.mp4见 demo/demo.py#L149-L190。四、命令行训练与评估4.1 两个训练脚本的定位仓库提供了 tools/plain_train_net.py 与 tools/train_net.py 两个入口二者都“为训练 detectron2 提供的所有配置而设计”都可以作为编写自己训练脚本的参考。区别依据两个脚本文件头的注释与实现tools/train_net.py 基于DefaultTrainertools/train_net.py#L82-L150支持更完整的默认特性如精确计时、精确 BN、测试时增强TTA通过GeneralizedRCNNWithTTA包装等tools/plain_train_net.py 支持的特性更少但抽象也更少——其do_train就是一个显式的小训练循环tools/plain_train_net.py#L113-L169更便于插入自定义逻辑官方注释也明确建议“研究项目若只需单一 evaluator可参考此文件”。4.2 多卡训练配置文件默认按 8 卡训练设计直接以 8 卡运行cd tools/ ./train_net.py --num-gpus 8 \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml4.3 单卡训练按线性缩放调整超参从 8 卡降到 1 卡时需要相应调整超参可按学习率线性缩放的经验做法例如./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其中SOLVER.IMS_PER_BATCH 2、SOLVER.BASE_LR 0.0025属于命令末尾的opts直接覆盖配置项多机多卡场景还可以用--num-machines与--machine-rank扩展。4.4 评估已有 checkpoint./train_net.py \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \ --eval-only MODEL.WEIGHTS /path/to/checkpoint_file--eval-only分支在 tools/train_net.py#L127-L137 中构建模型后用DetectionCheckpointer的resume_or_load加载cfg.MODEL.WEIGHTS然后执行Trainer.test若配置中TEST.AUG.ENABLED为真还会额外跑一次 TTA 评估并在主进程上调用verify_results校验结果。4.5 通用命令行参数来源两个训练脚本共用 detectron2/engine/defaults.py 中的default_argument_parserdetectron2/engine/defaults.py#L82-L142因此除demo.py之外的训练脚本支持以下参数参数说明--config-file配置文件路径--num-gpus每台机器的 GPU 数默认 1--num-machines/--machine-rank多机训练的机器总数与本机序号--dist-urlPyTorch 分布式初始化 URL默认按 uid 哈希生成确定性端口--resume从OUTPUT_DIR中的 checkpoint 断点续训--eval-only只执行评估opts位置参数空格分隔的PATH.KEY VALUE对Yacs 配置或path.keyvalueLazyConfig启动流程上两个脚本的invoke_main都是先default_argument_parser().parse_args()再调用launch(main, args.num_gpus, ...)tools/plain_train_net.py#L207-L217完成分布式环境初始化。setup阶段除合并配置外还会调用default_setupdetectron2/engine/defaults.py#L198-L258在主进程把完整配置备份到OUTPUT_DIR/config.yaml、记录环境信息与命令行参数、按SEED设置各进程随机种子。评估器方面两个脚本都通过MetadataCatalog中数据集的evaluator_type元数据选择 evaluatortools/plain_train_net.py#L56-L93COCO 类数据集对应COCOEvaluator全景分割额外追加COCOPanopticEvaluator语义分割用SemSegEvaluatorLVIS 用LVISEvaluatorCityscapes 与 Pascal VOC 各有专用 evaluator——这意味着同一个训练命令能适配 configs/ 下不同任务目录COCO 检测/分割/关键点、LVIS、Cityscapes 等的配置。五、把 Detectron2 作为库使用如果不想受限于命令行工具可以把 Detectron2 当库直接写代码典型的两类任务是用已有模型做推理、以及在自定义数据集上训练内置模型。从 demo/predictor.py 与 tools/plain_train_net.py 的源码可以看出库的核心 API 面detectron2.config.get_cfg加载配置、detectron2.modeling.build_model构建模型、detectron2.checkpoint.DetectionCheckpointer管理权重、detectron2.data下的build_detection_train_loader/build_detection_test_loader构建数据、detectron2.solver构建优化器与学习率调度、detectron2.evaluation提供inference_on_dataset等评估入口。仓库中 projects/ 下的每个子项目如 projects/DensePose、projects/TridentNet、projects/ViTDet都展示了“新增配置项 自定义模型/数据模块 独立train_net.py”的项目组织范式可作为扩展工程结构的参考。六、关键文件索引文件用途docs/tutorials/getting_started.md本文对应的入门文档原文demo/demo.py、demo/predictor.py推理演示命令行工具与可视化封装tools/train_net.py、tools/plain_train_net.py训练/评估入口脚本datasets/README.md内置数据集目录结构与准备方法MODEL_ZOO.md预训练模型与对应配置清单configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml文中示例配置detectron2/engine/defaults.py通用参数解析、训练器与预测器实现【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Detectron2 上手指南用内置命令行工具完成推理演示、模型训练与评估【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2本文基于 Detectron2 仓库的入门文档 docs/tutorials/getting_started.md 编写系统讲解其内置命令行工具的三大用途用 demo/demo.py 对预训练模型做推理可视化、用 tools/train_net.py 与 tools/plain_train_net.py 完成模型训练与评估以及如何把 Detectron2 作为库集成进自己的项目。读完后你可以直接复现“下载模型权重 → 跑一张图片推理 → 单/多卡训练 → 评估 checkpoint”的完整闭环并能定位到每个命令行参数背后的源码实现。一、三条上手路径总览Detectron2 面向使用者的入口分为三类推理演示demo/demo.py 提供命令行工具可对内置配置对应的模型跑图片、视频、摄像头推理并在 OpenCV 窗口中可视化检测结果训练与评估tools/train_net.py 与 tools/plain_train_net.py 两个脚本可用于训练仓库 configs/ 目录下提供的所有配置也可作为编写自定义训练脚本的参考API 编程在自己的 Python 代码中以库的方式调用 Detectron2 的推理与训练 API更多“在 Detectron2 之上搭建项目”的方式可参考仓库内置的项目示例目录 projects/含 DensePose、DeepLab、TridentNet、ViTDet 等子项目的配置与代码。二、训练前的数据集准备训练与评估都依赖内置数据集。按照 datasets/README.md 的说明数据集被假定存放在环境变量DETECTRON2_DATASETS指定的目录中该目录下应有coco/、lvis/、cityscapes/、VOC20{07,12}/等子目录设置方式为export DETECTRON2_DATASETS/path/to/datasets若不设置默认为当前工作目录下的./datasets以 COCO 为例期望的目录结构为coco/ annotations/ instances_{train,val}2017.json person_keypoints_{train,val}2017.json {train,val}2017/ # 对应 json 中提到的图片文件Panoptic-FPN、LVIS、Cityscapes、Pascal VOC、ADE20k 等数据集的期望结构与对应的准备脚本如 datasets/prepare_panoptic_fpn.py、datasets/prepare_cocofied_lvis.py、datasets/prepare_ade20k_sem_seg.py均在 datasets/README.md 中有完整说明训练前应先阅读该文档。三、用预训练模型做推理演示3.1 基本命令从 MODEL_ZOO.md 中挑选一个模型及其配置文件例如实例分割配置 configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml然后运行cd demo/ python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input1.jpg input2.jpg \ [--other-options] --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl这条命令会执行推理并在 OpenCV 窗口中展示可视化结果。需要特别理解的一点是配置文件本身是为训练设计的其中的MODEL.WEIGHTS指向 ImageNet 预训练权重而非最终检测权重可对照 mask_rcnn_R_50_FPN_3x.yaml 中WEIGHTS: detectron2://ImageNetPretrained/MSRA/R-50.pkl因此评估/推理时必须通过--opts MODEL.WEIGHTS model zoo 中的权重 URI显式覆盖为 model zoo 中训练好的模型。3.2 常用命令行参数从 demo/demo.py 的参数定义demo/demo.py#L39-L73可以确认完整参数列表如下参数作用源码依据--config-file配置文件路径默认指向configs/quick_schedules/mask_rcnn_R_50_FPN_inference_acc_test.yamldemo/demo.py#L41-L46--input一张或多张图片或单个 glob 模式如directory/*.jpgdemo/demo.py#L49-L54--webcam从摄像头读取输入与--input互斥demo/demo.py#L47--video-input视频文件路径demo/demo.py#L48--output图片保存到目录单图则存文件视频/摄像头输出存为视频文件demo/demo.py#L55-L59--confidence-threshold实例预测的最低显示分数默认 0.5demo/demo.py#L61-L66--opts以KEY VALUE键值对方式覆盖任意配置项demo/demo.py#L67-L72几个常见用法摄像头推理把--input files换成--webcam视频推理把--input files换成--video-input video.mp4CPU 推理在--opts之后追加MODEL.DEVICE cpu保存输出图片结果用--output指定目录或单图文件名摄像头/视频结果存为文件。3.3 参数如何生效源码级解读demo/demo.py#L23-L36 中的setup_cfg展示了配置合并顺序先get_cfg()取默认配置再merge_from_file合并 YAML 文件最后merge_from_list(args.opts)应用命令行覆盖因此--opts MODEL.WEIGHTS ...的优先级最高。同时--confidence-threshold会被写入三处测试阈值MODEL.RETINANET.SCORE_THRESH_TEST、MODEL.ROI_HEADS.SCORE_THRESH_TEST与MODEL.PANOPTIC_FPN.COMBINE.INSTANCES_CONFIDENCE_THRESH分别对应单阶段检测器、R-CNN 系列与全景分割模型这解释了为何一个参数能通吃多种内置模型。图像入口侧--input支持 glob当只传入一个参数时会执行glob.glob展开demo/demo.py#L104-L107并断言至少匹配到一个文件每张图经read_image(path, formatBGR)读取与评估流程保持 BGR 一致再交给VisualizationDemo处理。可视化与预测的封装在 demo/predictor.py 中VisualizationDemo.__init__demo/predictor.py#L16-L35内部使用 detectron2/engine/defaults.py 中的DefaultPredictor后者会自动加载cfg.MODEL.WEIGHTS的 checkpoint、按cfg.INPUT.FORMAT做颜色转换、按cfg.INPUT.{MIN,MAX}_SIZE_TEST做缩放run_on_image根据模型输出字典中是否存在panoptic_seg、sem_seg、instances键分别调用Visualizer对应的绘制方法因此同一 demo 工具能渲染全景分割、语义分割与实例/关键点三类预测run_on_video对摄像头与视频文件逐帧取图并绘制--output在视频分支中会优先尝试 x264.mkv不可用时回退 mp4v.mp4见 demo/demo.py#L149-L190。四、命令行训练与评估4.1 两个训练脚本的定位仓库提供了 tools/plain_train_net.py 与 tools/train_net.py 两个入口二者都“为训练 detectron2 提供的所有配置而设计”都可以作为编写自己训练脚本的参考。区别依据两个脚本文件头的注释与实现tools/train_net.py 基于DefaultTrainertools/train_net.py#L82-L150支持更完整的默认特性如精确计时、精确 BN、测试时增强TTA通过GeneralizedRCNNWithTTA包装等tools/plain_train_net.py 支持的特性更少但抽象也更少——其do_train就是一个显式的小训练循环tools/plain_train_net.py#L113-L169更便于插入自定义逻辑官方注释也明确建议“研究项目若只需单一 evaluator可参考此文件”。4.2 多卡训练配置文件默认按 8 卡训练设计直接以 8 卡运行cd tools/ ./train_net.py --num-gpus 8 \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml4.3 单卡训练按线性缩放调整超参从 8 卡降到 1 卡时需要相应调整超参可按学习率线性缩放的经验做法例如./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其中SOLVER.IMS_PER_BATCH 2、SOLVER.BASE_LR 0.0025属于命令末尾的opts直接覆盖配置项多机多卡场景还可以用--num-machines与--machine-rank扩展。4.4 评估已有 checkpoint./train_net.py \ --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml \ --eval-only MODEL.WEIGHTS /path/to/checkpoint_file--eval-only分支在 tools/train_net.py#L127-L137 中构建模型后用DetectionCheckpointer的resume_or_load加载cfg.MODEL.WEIGHTS然后执行Trainer.test若配置中TEST.AUG.ENABLED为真还会额外跑一次 TTA 评估并在主进程上调用verify_results校验结果。4.5 通用命令行参数来源两个训练脚本共用 detectron2/engine/defaults.py 中的default_argument_parserdetectron2/engine/defaults.py#L82-L142因此除demo.py之外的训练脚本支持以下参数参数说明--config-file配置文件路径--num-gpus每台机器的 GPU 数默认 1--num-machines/--machine-rank多机训练的机器总数与本机序号--dist-urlPyTorch 分布式初始化 URL默认按 uid 哈希生成确定性端口--resume从OUTPUT_DIR中的 checkpoint 断点续训--eval-only只执行评估opts位置参数空格分隔的PATH.KEY VALUE对Yacs 配置或path.keyvalueLazyConfig启动流程上两个脚本的invoke_main都是先default_argument_parser().parse_args()再调用launch(main, args.num_gpus, ...)tools/plain_train_net.py#L207-L217完成分布式环境初始化。setup阶段除合并配置外还会调用default_setupdetectron2/engine/defaults.py#L198-L258在主进程把完整配置备份到OUTPUT_DIR/config.yaml、记录环境信息与命令行参数、按SEED设置各进程随机种子。评估器方面两个脚本都通过MetadataCatalog中数据集的evaluator_type元数据选择 evaluatortools/plain_train_net.py#L56-L93COCO 类数据集对应COCOEvaluator全景分割额外追加COCOPanopticEvaluator语义分割用SemSegEvaluatorLVIS 用LVISEvaluatorCityscapes 与 Pascal VOC 各有专用 evaluator——这意味着同一个训练命令能适配 configs/ 下不同任务目录COCO 检测/分割/关键点、LVIS、Cityscapes 等的配置。五、把 Detectron2 作为库使用如果不想受限于命令行工具可以把 Detectron2 当库直接写代码典型的两类任务是用已有模型做推理、以及在自定义数据集上训练内置模型。从 demo/predictor.py 与 tools/plain_train_net.py 的源码可以看出库的核心 API 面detectron2.config.get_cfg加载配置、detectron2.modeling.build_model构建模型、detectron2.checkpoint.DetectionCheckpointer管理权重、detectron2.data下的build_detection_train_loader/build_detection_test_loader构建数据、detectron2.solver构建优化器与学习率调度、detectron2.evaluation提供inference_on_dataset等评估入口。仓库中 projects/ 下的每个子项目如 projects/DensePose、projects/TridentNet、projects/ViTDet都展示了“新增配置项 自定义模型/数据模块 独立train_net.py”的项目组织范式可作为扩展工程结构的参考。六、关键文件索引文件用途docs/tutorials/getting_started.md本文对应的入门文档原文demo/demo.py、demo/predictor.py推理演示命令行工具与可视化封装tools/train_net.py、tools/plain_train_net.py训练/评估入口脚本datasets/README.md内置数据集目录结构与准备方法MODEL_ZOO.md预训练模型与对应配置清单configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml文中示例配置detectron2/engine/defaults.py通用参数解析、训练器与预测器实现【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
