企业官网建设流程全解析

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

导读：本文是 contrib/PanopticSeg 全景分割工具箱的快速上手指南。PanopticSeg 是构建在 PaddleSeg 之上的全景分割工具包，将语义分割（逐像素分类）与实例分割（逐目标检测与分割）统一为一个图像解析任务。读完本文，你将掌握从环境安装、预训练模型推理、可视化结果解读，到数据集准备、模型训练与精度评估的完整实操流程，并理解其中配置文件的底层设计。

1 工具箱背景：为什么需要全景分割

传统的图像分割任务通常被划分为两个独立分支：语义分割为每个像素赋予一个类别标签（如"道路""行人"），实例分割则检测并分割每一个独立目标（区分"行人 A"与"行人 B"）。全景分割（Panoptic Segmentation）将两者统一起来：对"stuff"类（如道路、天空等无定形区域）按语义类别划分，对"thing"类（如行人、车辆等可数目标）按实例划分，最终为图像中的每个像素同时给出语义类别与实例 ID。

contrib/PanopticSeg 正是为此设计的工具箱，它基于 PaddleSeg API 构建，提供开箱即用的高性能全景分割模型、多进程异步 I/O 与多卡并行训练等加速策略，以及从模型设计到部署的完整工作流。工具包目前提供两个代表性模型（见 configs 目录）：

• Panoptic-DeepLab：自底向上的简洁强基线模型，配置与权重见 panoptic_deeplab/README.md；
• Mask2Former：基于掩码注意力（masked attention）的通用图像分割模型，配置与权重见 mask2former/README.md。

本文以quick_start_en.md（英文版，另有 简体中文版）为主线展开。

2 安装环境

快速开始文档将安装细节指向完整功能文档 full_features_en.md 的 Installation 一节，核心步骤如下。

2.1 安装 PaddlePaddle

• PaddlePaddle >= 2.4.0
• Python >= 3.7

由于模型训练计算开销较大，强烈建议安装 GPU 版 PaddlePaddle（CUDA 10.2 及以上）。安装教程请参考 PaddlePaddle 官方安装指引（pip方式）。

2.2 获取 PaddleSeg 源码

git clone https://github.com/PaddlePaddle/PaddleSeg

注意满足版本要求：PaddleSeg >= 2.8。

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

先切换到 PaddleSeg 仓库根目录，安装 PaddleSeg 及其依赖：

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

然后安装全景分割工具箱（以可编辑模式安装，便于开发调试）：

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

2.4 验证安装

运行如下命令，若正常打印工具箱版本号，则说明安装成功：

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

paddlepanseg是工具箱的核心 Python 包，其模块结构（模型、后处理器、runner、transform 等）位于 paddlepanseg 目录 下，例如：

• 模型实现：paddlepanseg/models/panoptic_deeplab.py、paddlepanseg/models/mask2former；
• 后处理器：paddlepanseg/postprocessors；
• 数据变换与目标生成：paddlepanseg/transforms。

3 使用预训练模型进行推理

3.1 下载预训练权重与示例数据

首先下载预训练模型权重model.pdparams（Panoptic-DeepLab，ResNet50-vd 骨干，Cityscapes 1025x513 输入，90k 迭代训练）：

• 权重下载地址：https://paddleseg.bj.bcebos.com/dygraph/panoptic_segmentation/cityscapes/panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k/model.pdparams
• 示例图像demo.png下载地址：https://paddleseg.bj.bcebos.com/dygraph/panoptic_segmentation/tutorials/demo/demo.png

将两个文件放入本项目根目录（即contrib/PanopticSeg目录，与tools/、configs/同级）。

该权重的精度表现记录在 panoptic_deeplab/README.md：在 Cityscapes 验证集上达到 PQ 60.32%、mIoU 46.34%、mAP50 79.68%（8 卡训练）。训练时采用 1025x513 输入分辨率并将align_corners设为 True 可获得更好效果。

3.2 执行推理

