企业官网建设流程全解析

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

本文是 PaddleSeg 全景分割工具箱（位于仓库 contrib/PanopticSeg）的快速开始指南。工具箱基于 PaddleSeg 打造，将语义分割与实例分割统一为全景分割任务，提供 Mask2Former、Panoptic-DeepLab 等前沿模型的训练、验证与部署全流程能力。读完本文，你将能够完成从环境安装、下载预训练权重执行单图预测、解读三类可视化结果，到数据集准备、模型训练、多卡并行训练与 PQ/mIoU/mAP 精度评估的完整实操闭环。

一、环境准备与工具箱安装

1.1 版本要求

根据 完整功能文档 的说明，本工具箱对运行环境有明确的版本约束：

由于模型训练需要较高算力，建议安装 GPU 版本的 PaddlePaddle。PaddlePaddle 的详细安装教程请参考其官方安装文档。

1.2 安装 PaddleSeg 与全景分割工具箱

首先拉取 PaddleSeg 项目（默认获取最新发行版本），切换到项目根目录后安装 PaddleSeg 本体：

git clone https://github.com/PaddlePaddle/PaddleSeg cd PaddleSeg # 安装 PaddleSeg 所需依赖 pip install -r requirements.txt # 从源码安装 PaddleSeg pip install .

接着进入全景分割工具箱目录，以可编辑模式安装：

cd PaddleSeg/contrib/PanopticSeg # 安装依赖 pip install -r requirements.txt # 以可编辑模式安装 pip install -e .

其中pip install -e .依赖工具箱根目录下的 setup.py，可编辑安装便于在开发过程中即时生效代码改动。

1.3 检查安装情况

执行如下指令验证安装是否成功：

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

若能打印出版本号，则证明工具箱安装成功，可以进入下一步。

二、使用预训练模型进行预测

2.1 下载预训练模型权重与示例数据

官方文档提供了可直接使用的预训练权重与示例图像，请分别下载并放置于项目根目录（即contrib/PanopticSeg目录）：

• 预训练模型权重model.pdparams：Panoptic-DeepLab（ResNet50、os32、Cityscapes 1025x513、bs8、90k 迭代）的训练权重；
• 示例图像demo.png：用于演示预测效果的示例图片。

2.2 执行预测

在contrib/PanopticSeg目录下，先创建可视化结果输出目录，再执行预测命令：

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加载配置文件、由make_default_builder统一构建模型与后处理器，再调用paddlepanseg.core.predict完成推理；--save_dir在源码中的默认值为./output/result。这意味着即使不显式指定--save_dir，结果也会落到默认目录。

2.3 观察可视化结果

预测完成后，对输入图像demo.png，vis目录下会生成三个可视化结果文件，分别从语义、实例、全景三个角度呈现预测：

• demo_sem.png（语义分割视角）：用不同颜色表示不同的语义类别，与常规语义分割可视化一致；
• demo_ins.png（实例分割视角）：用不同颜色表示不同的实例，其中 stuff 类别（如天空、道路等背景区域）的所有像素被当作一个实例整体呈现；
• demo_pan.png（全景分割视角）：用不同的基准颜色表示不同的语义类别，在此基础上为每个实例叠加颜色偏移以区分不同实例，是语义与实例信息的融合视图。

关于可视化结果的具体生成逻辑与pan_id编码协议，可参考 编码协议文档 与 完整功能文档。

三、模型训练

3.1 准备数据集

工具箱支持在公开数据集或自定义数据集上训练与评估：

• 公开数据集：工具箱预置了自动化预处理脚本，可对部分公开全景分割数据集生成 file list，详见 tools/data/README.md。例如 Cityscapes 的 file list 生成脚本位于 create_cityscapes_file_lists.py，COCO 的对应脚本位于 create_coco_file_lists.py；
• 自定义数据集：需要手动编写 file list。file list 每行包含一对以空格分隔的路径：第一条指向原始图像，第二条指向全景分割标签。示例：

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 通道值按下式计算：

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

其中id是能够唯一标识图像中一个实例或一个 stuff 区域的标识符。同时，还需提供 JSON 格式的全景分割标注文件（如 Cityscapes 的cityscapes_panoptic_train_trainId.json），配置文件中的json_path即指向该文件。

3.2 确认配置文件

训练前需确认使用的配置文件。工具箱预置的所有配置均存放在 configs 目录下，当前支持两类模型：

• Panoptic-DeepLab：panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml，详见 模型说明；
• Mask2Former：mask2former_resnet50_os16_coco_1024x1024_bs4_370k.yml，详见 模型说明。

3.3 执行训练

以 Panoptic-DeepLab 为例，训练命令如下：

python tools/train.py \ --config configs/panoptic_deeplab/panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml \ --do_eval \ --save_dir output

其中--do_eval表示在训练过程中周期性评估模型精度，--save_dir output指定训练结果（模型权重等）的保存目录。tools/train.py支持的完整命令行选项可通过python tools/train.py --help查看，部分重要选项如下：

多卡并行训练：指定 GPU 编号并使用paddle.distributed.launch启动：

# 指定要使用的 GPU 编号 export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 python -m paddle.distributed.launch tools/train.py \ --config {配置文件路径}

保存训练日志：如需将日志落盘，可采用如下组合（以 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"

3.4 模型前置条件说明

请注意，某些模型可能包含『前置条件』。例如，Mask2Former 在训练、评估前可能需要编译外部 C++/CUDA 算子——其可变形注意力模块的算子源码位于 paddlepanseg/models/ops/ms_deform_attn（含.cc、.cu实现与 setup.py）。请在对应config目录下的 README.md 中细节。

四、评估模型精度指标

4.1 评估命令

