PaddleSeg FAQ 实战指南：预训练权重加载、迭代式训练与数据增强配置排查

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

本文围绕 PaddleSeg 官方 FAQ（docs/faq/faq/faq.md）展开，系统梳理了训练环节中最常被问到的七个问题：本地预训练权重加载、iters与epoch的关系、数据增强配置的继承与加载顺序、DataLoader 线程报错排查、Cityscapes SOTA 模型、best_model保存条件以及 VisualDL 日志续写。读完本文，你将能独立看懂并修改 PaddleSeg 的 yaml 配置文件，正确发起一次训练，并定位训练中的常见问题。

Q1：如何从本地加载预训练模型的权重参数？

PaddleSeg 每个模型的推荐配置统一存放在 configs 下各模型文件夹的 yaml 文件中。以 ANN 模型为例，配置位于 configs/ann/ann_resnet50_os8_cityscapes_1024x512_80k.yml，其model字段结构如下：

model: type: ANN backbone: type: ResNet50_vd output_stride: 8 pretrained: https://bj.bcebos.com/paddleseg/dygraph/resnet50_vd_ssld_v2.tar.gz backbone_indices: [2, 3] key_value_channels: 256 inter_channels: 512 psp_size: [1, 3, 6, 8] enable_auxiliary_loss: True align_corners: False pretrained: null

图中存在两处与预训练相关的配置：

• 红色部分：骨干网络的pretrained。位于model.backbone下。默认写法直接给出一个 https 链接，训练启动时会自动下载 PaddleSeg 官方提供的预训练参数（如上述 ResNet50_vd_ssld_v2）。如果你本地已有骨干网络预训练参数，请用绝对路径替换该字段；也可以根据将要执行train.py时所在的目录，为其设置相对路径。
• 绿色部分：分割网络自身的pretrained。位于model顶层，默认值为null，表示分割头（如 ANN）从头初始化，仅加载骨干预训练权重。如果本地已有分割网络全量预训练参数，同样用绝对路径或相对路径替换该字段即可。

从源码看，模型的构建与权重加载发生在 paddleseg/cvlibs/config.py 的model_cfg属性以及SegBuilder的模型组装逻辑中：pretrained字段会随model/backbone配置一起被读取，并由模型加载逻辑按路径或链接拉取权重。因此，无论替换为本地路径还是保留下载链接，都必须保证路径可被训练进程访问到，否则会在权重初始化阶段报错。

Q2：为什么 PaddleSeg 不采用设置 epoch 的方式？

epoch（完整遍历数据集的轮数）会受数据集规模影响：同一份配置换到不同大小的数据集，实际训练轮数会截然不同，且难以精确控制计算量。因此 PaddleSeg 统一以iters（总迭代步数）作为训练长度指标，例如上述 ANN 配置中iters: 80000。

训练配置参数之间存在如下换算关系：

• 数据集大小：N
• 批量大小：batch_size（单卡 batch）
• GPU 数量：num_gpus
• 总迭代次数：iters

换算公式为：

epoch = (iters * batch_size * num_gpus) / N

即一次迭代处理batch_size * num_gpus张图片，总处理样本数为iters * batch_size * num_gpus，除以数据集大小即为完整过数据集的次数。相关字段在 paddleseg/cvlibs/config.py 中通过batch_size、iters属性对外暴露，并在 tools/train.py 中由命令行参数覆盖后传入训练核心。

Q3：数据增强配置的加载顺序是怎样的？

数据增强在 yaml 的train_dataset.transforms中指定。Cityscapes 是最常用的语义分割数据集之一，PaddleSeg 已为其沉淀了常用配置，见 configs/base/cityscapes.yml：

train_dataset: type: Cityscapes dataset_root: data/cityscapes transforms: - type: ResizeStepScaling min_scale_factor: 0.5 max_scale_factor: 2.0 scale_step_size: 0.25 - type: RandomPaddingCrop crop_size: [1024, 512] - type: RandomHorizontalFlip - type: RandomDistort brightness_range: 0.4 contrast_range: 0.4 saturation_range: 0.4 - type: Normalize mode: train

PaddleSeg 以_base_关键字指定配置之间的继承关系：

_base_: '../_base_/cityscapes.yml' _base_: '../_base_/cityscapes_1024x1024.yml'

关于加载顺序，需要理解三条规则：

1. 数据增强按transforms列表从上到下依次加载执行。例如上面的顺序是先做多尺度缩放（ResizeStepScaling），再随机裁剪到固定尺寸（RandomPaddingCrop），然后水平翻转、色彩扰动，最后归一化。
2. 子类覆盖父类中的同名配置。_base_的合并逻辑在 paddleseg/cvlibs/config.py 中实现：parse_from_yaml会先递归解析_base_指向的父配置，再通过merge_config_dicts用子配置覆盖父配置；当键值同为 dict 时逐层递归合并，否则直接覆盖。因此子 yaml 中写的batch_size: 2会覆盖基类中的同名项。
3. 命令行参数覆盖 yaml 内同名配置。例如执行python tools/train.py --config xxx.yml --batch_size 4时，命令行传入的batch_size: 4会覆盖 yaml 中的batch_size: 2。这一逻辑由 tools/train.py 构造Config时传入的learning_rate、iters、batch_size等参数实现（见 update_config_dict）；此外--opts key=value可以按点分路径更新任意嵌套配置，如--opts test_config.scales=0.75,1.0,1.25。

