企业官网建设流程全解析

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

本文以 QualityInspector（飞桨工业质检全流程解决方案）中configs/seg/目录下的分割模型配置文件为对象，系统讲解 PaddleSeg 训练配置文件中的全部核心配置项——训练/验证数据集、批大小、迭代数、优化器、学习率、损失函数、模型结构与导出配置，并结合仓库内的真实 YAML 示例（Cityscapes 基线与缺陷检测 OCRNet 配置）说明如何在工业质检场景中编写、复用与运行这些配置，最终完成分割模型的训练与验证。

一、配置文件在 QualityInspector 中的作用

QualityInspector 是飞桨视觉套件（PaddleClas、PaddleSeg、PaddleDetection）之上构建的工业质检全流程解决方案，其核心特性之一就是"统一可配置的解决方案"：支持检测、分割单模型以及"检测 + RoI 分割串联 + 后处理"的组合方案，只需修改配置即可组合视觉套件中的模型（见 QualityInspector 项目说明）。

在分割任务中，contrib/QualityInspector/configs/seg/目录下保存了不同模型的配置文件，PaddleSeg 依靠这些 YAML 文件完成模型的训练（train）、验证（val）与导出（export）。配置文件即"算法方案说明书"——数据集用哪个、训练多少步、用什么优化器和学习率策略、接什么损失函数、选哪个模型骨架，全部由它声明。

当前仓库中configs/seg/目录的构成如下：

• _base_/：可被其他配置继承的公共基配置（如cityscapes.yml、ade20k.yml、mtile_dataset.yml等）；
• 各模型子目录：mobileseg/、mscale_ocrnet/、ocrnet/、pspnet/、segformer/、uhrnet/、unet/、upernet/，每个目录内含 README 与该模型的训练 YAML；
• 目录根部的 README.md 与 README_cn.md：即本文所讲解的配置项总览。

二、核心配置项总览

一份典型的分割训练配置由以下顶层字段组成：train_dataset、val_dataset、batch_size、iters、optimizer、lr_scheduler、loss、model、export。下面逐一展开。

1. train_dataset：训练数据集

train_dataset: type: Cityscapes # 数据集类型 dataset_root: data/cityscapes transforms: - type: Normalize mode: train # 训练模式

• type：数据集类型，PaddleSeg 内置了 Cityscapes、ADE20K、VOC 等标准数据集，也支持通用Dataset类型（配合train_path/val_path指向自定义数据清单，质检缺陷数据即用此类）；
• 其余参数（dataset_root、transforms、mode等）：具体取值请参考对应模型训练配置文件与数据集文档。

2. val_dataset：验证数据集

val_dataset: type: Cityscapes dataset_root: data/cityscapes transforms: - type: Normalize mode: val # 验证模式

结构与train_dataset一致，区别在于mode: val，且验证阶段通常只做归一化（Normalize）而不做数据增强。训练过程中可通过--do_eval定期在验证集上评测。

3. batch_size：单卡批大小

单张卡上，每步迭代训练时的数据量。一般来说，显存越大，可相应调高batch_size的值。

注意该字段是"单卡"维度：多卡训练时实际吞吐为batch_size × 卡数。在 QualityInspector 的缺陷分割配置中（如ocrnet_hrnetw18_defect_256x256_40k.yml）输入尺寸小（256×256），批大小可设到 16；而 Cityscapes 基线的 1024×512 输入则通常设为 2。

4. iters：训练迭代数

使用一个 batch 数据对模型做一次参数更新即一次迭代（iteration），iters即训练总迭代次数。它与"epoch"不同——PaddleSeg 配置以迭代数为训练终止条件，例如：

• Cityscapes 常规训练：iters: 80000或160000；
• 质检缺陷分割（数据量较小）：iters: 40000（见 ocrnet_hrnetw18_defect_256x256_40k.yml）。

5. optimizer：训练优化器

optimizer: type: sgd momentum: 0.9 weight_decay: 4.0e-5

• type：优化器类型。README 指出"支持 Paddle 官方所有优化器"；在 PaddleSeg 主仓库的配置文件详解中明确当前训练链路常用的为sgd与adam（及 Transformer 类模型常用的AdamW）；
• weight_decay：L2 正则化强度，如4.0e-5；
• 其余参数（momentum、beta1、beta2等）：参考 Paddle 官方 Optimizer 文档。

实际仓库中可以看到两种典型用法：卷积类模型用sgd + momentum（如 cityscapes.yml），而 SegFormer 等 Transformer 模型使用AdamW并显式关闭继承（_inherited_: False）：

optimizer: _inherited_: False # 不继承基配置中的优化器 type: AdamW beta1: 0.9 beta2: 0.999 weight_decay: 0.01

（见 segformer_b0_cityscapes_1024x512_160k.yml）

6. lr_scheduler：学习率策略（推荐）

lr_scheduler: type: PolynomialDecay learning_rate: 0.01 end_lr: 0 power: 0.9

