企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 预训练

本文围绕 PaddleSeg 仓库中的 PanopticSeg 全景分割工具包 展开，系统讲解如何基于该工具包完成全景分割（Panoptic Segmentation）模型的安装、数据准备、配置、训练、评估、可视化与部署。读完本文，你将掌握 Mask2Former 与 Panoptic-DeepLab 两种模型的完整使用链路，理解pan_id编码协议、InfoDict数据管线与后处理器（Postprocessor）等工具包特有的机制，并能在自己的数据集上直接复现训练与推理流程。

一、全景分割与 PanopticSeg 工具包

1.1 什么是全景分割

全景分割是一种统一的图像解析任务，它将两个原本相互独立的子任务合二为一：

• 语义分割（Semantic Segmentation）：为图像中每个像素赋予一个类别标签；
• 实例分割（Instance Segmentation）：检测并分割出图像中的每一个目标实例。

在全景分割结果中，背景等 "stuff"（无定形区域）按语义类别划分，而前景 "thing"（可数目标）则进一步区分到实例级别，两者共享同一个标签体系。这一任务需要模型同时具备"逐像素分类"与"实例级区分"的能力，因此对网络结构、训练目标与后处理都有更高要求。

1.2 工具包定位与三大特点

PanopticSeg 是构建在 PaddleSeg 之上的全景分割工具包，围绕"开箱即用、低成本训练、全流程覆盖"三个目标设计：

• 高性能模型：内置可直接使用的全景分割模型（Mask2Former、Panoptic-DeepLab），并附带在公开数据集上训练好的权重；
• 高效率训练：支持多进程异步 I/O、多卡并行训练与评估等加速策略，并借助 PaddlePaddle 的内存优化功能，降低训练成本；
• 完整流程：覆盖从模型设计、数据准备、训练评估到模型部署的完整工作流。

从代码结构看，工具包以独立 Python 包paddlepanseg组织，核心 API（训练、评估、推理）位于 paddlepanseg/core，模型实现位于 paddlepanseg/models，用户入口脚本统一放在 tools 目录下（train.py、val.py、predict.py、export.py等），详见 开发者指南。

1.3 版本更新记录

依据工具包 README 的更新记录，2022 年 12 月新增了 Mask2Former 与 Panoptic-DeepLab 两个模型，这是目前工具包内置的两大主力模型，分别代表 Transformer 类与卷积类全景分割方案。

二、支持的模型与官方指标

工具包官方提供了两个模型的配置与预训练权重，模型专属说明位于：

• Mask2Former 模型文档
• Panoptic-DeepLab 模型文档

2.1 Mask2Former（COCO）

Mask2Former（Masked-Attention Mask Transformer for Universal Image Segmentation）以"掩码注意力 + Transformer 解码器"实现通用图像分割。官方文档报告的 COCO minival 验证集指标如下：

| 模型 | 骨干网络 | 输入分辨率 | 训练迭代数 | PQ | mIoU | mAP50 | |-|-|-|-|-|-|-| | Mask2Former | ResNet50-vd | 1024x1024 | 370k | 53.69% | 63.22% | 49.16% |

官方文档注明该模型使用 4 张 GPU 训练；该模型当前不支持导出为静态图，部署前请确认这一点。

由于 Mask2Former 依赖多尺度可变形注意力（Multi-Scale Deformable Attention）外部算子，使用前必须先编译安装 C++/CUDA 算子，详见模型文档中的前置要求：

cd paddlepanseg/models/ops cd ms_deform_attn python setup.py install

2.2 Panoptic-DeepLab（Cityscapes）

Panoptic-DeepLab 是自底向上的简单、强且快的全景分割基线。官方文档报告的 Cityscapes 验证集指标如下：

| 模型 | 骨干网络 | 输入分辨率 | 训练迭代数 | PQ | mIoU | mAP50 | |-|-|-|-|-|-|-| | Panoptic-DeepLab | ResNet50-vd | 1025x513 | 90k | 60.32% | 46.34% | 79.68% |

