企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习
• 预训练
• 微调

在 Vision Mamba（Vim）项目的检测分支（det/）中，模型训练与评估依赖一套完整的 Detectron2 数据基础设施。本文以 det/docs/tutorials/builtin_datasets.md 为骨架，结合仓库源码（det/detectron2/data/catalog.py、det/detectron2/data/datasets/builtin.py等），系统讲解内置数据集的目录结构、环境变量配置、六大数据集的准备流程，以及数据准备脚本背后的实现原理。读完本文，你将能够独立搭建 COCO、LVIS、Cityscapes、Pascal VOC、ADE20K 与 PanopticFPN 所需的数据目录，并理解DatasetCatalog/MetadataCatalog的注册与读取机制，从而顺利运行仓库提供的训练与评估脚本。

一、数据集访问的两大入口：DatasetCatalog 与 MetadataCatalog

在det/的 Detectron2 框架中，任何数据集都通过两个全局注册表被访问：

• DatasetCatalog：存储"数据集名字 → 解析函数"的映射，调用get(name)时会执行注册的解析函数，返回list[dict]格式的样本列表（每个 dict 描述一张图片及其标注）；
• MetadataCatalog：存储数据集的元信息（如类别名称thing_classes、评估器类型evaluator_type等）。

两者的实现位于 det/detectron2/data/catalog.py：

• _DatasetCatalog.register(name, func)要求func是无参数可调用对象且多次调用返回相同结果（catalog.py 的 register 实现）；
• _DatasetCatalog.get(name)在名字未注册时会抛出KeyError并列出所有已注册数据集（catalog.py 的 get 实现）；
• Metadata对象是单例：首次MetadataCatalog.get(name)会创建并常驻内存，后续调用返回同一实例，同一属性不允许被赋成不同值（catalog.py 的 Metadata 实现）。

内置数据集的注册入口在 det/detectron2/data/datasets/builtin.py：该文件在__name__.endswith(".builtin")时读取环境变量DETECTRON2_DATASETS（默认"datasets"），并依次调用register_all_coco、register_all_lvis、register_all_cityscapes、register_all_cityscapes_panoptic、register_all_pascal_voc、register_all_ade20k完成全部内置数据集注册（builtin.py 的注册入口）。例如 COCO 的预定义切分表_PREDEFINED_SPLITS_COCO把coco_2017_train、coco_2017_val等名字映射到(图片目录, 标注 json)元组（builtin.py 的 COCO 切分表）。

二、数据集根目录与环境变量 DETECTRON2_DATASETS

所有内置数据集都假定存放在由环境变量DETECTRON2_DATASETS指定的根目录下，其期望的顶层结构为：

$DETECTRON2_DATASETS/ coco/ lvis/ cityscapes/ VOC20{07,12}/

配置方式：

export DETECTRON2_DATASETS=/path/to/datasets

若不设置该变量，默认值为当前工作目录下的./datasets（见 builtin.py 第 253 行 的os.path.expanduser(os.getenv("DETECTRON2_DATASETS", "datasets"))）。因此从det/目录启动训练时，最简单的方式就是把数据放在det/datasets/下。

仓库中引用这些内置数据集的模型配置可参考 det/MODEL_ZOO.md，而det/configs/下的 YAML 配置（如 det/configs/COCO-Detection/faster_rcnn_R_50_FPN_1x.yaml、det/configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml）中的DATASETS.TRAIN/DATASETS.TEST字段即填写上述注册名（如("coco_2017_train",)、("coco_2017_val",)）。

三、COCO 实例 / 关键点检测数据集

3.1 期望的目录结构

从 COCO 官网下载页面（此处仅作来源说明，命令以仓库为准）获取标注与图片后，需整理为：

coco/ annotations/ instances_{train,val}2017.json person_keypoints_{train,val}2017.json {train,val}2017/ # 与对应 json 中提及的图片文件

同样支持使用 2014 版数据集：把train2014/val2014图片目录与instances_train2014.json等标注文件放入coco/即可。从源码看，2014 版还预定义了coco_2014_minival与coco_2014_valminusminival切分（builtin.py 的 COCO 2014 切分）。

3.2 加载原理与注册实现

COCO 格式标注由 det/detectron2/data/datasets/coco.py 中的load_coco_json解析。关键行为包括：