在工具箱根目录运行 tools/predict.py：

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

参数说明：

• --config：模型配置文件路径，此处指向 panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml；
• --model_path：预训练权重路径；
• --image_path：单张图像或图像文件夹路径；
• --save_dir：结果保存目录。

需要说明的是，上述命令使用的是动态图格式模型进行推理，效率通常较低。在部署阶段，建议改用效率更高的静态图格式模型，具体做法见下文"模型部署"小节（或 full_features_en.md 的 Model Deployment 一节）。

tools/predict.py的完整命令行选项可通过python tools/predict.py --help查看。推理的底层流程由 paddlepanseg/core/predict.py 实现，可视化逻辑见 paddlepanseg/utils/visualize.py。

3.3 解读三种可视化结果

每张输入图像会生成三个可视化结果（同一前缀），均存放在--save_dir指定的目录（此处为vis）：

可视化结果的详细描述可参考 full_features_en.md 的 Get Visualization Results 一节。三张图的互补关系直观体现了全景分割"语义 + 实例"双视角统一的特性。

4 训练与评估模型

4.1 准备数据集

工具箱为常用的公开全景分割数据集提供了自动预处理脚本，详细用法见 tools/data/README.md。以Cityscapes为例，流程如下：

1. 从官方站点下载 Cityscapes 数据集，期望目录结构为gtFine/{test,train,val}与leftImg8bit/{test,train,val}；
2. 使用 cityscapesScripts 中的createPanopticImgs.py生成全景标签，处理训练子集时必须指定--use-train-id；
3. 运行脚本生成文件列表：

python tools/data/create_cityscapes_file_lists.py --data_dir {PATH_TO_CITYSCAPES_DATASET} --out_dir {PATH_TO_CITYSCAPES_DATASET}

4. 将 Cityscapes 目录软链接到data/cityscapes（或直接复制），期望结构包含gtFine（含cityscapes_panoptic_trainId、cityscapes_panoptic_val等全景标注目录与对应的.json文件）、leftImg8bit、train_list.txt与val_list.txt。

MS COCO的流程类似：下载 2017 版数据（含panoptic_train2017.json、panoptic_val2017.json与对应全景图目录），运行 create_coco_file_lists.py 生成文件列表，再软链接到data/coco。

文件列表的每一行是一对路径（原始图像路径 + 全景标签路径，以单个空格分隔），例如：

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

全景标签以RGB 图像编码，其 R/G/B 通道像素值由区域（实例或 stuff）的唯一 ID 按如下公式决定：

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

其中id是图像中每个实例/stuff 区域的唯一标识符。这一编码协议与推理输出结果（见后文部署小节）保持一致，具体细节可参考 encoding_protocol_en.md。

4.2 训练模型

首先在configs中找到计划使用的配置文件，例如 panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml。然后执行 tools/train.py：

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：模型 checkpoint 保存目录（默认output）。

⚠️ 注意：某些模型存在"前置条件"。例如 Mask2Former 依赖多尺度可变形注意力算子（ms_deform_attn），在训练、评估前必须先编译安装外部 C++/CUDA 算子（见 mask2former/README.md）：

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

算子源码位于 paddlepanseg/models/ops/ms_deform_attn，各模型的详细说明请查阅config目录下对应模型的文档。

常用训练命令行选项（完整列表见python tools/train.py --help与 PaddleSeg 训练文档）：

命令行参数优先级高于配置文件中的设置，可用于临时覆盖某个配置。默认日志不落盘，可借助 shell 重定向保存，例如：

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}

4.3 评估模型精度

训练过程中或结束后，--save_dir（默认output）目录下会存储模型 checkpoint（模型权重及可能的优化器参数）。验证集上 PQ（Panoptic Quality） 评估：

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

要点：