• type：学习率策略类型，共支持 10 种：PolynomialDecay、PiecewiseDecay、StepDecay、CosineAnnealingDecay、ExponentialDecay、InverseTimeDecay、LinearWarmup、MultiStepDecay、NaturalExpDecay、NoamDecay（PaddleSeg 主仓库的 use 文档中还提及ReduceOnPlateau、LambdaDecay两种，合计 12 种）；
• 其余参数（learning_rate、end_lr、power等）：随策略类型不同而不同，详见 Paddle 官方 LRScheduler 文档。

分割训练中最常用的是PolynomialDecay（多项式衰减）：学习率从learning_rate按power次方衰减至end_lr。Cityscapes 基线使用learning_rate: 0.01, power: 0.9, end_lr: 0；SegFormer 则使用更小的learning_rate: 0.00006, power: 1。

7. learning_rate：旧式学习率配置（不推荐）

该配置不推荐使用，将来会被废弃，建议使用lr_scheduler代替。

旧式写法以value指定初始学习率，以decay声明衰减：

learning_rate: value: 0.1 decay: type: poly # 衰减类型，目前只支持 poly power: 0.9 end_lr: 0.0001

• value：初始学习率；
• decay.type：衰减类型，目前仅支持poly；
• decay.power：衰减率；
• decay.end_lr：最终学习率。

新项目请一律使用lr_scheduler字段。

8. loss：损失函数

loss: types: - type: CrossEntropyLoss coef: [1]

• types：损失函数列表，类型取自 PaddleSeg 损失函数库（CrossEntropyLoss、DiceLoss、LovaszSoftmaxLoss 等，具体支持值参考损失函数库文档）；
  • ignore_index：训练过程中需要忽略的类别（如标注中的边界/未知像素）。默认取值与train_dataset的ignore_index一致，推荐不设置此项；若手动设置，必须保证loss与train_dataset的ignore_index相同，否则会造成标签与损失计算不一致；
• coef：与损失列表一一对应的加权系数。多损失组合时用于平衡各分支，例如 OCRNet 使用主损失 + 辅助（空间细节）损失：

loss: types: - type: CrossEntropyLoss - type: CrossEntropyLoss coef: [1, 0.4]

（见 ocrnet_hrnetw18_defect_256x256_40k.yml）

9. model：待训练模型

model: type: OCRNet backbone: type: HRNet_W18 pretrained: https://bj.bcebos.com/paddleseg/dygraph/hrnet_w18_ssld.tar.gz num_classes: 6 backbone_indices: [0]

• type：模型类型，支持值见 PaddleSeg 模型库（FCN、OCRNet、SegFormer、PSPNet、UPerNet、MobileSeg、UHRNet、UNet 等，configs/seg/下各子目录即对应实现）；
• backbone：骨干网络，可指定pretrained预训练权重（本地路径或 URL）；
• num_classes：像素类别数，必须与数据集的类别数一致（质检缺陷分割中常为背景 + N 类缺陷，如 6 类）；
• 其余参数（backbone_indices、embedding_dim等）随模型不同而不同，请参考对应模型训练配置文件。

10. export：模型导出配置

export: transforms: - type: Normalize

• transforms：预测（部署）阶段的预处理操作，支持配置的 transforms 与train_dataset、val_dataset等相同。若不填写该项，默认只对数据做归一化标准化——这意味着导出模型在推理时若需要 resize、padding 等操作，必须在此显式声明，与训练/验证阶段的预处理保持一致。

三、配置继承机制：_base_与_inherited_

QualityInspector 的配置体系支持继承，这是组织多套实验配置的关键机制：

• 子配置通过_base_: '../_base_/cityscapes.yml'声明继承某个基配置，未在子配置中重写的字段自动沿用基配置值；
• 某个字段若想完全推翻基配置而非增量覆盖，需显式标记_inherited_: False（如 SegFormer 中替换优化器为 AdamW）。

典型示例：

# configs/seg/segformer/segformer_b0_cityscapes_1024x512_160k.yml _base_: '../_base_/cityscapes.yml' batch_size: 1 iters: 160000 model: type: SegFormer backbone: type: MixVisionTransformer_B0 pretrained: https://bj.bcebos.com/paddleseg/dygraph/backbone/mix_vision_transformer_b0.tar.gz embedding_dim: 256 num_classes: 19

这样便复用了基配置中的数据集定义、数据增强管线等公共内容，仅针对模型本身做替换。

四、完整配置示例（可直接运行的骨架）

综合 PaddleSeg 配置文件详解 中的完整示例，一份自洽的分割训练配置如下：