• 通过pycocotools.coco.COCO读取 json，并按图片 id 排序保证结果可复现（coco.py 的排序逻辑）；
• 当传入dataset_name时，自动从 json 的categories字段生成thing_classes，并把非连续的真实类别 id 映射为[0, 类别数)的连续 id，存入thing_dataset_id_to_contiguous_id（coco.py 的类别映射）；
• 过滤点数不足的多边形（少于 3 个顶点）实例，将 bbox 标记为BoxMode.XYWH_ABS，关键点坐标加 0.5 以从像素索引转换为浮点坐标（coco.py 的标注处理）。

注册函数register_coco_instances将"名字 → 加载函数"写入DatasetCatalog，同时把json_file、image_root、evaluator_type="coco"等写入MetadataCatalog（coco.py 的 register_coco_instances）。

3.3 快速测试数据集

内置的若干测试脚本（det/dev/run_*_tests.sh）使用一个仅含 100 张图片的迷你 COCO 数据集，可通过 det/datasets/prepare_for_tests.sh 一键下载：

# 在 det/ 目录下执行 ./datasets/prepare_for_tests.sh

该脚本会从 Detectron2 的公共文件服务器下载instances_val2017_100.json、person_keypoints_val2017_100.json与val2017_100.tgz（解压后得到coco/val2017图片目录），并写入$DETECTRON2_DATASETS/coco/annotations/（未设置环境变量时即./coco/annotations/）。已存在的文件会被自动跳过（prepare_for_tests.sh 的下载逻辑）。val2017_100切分也在 builtin.py 的切分表 中预注册，方便快速跑通训练与评估流程。

四、PanopticFPN 全景分割数据集

4.1 期望的目录结构

从 COCO 官网下载全景标注后，需整理为：

coco/ annotations/ panoptic_{train,val}2017.json panoptic_{train,val}2017/ # png 标注 panoptic_stuff_{train,val}2017/ # 由脚本生成

安装panopticapi工具包：

pip install git+https://github.com/cocodataset/panopticapi.git

随后在det/目录下执行 det/datasets/prepare_panoptic_fpn.py：

python datasets/prepare_panoptic_fpn.py

4.2 脚本原理：从全景标注生成语义标注

separate_coco_semantic_from_panoptic函数把 COCO 全景标注转换为 PanopticFPN 所需的语义分割标注（prepare_panoptic_fpn.py 的核心实现），其映射规则是：

• 所有 thing（物体）类别映射为类别 0；
• 所有 stuff（背景）类别映射为从 1 开始的连续 id；
• 未标注像素（id 0）映射为 255（忽略标签）。

实现上先读取panoptic_{train,val}2017.json，用panopticapi.utils.rgb2id把 RGB 编码的 png 还原为 id 矩阵，再按segments_info逐段写入输出目录，并通过multiprocessing.Pool并行处理加速（prepare_panoptic_fpn.py 的逐段写入）。脚本最后还会下载panoptic_val2017_100.json并通过符号链接生成panoptic_val2017_100与panoptic_stuff_val2017_100迷你验证集（prepare_panoptic_fpn.py 的 100 张验证集逻辑）。

注册层面，builtin.py 同时注册了两种全景变体：

• register_coco_panoptic_separated：使用panoptic_stuff_*语义标注的分离式版本，供 PanopticFPN 使用；
• register_coco_panoptic：标准版本，供 Panoptic-DeepLab 等使用（可参考 det/projects/Panoptic-DeepLab）。

五、LVIS 长尾实例分割数据集

5.1 期望的目录结构

LVIS 复用 COCO 的图片，标注文件独立存放：

coco/ {train,val,test}2017/ lvis/ lvis_v0.5_{train,val}.json lvis_v0.5_image_info_test.json lvis_v1_{train,val}.json lvis_v1_image_info_test{,_challenge}.json

安装 lvis-api：

pip install git+https://github.com/lvis-dataset/lvis-api.git

注意 LVIS 图片路径依赖 json 中的coco_url字段，加载器从该 URL 的最后两段解析出train2017/val2017/test2017子目录并拼接图片路径（lvis.py 的 get_file_name），因此 LVIS 图片必须按上列结构放入coco/下。

5.2 加载器与元数据