官方文档注明该模型使用 8 张 GPU 训练；训练时采用 1025x513 输入并设置align_corners: True可观察到更优性能。该模型支持导出与部署。

三、环境安装

3.1 基础依赖

依据 完整特性文档，安装前需满足：

• PaddlePaddle >= 2.4.0
• Python >= 3.7
• PaddleSeg >= 2.8

由于全景分割训练计算量大，官方强烈推荐安装 GPU 版 PaddlePaddle（CUDA 10.2 及以上）。

3.2 安装步骤

先克隆 PaddleSeg 仓库并安装其依赖：

# 安装 PaddleSeg 依赖 pip install -r requirements.txt # 安装 PaddleSeg pip install .

然后进入工具包目录，以可编辑（editable）模式安装：

cd PaddleSeg/contrib/PanopticSeg # 安装工具包依赖 pip install -r requirements.txt # 以可编辑模式安装全景分割工具包 pip install -e .

3.3 验证安装

python -c "import paddlepanseg; print(paddlepanseg.__version__)"

如果成功打印出版本号，说明安装完成。

四、数据集准备

4.1 公开数据集：Cityscapes 与 MS COCO

工具包为常用公开数据集提供了自动预处理脚本，详细用法见 tools/data/README.md。

Cityscapes 流程：从官网下载gtFine与leftImg8bit目录结构后，先用 cityscapesScripts 的createPanopticImgs.py生成全景标签（处理训练子集时必须指定--use-train-id），再生成文件列表并软链接到data/cityscapes：

python tools/data/create_cityscapes_file_lists.py --data_dir {数据集路径} --out_dir {数据集路径}

最终期望的目录结构包含train_list.txt、val_list.txt、cityscapes_panoptic_trainId、cityscapes_panoptic_val等（完整结构见 tools/data/README.md）。

MS COCO 流程：使用 2017 划分，目录包含annotations/panoptic_train2017.json、panoptic_val2017.json、panoptic_train2017、panoptic_val2017、train2017、val2017，然后运行：

python tools/data/create_coco_file_lists.py --data_dir {数据集路径} --out_dir {数据集路径}

最后将数据集软链接到data/coco。

4.2 自定义数据集与文件列表格式

工具包同时支持自定义数据集。与 PaddleSeg 一致，每个数据子集需要一个文件列表（file list），格式与 PaddleSeg 规则相同，差异仅在于第二列由"语义分割标签路径"换成"全景标签路径"（编码在 RGB 图像中）。文件列表每行由原始图像路径与全景标签路径以单个空格分隔：

val2017/000000001000.jpg panoptic_val2017/000000001000.png val2017/000000001268.jpg panoptic_val2017/000000001268.png val2017/000000001296.jpg panoptic_val2017/000000001296.png ...

全景标签必须编码为 RGB 图像，其中每个像素的 R、G、B 通道值由该像素所属区域（实例或 stuff 区域）的唯一标识符id决定：

r = id % 256 g = id // 256 % 256 b = id // (256 * 256) % 256

4.3 编码协议：理解pan_id

编码协议文档 定义了工具包统一的全景标签编码方式：全景分割图（无论是真值标签还是模型预测）中的每个像素都具有一个值pan_id。设类别数为c，最大实例数为n，则pan_id取值范围为0到c * label_divisor + n。

• thing 类：pan_id = (cat_id + 1) * label_divisor + ins_id，其中cat_id为类别 ID（从 0 开始），ins_id为实例 ID（从 1 开始）；
• stuff 类：pan_id = (cat_id + 1) * label_divisor；
• 未知标签：pan_id = 0。

label_divisor是预定义常量，默认值为1000（例如 Panoptic-DeepLab 配置 中通过&label_divisor 1000定义并被各模块复用）。这套协议也是后处理器输出与部署阶段id2rgb转换（见 deploy/python/infer.py）的基础。

五、编写配置文件

工具包沿用了 PaddleSeg 的模块化设计，数据集、模型、优化器等组件完全可配置，配置文件是设置训练、评估、部署超参数的推荐方式。除 PaddleSeg 的基本规则外，工具包针对全景分割任务提供了两个特有机制。