batch_size: 4 # 一次迭代送入网络的图片数（单卡），显存越大可越高 iters: 80000 # 总迭代次数 train_dataset: # 训练数据集 type: Cityscapes dataset_root: data/cityscapes transforms: - type: ResizeStepScaling # 按 scale_step_size 为步长随机缩放 min_scale_factor: 0.5 max_scale_factor: 2.0 scale_step_size: 0.25 - type: RandomPaddingCrop # 随机裁剪图像与标注 crop_size: [1024, 512] - type: RandomHorizontalFlip # 随机水平翻转 - type: Normalize # 标准化 mode: train val_dataset: # 验证数据集 type: Cityscapes dataset_root: data/cityscapes transforms: - type: Normalize mode: val optimizer: type: sgd momentum: 0.9 weight_decay: 4.0e-5 lr_scheduler: type: PolynomialDecay learning_rate: 0.01 power: 0.9 end_lr: 0 loss: types: - type: CrossEntropyLoss coef: [1] model: type: FCN backbone: type: HRNet_W18 pretrained: pretrained_model/hrnet_w18_ssld num_classes: 19 pretrained: Null backbone_indices: [-1]

而面向工业质检缺陷分割的真实配置（OCRNet + HRNet_W18，256×256 输入，6 类，40k 迭代）见 ocrnet_hrnetw18_defect_256x256_40k.yml，其数据部分使用通用Dataset类型：

train_dataset: type: Dataset num_classes: 6 dataset_root: ./ train_path: dataset/MT_dataset/train.txt transforms: - type: ResizeStepScaling min_scale_factor: 0.5 max_scale_factor: 2.0 scale_step_size: 0.25 - type: RandomPaddingCrop crop_size: [256, 256] - type: RandomHorizontalFlip - type: RandomDistort brightness_range: 0.4 contrast_range: 0.4 saturation_range: 0.4 - type: Normalize mode: train

train_path/val_path指向的 txt 文件即样本清单（每行一个图像-标注对），这是把任意自建质检数据接入训练链路的标准方式；被注释的CopyPaste变换（prob: 0.5）则是针对缺陷样本少、可做贴片增强的预留手段。

五、用配置文件驱动训练与验证

配置文件编写完成后，即可通过 QualityInspector 提供的训练/验证脚本（tools/seg/）驱动。以缺陷分割配置为例（详见 训练&验证文档）：

单卡训练：

python3 tools/seg/train.py --config configs/seg/ocrnet/ocrnet_hrnetw18_defect_256x256_40k.yml \ --do_eval --use_vdl --save_interval 1000 --save_dir ./output/

多卡训练：

CUDA_VISIBLE_DEVICES=0,1 python3 -m paddle.distributed.launch \ --config configs/seg/ocrnet/ocrnet_hrnetw18_defect_256x256_40k.yml \ --do_eval --use_vdl --save_interval 1000 --save_dir ./output/

验证（使用训练中保存的最优模型）：

python3 tools/seg/val.py --config configs/seg/ocrnet/ocrnet_hrnetw18_defect_256x256_40k.yml \ --model_path ./output/best_model/model.pdparams

命令要点：

• --config（或-c）：指定 YAML 配置文件路径；
• --do_eval：训练过程中定期在验证集上评测，--save_interval控制保存间隔；
• --use_vdl：开启 VisualDL 可视化日志（--vdl_log_dir指定日志目录）；
• --model_path：验证时指定权重文件（如best_model/model.pdparams）；
• -o可覆盖配置文件中的任意字段（检测任务的eval.py常用-o weights=...指定权重）。

六、扩展与注意事项

1. 算法可扩展：QualityInspector 的configs/seg/只保留了部分算法配置（MobileSeg、OCRNet、PSPNet、SegFormer、UHRNet、UNet、UPerNet、MScaleOCRNet 等），但实际可使用 PaddleSeg 中集成的任意算法——只需把对应算法的 config 文件放入./configs/seg/即可按同样的流程训练。
2. 数据增强按需裁剪：训练集 transform 顺序影响最终效果，ResizeStepScaling→RandomPaddingCrop→RandomHorizontalFlip→RandomDistort→Normalize是分割任务的标准增强链；验证与导出阶段应保持与训练一致的Normalize参数。
3. 类别一致性：model.num_classes、train_dataset.num_classes与标注数据中的类别编号必须一一对应；loss中如设置ignore_index，需与数据集一致。
4. 学习率选择：卷积类模型（HRNet/ResNet 骨干）通常用PolynomialDecay + 0.01，Transformer 类模型（SegFormer/MixVisionTransformer）用更小的学习率（如6e-5）配合AdamW，二者不可混用默认值。
5. 导出前的预处理：export.transforms不填时导出模型仅含归一化，若部署链路需要 resize 等操作，务必在此显式声明，否则推理时输入尺寸与训练不一致会导致精度下降。

通过配置文件，QualityInspector 实现了"训练、验证、导出"三阶段行为与工业质检任务的解耦：更换模型、调整数据或调优超参，都只需要编辑 YAML 而非修改代码，这正是其"统一可配置解决方案"设计理念在分割链路上的直接体现。

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