det/detectron2/data/datasets/lvis.py 中的load_lvis_json通过lvis.LVIS解析标注，处理not_exhaustive_category_ids、neg_category_ids等 LVIS 特有字段，并将 1 起始的类别 id 减 1 转为 0 起始（lvis.py 的标注解析）。内置元数据由get_lvis_instances_meta提供：v0.5 有 1230 类、v1 有 1203 类，类别名取自官方 json 的同义词首项，v1 还附带类别图像计数（lvis.py 的元数据）。

5.3 COCOfied LVIS：用 COCO 指标评估 LVIS 模型

如需用 COCO 标注训练出的模型在 LVIS 标注上评估，运行 det/datasets/prepare_cocofied_lvis.py：

python datasets/prepare_cocofied_lvis.py

脚本通过 WordNet synset 映射表（COCO_SYNSET_CATEGORIES，prepare_cocofied_lvis.py 的映射表）把 LVIS 类别过滤并重映射为 COCO 类别 id，输出lvis_v0.5_{train,val}_cocofied.json。过滤原则是：剔除所有不在 COCO 中的类别，保留与 COCO 有实例交集的类别，并同步改写每张图片的not_exhaustive_category_ids与neg_category_ids（prepare_cocofied_lvis.py 的 cocofy_lvis）。生成的lvis_v0.5_train_cocofied/lvis_v0.5_val_cocofied名字在 builtin.py 的 LVIS 切分表 中预注册。

六、Cityscapes 城市街景数据集

6.1 期望的目录结构

Cityscapes 同时支撑实例分割、语义分割与全景分割三种任务，目录结构为：

cityscapes/ gtFine/ train/ aachen/ color.png, instanceIds.png, labelIds.png, polygons.json, labelTrainIds.png ... val/ test/ # 以下为生成的 Cityscapes 全景标注 cityscapes_panoptic_train.json cityscapes_panoptic_train/ cityscapes_panoptic_val.json cityscapes_panoptic_val/ cityscapes_panoptic_test.json cityscapes_panoptic_test/ leftImg8bit/ train/ val/ test/

安装 cityscapes 官方脚本：

pip install git+https://github.com/mcordts/cityscapesScripts.git

6.2 生成 labelTrainIds 与全景标注

生成labelTrainIds.png（语义分割训练需要，实例分割不需要）：

CITYSCAPES_DATASET=/path/to/abovementioned/cityscapes python cityscapesscripts/preparation/createTrainIdLabelImgs.py

生成 Cityscapes 全景标注（语义与实例分割不需要）：

CITYSCAPES_DATASET=/path/to/abovementioned/cityscapes python cityscapesscripts/preparation/createPanopticImgs.py

6.3 加载器行为

det/detectron2/data/datasets/cityscapes.py 中的load_cityscapes_instances会：

• 遍历leftImg8bit/<split>/<city>/下的图片，按文件名前缀匹配gtFine_instanceIds.png、gtFine_labelIds.png与gtFine_polygons.json（cityscapes.py 的文件匹配）；
• 从 json 读取多边形标注，用多进程预处理（进程数取max(cpu_count / world_size / 2, 4)）；
• 借助cityscapesscripts.helpers.labels把原始 id 映射为连续 id（cityscapes.py 的 id 映射）。

load_cityscapes_semantic则把labelIds替换为labelTrainIds作为语义标注文件，并将ignore_label设为 255（cityscapes.py 的语义加载）。注册后的数据集名为cityscapes_fine_instance_seg_{train,val,test}与cityscapes_fine_sem_seg_{train,val,test}（builtin.py 的 Cityscapes 注册）。

七、Pascal VOC 检测数据集

7.1 期望的目录结构

VOC20{07,12}/ Annotations/ ImageSets/ Main/ trainval.txt test.txt # 如使用 train/val 切分，还需要 train.txt 或 val.txt JPEGImages/