Q4：数据增强配置为何会引起 DataLoader reader thread 错误？

如果你使用形状不一致的自定义数据集，训练时出现 DataLoader reader thread 相关报错，很可能是数据增强加载顺序不当导致的。

结合 Q3 可知，transforms是严格按顺序执行的。例如RandomRotation（随机旋转）会改变图像尺寸，如果它被放在Resize、RandomPaddingCrop等"修正尺寸"的增强之后，同一 batch 内的图像尺寸就会不一致，DataLoader 在组 batch 时便无法对齐张量形状，从而抛出 reader thread 错误。

PaddleSeg 内置的各类增强算子统一注册在 paddleseg/transforms/transforms.py，包括Resize、ResizeStepScaling、ResizeByLong、ResizeByShort、RandomHorizontalFlip、RandomDistort、Normalize等。从实现看，它们大多在__call__中直接返回(im, label)对，前一个算子的输出即后一个算子的输入，因此改变尺寸的增强（旋转、缩放、裁剪）必须放在尺寸修正类增强之前。

通用建议：保持RandomRotation等尺寸变化算子位于Resize/RandomPaddingCrop之前；对自定义数据集，训练前请参照 Q3 仔细核对transforms顺序，并尽量保证样本原始尺寸一致。

Q5：目前 PaddleSeg 在 Cityscapes 上的 SOTA 模型是什么？

FAQ 指出，PaddleSeg 在 Cityscapes 上的 SOTA 模型可达到87% mIoU。该结论在仓库中可找到对应实现与验证记录：contrib/CityscapesSOTA/README.md 记载，基于分层多尺度注意力（Hierarchical Multi-Scale Attention）的 MscaleOCRNet（骨干 HRNet_W48）在 Cityscapes 验证集上达到 87.00% mIoU（5 scales + flip 评测；仅多尺度评测为 86.89%，多尺度加水平翻转评测为 86.99%）。

该实现相比原论文做了三点优化：使用 dice loss 与 bootstrapped cross entropy 替代交叉熵、每个 epoch 等量学习全部 fine 数据与 coarse 数据、评测采用等差分数的尺度序列。相关训练、验证与部署命令均可在 contrib/CityscapesSOTA 目录下找到，其中复现 SOTA 的验证命令为：

python val.py --config configs/mscale_ocr_cityscapes_autolabel_mapillary.yml \ --num_workers 3 --model_path saved_model/model.pdparams

需要注意的是，该 SOTA 需要较大显存（单模型评测约需 14.2GB GPU 显存，多尺度加翻转评测约需 21.2GB），复现前请评估硬件条件。

Q6：为什么训练过程中不保存 best_model？

best_model并非每轮迭代都会产生，它是在训练过程中通过验证对比得到的最优模型。PaddleSeg 的训练核心 paddleseg/core/train.py 中以best_mean_iou = -1.0初始化，并在每个save_interval（默认 1000 步）且存在验证集时，对当前模型在验证集上评估，若 mIoU 高于历史最优则更新best_model并保存。

因此，训练前必须开启--do_eval选项才会保存best_model：

python tools/train.py --config configs/ann/ann_resnet50_os8_cityscapes_1024x512_80k.yml \ --do_eval --save_dir ./output

同时从 paddleseg/core/train.py 的保存条件（iter % save_interval == 0 or iter == iters，且val_dataset is not None）可以确认：只有开启--do_eval（此时 tools/train.py 才会构造val_dataset）并配合适当的--save_interval，best_model才会被写入save_dir。若不需要保存最优模型，也可以不开启该选项以节省验证时间。

Q7：恢复训练后，vdl 为什么只可视化了后半部分？如何可视化中断前的部分？

由于算力限制或其他原因，训练可能无法一次跑完，此时通过--resume_model断点续训，会产生两个（或多个）独立的 VisualDL 日志文件，导致visualdl默认只能看到后半段曲线。FAQ 给出两种处理方式：

1. 手动合并日志：将第一次与第二次生成的日志内容拷贝到同一个新的二进制日志文件中，再交给 VisualDL 读取。这是无需额外工具的最直接办法。
2. 续写同一日志：对于"中断后继续训练"这类场景，可以在调用visualdl时显式指定日志文件名，使后续训练直接写入指定日志文件，避免产生多个文件。

此外，FAQ 同时说明新版本将支持多日志合并，建议关注 VisualDL 后续版本的日志合并能力。若你的训练中断较频繁，也可以结合--save_interval与--resume_model的配合，合理规划 checkpoint 间隔，减少日志碎片化。

总结

PaddleSeg 的 yaml 配置体系是理解整个训练流程的钥匙：pretrained决定权重从哪来，iters决定训练多长，_base_与transforms顺序决定数据如何被加工，--do_eval决定best_model是否产生。FAQ 中的七个问题环环相扣，逐一解决后即可顺畅完成从配置检查、训练启动到结果可视化的完整流程。相关配置与源码证据均可从 configs、paddleseg/cvlibs/config.py、tools/train.py 与 paddleseg/core/train.py 中进一步查阅。

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