5.1 后处理器（Postprocessor）配置

后处理器负责将网络输出转换为最终的全景分割结果（即图像中所有实例 ID 与每个像素的语义类别）。通过配置文件中的postprocessor键值对构造：

postprocessor: type: MaskFormerPostprocessor num_classes: 19 object_mask_threshold: 0.8 overlap_threshold: 0.8 label_divisor: 1000 ignore_index: 255

所有后处理器共有四个通用属性：num_classes、thing_ids、label_divisor与ignore_index。如果这四个属性在配置文件中未配置，工具包会优先从val_dataset（同键名）解析取值，最后才使用预定义默认值。从源码看，所有后处理器均继承自 paddlepanseg/postprocessors/base_pp.py 中的抽象基类Postprocessor，其__call__方法统一将处理结果封装为InfoDict中的PPOutDict。

5.2Collect：必须存在的最后一个数据变换

工具包与 PaddleSeg 配置文件的一个显著区别是：所有数据变换必须以Collect结尾。原因是工具包采用基于InfoDict的预处理管线，Collect负责从InfoDict对象中挑出所需的键值对。

训练通常需要以下键：

| 键 | 含义 | |-|-| |img| 预处理后作为网络输入的图像 | |label| 预处理后的全景分割标签 | |img_path| 原始输入图像路径 | |lab_path| 全景分割真值标签路径 | |img_h/img_w| 原始图像的高 / 宽 |

评估通常还需要：

| 键 | 含义 | |-|-| |ann| 从 JSON 注解文件解析出的标注信息 | |image_id| 原始图像 ID | |gt_fields| 应被标记为真值图的InfoDict键 | |trans_info| 张量形状元信息，用于恢复图像原始尺寸 | |pan_label/sem_label/ins_label| 预处理后的全景 / 语义 / 实例标签 |

5.3 两个模型的完整配置剖析

以 Panoptic-DeepLab 的 Cityscapes 配置 为例，其训练数据变换链为：ConvertRGBToID（将 RGB 编码标签还原为 ID）→ResizeStepScaling（0.5~2.0 倍步进缩放）→RandomPaddingCrop（裁剪 1025x513）→RandomHorizontalFlip→RandomDistort→GeneratePanopticDeepLabTrainTargets（生成 center/offset 等训练目标，sigma: 8、small_instance_area: 4096、small_instance_weight: 3）→Normalize→Collect。模型部分使用 ResNet50-vd 骨干（output_stride: 32）配合 ASPP 与双解码器（语义分支aspp_out_channels: 256、实例分支instance_num_classes: [1, 2]分别预测 center 与 offset）；损失为分类的CrossEntropyLoss（top_k_percent_pixels: 0.2）加 center 与 offset 的L1Loss，系数coef: [1, 200, 0.01]；后处理器PanopticDeepLabPostprocessor的关键参数包括stuff_area: 2048、threshold: 0.1、nms_kernel: 7、top_k: 200；优化器为 Adam，学习率采用PolynomialDecay（初始 0.0005、power: 0.9、1000 步 warmup）。

Mask2Former 的 COCO 配置 则展示了 Transformer 系模型的特点：骨干输出 stride 16 配合backbone_indices: [1, 2, 3]；像素解码器pd_num_layers: 6、pd_ff_dim: 1024；Transformer 解码器td_num_layers: 9、td_ff_dim: 2048、td_num_heads: 8、num_queries: 100；损失通过 runner 配置 CE / mask / dice 权重（weight_ce: 2.0、weight_mask: 5.0、weight_dice: 5.0）并启用num_points: 12544的点采样；优化器为 AdamW（weight_decay: 0.05、backbone 学习率乘 0.1、梯度裁剪clip_norm: 0.01），学习率采用MultiStepDecay。

六、模型训练、评估与可视化

6.1 训练模型

基础训练命令为：

python tools/train.py \ --config {CONFIG_PATH}

