TPU 仓库 ViLD 开放词汇检测实战：基于视觉-语言知识蒸馏的两阶段检测器全解析

深度学习后端开发工具【免费下载链接】tpuReference models and tools for Cloud TPUs.项目地址https://gitcode.com/gh_mirrors/tpu/tpu点击查看免费下载本文以 TensorFlow Cloud TPU 参考模型仓库中的 ViLD 项目文档 为主体系统讲解 ViLDVision and Language Distillation开放词汇目标检测方法的原理、代码组织、配置参数、数据预处理与推理流程。读完本文你将掌握如何在当前仓库中复现 ViLD 的 LVIS 评测管线理解教师-学生蒸馏在检测器中的落地方式并能够将预训练模型直接迁移到 PASCAL VOC、COCO、Objects365 等任意数据集上做零微调推理。一、ViLD 要解决的问题开放词汇目标检测传统目标检测器只能识别训练数据集中出现过的固定类别集合。开放词汇open-vocabulary目标检测的目标是检测任意文本描述所对应的目标。其根本困难在于训练数据的匮乏——现有检测数据集通常只有数百个类别且标注新类别成本极高。ViLD 提出的解决方案是一种视觉-语言知识蒸馏框架其核心思想是使用一个预训练的开放词汇图像分类模型教师模型本项目采用 OpenAI CLIP来编码类别文本与候选区域object proposals的图像区域训练一个两阶段检测器学生模型本项目基于 Mask R-CNN 架构使检测框的区域嵌入region embeddings与教师模型推断出的文本嵌入、图像嵌入对齐。从源码结构看这一思路在仓库中落地为四类模块蒸馏数据解析vild_parser.py、模型结构vild_model.py、检测头vild_head.py与损失函数vild_losses.py。论文作者在 LVIS 上通过将所有稀有类rare categories作为训练时未见过的 novel 类别来构建评测基准据论文报告 ViLD 以 ResNet-50 骨干取得 16.1 mask APr甚至超过有监督对照 3.8模型无需微调即可直接迁移到其他数据集在 PASCAL VOC、COCO 与 Objects365 上分别取得 72.2 AP50、36.6 AP 与 11.8 AP在 COCO 上较此前最优方法在 novel AP 与整体 AP 上分别提升 4.8 与 11.4。二、代码组织与启动入口ViLD 作为 Cloud TPU detection 框架下的一个项目代码集中在 models/official/detection/projects/vildprojects/vild/ ├── README.md # 本文主体对应的项目文档 ├── ViLD_demo.ipynb # Colab 交互演示两个示例可换自己的图与类别 ├── requirements.txt # Python 依赖 ├── configs/ │ ├── vild_config.py # 默认参数模板继承 DETECTION_CFG │ ├── vild_resnet.yaml # ViLDvanilla 蒸馏配置 │ └── vild_ensemble_resnet.yaml # ViLD-ensembledouble_branch 蒸馏配置 ├── dataloader/ │ ├── tf_example_decoder.py # 解码含蒸馏标签的 tf.Example │ └── vild_parser.py # 图像/标注/蒸馏标签解析器 ├── modeling/ │ ├── vild_head.py # ViLD Fast R-CNN 头CLIP 分类器 特征蒸馏投影 │ ├── vild_losses.py # 分类损失支持 mask_rare │ └── vild_model.py # ViLD 模型主体继承 base_model.BaseModel ├── ops/ │ └── postprocess_ops.py # 检测后处理NMS 等 └── preprocessing/ ├── create_lvis_tf_record.py # LVIS → TFRecord 转换脚本 └── dataset_util.pyViLD 通过三处工厂函数挂载到统一框架中参数模板configs/factory.py 中model vild时返回vild_config.VILD_CFG模型构建modeling/factory.py 中params.type vild时实例化vild_model.ViLDModel数据解析dataloader/factory.py 中parser vild_parser时实例化vild_parser.Parser检测头modeling/architecture/factory.py 中的vild_fast_rcnn_head_generator。启动入口是统一的 models/official/detection/main.py通过--modelvild与--modeeval/train等参数驱动。三、核心实现特征蒸馏如何在两阶段检测器内落地3.1 模型前向流程vild_model.pyViLDModel继承base_model.BaseModel整体保留 Mask R-CNN 的 ResNet-FPN-RPN 管线关键改造点见 vild_model.py训练时拼接蒸馏 ROI在 RPN 采样得到rpn_rois后若开启特征蒸馏visual_feature_distill非 None将教师模型预计算的labels[roi_boxes]形状[batch, max_distill_rois, 4]沿 axis1 与 RPN 的 ROI 拼接随后统一经过multilevel_crop_and_resize提取 ROI 特征前向结束后再tf.split还原。max_num_rois默认 300决定了每张图蒸馏 ROI 的数量RoI 特征 → 检测头_frcnn_head_fn返回class_outputs / box_outputs / distill_feat_outputs / distill_class_outputs四路输出其中distill_feat_outputs只在训练期参与蒸馏损失推理期_generate_detections_fn使用postprocess_ops.GenericDetectionGenerator做 NMS 等后处理vild_model.pyViLD-ensemble 额外传入distill_class_outputs做双分支分类集成。3.2 蒸馏损失build_losses总损失为vild_model.pymodel_loss rpn_score_loss rpn_box_loss frcnn_class_loss frcnn_box_loss mask_loss feat_distill_weight * feat_distill_loss其中特征蒸馏损失的计算细节vild_model.py训练时将教师预计算的gt_visual_feat按 L2 范数归一化normalize_feat_during_trainingTrue用valid_roisroi_boxes最大值大于 0 的条目作为权重掩码仅对有效 ROI 计算 L1 损失tf.losses.absolute_differenceSUM_BY_NONZERO_WEIGHTS损失值再乘以visual_feature_dim512以保持量纲稳定feat_distill_weight为蒸馏损失的缩放系数配置中 ResNet-50 取 0.5ResNet-152 取 1.0 或 2.0见后文 checkpoint 表。3.3 两种蒸馏模式vanilla 与 double_branchvisual_feature_distill支持三种取值vild_config.py 中注释为None / vanilla / double_branchNone关闭蒸馏退化为普通分类头vanilla对应 vild_resnet.yamlRPN ROI 与蒸馏 ROI 共享同一个 Fast R-CNN 特征提取网络训练时在投影到 CLIP 空间后按[num_rois - max_distill_rois, max_distill_rois]切分前者用于分类后者作为distill_feat_outputsdouble_branch对应 vild_ensemble_resnet.yaml在ViLDFastrcnnHead中为蒸馏 ROI 建立独立的 conv/fc 分支distill_conv_{i}、distill_fc{i6}与独立的投影层distill-project-to-clip训练、推理两路各自前向推理时将蒸馏分支的分类输出distill_class_outputs并入检测结果实现 ViLD-ensemble 集成效果vild_head.py 与 vild_head.py。3.4 ViLD 检测头与 CLIP 分类器vild_head.pyViLDFastrcnnHeadvild_head.py的关键参数与行为参数默认值作用clip_dim512CLIP 文本/视觉嵌入维度classifier_weight_path必填预计算的 CLIP 文本嵌入.npy路径作为分类权重normalize_classifierTrue是否对分类器权重按列做 L2 归一化后除到 logits 上normalize_visualTrue是否对投影后的视觉特征做 L2 归一化temperature100.0乘到 logits 上的温度系数放大对比度visual_feature_distillNone蒸馏模式None/vanilla/double_branchmax_distill_rois300蒸馏 ROI 数量上限class_agnostic_bbox_predTrue类别无关的框回归只预测 4 个坐标而非 num_classes×4实现要点训练期通过tf.gfile.GFile(self._classifier_weight_path)加载文本嵌入断言形状为(clip_dim, num_classes - 1)并以tf.initializers.constant作为class-predict全连接层无 bias的核初始化vild_head.py。这意味着1204 个类别 1 个背景类 1203 个 LVIS 类别分类器与背景分支分别做 L2 归一化后拼接background_output在前与tf.concat组合最后统一乘以temperaturevild_head.py变量作用域为frcnn_layer_0/fast_rcnn_head配合配置frozen_variable_prefix: frcnn_layer_0/fast_rcnn_head/class-predict在训练时冻结 CLIP 分类器权重仅微调视觉投影与检测头。3.5 分类损失与稀有类掩码vild_losses.pyFastrcnnClassLossvild_losses.py在配置frcnn_class_loss.mask_rareTrue时从rare_mask_path加载 LVIS 稀有类二值掩码将稀有类 logits 置零后计算 softmax 交叉熵。这一设计保证在仅监督基类frequent/common categories的训练设定下稀有类novel categories不会产生错误的梯度信号与论文的“稀有类全部视作 novel”基准保持一致。四、配置文件深度解析ViLD 提供两个 YAML 配置均以 vild_config.py 中的VILD_CFG为默认模板通过--config_file加载、--params_override覆盖。4.1 vild_resnet.yamlViLDResNet-50核心字段含义architecturebackbone: resnet、multilevel_features: fpn特征金字塔 level 2–6num_classes: 1204include_mask: true、mask_target_size: 28输出 mask 尺寸visual_feature_distill: vanilla、visual_feature_dim: 512、max_num_rois: 300、feat_distill_weight: 0.5、normalize_feat_during_training: true、filter_distill_boxes_size: 00 表示不过滤小于指定尺寸的蒸馏框frcnn_headnum_convs: 4、num_filters: 256、num_fcs: 2、fc_dims: 1024clip_dim: 512、normalize_classifier: true、normalize_visual: true、temperature: 100.0、class_agnostic_bbox_pred: trueresnetresnet_depth: 50frcnn_class_lossmask_rare: true配合推理脚本中的rare_mask_pathroi_proposal / roi_samplingRPN 训练期rpn_pre_nms_top_k: 2000、rpn_post_nms_top_k: 1000、nms_iou_threshold: 0.7ROI 采样num_samples_per_image: 512、fg_fraction: 0.25、fg_iou_thresh: 0.5、mix_gt_boxes: truepostprocessmax_total_size: 300、pre_nms_num_boxes: 1000、nms_iou_threshold: 0.5、score_threshold: 0.0、apply_nms: truetrainfrozen_variable_prefix: frcnn_layer_0/fast_rcnn_head/class-predict冻结 CLIP 文本分类器l2_weight_decay: 4.0e-05total_steps: 180000train_batch_size: 256step 式学习率init_learning_rate: 0.32、learning_rate_steps: [162000, 171000, 175500]、warmup_steps: 1000momentum 优化器0.9vild_parser输入图output_size: [1024, 1024]RPN 匹配阈值 0.7/0.3随机水平翻转尺度增强aug_scale_min: 0.1、aug_scale_max: 2.0mask_crop_size: 112、max_num_instances: 300训练时跳过 crowd 标注evaltype: lvis_box_and_mask、eval_samples: 19809、use_json_file: true。4.2 vild_ensemble_resnet.yamlViLD-ensemble与 vanilla 配置的差异集中在两点visual_feature_distill: double_branch见 3.3 节的双分支实现与use_tpu: false。README 中 ViLD-ensemble 与 ResNet-152 系列的 checkpoint 均引用该配置蒸馏权重依据下表使用feat_distill_weight覆盖。五、环境准备与依赖运行前需要满足两个前提详见 README.md安装 TensorFlow代码基于tensorflow.compat.v1编写需确保导入兼容安装 requirements.txt 中的依赖tensorflow pycocotools lvis opencv-python此外脚本内部存在sys.path.insert(0, tpu/models)的路径假设见 main.py 与 vild_config.py因此从仓库根目录出发命令中的配置路径与模块路径应以tpu/models/official/detection/...形式书写与官方 README 中的脚本保持一致。六、数据预处理LVIS v1.0 → TFRecord6.1 目录结构要求下载并解压 LVIS v1.0 验证集到DATA_DIR需按如下结构组织DATA_DIR -- lvis_v1_val.json -- val2017 | -- ***.jpg | -- ...6.2 转换脚本在models/official/detection/projects/vild/preprocessing/目录下执行脚本入口为 create_lvis_tf_record.pymax_num_processes可按机器核数调整DEST_DIR指定 TFRecord 输出目录DATA_DIR[DATA_DIR] DEST_DIR[DEST_DIR] VAL_JSON${DATA_DIR}/lvis_v1_val.json python3 preprocessing/create_lvis_tf_record.py \ --image_dir${DATA_DIR} \ --json_path${VAL_JSON} \ --dest_dir${DEST_DIR} \ --include_maskTrue \ --splitval \ --num_parts100 \ --max_num_processes100脚本支持的 flags 包括--include_mask是否包含 PNG 编码的实例分割掩码、--split取值train/val、--num_parts生成的 TFRecord 分片数、--debug等。脚本会把 LVIS 的[x, y, width, height]绝对坐标转换为 TensorFlow Object Detection API 期望的[ymin, xmin, ymax, xmax]归一化格式并利用 pycocotools 的 mask 工具解码 RLE 分割标注。6.3 训练数据说明从 vild_parser.py 与 tf_example_decoder.py 可以看出ViLD 训练所用的 TFRecord 除常规图像、框、类别、掩码标注外还须包含教师模型预计算的蒸馏标签roi_boxes蒸馏候选框与groundtruth_visual_featuresCLIP 图像区域嵌入。解析器在训练期会将这些标签随 RPN 标签一起打包labels[roi_boxes]、labels[gt_visual_feat]clip 到max_num_rois长度并可选地按filter_distill_boxes_size过滤过小的蒸馏框。这类带蒸馏标签的训练数据需要依据论文的离线教师推理流程预先产生官方文档未在仓库内给出其生成脚本。七、预训练 Checkpoint 与评测指标官方在 LVIS稀有类全部作为 novel上发布的预训练模型与指标如下表数据来自 README.mdMethodBackboneDistillation weightAPrAPcAPfAPconfigckptViLDResNet-500.516.619.828.222.5vild_resnet.yamlresnet50_vild.tar.gzViLD-ensembleResNet-500.51824.730.625.9vild_resnet.yamlresnet50_vild_ensemble.tar.gzViLDResNet-1521.019.621.628.524.0vild_ensemble_resnet.yamlresnet152_vild.tar.gzViLD-ensembleResNet-1522.019.224.830.826.2vild_ensemble_resnet.yamlresnet152_vild_ensemble.tar.gz其中 APr/APc/APf 分别对应 LVIS 的稀有类、常见类与频繁类 AP蒸馏权重feat_distill_weight越大模型越偏向蒸馏信号。官方 checkpoint 均托管于云存储下载地址见原文档表格。另外据论文报告使用 ResNet-50 骨干时 ViLD 取得 16.1 mask APr较有监督对照提升 3.8跨数据集零微调迁移结果为 PASCAL VOC 72.2 AP50、COCO 36.6 AP、Objects365 11.8 AP。八、推理Evaluation完整流程8.1 准备推理所需的三个输入下载 CLIP 文本嵌入 clip_synonym_prompt.npy 与稀有类二值掩码 lvis_rare_masks.npy放入[WEIGHTS_DIR]下载并解压上表任一预训练模型到[MODEL_DIR]将[RESNET_DEPTH]、[MODEL_DIR]、[DATA_DIR]、[DEST_DIR]、[WEIGHTS_DIR]、[CONFIG_FILE]替换为实际值。8.2 运行脚本BATCH_SIZE1 RESNET_DEPTH[RESNET_DEPTH] MODEL_DIR[MODEL_DIR] EVAL_FILE_PATTERN[DEST_DIR]/val* VAL_JSON_FILE[DATA_DIR]/lvis_v1_val.json RARE_MASK_PATH[WEIGHTS_DIR]/lvis_rare_masks.npy CLASSIFIER_WEIGHT_PATH[WEIGHTS_DIR]/clip_synonym_prompt.npy CONFIG_FILEtpu/models/official/detection/projects/vild/configs/[CONFIG_FILE] python3 tpu/models/official/detection/main.py \ --modelvild \ --model_dir${MODEL_DIR?} \ --modeeval \ --use_tpuFalse \ --config_file${CONFIG_FILE?} \ --params_override{ resnet: {resnet_depth: ${RESNET_DEPTH?}}, predict: {predict_batch_size: ${BATCH_SIZE?}}, eval: {eval_batch_size: ${BATCH_SIZE?}, val_json_file: ${VAL_JSON_FILE?}, eval_file_pattern: ${EVAL_FILE_PATTERN?} }, frcnn_head: {classifier_weight_path: ${CLASSIFIER_WEIGHT_PATH?}}, postprocess: {rare_mask_path: ${RARE_MASK_PATH?}}}8.3 参数含义与底层行为--modelvild由 main.py 决定加载 ViLD 参数模板与模型--modeeval触发评估--use_tpuFalse时 main.py 会强制关闭 bfloat16 与同步 BN因此纯 GPU/CPU 即可运行推理--config_file指向vild_resnet.yaml或vild_ensemble_resnet.yaml两者通过--params_override覆盖骨干深度、批大小、数据路径与两个.npy权重路径classifier_weight_path最终进入ViLDFastrcnnHead作为class-predict层核初始化并在归一化后参与打分rare_mask_path同时服务于frcnn_class_loss训练期掩码与后处理阶段的稀有类约束评估类型为lvis_box_and_mask输出 mask 与 box 双模态指标predict_batch_size与eval_batch_size保持一致即可示例取 1以降低显存占用。更完整的训练/评估流程可参考检测模块通用指南 GETTING_STARTED.md。九、Colab 交互演示仓库提供两种演示途径见 README.md在线 Colab原文档给出的ViLD_demo.ipynb托管版本本地 NotebookViLD_demo.ipynb。演示内置两个示例同时支持上传自己的图片并指定想检测的类别文本直观展示开放词汇检测能力。十、引用与说明本项目致谢部分明确说明教师模型使用 OpenAI 的 CLIP 模型整体代码构建于 Cloud TPU detection 框架之上。若在研究中引用 ViLD可按原文档给出的 BibTeX 条目引用Gu, Xiuye; Lin, Tsung-Yi; Kuo, Weicheng; Cui, Yin. Open-Vocabulary Detection via Vision and Language Knowledge Distillation. arXiv:2104.13921, 2021.。仓库许可证与 LICENSE 一致使用前请留意。结语ViLD 通过将 CLIP 的开放词汇能力蒸馏进两阶段检测器为开放词汇目标检测提供了一个可复现、可迁移的完整实现。本文沿着“原理 → 源码 → 配置 → 数据 → 推理”的路径覆盖了 vild/README.md 的全部实操内容并深入到 vild_model.py、vild_head.py、vild_config.py 等实现细节读者可按文中命令在本地或 Cloud TPU 上复现 LVIS 评测或将预训练模型直接用于自定义数据集的开放词汇检测。赞分享深度学习后端开发工具【免费下载链接】tpuReference models and tools for Cloud TPUs.项目地址https://gitcode.com/gh_mirrors/tpu/tpu点击查看免费下载相关推荐F-VLM 实战指南基于冻结视觉语言模型的开词汇目标检测JAX/FLAX 实现F VLM 实战指南基于冻结视觉语言模型的开词汇目标检测JAX/FLAX 实现 F VLMFrozen Vision Language Model是人工智能深度学习NLP计算机视觉强化学习MMDetection 中的 GLIP 实现指南视觉-语言联合预训练的开放词汇目标检测MMDetection 中的 GLIP 实现指南视觉 语言联合预训练的开放词汇目标检测 GLIPGrounded Language Image Pre tr人工智能计算机视觉深度学习模型评测Sentence Transformers 稀疏编码器知识蒸馏实战基于 SparseMarginMSELoss 训练 SPLADE 检索模型Sentence Transformers 稀疏编码器知识蒸馏实战基于 SparseMarginMSELoss 训练 SPLADE 检索模型 知识蒸馏是训练最人工智能NLPEmbedding微调机器学习上一篇为什么我劝你用 ZonyLrcToolsX 做歌词批量下载完整上手与避坑指南下一篇告别缺少 MSVCP140.dllVisualCppRedist AIO 一次装齐 2005-2022 全部 Visual C 运行库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考