其中ImageSets/Main/*.txt每行是一个不含扩展名的图片文件名（如000001），Annotations/下是对应的 XML 标注，JPEGImages/下是对应的.jpg图片。

7.2 加载器与预注册切分

det/detectron2/data/datasets/pascal_voc.py 中的load_voc_instances通过numpy.loadtxt读取 split 文件，用xml.etree.ElementTree解析每个 XML：bbox 坐标减 1.0 从 1 起始像素索引转为 0 起始坐标，类别用CLASS_NAMES元组的索引作为连续 id（pascal_voc.py 的解析逻辑）。CLASS_NAMES是 VOC 的 20 个标准类别（pascal_voc.py 的类别表）。

builtin.py 预注册了voc_2007_trainval、voc_2007_train、voc_2007_val、voc_2007_test以及 2012 版对应的四个切分，评估器统一为pascal_voc。仓库中的相关配置示例见 det/configs/PascalVOC-Detection/faster_rcnn_R_50_C4.yaml。

八、ADE20K 场景解析数据集

8.1 期望的目录结构

ADEChallengeData2016/ annotations/ annotations_detectron2/ images/ objectInfo150.txt

其中annotations_detectron2目录由脚本生成，原始下载的annotations/与images/内需包含training与validation两个子目录（分别对应ade20k_sem_seg_train与ade20k_sem_seg_val切分）。

8.2 生成 annotations_detectron2

运行 det/datasets/prepare_ade20k_sem_seg.py：

python datasets/prepare_ade20k_sem_seg.py

脚本把annotations/{training,validation}下原始 uint8 语义标注的每个像素值减 1：原标签 0（ignore）变成 255，其余类别整体平移 1，结果写入annotations_detectron2/{training,validation}（prepare_ade20k_sem_seg.py 的转换逻辑）。这一转换与 Detectron2 语义分割约定的 0 起始连续标签（255 为忽略）保持一致。

8.3 注册与加载

builtin.py 的 register_all_ade20k 为 train / val 两个切分注册：

• 图片根目录ADEChallengeData2016/images/{training,validation}，图片扩展名.jpg；
• 标注根目录ADEChallengeData2016/annotations_detectron2/{training,validation}，标注扩展名.png；
• 元数据包含 150 个 stuff 类别（ADE20K_SEM_SEG_CATEGORIES，定义于 det/detectron2/data/datasets/builtin_meta.py）、evaluator_type="sem_seg"、ignore_label=255。

实际解析由 coco.py 的 load_sem_seg 完成：它基于相对路径（不含扩展名）匹配图片与标注；若两侧文件数量不一致，会取两者的交集并给出告警日志——这一设计也使得val2017_100迷你标注可以配合完整val2017图片使用。

九、数据就绪后的验证与运行

数据目录准备完成后，可以通过以下方式快速验证注册是否生效：

# 从 det/ 目录运行，确认 COCO 等数据集已注册 python -c "import detectron2.data.datasets; from detectron2.data import DatasetCatalog; print(len(DatasetCatalog.list())); print(DatasetCatalog.list()[:10])"

也可直接以模块方式可视化某个数据集，例如 coco.py 的模块入口 支持：

python -m detectron2.data.datasets.coco /path/to/instances_val2017.json /path/to/val2017 coco_2017_val

该命令会加载指定 json，并用Visualizer把标注画到图片上输出到coco-data-vis/目录，便于人工核对数据准备是否正确。LVIS 加载器也有类似的独立入口（lvis.py 的模块入口）。

随后即可使用仓库配置进行训练与评估，例如 Vision Mamba 检测配置位于 det/configs/common/models/mask_rcnn_vimdet.py，配合 det/scripts/ft_vim_tiny_vimdet.sh 与 det/scripts/eval_vim_tiny_vimdet.sh 运行。注意脚本中DATASETS.TRAIN/DATASETS.TEST指向的数据集名必须与DETECTRON2_DATASETS根目录下的实际数据一一对应，否则DatasetCatalog.get会直接抛出未注册异常。

十、常见问题排查要点

1. "Dataset 'xxx' is not registered!"：说明该名字未在 builtin.py 中预注册，或注册代码未被 import（需要import detectron2.data.datasets触发注册）；可从异常信息中列出的已注册列表核对拼写。
2. "No annotations found in ..."：load_sem_seg在标注目录为空时直接断言失败，请检查annotations_detectron2或panoptic_stuff_*是否已由脚本生成。
3. 类别 id 不连续告警：load_coco_json对非 1 起始、非连续的类别 id 会自动做映射并打印警告（coco.py 的映射告警），这是正常行为，但建议使用官方 json 以避免歧义。
4. 符号链接失效：prepare_panoptic_fpn.py生成*_100目录时使用相对符号链接，请勿移动coco/目录的层级结构。
5. 大文件下载中断：prepare_for_tests.sh会跳过已存在的目标文件，可安全重跑续传。

通过以上步骤，即可为 Vision Mamba 项目的检测与分割实验搭建完整、可复现的数据环境。

• 人工智能
• 计算机视觉
• 深度学习
• 预训练
• 微调