Detectron2 内置演示工具 demo.py 实战指南用预训练模型跑通目标检测、实例分割与全景分割推理【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2本指南聚焦 Detectron2 仓库提供的命令行演示工具demo.pydemo/README.md介绍如何基于 Model Zoo 预训练权重对图片、视频与摄像头实时画面运行推理并正确理解--config-file、--opts、MODEL.WEIGHTS等关键参数的配合逻辑。读完本文后你将能够在无需训练任何模型的前提下一条命令完成目标检测、实例分割、关键点检测与全景分割的可视化输出并具备基于内置 APIDefaultPredictor、VisualizationDemo编写自定义推理脚本的能力。demo.py 是什么一个面向内置配置的命令行推理工具在 Detectron2 的源码树中demo/README.md 用一句话定义了该目录的定位Detectron2 提供一个命令行工具用来对内置builtin配置文件运行简单演示demo其具体用法在 GETTING_STARTED.md 中有完整说明。也就是说demo目录承载的是零门槛体验 Detectron2 推理能力的入口而非训练代码。该目录下仅包含两个核心 Python 文件职责划分非常清晰文件职责demo/demo.py命令行入口解析用户参数、组装配置、加载模型并处理图片/视频/摄像头三种输入源的循环与可视化展示demo/predictor.py推理与可视化的封装层定义VisualizationDemo类内部再调用DefaultPredictor/AsyncPredictor与VideoVisualizer协作完成逐帧绘制demo.py的能力并不局限于某一类任务——由于它直接复用 detectron2 内置的 Model Zoo 配置文件凡是 Model Zoo 里提供的 Mask R-CNN实例分割、Faster R-CNN目标检测、RetinaNet密集检测、Keypoint R-CNN关键点、Panoptic FPN全景分割等模型都可以用它一键跑起来。下文将按准备 → 命令 → 参数 → 原理的路径逐步展开。运行前的准备环境与预训练模型在动手前请确认以下几点detectron2 已正确安装且 Python 环境中包含 OpenCVcv2、tqdm、numpy等依赖。demo.py顶部即导入了cv2与tqdmdemo/demo.py缺失会导致直接报错。选择一个 Model Zoo 模型与其配置文件。Model Zoo 全量清单见 MODEL_ZOO.md配置目录则位于仓库根的 configs 下按任务域分目录组织例如实例分割configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml目标检测configs/COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml关键点检测configs/COCO-Keypoints/keypoint_rcnn_R_50_FPN_3x.yaml全景分割configs/COCO-PanopticSegmentation/panoptic_fpn_R_50_3x.yaml理解为什么必须显式指定MODEL.WEIGHTS仓库内置的 yaml 是为训练设计的它们通常只把MODEL.WEIGHTS指向 ImageNet 预训练主干或留空因此要直接用预训练权重做推理需要把该字段覆盖为 Model Zoo 的权重。这正是 GETTING_STARTED.md 强调的The configs are made for training, therefore we need to specify MODEL.WEIGHTS to a model from model zoo for evaluation.第一条推理命令对单张图片运行 Mask R-CNN从仓库根目录进入demo子目录后执行示例参考 GETTING_STARTED.md 的 Inference Demo 小节cd demo/ python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --input input1.jpg input2.jpg \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl命令的核心要素拆解如下--config-file指向要演示的模型配置。注意命令中的路径../configs/...是相对于demo/目录的写法若直接在仓库根目录运行等价写法是python demo/demo.py --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml。--input空格分隔的多张图片也支持单个 glob 通配符如directory/*.jpg。--opts MODEL.WEIGHTS detectron2://...以KEY VALUE的形式覆盖配置项这里把权重指向 Model Zoo 预训练模型。detectron2://前缀由 detectron2/utils/file_io.py 定义会被统一文件访问层解析成实际可下载的远程地址后自动拉取缓存。该命令会逐张图片执行推理并在OpenCV 窗口中弹出可视化结果窗口名为COCO detections定义于 demo/demo.py按Esc键退出代码中cv2.waitKey(0) 27即监听 ESC。在屏幕显示与保存到文件之间切换demo 的输出行为由--output参数控制demo/demo.py不传--output结果实时显示在 OpenCV 窗口--output指向一个已存在的目录每张输入图按os.path.basename命名保存到该目录--output指向一个文件路径此时要求--input只能有一个输入源码assert len(args.input) 1结果保存为该单文件配合--video-input使用时--output为输出视频文件路径若指向目录则在目录内生成与输入同名的视频。命令行参数全景解读全部参数定义集中在 demo/demo.py 的get_parser()中汇总如下参数默认值说明--config-fileconfigs/quick_schedules/mask_rcnn_R_50_FPN_inference_acc_test.yaml内置模型配置路径。默认值是一个推理精度回归测试用的快速配置稍后详述--input无一个或多个图片路径或单个 glob 模式nargs--webcamFalse切换到摄像头实时输入开关型参数--video-input无视频文件路径--output无可视化结果保存路径文件或目录缺省则在 OpenCV 窗口弹出--confidence-threshold0.5实例预测置信度下限低于该分数的框/掩膜将被滤除--opts[]以KEY VALUE对覆盖任意配置项nargsargparse.REMAINDER使其捕获其后所有参数值得注意--confidence-threshold的默认值0.5会显式覆盖配置中的阈值。setup_cfg()demo/demo.py依次写入三个不同的阈值键以兼容三类模型架构cfg.MODEL.RETINANET.SCORE_THRESH_TEST args.confidence_threshold cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST args.confidence_threshold cfg.MODEL.PANOPTIC_FPN.COMBINE.INSTANCES_CONFIDENCE_THRESH args.confidence_threshold对照 detectron2/config/defaults.py 可看到它们各自的训练期默认值其实更低MODEL.ROI_HEADS.SCORE_THRESH_TEST与MODEL.RETINANET.SCORE_THRESH_TEST默认为0.05defaults.py 与 defaults.pyPANOPTIC_FPN.COMBINE.INSTANCES_CONFIDENCE_THRESH默认为0.5defaults.py。原因是训练/评测阶段需要低阈值保留更多候选以计算召回率而 demo 面向展示0.5更干净直观若想看到更多低置信度目标把它调低即可。三种输入模式图片、视频与摄像头视频文件python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --video-input video.mp4 \ --output output_video \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl处理视频时代码会先探测输出编码器可用性demo/demo.py通过实际写一段临时视频测试x264编解码器若不可用则回退到mp4v.mp4并打印警告。逐帧推理结果通过tqdm展示进度条进度总数取cv2.CAP_PROP_FRAME_COUNT无--output时逐帧弹窗播放ESC 退出。摄像头实时流python demo.py --config-file ../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \ --webcam \ --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl摄像头模式直接打开cv2.VideoCapture(0)默认索引 0 对应的设备。demo.py 在源码层面对该模式有两条强约束--webcam与--input互斥assert args.input is None--webcam暂不支持--outputassert args.output is None, output not yet supported with --webcam!。这点与 GETTING_STARTED.md 中对--output的笼统描述略有出入以源码实际行为为准。纯 CPU 环境若机器无 GPU或希望强制 CPU 推理只需在--opts后追加MODEL.DEVICE cpupython demo.py --config-file ... --input in.jpg \ --opts MODEL.WEIGHTS detectron2://... MODEL.DEVICE cpu这一用法在 GETTING_STARTED.md 中被直接列为常见操作。理解默认配置quick_schedules 下的推理回归配置不带--config-file直接运行 demo.py 时默认加载 configs/quick_schedules/mask_rcnn_R_50_FPN_inference_acc_test.yaml。该文件是一个服务于 CI 的轻量配置其结构恰好演示了 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], ...] AUG: ENABLED: True MIN_SIZES: (700, 800)_BASE_指向 COCO 实例分割的标准 3x 训练配置然后只覆盖三项权重、仅含 100 张验证图的测试集、期望的精度回归阈值。对 demo 而言最有价值的启示是——demo 的权重路径与 detectron2/model_zoo/model_zoo.py 中的官方模型清单完全一致。该模块内部维护了一张CONFIG_PATH_TO_URL_SUFFIX映射表model_zoo.py把configs/下的相对路径如COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x映射到dl.fbaipublicfiles.com的下载后缀再由get_checkpoint_url()model_zoo.py拼出完整 URL。因此如果你想让模型代码自动获取正确权重可写from detectron2 import model_zoo url model_zoo.get_checkpoint_url(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml) # 等价于 detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl若传入的配置不在官方清单中get_checkpoint_url会抛出RuntimeError(Pretrained model for ... is not available!)这也是随便挑一个配置但拿不到权重时最常见的报错来源。框架内核剖析从 demo.py 到 DefaultPredictor 的调用链要写出比 demo.py 更灵活的自定义推理脚本理解其背后的调用链至关重要。整条链路为demo.py main() └─ setup_cfg() # 合并 yaml 命令行 opts 阈值覆盖cfg.freeze() └─ VisualizationDemo(cfg) # predictor.py └─ DefaultPredictor(cfg) # detectron2/engine/defaults.py └─ Visualizer / VideoVisualizer① 配置组装setup_cfg()流程是get_cfg()初始化默认配置 →merge_from_file(config_file)读入 yaml →merge_from_list(opts)覆盖命令行 KV → 设置三类置信度阈值 →cfg.freeze()冻结。冻结后任何对配置的写操作都会抛异常避免推理阶段意外修改配置。② 推理引擎DefaultPredictordetectron2/engine/defaults.py 中的DefaultPredictor是专为单设备、单图、简单演示设计的端到端预测器其 docstring 明确指出它自动完成了四件事从cfg.MODEL.WEIGHTS加载检查点始终接受BGR顺序的输入图并按cfg.INPUT.FORMAT默认BGR见 defaults.py决定是否翻转通道按cfg.INPUT.MIN_SIZE_TEST默认 800与cfg.INPUT.MAX_SIZE_TEST默认 1333执行ResizeShortestEdge缩放单图进、单图出内部包成 batch 送入self.model([inputs])[0]。DefaultPredictor.__call__在torch.no_grad()下执行预处理与模型前向返回一个预测字典predictions其中可能包含instances、panoptic_seg、sem_seg等键——具体含哪些键取决于模型类型。③ 可视化VisualizationDemodemo/predictor.py 的VisualizationDemo负责把预测字典翻译成带标注的图片。其构造参数包括cfg冻结后的配置对象instance_mode标注的色彩模式默认ColorMode.IMAGE用原图颜色还可选择SEGMENTATION等parallel是否把模型推理放到独立进程中与可视化并行——对视频渲染尤其有用因为 OpenCV 绘图本身较慢。run_on_image()的核心逻辑predictor.py展示了三种预测类型的绘制分支if panoptic_seg in predictions: # 全景分割 → draw_panoptic_seg_predictions ... else: if sem_seg in predictions: # 语义分割 → draw_sem_seg ... if instances in predictions: # 实例级 → draw_instance_predictions ...模型输出都在 GPU 上可视化前统一.to(self.cpu_device)搬回 CPU。这里可以看到 demo 天然支持三族模型RetinaNet/Faster R-CNN/Mask R-CNN/Keypoint R-CNN 走instances分支语义分割模型走sem_seg分支Panoptic FPN 走panoptic_seg分支。run_on_video()则逐帧用VideoVisualizer绘制并yieldBGR 帧。其并行模式复用了一个AsyncPredictorpredictor.py它为每张 GPU 各 fork 一个_PredictWorker子进程通过mp.Queue流水线化地喂图、取结果并借助bisect按序号缓存乱序结果保证帧序正确。parallelTrue时 demo.py 可跨多 GPU 分摊视频推理负载。④ 把这一切封装进你的脚本理解了调用链后你完全可以用最小代码复刻 demo 的推理能力这也正是DefaultPredictor官方 docstring 给出的示例用法from detectron2.config import get_cfg from detectron2.engine import DefaultPredictor import cv2 cfg get_cfg() cfg.merge_from_file(configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml) cfg.MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 # 展示用高阈值 cfg.freeze() predictor DefaultPredictor(cfg) image cv2.imread(input.jpg) # 注意BGR 顺序 outputs predictor(image) # 返回 predictions 字典如需带可视化则直接实例化VisualizationDemofrom detectron2.demo.predictor import VisualizationDemo调用demo.run_on_image(img)拿到(predictions, vis_output)其中vis_output是VisImage可通过.get_image()取回 numpy 图像、.save(path)写盘。让 demo 支持更多项目配置demo 的配置文件解析基于标准的get_cfg()默认命名空间。像 Panoptic-DeepLab见 projects/Panoptic-DeepLab/这类需要向配置对象注册自定义字段的项目必须先调用其配置注册函数否则merge_from_file会因遇到未知键而报错。demo.py 在setup_cfg()中为此预留了注释位demo/demo.py# To use demo for Panoptic-DeepLab, please uncomment the following two lines. # from detectron2.projects.panoptic_deeplab import add_panoptic_deeplab_config # noqa # add_panoptic_deeplab_config(cfg)即取消注释、让add_panoptic_deeplab_config(cfg)在merge_from_file之前把该项目专属键注入cfg随后即可用 projects/Panoptic-DeepLab/configs/ 下的配置驱动 demo。这是把 demo 扩展到仓库内各类 projects 的通用模式。演示流程中的实测细节与常见坑结合源码梳理运行过程中有若干容易被忽略的细节日志信息demo 每次对单张图推理完成后会用 logger 打印耗时与检测实例数如detected 12 instances格式在 demo/demo.py耗时信息可直接用于粗略估计推理速度。输入图读取格式--input图片经 detectron2/data/detection_utils.py 的read_image(path, formatBGR)读取与评测流程保持一致demo.py 注释use PIL, to be consistent with evaluation而摄像头/视频帧本身就是 OpenCV 的 BGR 格式。可视化展示时再统一[:, :, ::-1]翻转成 RGB 供 Matplotlib 绘制。glob 解析--input只有单个参数时代码会尝试glob.glob(os.path.expanduser(...))展开通配符若展开结果为空则直接断言失败并提示The input path(s) was not founddemo/demo.py。因此输入路径写错时你会第一时间看到这个错误。进程启动方式main()开头强制mp.set_start_method(spawn, forceTrue)这是为兼容AsyncPredictor的多进程推理在交互式环境如 notebook 内直接import后调用 main可能受限最好以独立脚本方式运行。ESC 交互约定图片模式按一次 ESC 即跳过后续输入视频/摄像头模式按 ESC 立即终止循环。若想看下一张图而非退出需改动cv2.waitKey逻辑。命令行训练与评测demo 之外的同源配套demo/README.md 将使用说明整体指向 GETTING_STARTED.md后者在 Inference Demo 之外还介绍了与 demo 共享同一批配置文件的两个训练入口可作为对比理解配置继承机制的参考tools/train_net.py完整功能的默认训练脚本需先按 datasets/README.md 准备数据集tools/plain_train_net.py功能更少、抽象更薄便于改造自定义训练逻辑。例如8 卡训练 Mask R-CNN 的标准命令为见 GETTING_STARTED.md 的 Training Evaluation 小节cd tools/ ./train_net.py --num-gpus 8 \ --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 MODEL.WEIGHTS /path/to/checkpoint则用于只评测不训练。这些命令与 demo 共用configs/下的同一批 yaml佐证了 demo 中训练配置 显式权重覆盖这一设计为何必要——训练配置面向 8 卡与多 epoch而 demo 仅需其中定义好的网络结构部分。小结demo.py是打通配置 → 权重 → 推理 → 可视化全链路的极简入口通过--config-file选定内置架构、--opts MODEL.WEIGHTS挂载 Model Zoo 预训练权重即可对图片、视频、摄像头实时运行包括目标检测、实例/语义/全景分割在内的多种视觉任务。进一步地VisualizationDemo、DefaultPredictor的分层设计让这套能力可以直接沉淀为自定义推理代码。建议以python demo.py -h查看最新参数帮助并结合 demo/demo.py、demo/predictor.py、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），仅供参考