MMDetection 集成 X-Decoder 实战指南：统一像素/图像/语言解码的开放词汇分割与视觉语言推理

MMDetection 集成 X-Decoder 实战指南统一像素/图像/语言解码的开放词汇分割与视觉语言推理【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection导读本文围绕 MMDetection 仓库中projects/XDecoder项目系统讲解如何将微软 X-DecoderGeneralized Decoding for Pixel, Image, and Language这一多任务统一解码模型接入 MMDetection并落地开放词汇语义分割、实例分割、全景分割、指代分割Referring Segmentation、图像描述Caption、指代描述与文本-图像区域检索等七类任务。读完本文你将掌握 X-Decoder 在 MMDetection 中的环境安装、权重下载、零样本 demo 推理、官方配置结构与关键超参数含义以及基于 ADE20K / COCO / RefCOCO / COCO2014 的分布式评测方法与复现结果对照。一、X-Decoder 是什么多任务统一解码范式X-Decoder 是微软提出的一种广义解码模型其论文发表于 arXivX-Decoder: Generalized Decoding for Pixel, Image, and Language。与以往一个任务一个头的专用模型不同X-Decoder 输入两类查询query通用非语义查询generic non-semantic queries用于解码像素级输出mask文本诱导的语义查询semantic queries induced from text inputs用于解码 token 级输出。两类输出落在同一个语义空间中从而以统一方式支持各类图像分割任务以及多种视觉语言Vision-Language, VL任务。论文进一步指出这种设计允许不同粒度的任务之间无缝交互通过共享一个丰富且通用的像素级视觉语义理解空间实现相互增益且不依赖任何伪标注。在 MMDetection 的projects/XDecoder目录中该模型被实现为一个完整的 MMDetection 检测器XDecoder可直接复用 MMDetection 的数据管线、评测体系与分布式训练/测试工具。项目目录结构如下projects/XDecoder/demo.py多任务统一推理入口projects/XDecoder/xdecoder/模型实现FocalNet 骨干、像素解码器、Transformer 解码器、统一头等projects/XDecoder/xdecoder/inference/为 Caption、Retrieval 等非分割任务定制的 Inferencerprojects/XDecoder/configs/七个任务的零样本推理配置与评测配置projects/XDecoder/README.md官方使用说明与结果复现表本文即基于该文档展开。二、环境安装与依赖2.1 安装 multimodal 依赖X-Decoder 依赖语言模型编码与多模态推理组件需要安装 MMDetection 的多模态可选依赖。根据来源不同有两种安装方式见 projects/XDecoder/README.md# 源码方式在 mmdetection 仓库根目录执行 pip install -r requirements/multimodal.txt # 已安装 mmdet wheel 包时 mim install mmdet[multimodal]其中requirements/multimodal.txt是仓库根目录下的依赖清单文件包含 X-Decoder 推理所需的额外 Python 包如语言模型相关依赖。安装完成后projects/XDecoder/configs/_base_/xdecoder-tiny_open-vocab-semseg.py中通过custom_imports机制注册项目模块custom_imports dict( imports[projects.XDecoder.xdecoder], allow_failed_importsFalse)这意味着运行任意 X-Decoder 配置时MMEngine 会自动导入projects/XDecoder/xdecoder包并注册其中的模型组件无需手动import。2.2 下载预训练权重官方提供了两份直接从微软官方仓库原样拷贝的权重未做任何修改下载到mmdetection根目录即可wget https://download.openmmlab.com/mmdetection/v3.0/xdecoder/xdecoder_focalt_last_novg.pt wget https://download.openmmlab.com/mmdetection/v3.0/xdecoder/xdecoder_focalt_best_openseg.ptxdecoder_focalt_last_novg.pt用于绝大多数零样本 demo 推理以及 COCO 系列评测xdecoder_focalt_best_openseg.pt用于 ADE20K 语义/实例/全景分割评测。此外为了演示方便文档建议从微软 X-Decoder 官方仓库下载inference_demo/images示例图片文件夹并放置到 mmdetection 根目录即mmdetection/images/后续 demo 命令中的../../images/xxx即指向该目录。三、七类任务的零样本推理demo.py 实战projects/XDecoder/demo.py是统一推理入口其核心逻辑是读取配置 → 依据cfg.model.head.task字段自动选择对应的 Inferencer → 执行推理并可视化。从源码看projects/XDecoder/demo.py任务与 Inferencer 的映射为TASKINFOS { semseg: DetInferencer, # 开放词汇语义分割 ref-seg: DetInferencer, # 指代分割 instance: DetInferencer, # 开放词汇实例分割 panoptic: DetInferencer, # 开放词汇全景分割 caption: ImageCaptionInferencer, # 图像描述 ref-caption: RefImageCaptionInferencer, # 指代描述 retrieval: TextToImageRegionRetrievalInferencer, # 文本-图像区域检索 }常用命令行参数包括参数说明inputs位置参数输入图片文件或文件夹路径model位置参数配置文件路径--weights权重文件路径--texts文本提示词分割类任务的类别名以.分隔--out-dir输出目录默认outputs--device推理设备默认cuda:0--show弹窗显示结果--no-save-vis不保存可视化结果--palette可视化配色可选ade20k / coco / voc / citys / random / none默认none--pred-score-thr仅实例分割使用bbox 置信度阈值默认 0.5--stuff-texts仅全景分割使用stuff 类别文本提示注意caption任务不要求--textspanoptic任务额外要求--stuff-textsstuff 类别而thing类别通过--texts传入。3.1 开放词汇语义分割Open Vocabulary Semantic Segmentationcd projects/XDecoder python demo.py ../../images/animals.png configs/xdecoder-tiny_zeroshot_open-vocab-semseg_coco.py --weights ../../xdecoder_focalt_last_novg.pt --texts zebra.giraffe文本提示zebra.giraffe指定了期望分割的两个类别斑马、长颈鹿模型在开放词汇条件下直接输出对应类别的语义掩码。3.2 开放词汇实例分割Open Vocabulary Instance Segmentationcd projects/XDecoder python demo.py ../../images/owls.jpeg configs/xdecoder-tiny_zeroshot_open-vocab-instance_coco.py --weights ../../xdecoder_focalt_last_novg.pt --texts owl该任务会为每个实例生成独立掩码输出通过--pred-score-thr过滤低置信度结果。3.3 开放词汇全景分割Open Vocabulary Panoptic Segmentationcd projects/XDecoder python demo.py ../../images/street.jpg configs/xdecoder-tiny_zeroshot_open-vocab-panoptic_coco.py --weights ../../xdecoder_focalt_last_novg.pt --text car.person --stuff-text tree.sky全景分割同时建模 thing 类别--textscar、person与 stuff 类别--stuff-textstree、sky二者在输出中被统一编码为全景图。3.4 指代分割Referring Expression Segmentationcd projects/XDecoder python demo.py ../../images/fruit.jpg configs/xdecoder-tiny_zeroshot_open-vocab-ref-seg_refcocog.py --weights ../../xdecoder_focalt_last_novg.pt --text The larger watermelon. The front white flower. White tea pot.指代分割接受完整的自然语言描述可用.分隔多个指代目标模型定位并分割描述对应的区域。3.5 图像描述Image Captioncd projects/XDecoder python demo.py ../../images/penguin.jpeg configs/xdecoder-tiny_zeroshot_caption_coco2014.py --weights ../../xdecoder_focalt_last_novg.ptCaption 任务不需要文本提示模型自动为整张图像生成自然语言描述。3.6 指代描述Referring Expression Image Captioncd projects/XDecoder python demo.py ../../images/fruit.jpg configs/xdecoder-tiny_zeroshot_ref-caption.py --weights ../../xdecoder_focalt_last_novg.pt --text White tea pot指代描述是指代分割 图像描述的组合任务先依据文本定位目标区域再对区域生成描述。这对应源码中XDecoderUnifiedhead的特殊处理——当task ref-caption时return_inter_mask True需要返回中间 mask 供描述解码使用见 projects/XDecoder/xdecoder/unified_head.py。3.7 文本-图像区域检索Text Image Region Retrievalcd projects/XDecoder python demo.py ../../images/coco configs/xdecoder-tiny_zeroshot_text-image-retrieval.py --weights ../../xdecoder_focalt_last_novg.pt --text pizza on the plate输入可以是文件夹模型在该文件夹的全部图像中检索与文本最匹配的图像区域The image that best matches the given text is ../../images/coco/000.jpg and probability is 0.9983.8 浏览器端交互gradio demo除命令行外仓库还在projects/gradio_demo目录准备了 Gradio 程序可在浏览器中交互式运行 MMDetection 支持的所有推理任务便于快速体验与演示。四、源码级剖析XDecoder 的统一解码架构4.1 检测器主体XDecoderprojects/XDecoder/xdecoder/xdecoder.py定义了注册名为XDecoder的检测器继承自 MMDetection 的SingleStageDetectorMODELS.register_module() class XDecoder(SingleStageDetector): def __init__(self, backbone, neckNone, headNone, test_cfgNone, data_preprocessorNone, init_cfgNone): ... self.backbone MODELS.build(backbone) if neck is not None: self.neck MODELS.build(neck) head_ head.deepcopy() head_.update(test_cfgtest_cfg) self.sem_seg_head MODELS.build(head_)其前向预测流程为extract_feat提取骨干特征 → 送入统一头sem_seg_head.predict得到分割结果。整个模型没有 RPN、没有 anchor完全依赖查询解码范式。4.2 统一头XDecoderUnifiedheadXDecoderUnifiedheadprojects/XDecoder/xdecoder/unified_head.py是架构的核心构造参数与基础配置projects/XDecoder/configs/_base_/xdecoder-tiny_open-vocab-semseg.py一一对应model dict( typeXDecoder, data_preprocessordict( typeDetDataPreprocessor, mean[123.675, 116.28, 103.53], std[58.395, 57.12, 57.375], bgr_to_rgbTrue, pad_size_divisor32), backbonedict(typeFocalNet), headdict( typeXDecoderUnifiedhead, in_channels(96, 192, 384, 768), pixel_decoderdict(typeXTransformerEncoderPixelDecoder), transformer_decoderdict(typeXDecoderTransformerDecoder), tasksemseg, ), test_cfgdict(mask_thr0.5, use_thr_for_mcTrue, ignore_index255), )各组件职责FocalNet骨干projects/XDecoder/xdecoder/focalnet.py输出四层多尺度特征in_channels(96, 192, 384, 768)对应 tiny 尺寸;像素解码器XTransformerEncoderPixelDecoderpixel_decoder.py融合多尺度特征生成统一的mask_features与multi_scale_featuresTransformer 解码器XDecoderTransformerDecodertransformer_decoder.py接收文本编码器输出的查询嵌入与视觉特征解码出 mask 预测pred_masks与 logits 预测pred_logits语言模型language_model.py负责文本编码包括get_mean_embeds分割类任务、get_text_embeds指代/检索任务、get_sot_tokencaption 起始 tokentask字段决定后处理分支可取semseg / instance / panoptic / ref-seg / caption / ref-caption / retrieval。从pre_process的实现可以看出一处关键设计文本提示按.分割后会被缓存self._all_text_prompts当多张图的文本提示相同时避免重复编码提升批量推理效率同时所有任务都会在文本末尾追加background类别仅 semseg/instance/panoptic用于建模背景。4.3 后处理与 test_cfg 关键参数post_process按任务分流projects/XDecoder/xdecoder/unified_head.py涉及以下核心test_cfg参数理解它们对评测结果至关重要参数默认值作用域说明mask_thr0.5semseg/ 0.8panoptic全部mask 二值化阈值mask_pred.sigmoid() mask_thr判定为前景use_thr_for_mcTruesemseg / ref-seg多类别语义分割是否使用阈值过滤为 True 时若某像素在所有类别上的得分都不超过mask_thr则置为ignore_index背景ignore_index255语义/全景背景或忽略像素的编码值max_per_img100instance每张图最多保留的实例数top-k 选取overlap_thr0.8panopticpanopticstuff 区域合并时的重叠面积比阈值用于抑制跨区域重叠实例分割的完整后处理链在_instance_inferenceprojects/XDecoder/xdecoder/unified_head.py对mask_cls做 softmax去掉 background 列→ topk 取max_per_img个候选 → 对 mask 做 sigmoid 并阈值化 → 将分类得分与平均 mask 得分相乘得到最终实例得分同时附上label_names对应文本提示的类别名。语义分割的_semantic_inference使用torch.einsum(qc,qhw-chw, mask_cls, mask_pred)将类别得分与 mask 加权求和得到逐类得分图再按use_thr_for_mc决定是否过滤背景。全景分割的_panoptic_inference则结合mask_thr与overlap_thr做区域级处理thing 实例以类别 id 实例 id * INSTANCE_OFFSET编码stuff 区域直接以类别 id 编码INSTANCE_OFFSET来自mmdet.evaluation.functional。五、五个基础配置的差异projects/XDecoder/configs/_base_/下的五个基础配置通过继承与覆盖组合出所有任务# xdecoder-tiny_open-vocab-instance.py _base_ xdecoder-tiny_open-vocab-semseg.py model dict(headdict(taskinstance), test_cfgdict(max_per_img100))# xdecoder-tiny_open-vocab-panoptic.py _base_ xdecoder-tiny_open-vocab-semseg.py model dict(headdict(taskpanoptic), test_cfgdict(mask_thr0.8, overlap_thr0.8))# xdecoder-tiny_caption.py / xdecoder-tiny_ref-seg.py model dict(headdict(taskcaption)) # 或 taskref-seg可以看到实例/全景/描述/指代等任务与语义分割共享同一套骨干与解码器仅通过task字段切换输出头与后处理策略这正是统一解码思想在工程实现上的直接体现。六、模型评测与结果复现官方在 ADE20K、COCO2017、RefCOCO、COCO2014 四个数据集上给出了完整的评测命令与复现结果。所有评测命令均通过仓库根目录的tools/dist_test.sh发起分布式测试权重放在 mmdetection 根目录。6.1 ADE20K 语义分割数据集按 docs/en/user_guides/dataset_prepare.md 准备。由于语义分割是像素级任务无需阈值过滤低置信度预测测试命令需显式关闭多类别阈值./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-semseg_ade20k.py xdecoder_focalt_best_openseg.pt 8 --cfg-options model.test_cfg.use_thr_for_mcFalseModelmIoUmIoU(official)Configxdecoder_focalt_best_openseg.pt25.2425.13config6.2 ADE20K 实例分割./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-instance_ade20k.py xdecoder_focalt_best_openseg.pt 8ModelmIoUmIoU(official)Configxdecoder_focalt_best_openseg.pt10.110.1config6.3 ADE20K 全景分割./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-panoptic_ade20k.py xdecoder_focalt_best_openseg.pt 8ModelmIoUmIoU(official)Configxdecoder_focalt_best_openseg.pt19.1118.97config6.4 COCO2017 语义分割数据准备参考 docs/en/user_guides/dataset_prepare.md 中 (2) use panoptic dataset 部分。COCO 语义分割使用 133 个类别含 80 个 thing 类与扩展的 stuff 类类别列表定义在配置的x_decoder_coco2017_semseg_classes中同样需要关闭多类别阈值./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-semseg_coco.py xdecoder_focalt_last_novg.pt 8 --cfg-options model.test_cfg.use_thr_for_mcFalseModelmIoUmIoU(official)Configxdecoder-tiny_zeroshot_open-vocab-semseg_coco62.162.1config6.5 COCO2017 实例分割./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-instance_coco.py xdecoder_focalt_last_novg.pt 8ModelMask mAPMask mAP(official)Configxdecoder-tiny_zeroshot_open-vocab-instance_coco39.839.7config6.6 COCO2017 全景分割./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-panoptic_coco.py xdecoder_focalt_last_novg.pt 8ModelPQPQ(official)Configxdecoder-tiny_zeroshot_open-vocab-panoptic_coco51.4251.16config6.7 RefCOCO 指代分割数据准备参考 docs/en/user_guides/dataset_prepare.md。测试时通过--cfg-options指定验证集划分./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_open-vocab-ref-seg_refcocog.py xdecoder_focalt_last_novg.pt 8 --cfg-options test_dataloader.dataset.splitvalModeltext modecIoUcIoU(official)Configxdecoder_focalt_last_novg.ptselect first58.841557.85configxdecoder_focalt_last_novg.ptoriginal60.0321-configxdecoder_focalt_last_novg.ptconcat60.3551-config注意若将Resize的 scale 改为 (1024, 512)结果会变为 57.69。关于text modeRefCoCoDataset参数它决定加载到数据列表中的文本描述方式可取四个值select_first取文本列表中的第一条描述作为该实例的描述对应上表第一行original使用文本列表中的所有描述作为该实例的描述concat将文本列表中的所有描述拼接为一条random随机选择一条描述通常用于训练阶段。仓库中同时提供了 RefCOCOxdecoder-tiny_zeroshot_open-vocab-ref-seg_refcoco.py与 RefCOCOxdecoder-tiny_zeroshot_open-vocab-ref-seg_refcoco.py的零样本配置可用于不同指代数据集上的扩展评测。6.8 COCO2014 图像描述数据准备参考 docs/en/user_guides/dataset_prepare.md。测试前需安装 JDK 1.8否则评测过程中会提示 java 不存在COCO caption 官方评测工具基于 Java 实现./tools/dist_test.sh projects/XDecoder/configs/xdecoder-tiny_zeroshot_caption_coco2014.py xdecoder_focalt_last_novg.pt 8ModelBLEU-4CIDErConfigxdecoder-tiny_zeroshot_caption_coco201435.26116.81configCaption 配置继承自mmdet::_base_/datasets/coco_caption.py数据集配置测试时以ResizeShortestEdge(scale224)作为输入预处理见 projects/XDecoder/configs/xdecoder-tiny_zeroshot_caption_coco2014.py。而检索任务配置xdecoder-tiny_zeroshot_text-image-retrieval.py在此基础上仅将head.task改为retrieval并改用 bicubic 插值缩放展现了配置继承的极简组合方式。七、小结与扩展X-Decoder 在 MMDetection 中的落地展示了一条统一解码器 任务字段切换的多任务范式同一套 FocalNet 骨干、同一组 Transformer 解码器仅通过task字段与test_cfg参数即可在语义/实例/全景分割、指代分割、描述与检索等任务间自由切换。实测复现结果ADE20K 语义 25.24 mIoU、COCO 实例 39.8 Mask mAP、COCO 全景 51.42 PQ、RefCOCOg 指代最高 60.36 cIoU、COCO2014 描述 116.81 CIDEr与官方数值基本一致可直接作为零样本与开放词汇研究的基线。如需进一步探索可重点阅读以下仓库文件推理入口与参数解析projects/XDecoder/demo.py检测器定义projects/XDecoder/xdecoder/xdecoder.py统一头与后处理实现projects/XDecoder/xdecoder/unified_head.py基础配置含 test_cfg 默认值projects/XDecoder/configs/base/xdecoder-tiny_open-vocab-semseg.py评测结果总览projects/XDecoder/README.md引用若在科研工作中使用本项目请引用原始论文article{zou2022xdecoder, author {Zou*, Xueyan and Dou*, Zi-Yi and Yang*, Jianwei and Gan, Zhe and Li, Linjie and Li, Chunyuan and Dai, Xiyang and Wang, Jianfeng and Yuan, Lu and Peng, Nanyun and Wang, Lijuan and Lee*, Yong Jae and Gao*, Jianfeng}, title {Generalized Decoding for Pixel, Image and Language}, publisher {arXiv}, year {2022}, }【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考