• 默认在验证集上评估全景分割指标（如PQ），可通过修改配置文件更改评估数据集；
• 指定--eval_sem额外计算语义分割指标（如mIoU），指定--eval_ins额外计算实例分割指标（如mAP）；
• 注意计算语义/实例指标会显著增加评估耗时；
• 评估其他 checkpoint 时直接修改--model_path即可，完整选项见python tools/val.py --help。

指标评估的底层实现位于 paddlepanseg/utils/evaluation，其中pan_seg_evaluator.py负责 PQ 计算、sem_seg_evaluator.py负责 mIoU、ins_seg_evaluator.py负责实例指标。

5 深入理解配置文件（结合源码）

由于工具箱构建在 PaddleSeg API 之上，配置文件的基本规则遵循 PaddleSeg 标准。全景分割任务引入了若干特有组件，这里结合示例配置 panoptic_deeplab 配置文件 说明其结构（YAML 锚点&与引用*用于复用num_classes、ignore_index、label_divisor等公共值）：

num_classes: &num_classes 19 ignore_index: &ignore_index 255 label_divisor: &label_divisor 1000 iters: &iters 90000 batch_size: &batch_size 8 train_dataset: type: CityscapesTrain dataset_root: data/cityscapes transforms: - type: ConvertRGBToID - type: ResizeStepScaling min_scale_factor: 0.5 max_scale_factor: 2.0 scale_step_size: 0.25 - type: RandomPaddingCrop crop_size: &crop_size [1025, 513] im_padding_value: 0 - type: RandomHorizontalFlip - type: RandomDistort brightness_range: 0.4 contrast_range: 0.4 saturation_range: 0.4 - type: GeneratePanopticDeepLabTrainTargets ignore_index: *ignore_index sigma: 8 ignore_stuff_in_offset: true small_instance_area: 4096 small_instance_weight: 3 ignore_crowd_in_semantic: false num_classes: *num_classes - type: Normalize - type: Collect keys: - img - label - img_path - lab_path - sem_label - img_h - img_w - center - offset - sem_seg_weights - center_weights - offset_weights mode: train file_list: data/cityscapes/train_list.txt json_path: data/cityscapes/gtFine/cityscapes_panoptic_train_trainId.json label_divisor: *label_divisor num_classes: *num_classes ignore_index: *ignore_index model: type: PanopticDeepLab backbone: type: ResNet50_vd output_stride: 32 pretrained: https://bj.bcebos.com/paddleseg/dygraph/resnet50_vd_ssld_v2.tar.gz backbone_indices: [2, 1, 0, 3] num_classes: *num_classes aspp_ratios: [1, 3, 6, 9] aspp_out_channels: 256 decoder_channels: 256 low_level_channels_projects: [128, 64, 32] align_corners: True instance_aspp_out_channels: 256 instance_decoder_channels: 128 instance_low_level_channels_projects: [64, 32, 16] instance_num_classes: [1, 2] instance_head_channels: 32 optimizer: type: Adam lr_scheduler: type: PolynomialDecay learning_rate: 0.0005 power: 0.9 end_lr: 0.0 warmup_iters: 1000 warmup_start_lr: 5.e-7 loss: types: - type: CrossEntropyLoss top_k_percent_pixels: 0.2 - type: L1Loss - type: L1Loss coef: [1, 200, 0.01] 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 runner: type: PanopticDeepLabRunner

其中值得注意的几点：

