使用 MMDetection 现有模型进行推理：DetInferencer 高级 API 与五个 Demo 脚本实战指南

使用 MMDetection 现有模型进行推理DetInferencer 高级 API 与五个 Demo 脚本实战指南【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection本篇技术指南以 docs/en/user_guides/inference.md 为核心脉络系统讲解 MMDetection 中用训练好的模型在图像上做目标检测这一核心场景以统一的DetInferencer高级推理接口为主线覆盖模型初始化、设备选择、多种输入形式、结果导出与批量推理并逐一拆解图像、摄像头、视频、GPU 加速视频、大图切片五个开箱即用的 Demo 脚本最后演示 GLIP 多模态文本提示推理与评测流程。读完本文你可以用几行 Python 代码或一条命令行快速完成任意 MMDetection 模型的推理、可视化与结果落盘。前置准备一个检测模型 一份配置文件 一份权重文件在 MMDetection 中模型由两部分共同定义见 配置文档配置文件Configuration File描述模型结构、数据预处理流水线pipeline、评测与可视化配置等通常位于 configs 目录下例如 configs/rtmdet/rtmdet_l_8xb32-300e_coco.py权重文件Checkpoint保存模型训练得到的参数通常以.pth结尾。MMDetection 的 Model Zoo 中提供了大量预训练检测模型对应关系记录在各算法目录的metafile.yml中例如 configs/rtmdet/metafile.yml。官方推荐的入门模型是 RTMDet建议将权重文件下载到仓库根目录下的checkpoints目录中统一管理mkdir -p checkpoints # 将 rtmdet_l_8xb32-300e_coco 的权重下载至 checkpoints 目录以rtmdet_tiny为例configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py 通过继承rtmdet_s配置将主干backbone的deepen_factor设为 0.167、widen_factor设为 0.375并把颈部neck输入通道调整为[96, 192, 384]、输出通道压缩到 96——这是 tiny 版本参数量的主要来源。了解这一点有助于理解不同模型名对应不同配置文件与权重的映射关系。高级推理 APIDetInferencerOpenMMLab 将各库的推理操作统一抽象为Inferencer接口。DetInferencer就是 MMDetection 对目标检测任务的实现与 OpenMMLab 其他库如 MMClassification、MMSegmentation的 Inferencer 保持高度一致的 API 风格学习成本极低。仓库提供了配套的 Jupyter Notebook 演示demo/inference_demo.ipynb。三行代码完成一次推理from mmdet.apis import DetInferencer # 初始化 DetInferencer自动从 Model Zoo 下载并加载权重 inferencer DetInferencer(rtmdet_tiny_8xb32-300e_coco) # 执行推理并在弹窗中展示可视化结果 inferencer(demo/demo.jpg, showTrue)在源码中DetInferencer继承自 MMEngine 的BaseInferencer见 mmdet/apis/det_inferencer.py整个调用链被划分为preprocess - forward - visualize - postprocess四个阶段preprocess将原始输入按测试 pipeline 加工为模型可喂入的数据forward调用model.test_step完成前向visualize调用 Visualizer 绘制结果postprocess把DetDataSample转换为 JSON 可序列化的字典。这一设计使高级 API 在保持简洁的同时也保留了通过**kwargs深入定制每个阶段的能力。注意无 GUI 环境如果运行在无图形界面的服务器上或通过关闭 X11 转发的 SSH 隧道访问showTrue将无法弹出窗口。此时改用out_dir将可视化结果保存为文件即可详见下文结果导出一节。模型初始化初始化 Inferencer 时必须指定模型可选方式共有四种方式一直接传预训练模型名推荐。权重会自动从 Model Zoo 下载并加载inferencer DetInferencer(modelrtmdet_tiny_8xb32-300e_coco)需要列出 MMDetection 支持的全部模型名时使用list_models方法# models 为模型名列表方法内部会自动打印 models DetInferencer.list_models(mmdet)方式二模型名 自定义权重路径/URL。适合想用同名配置加载其他权重如自行微调后的结果的场景inferencer DetInferencer( modelrtmdet_tiny_8xb32-300e_coco, weightspath/to/rtmdet.pth)方式三自定义配置 权重路径。model传入配置文件的路径inferencer DetInferencer( modelpath/to/rtmdet_config.py, weightspath/to/rtmdet.pth)方式四仅传权重文件路径。MMEngine 默认会把配置序列化到权重文件中因此对 MMEngine 训练的权重可以省略modelinferencer DetInferencer(weightspath/to/ddq-detr-4scale_r50.pth)这种方式要求权重内包含可解析的配置字符串否则会报错。目前 MMDetection 模型仓库中只有ddq-detr-4scale_r50系列权重支持此加载方式。另外需要提醒如果只给model传配置文件而不给weights得到的将是随机初始化模型推理结果无实际意义。从源码看mmdet/apis/det_inferencer.py_load_weights_to_model在加载 checkpoint 时会读取meta中的dataset_meta3.x 权重或CLASSES2.x 及更早权重据此设置模型类别信息完全无法获取时则默认使用 COCO 的 80 个类别并给出警告。设备选择每个 Inferencer 实例绑定一个推理设备。默认由 MMEngine 自动选择可用设备也可以在初始化时通过device参数指定# 使用 GPU 1 推理 inferencer DetInferencer( modelrtmdet_tiny_8xb32-300e_coco, devicecuda:1) # 使用 CPU 推理 inferencer DetInferencer( modelrtmdet_tiny_8xb32-300e_coco, devicecpu)device接受torch.device支持的所有字符串形式如cuda:0、cpu等。推理输入初始化后直接调用 Inferencer 实例即可支持四种输入形式源码中的_inputs_to_list负责统一归一化见 mmdet/apis/det_inferencer.py字符串图像路径/URLinferencer(demo/demo.jpg)numpy 数组BGR 顺序的图像import mmcv array mmcv.imread(demo/demo.jpg) inferencer(array)列表上述基本类型的混合列表每个元素单独处理inferencer([img_1.jpg, img_2.jpg]) # 甚至可以混合不同类型 inferencer([img_1.jpg, array])字符串目录路径目录下所有图像都会被处理inferencer(path/to/your_imgs/)其中目录展开逻辑会按IMG_EXTENSIONS (.jpg, .jpeg, .png, .ppm, .bmp, .pgm, .tif, .tiff, .webp)过滤文件见 mmdet/apis/det_inferencer.py其他后缀的文件会被自动忽略。输出结构默认每个 Inferencer 以字典形式返回预测结果包含两个键visualization可视化后的图像数组predictionsJSON 可序列化的预测结果默认返回的是空列表需要设置return_visTrue才会填充内容。{ predictions: [ # 每个元素对应一张输入图像 { labels: [...], # int 列表长度 (N, ) scores: [...], # float 列表长度 (N, ) bboxes: [...], # 二维列表形状 (N, 4)格式 [min_x, min_y, max_x, max_y] }, ... ], visualization: [ array(..., dtypeuint8), ] }从源码pred2dict实现mmdet/apis/det_inferencer.py可以看到该字典由DetDataSample.pred_instances中的labels、scores、bboxes以及可选的masks分割模型整理而来实例分割模型的 mask 会以 RLE 编码字符串形式写入结果如 SOLO 等无 bbox 输出的模型会自动通过mask2bbox生成伪 bbox。全景分割结果则以pred_panoptic_seg形式额外返回。如果你希望拿到模型的原始输出可将return_datasamplesTrue此时返回原始的 DataSample 对象而非字典并存入predictions字段。结果导出Dumping Results除了从返回值获取预测还可以通过out_dir配合no_save_pred/no_save_vis将预测与可视化结果写入文件inferencer(demo/demo.jpg, out_diroutputs/, no_save_predFalse)生成目录结构如下outputs ├── preds │ └── demo.json └── vis └── demo.jpg文件命名规则与输入图像文件名一致当输入是 numpy 数组时文件名从 0 开始编号源码中通过str(self.num_visualized_imgs).zfill(8)生成 8 位数字命名见 mmdet/apis/det_inferencer.py。批量推理通过batch_size参数可自定义推理批量大小默认值为 1inferencer([img_1.jpg, img_2.jpg, img_3.jpg], batch_size2)API 参数速查表DetInferencer.__init__()参数类型默认值说明modelstr, optionalNone配置文件路径或 metafile 中定义的模型名例如rtmdet-s、rtmdet_s_8xb32-300e_coco或configs/rtmdet/rtmdet_s_8xb32-300e_coco.py。若未指定则必须提供包含配置字符串的 MMEngine 权重weightsweightsstr, optionalNonecheckpoint 路径。若未指定且model为 metafile 中的模型名则权重会从 metafile 加载devicestr, optionalNone推理设备接受torch.device支持的所有字符串如cuda:0、cpu为 None 时自动选择可用设备scopestr, optionalmmdet模型所属的 scopepalettestrnone可视化配色。优先级为 palette - config - checkpointshow_progressboolTrue推理过程中是否显示进度条DetInferencer.__call__()参数类型默认值说明inputsstr/list/tuple/np.array必填图像路径/文件夹路径/np 数组或由上述类型构成的列表/元组batch_sizeint1推理批量大小print_resultboolFalse是否将推理结果打印到控制台showboolFalse是否在弹窗中展示可视化结果wait_timefloat0弹窗展示的时间间隔秒no_save_visboolFalse是否强制不保存可视化结果draw_predboolTrue是否绘制预测框pred_score_thrfloat0.3绘制 bbox 的最低分数阈值return_datasamplesboolFalse是否以 DataSamples 形式返回结果为 False 时打包为字典no_save_predboolTrue是否强制不保存预测结果out_dirstr结果输出目录textsstr/list[str], optionalNone文本提示开放词表任务如 GLIPstuff_textsstr/list[str], optionalNone开放全景任务的 stuff 文本提示custom_entitiesboolFalse是否使用自定义实体仅在 GLIP 中使用**kwargs——透传给preprocess/forward/visualize/postprocess的其他关键字参数每个键须属于对应阶段的 kwargs 集合需要特别说明的是palette的优先级逻辑源码中先检查显式传入的palette其次读取cfg.test_dataloader.dataset的 metainfo 中的调色板最后才回退到 checkpoint 内保存的调色板若均不存在则使用random并告警见 mmdet/apis/det_inferencer.py。五个开箱即用的 Demo 脚本除了高级 API仓库还在 demo 目录下提供了四个加上大图共五个基于高级 API 或底层 API 实现的 Demo 脚本可直接在命令行使用。图像推理image_demo.py对单张图像执行推理python demo/image_demo.py \ ${IMAGE_FILE} \ ${CONFIG_FILE} \ [--weights ${WEIGHTS}] \ [--device ${GPU_ID}] \ [--pred-score-thr ${SCORE_THR}]示例RTMDet-LCPU 推理python demo/image_demo.py demo/demo.jpg \ configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \ --weights checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \ --device cpu从 demo/image_demo.py 的参数解析逻辑看该脚本对DetInferencer做了更细的封装额外支持--out-dir输出目录默认outputs保存可视化与 JSON 预测--show/--print-result/--palette弹窗展示、打印结果、选择配色coco/voc/citys/random/none--texts文本提示。若以$:开头如$: coco、$: lvis、$: voc会自动从数据集类名中构建提示词对应 mmdet/evaluation 中的类别表--custom-entities/-c自定义实体仅 GLIP 与 Grounding DINO文本须为cls_name1 . cls_name2 . cls_name3 .格式--chunked-size/-s类别数极大时按此参数分批预测默认 -1 表示不分批--tokens-positive/-p指定输入文本中用户感兴趣的区间-1表示无感兴趣区域仅 Grounding DINO。此外脚本还支持直接把.pth权重文件作为第二个位置参数传入自动转赋给--weights并支持rtmdet-s这类 metafile 模型名如python demo/image_demo.py demo/demo.jpg rtmdet-s。摄像头实时推理webcam_demo.py从摄像头读取画面进行实时检测python demo/webcam_demo.py \ ${CONFIG_FILE} \ ${CHECKPOINT_FILE} \ [--device ${GPU_ID}] \ [--camera-id ${CAMERA-ID}] \ [--score-thr ${SCORE_THR}]示例python demo/webcam_demo.py \ configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \ checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth源码demo/webcam_demo.py基于cv2.VideoCapture(args.camera_id)逐帧读取--camera-id默认 0即默认摄像头每帧调用底层inference_detector推理后经 Visualizer 绘制按Esc/q/Q键退出。注意该脚本默认置信度阈值--score-thr为 0.5与image_demo.py的 0.3 不同。视频推理video_demo.py对视频文件逐帧执行推理可保存或展示python demo/video_demo.py \ ${VIDEO_FILE} \ ${CONFIG_FILE} \ ${CHECKPOINT_FILE} \ [--device ${GPU_ID}] \ [--score-thr ${SCORE_THR}] \ [--out ${OUT_FILE}] \ [--show] \ [--wait-time ${WAIT_TIME}]示例python demo/video_demo.py demo/demo.mp4 \ configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \ checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \ --out result.mp4与image_demo.py使用DetInferencer不同该脚本走的是底层 APIinit_detector加载模型 inference_detector逐帧推理见 demo/video_demo.py。它先将测试 pipeline 的首个变换替换为mmdet.LoadImageFromNDArray以支持 numpy 帧输入再用mmcv.VideoReader读取视频、cv2.VideoWriter编码mp4v写出结果。脚本强制要求--out与--show至少指定其一否则直接报错。GPU 加速视频推理video_gpuaccel_demo.py借助 GPU 硬件解码加速视频推理python demo/video_gpuaccel_demo.py \ ${VIDEO_FILE} \ ${CONFIG_FILE} \ ${CHECKPOINT_FILE} \ [--device ${GPU_ID}] \ [--score-thr ${SCORE_THR}] \ [--nvdecode] \ [--out ${OUT_FILE}] \ [--show] \ [--wait-time ${WAIT_TIME}]示例启用--nvdecode硬件解码python demo/video_gpuaccel_demo.py demo/demo.mp4 \ configs/rtmdet/rtmdet_l_8xb32-300e_coco.py \ checkpoints/rtmdet_l_8xb32-300e_coco_20220719_112030-5a0be7c4.pth \ --nvdecode --out result.mp4使用前提是运行环境支持 NVIDIA 硬件解码NVDEC并已安装相应依赖。大图切片推理large_image_demo.py针对卫星影像等超大尺寸图像脚本会先切片patch推理再把各切片结果合并回整图坐标系python demo/large_image_demo.py \ ${IMG_PATH} \ ${CONFIG_FILE} \ ${CHECKPOINT_FILE} \ --device ${GPU_ID} \ --show \ --tta \ --score-thr ${SCORE_THR} \ --patch-size ${PATCH_SIZE} \ --patch-overlap-ratio ${PATCH_OVERLAP_RATIO} \ --merge-iou-thr ${MERGE_IOU_THR} \ --merge-nms-type ${MERGE_NMS_TYPE} \ --batch-size ${BATCH_SIZE} \ --debug \ --save-patch示例一无 TTApython demo/large_image_demo.py \ demo/large_image.jpg \ configs/faster_rcnn/faster-rcnn_r101_fpn_2x_coco.py \ checkpoint/faster_rcnn_r101_fpn_2x_coco_bbox_mAP-0.398_20200504_210455-1d2dac9c.pth示例二开启 TTA 测试时增强需要配置文件内含tta_model与tta_pipeline字段python demo/large_image_demo.py \ demo/large_image.jpg \ configs/retinanet/retinanet_r50_fpn_1x_coco.py \ checkpoint/retinanet_r50_fpn_1x_coco_20200130-c2398f9e.pth --tta参数默认值见 demo/large_image_demo.py--patch-size默认 640--patch-overlap-ratio默认 0.25--merge-iou-thr默认 0.25--merge-nms-type默认nms--score-thr默认 0.3。切片的底层实现依赖 SAHI 库from sahi.slicing import slice_image合并过程使用 mmdet/utils/large_image.py 中的merge_results_by_nms与shift_predictions先按切片偏移量将预测框平移回原图坐标再统一做 NMS 合并从而去除相邻切片重叠区域产生的重复框。若传入--debug可在合并前导出各切片的中间结果。多模态算法推理与评测以 GLIP 为例随着多模态视觉算法的发展MMDetection 也集成了 GLIP、Grounding DINO 等开放词表检测算法。本节以 GLIP 为例演示多模态算法的推理与评测流程。MMDetection 还集成了 projects/gradio_demo 项目开发者可在本地通过图形界面快速体验 MMDetection 的全部图像输入任务详见 projects/gradio_demo/README.md。环境准备先确保安装了多模态相关依赖# 源码方式安装 pip install -r requirements/multimodal.txt # wheel 方式安装 mim install mmdet[multimodal]下载 GLIP 预训练权重MMDetection 已完整实现 GLIP 并提供权重cd mmdetection wget https://download.openmmlab.com/mmdetection/v3.0/glip/glip_tiny_a_mmdet-b3654169.pth文本提示推理权重下载完成后直接使用demo/image_demo.py执行推理python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts bench检测多个目标时用xx. xx格式声明多个文本提示python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts bench. car也可以直接输入一句自然语言描述作为提示python demo/image_demo.py demo/demo.jpg glip_tiny_a_mmdet-b3654169.pth --texts There are a lot of cars here.从底层配置看GLIP 模型由 SwinTransformer 视觉主干 BERT 语言模型lang_model_name bert-base-uncasedATSSVLFusionHead检测头构成见 configs/glip/glip_atss_swin-t_a_fpn_dyhead_pretrain_obj365.py测试 pipeline 会把text、custom_entities等键写入 meta从而把文本提示与图像一起送入模型做跨模态对齐。前述--texts $: coco、--custom-entities、--chunked-size等参数正是为这类开放词表模型准备的。评测MMDetection 的 GLIP 实现相比官方无性能损失官方文档给出的基准对比如下模型官方 mAPMMDetection mAPglip_A_Swin_T_O365.yaml42.943.0glip_Swin_T_O365.yaml44.944.9glip_Swin_L.yaml51.451.3使用 tools/test.py 或 tools/dist_test.sh 即可复现评测# 单卡评测 python tools/test.py configs/glip/glip_atss_swin-t_fpn_dyhead_pretrain_obj365.py glip_tiny_a_mmdet-b3654169.pth # 8 卡分布式评测 ./tools/dist_test.sh configs/glip/glip_atss_swin-t_fpn_dyhead_pretrain_obj365.py glip_tiny_a_mmdet-b3654169.pth 8完整的评测参数说明与 COCO 等数据集的评测流程可进一步阅读 测试与评测文档。总结如何选择推理方式场景推荐方式入口Python 内嵌、批处理、结果结构化落盘DetInferencer高级 APImmdet/apis/det_inferencer.py单张图像命令行推理含 GLIP 文本提示image_demo.pydemo/image_demo.py摄像头实时检测webcam_demo.pydemo/webcam_demo.py普通视频推理video_demo.pydemo/video_demo.pyGPU 硬解加速视频推理video_gpuaccel_demo.pydemo/video_gpuaccel_demo.py卫星影像等大图large_image_demo.pySAHI 切片 NMS 合并demo/large_image_demo.py无论是希望以最少代码接入推理流水线还是需要精细控制每个阶段的命令行工具MMDetection 都提供了对应用例。以DetInferencer为入口配合 配置文档 理解model、weights、device等核心参数再结合各 Demo 脚本源码demo 目录按需裁剪即可快速搭建从加载权重到可视化/落盘的完整推理链路。【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考