命令行参数优先级高于配置文件，便于临时覆盖设置。以 tools/train.py 源码为准，常用参数包括：

| 参数 | 说明 | |-|-| |--config| 配置文件路径（必填） | |--save_dir| 模型 checkpoint 保存目录（默认./output） | |--num_workers| 数据预取子进程数（默认 0） | |--do_eval| 训练期间周期性评估模型 | |--log_iters| 每隔log_iters显示一次日志（默认 10） | |--eval_sem| 验证时计算语义分割指标（如 mIoU） | |--eval_ins| 验证时计算实例分割指标（如 mAP） | |--debug| 调试模式，异常处设置 pdb 断点便于事后调试 | |--precision/--amp_level| 混合精度训练（fp16，AMP O1/O2） | |--device| 训练设备：cpu / gpu / xpu / npu / mlu | |--opts| 直接更新配置文件中已有键值对 |

默认不将日志写入文件，可通过 shell 重定向方便落盘，例如训练 Mask2Former：

TAG='mask2former' python tools/train.py \ --config configs/mask2former/mask2former_resnet50_os16_coco_1024x1024_bs4_370k.yml \ --log_iters 50 \ --num_workers 4 \ --do_eval \ --eval_sem \ --eval_ins \ --save_dir "output/${TAG}" \ 2>&1 \ | tee "output/train_${TAG}.log"

多卡分布式训练使用paddle.distributed.launch：

# 设置使用的设备 ID export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 python -m paddle.distributed.launch tools/train.py \ --config {CONFIG_PATH}

注意：部分模型存在前置条件（如 Mask2Former 需先编译外部 C++/CUDA 算子），详见各模型文档。

6.2 评估模型

训练期间与训练结束后，--save_dir指定的目录下会保存模型 checkpoint（含权重与可能的优化器状态）。官方推荐评估在验证集上取得最高全景质量（PQ）的 checkpoint（即output/best_model）：

python tools/val.py \ --config {CONFIG_PATH} \ --model_path output/best_model/model.pdparams

若同时设置--eval_sem与--eval_ins，还会额外报告语义分割指标（mIoU）与实例分割指标（mAP），但会显著延长评估时间。可用python tools/val.py --help查看全部选项。

6.3 快速体验：用预训练模型推理

参照 快速开始文档，下载 Panoptic-DeepLab 的预训练权重（model.pdparams）与示例图片（demo.png）并放到项目根目录后，执行：

mkdir -p vis python tools/predict.py \ --config configs/panoptic_deeplab/panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml \ --model_path model.pdparams \ --image_path demo.png \ --save_dir vis

tools/predict.py的四个核心参数为--config、--model_path、--image_path（单张图片或图片目录）与--save_dir（默认./output/result）。从 predict.py 源码 可以看到，推理流程会基于val_dataset的变换自动构建测试变换（constr_test_transforms），并利用val_dataset提供的label_divisor、ignore_index与 colormap 完成可视化。

6.4 三种可视化输出

每张输入图片会生成三个前缀相同的结果图：

• {PREFIX}_sem.png：语义视角，每个像素的颜色代表语义类别；
• {PREFIX}_ins.png：实例视角，不同颜色代表不同实例；对于 stuff 类别，该类的所有像素视为同一个实例；
• {PREFIX}_pan.png：全景视角，不同基色标记不同语义类别；对于 thing 类别，为区分不同实例，会在基色上叠加唯一的颜色偏移。

七、模型部署

动态图推理通常效率偏低，官方推荐将模型转换为静态图后进行推理（注意并非所有模型都支持导出，如 Mask2Former 当前不支持，详见 模型文档）。

7.1 导出静态图模型

python tools/export.py \ --config {CONFIG_PATH} \ --model_path {MODEL_PATH} \ --save_dir {导出模型保存目录} \ --input_shape {输入张量的固定形状}

导出详情参考 PaddleSeg 的模型导出文档。从 Panoptic-DeepLab 配置 可以看到，导出使用的变换（Resize到 2049x1025 →Normalize→Collect）也独立配置在export字段下。