• 训练/验证变换以Collect结尾：这是本工具箱与 PaddleSeg 配置文件的一个显著区别——本工具箱所有数据变换必须以Collect收尾。原因是其数据处理基于InfoDict管线（见 dev_guide_en.md 的 InfoDict 一节，实现位于 paddlepanseg/cvlibs/info_dicts.py），Collect负责从InfoDict对象中挑选所需键值对。训练通常需要img、label、img_path、lab_path、img_h、img_w等键；评估还需ann、image_id、gt_fields、trans_info、pan_label、sem_label、ins_label等键；
• 后处理器（Postprocessor）：负责将网络输出转换为最终全景分割结果（图像中所有实例 ID 与每个像素的语义类别）。除上例的PanopticDeepLabPostprocessor（配置stuff_area、threshold、nms_kernel、top_k等）外，还有MaskFormerPostprocessor（配置object_mask_threshold、overlap_threshold等）。所有后处理器共有的四个属性为num_classes、thing_ids、label_divisor、ignore_index——若配置文件中未显式给出，工具箱会先从val_dataset中同名键解析，再回退到预定义默认值。实现见 paddlepanseg/postprocessors；
• Runner：定义模型的训练/验证逻辑，如PanopticDeepLabRunner与MaskFormerRunner（后者可配置weight_ce、weight_mask、weight_dice、eos_coef、num_points等损失权重），实现见 paddlepanseg/runners；
• Mask2Former 的完整配置示例见 mask2former_resnet50_os16_coco_1024x1024_bs4_370k.yml，其训练数据变换以GenerateMaskFormerTrainTargets生成gt_ids/gt_masks目标，COCO 数据集（133 类）需在train_dataset中通过no_collation_keys声明不做批量拼接的键。

6 模型部署：静态图导出与推理

为获得更高推理效率，官方推荐将模型转换为静态图格式。完整细节见 full_features_en.md 的 Model Deployment 一节。

6.1 导出模型

运行 tools/export.py：

python tools/export.py \ --config {CONFIG_PATH} \ --model_path {MODEL_PATH} \ --save_dir {PATH_TO_SAVE_EXPORTED_MODEL} \ --input_shape {FIXED_SHAPE_OF_INPUT_TENSOR}

导出细节可参考 PaddleSeg 的模型导出文档。注意并非所有模型都支持导出——例如 Mask2Former 目前不能导出（见 mask2former/README.md），使用前请查阅configs中对应模型文档确认。

6.2 使用 Paddle-Inference API 推理

导出完成后，基于 Paddle-Inference API 执行推理：

python deploy/python/infer.py \ --config {DEPLOY_CONFIG_PATH} \ --image_path {PATH_TO_SINGLE_IMAGE_OR_FOLDER}

其中{DEPLOY_CONFIG_PATH}指向导出模型目录下的deploy.yaml文件，推理脚本见 deploy/python/infer.py。导出时配置的变换（Resize、Normalize、Collect）定义于配置文件的export.transforms字段中。

推理输出的是一张 RGB 图像，其像素值编码规则与训练标签一致：

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

其中pan_id是图像中每个实例（thing 类）或 stuff 区域的唯一标识符，由网络与后处理器共同给出；pan_id的具体计算方式详见 encoding_protocol_en.md。

7 小结与常见问题

• 安装链路：PaddlePaddle >= 2.4.0 → PaddleSeg >= 2.8（pip install -r requirements.txt && pip install .）→contrib/PanopticSeg内pip install -r requirements.txt && pip install -e .，最后以import paddlepanseg验证；
• 推理：tools/predict.py+ 预训练权重 + 配置文件，每张图产出{prefix}_sem.png、{prefix}_ins.png、{prefix}_pan.png三张可视化图；
• 训练：tools/train.py --config ... --do_eval --save_dir output，Mask2Former 需先编译 ms_deform_attn 外部算子；
• 评估：tools/val.py默认给出 PQ，--eval_sem/--eval_ins分别补充 mIoU 与 mAP；
• 数据集：Cityscapes 训练子集生成全景标签时必须加--use-train-id，文件列表每行以"图像路径 + 空格 + 全景标签路径"组织，标签为 RGB 编码（r = id % 256等公式）；
• 部署：tools/export.py导出静态图后，用 deploy/python/infer.py 推理，注意 Mask2Former 暂不支持导出。

如需深入了解数据管线（InfoDict）、后处理器设计或编码协议的实现细节，可继续阅读 dev_guide_en.md 与 encoding_protocol_en.md；对应的中文文档分别为 dev_guide_cn.md、encoding_protocol_cn.md。

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