训练过程中或训练完成后，--save_dir指定目录（默认为output）下会存储模型权重等训练结果。其中output/best_model保存的是验证集上PQ 指标最高的模型权重，可对其执行精度评估：

python tools/val.py \ --config configs/panoptic_deeplab/panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml \ --model_path output/best_model/model.pdparams \ --eval_sem \ --eval_ins

也可通过修改--model_path对其他模型权重进行精度评估，python tools/val.py --help可查看完整选项列表。

4.2 指标说明

• 默认仅计算全景分割指标，如PQ（Panoptic Quality，全景质量，出自 CVPR 2019 论文《Panoptic Segmentation》）；
• 指定--eval_sem后额外计算语义分割指标，如mIoU；
• 指定--eval_ins后额外计算实例分割指标，如mAP。

需要留意，同时开启语义与实例指标评估会延长评估耗时。

五、配置进阶：后处理器与 Collect 算子

5.1 配置文件基本规则

工具箱采用模块化设计，将数据集、模型、损失、优化器等定义为完全可配置的组件，推荐通过 YAML 配置文件统一设置超参数。由于工具箱基于 PaddleSeg API 实现，配置文件的基本编写规则与 PaddleSeg 一致（锚点引用、组件type字段等语法可参考 PaddleSeg 配置文档）。以 Panoptic-DeepLab 的配置文件为例，其顶层包含train_dataset、val_dataset、model、optimizer、lr_scheduler、loss、postprocessor、runner、export等键，并通过 YAML 锚点（如&num_classes 19）在各组件间共享num_classes、ignore_index、label_divisor等关键值。

5.2 后处理器（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 定义通用接口，panoptic_deeplab_pp.py 与 maskformer_pp.py 分别实现两种模型的后处理逻辑。以 PanopticDeepLabPostprocessor 为例，其处理流程可概括为：对语义分支输出做 softmax 得到sem_pred→ 通过阈值过滤与 NMS（nms_kernel、top_k）从 center heatmap 中提取实例中心 → 结合偏移量（offset）将像素分组归属到各实例中心 → 通过多数投票将 thing 区域粘贴为实例 ID、将面积不小于stuff_area的 stuff 区域填充为语义类别，最终得到全景图。配置文件 panoptic_deeplab 配置 中对应的后处理参数为：

postprocessor: type: PanopticDeepLabPostprocessor num_classes: *num_classes label_divisor: *label_divisor stuff_area: 2048 threshold: 0.1 nms_kernel: 7 top_k: 200 ignore_index: *ignore_index

5.3 Collect 算子

与 PaddleSeg 不同，本工具箱的所有数据变换（transforms）配置均需以Collect算子结尾。这是因为其数据预处理基于InfoDict机制（详见 开发指南），Collect算子负责从InfoDict对象中提取后续流程需要的键值对。

• 训练阶段一般提取：img（预处理后的模型输入）、label（预处理后的参考标签）、img_path、lab_path、img_h、img_w；
• 评估阶段一般提取：img、label、ann（从 JSON 标注解析的标注信息）、image_id、gt_fields（标记哪些项为参考标签）、trans_info（用于恢复图像尺寸的张量形状元信息）、img_path、lab_path、pan_label、sem_label、ins_label。

不同模型还会追加模型专属的键：Panoptic-DeepLab 的训练变换中还需收集center、offset、sem_seg_weights、center_weights、offset_weights（由GeneratePanopticDeepLabTrainTargets生成）；Mask2Former 的训练变换则收集gt_ids、gt_masks（由GenerateMaskFormerTrainTargets生成），并需要在train_dataset中通过no_collation_keys声明这两个键不参与默认批量化拼接。

六、模型部署

6.1 导出静态图模型

为获得更高的推理效率，部署阶段推荐将模型转换为静态图格式：

python tools/export.py \ --config {配置文件路径} \ --model_path {模型路径} \ --save_dir {导出模型保存路径} \ --input_shape {输入张量形状}

请注意，部分全景分割模型目前尚不支持导出为静态图格式，请参考configs中的相关文档确认模型是否支持导出。导出时使用的预处理变换由配置文件的export.transforms字段定义（如 Panoptic-DeepLab 配置中的Resize→Normalize→Collect）。

6.2 使用 Paddle-Inference API 预测

导出完成后，基于 Paddle-Inference API 执行预测：

python deploy/python/infer.py \ --config {部署配置文件路径} \ --image_path {单幅图像路径或包含图像的目录}

其中{部署配置文件路径}是导出模型目录中deploy.yaml文件的路径（推理脚本实现位于 deploy/python/infer.py）。输出的预测结果是 RGB 图像，各通道像素值按如下公式编码：

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

其中pan_id由后处理器计算得到，唯一标识图像中的一个实例或 stuff 区域，详细说明参见 编码协议文档。

七、相关文档与源码导航

如需继续深入，建议按序阅读以下仓库内文档与源码：

• 完整功能文档：安装、数据准备、配置编写、训练、部署的完整说明；
• 开发指南：InfoDict、组件注册机制等内部设计原理；
• 编码协议文档：pan_id与 RGB 标签编码协议；
• 预测入口 tools/predict.py、训练入口 tools/train.py、评估入口 tools/val.py、导出入口 tools/export.py；
• 后处理器实现 paddlepanseg/postprocessors、模型实现 paddlepanseg/models、评估器 paddlepanseg/utils/evaluation。

至此，你已经掌握了基于 PaddleSeg 的全景分割工具箱从安装、预测、训练、评估到部署的完整流程。无论是快速体验预训练模型的三视角可视化效果，还是在自定义数据集上从零训练 Mask2Former 或 Panoptic-DeepLab，均可参照本文逐步落地。

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