7.2 基于 Paddle-Inference 的推理

使用 deploy/python/infer.py 基于 Paddle-Inference API 执行推理：

python deploy/python/infer.py \ --config {DEPLOY_CONFIG_PATH} \ --image_path {单张图片或目录路径}

其中{DEPLOY_CONFIG_PATH}指向导出模型目录下的deploy.yaml。

推理输出是一张 RGB 图像，像素值遵循编码协议：

r = pan_id % 256 g = pan_id // 256 % 256 b = pan_id // (256 * 256) % 256

其中pan_id是网络与后处理器给出的、代表图像中某实例（thing 类）或 stuff 区域的唯一标识符（对应实现见 paddlepanseg/transforms/functional.py 中的id2rgb）。此外，infer.py 还提供了丰富的推理加速选项：GPU 下可用--use_trt启用 TensorRT（支持 fp32 / fp16 / int8 精度与--enable_auto_tune自动收集动态形状），CPU 下可用--cpu_threads与--enable_mkldnn加速，--benchmark可输出推理性能报告。

八、源码级机制解析与二次开发

8.1InfoDict数据管线

InfoDict是工具包最核心、且 PaddleSeg 中不存在的数据结构（定义于 paddlepanseg/cvlibs/info_dicts.py），作为样本、预测结果等的统一容器，内置四种类型：

| 类型 | 用途 | |-|-| |SampleDict| 存放数据样本的信息与元信息 | |NetOutDict| 存放网络输出 | |PPOutDict| 存放后处理器输出 | |MetricDict| 存放Evaluator对象调用evaluate()的输出 |

推荐通过工厂函数build_info_dict()构造，传入_type_参数（'sample'、'net_out'、'pp_out'、'metric'）指定类型。

8.2 数据集定制

推荐将自定义数据集组织为 MS COCO 格式，并继承paddlepanseg.datasets.base_dataset.COCOStylePanopticDataset编写新数据集接口，通常包含以下步骤（详见 开发者指南）：

1. 将数据集元信息存入 dict 列表，参考 cityscapes.py 中的CITYSCAPES_CATEGORIES；
2. 定义继承COCOStylePanopticDataset的类，设置类属性CATEGORY_META_INFO与NUM_CLASSES；
3. 重写静态方法_get_image_id()，根据图片路径返回唯一标识；
4. 用装饰器paddlepanseg.cvlibs.manager.DATASETS.add_component()注册新数据集类。

8.3 目录结构与测试支撑

工具包目录遵循清晰的模块划分：configs（按模型组织的配置）、deploy（部署代码）、paddlepanseg（核心实现，含core、cvlibs、datasets、models、postprocessors、runners、transforms、utils）、tools（用户工具脚本）与test_tipc（TIPC 训练推理一体化测试脚本，为 Mask2Former 与 Panoptic-DeepLab 分别提供train_infer_python.txt与配套 yml 配置，可用于端到端流程验证）。这些目录结构在 开发者指南 中有完整说明，是理解工具包内部调用关系与二次开发的最佳入口。

九、常见问题与社区支持

• 模型前置条件（如算子编译、导出限制）以configs下各模型 README 为准；
• 训练/评估/预测脚本的完整参数列表可通过python tools/train.py --help、python tools/val.py --help、python tools/predict.py --help查看；
• 如遇到问题或有功能建议，可在 PaddleSeg 的 GitHub Issues 中反馈，也可加入 PaddleSeg 微信交流群与社区沟通（联系方式见 工具包 README）。

总而言之，PanopticSeg 将全景分割这一复杂任务所需的模型、数据、训练与部署环节封装为一套与 PaddleSeg 风格一致的完整工作流。从 Mask2Former 与 Panoptic-DeepLab 的开箱即用，到pan_id编码协议与InfoDict管线的可扩展设计，再到多卡训练与 Paddle-Inference 部署的工程化支撑，它为全景分割的研究与落地提供了一条低门槛、可复现的实践路径。

• 人工智能
• 计算机视觉
• 预训练