PaddleSeg MedicalSeg 实战指南：从参数配置、一键训练评估到模型部署与自定义数据集扩展

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

本指南基于 PaddleSeg 仓库中的 MedicalSeg 医学图像分割子项目，系统讲解其"三级 YAML 配置 → 一键数据准备 → 一键训练评估 → 静态图导出与推理部署 → 自定义数据集扩展"的完整工作流，并以 COVID-19 CT 肺部分割（VNet 模型）为主线给出可直接复制的命令与参数说明。读完本文，你将掌握 MedicalSeg 的配置体系、核心训练/评估/导出命令的每一个参数含义，并能独立把任意新数据集接入该框架完成训练与部署。

1. 参数配置：三级 YAML 配置体系

MedicalSeg 采用_base_继承式的多级 YAML 配置设计，让"数据/损失/优化器"与"模型结构"解耦：同一个数据集配置（二级配置）可以搭配任意多个模型配置（三级配置），只需新建一个几行的三级配置即可换模型。

1.1 配置目录结构

以configs/目录为根，配置按如下层次组织（见 configs 目录）：

├── _base_ # 一级基础配置，后面所有的二级配置都需要继承它，你可以在这里设置自定义的数据路径，确保它有足够的空间来存储数据。 │ └── global_configs.yml ├── lung_coronavirus # 每个数据集/器官有个独立的文件夹，这里是 COVID-19 CT scans 数据集的路径。 │ ├── lung_coronavirus.yml # 二级配置，继承一级配置，关于损失、数据、优化器等配置在这里。 │ ├── README.md │ └── vnet_lung_coronavirus_128_128_128_15k.yml # 三级配置，关于模型的配置，不同的模型可以轻松拥有相同的二级配置。 └── schedulers # 用于规划两阶段的配置，暂时还没有使用它。 └── two_stage_coarseseg_fineseg.yml

• 一级配置_base_/global_configs.yml：目前只定义全局数据根目录，其内容为data_root: data/，所有数据下载、预处理产物都默认落在此目录下。如果你的磁盘空间紧张，只需修改这里的路径指向一个容量充足的目录，全部二级配置都会自动继承。
• 二级配置：以lung_coronavirus/lung_coronavirus.yml为代表，集中了数据集、数据增强、优化器、学习率调度与损失函数等训练要素。
• 三级配置：如vnet_lung_coronavirus_128_128_128_15k.yml，只负责定义模型结构，通过_base_: 'lung_coronavirus.yml'继承二级配置。这样，同一数据集下切换 VNet、UNETR、Swin-UNet 等模型时，二级配置无需任何改动。

仓库中已经预置了多个数据集/器官的配置目录，包括acdc（心脏）、mri_spine_seg（脊柱 MRI）、msd_brain_seg（脑部）、synapse（腹部多器官）以及nnunet（Medical Segmentation Decathlon 标准流程），可作为参照模板。

1.2 二级配置参数详解

以 configs/lung_coronavirus/lung_coronavirus.yml 为例，逐段解释：

_base_: '../_base_/global_configs.yml' batch_size: 6 iters: 15000 train_dataset: type: LungCoronavirus dataset_root: lung_coronavirus/lung_coronavirus_phase0 result_dir: lung_coronavirus/lung_coronavirus_phase1 transforms: - type: RandomResizedCrop3D size: 128 scale: [0.8, 1.2] - type: RandomRotation3D degrees: 90 - type: RandomFlip3D mode: train num_classes: 3 val_dataset: type: LungCoronavirus dataset_root: lung_coronavirus/lung_coronavirus_phase0 result_dir: lung_coronavirus/lung_coronavirus_phase1 num_classes: 3 transforms: [] mode: val dataset_json_path: "data/lung_coronavirus/lung_coronavirus_raw/dataset.json" optimizer: type: sgd momentum: 0.9 weight_decay: 1.0e-4 lr_scheduler: type: PolynomialDecay decay_steps: 15000 learning_rate: 0.001 end_lr: 0 power: 0.9 loss: types: - type: MixedLoss losses: - type: CrossEntropyLoss weight: Null - type: DiceLoss coef: [1, 1] coef: [1]

关键字段说明：

• _base_：指向继承的一级配置（或上一级二级配置），相对路径以当前文件所在目录为基准。
• batch_size/iters：单卡批大小与总迭代数。本示例为 6 与 15000，也可在命令行用--batch_size、--iters临时覆盖。
• train_dataset/val_dataset：type对应 medicalseg/datasets/lung_coronavirus.py 中注册的LungCoronavirus类；dataset_root指向预处理后的phase0数据目录；result_dir用于存放训练/评估过程中产生的预测结果。num_classes: 3对应背景、左肺、右肺三个类别。
• transforms：3D 专用数据增强，训练集启用RandomResizedCrop3D（随机裁剪缩放到 128³ 体素、尺度范围 0.8~1.2）、RandomRotation3D（90° 随机旋转）、RandomFlip3D（随机翻转）；验证集transforms: []不做增强，保证评估结果可复现。
• optimizer：SGD，动量 0.9，权重衰减 1e-4。训练时权重衰减会作用于所有可训练参数，帮助抑制过拟合。
• lr_scheduler：多项式衰减调度器，从 0.001 线性/多项式衰减到end_lr: 0，power: 0.9控制衰减曲线形状，decay_steps与总迭代数保持一致。
• loss：使用MixedLoss组合交叉熵损失（CrossEntropyLoss）与 Dice 损失（DiceLoss），coef: [1, 1]表示两者等权相加，外层coef: [1]是该混合损失在总损失中的权重。交叉熵保证逐体素分类精度，Dice 损失直接优化分割区域的重叠度，两者结合对医学影像中常见的类别不均衡问题更稳健。

1.3 三级配置参数详解

vnet_lung_coronavirus_128_128_128_15k.yml 内容非常精简：

_base_: 'lung_coronavirus.yml' model: type: VNet elu: False in_channels: 1 num_classes: 3 pretrained: https://bj.bcebos.com/paddleseg/dygraph/lung_coronavirus/vnet_lung_coronavirus_128_128_128_15k/pretrain/model.pdparams

• type: VNet：指定 3D 分割网络 VNet（以 128×128×128 体素输入，训练 15k 迭代，配置文件名即这三要素的缩写）。
• elu：是否在 VNet 中使用 ELU 激活函数，False时使用默认激活。
• in_channels: 1：CT 为单通道灰度体数据。
• num_classes: 3：输出 3 类（背景、左肺、右肺）。
• pretrained：预训练权重地址。模型首次加载时会自动下载，也可在本地准备好该权重后离线训练。

2. 数据准备：一键下载、预处理与切分

MedicalSeg 为每个数据集提供了独立的准备脚本，将"下载原始数据 → 解压 → 归一化/重采样 → 转成 numpy → 划分训练/验证集 → 生成索引文件"全流程自动化。以 COVID-19 CT scans 为例（见 tools/prepare_lung_coronavirus.py）：

python tools/prepare_lung_coronavirus.py # 以 COVID-19 CT scans 为例。

2.1 脚本内部做了什么

从源码看，该脚本继承prepare.py中的Prep基类并完成四件事：

1. 下载并解压：内置lung_infection.zip、lung_mask.zip、infection_mask.zip、20_ncov_scan.zip四个压缩包的下载地址，自动下载并解压到data/lung_coronavirus/lung_coronavirus_raw/下的20_ncov_scan、infection_mask、lung_infection、lung_mask等目录。
2. 预处理：对 CT 图像执行 HU 归一化（HUnorm），随后用resample把体数据统一重采样到[128, 128, 128]尺寸——图像使用order=1（线性插值保留灰度细节），标签使用order=0（最近邻插值，避免产生新类别值）。
3. 保存为 numpy：将处理结果以.npy文件写入lung_coronavirus_phase0/下的images/与labels/目录，命名规则与原始病例一一对应。
4. 划分数据集：以train_split=0.75（75% 训练、25% 验证）的比例生成train_list.txt与val_list.txt，并在dataset.json中登记模态（CT）与类别语义（0: background、1: left lung、2: right lung）。

2.2 预处理产物的目录规范

预处理完成后，得到如下结构（这也是后续所有数据集必须遵循的输入约定）：

├── lung_coronavirus_phase0 # 预处理后的文件路径 │ ├── images │ │ ├── imagexx.npy │ │ ├── ... │ ├── labels │ │ ├── labelxx.npy │ │ ├── ... │ ├── train_list.txt # 训练数据，格式: /path/to/img_name_xxx.npy /path/to/label_names_xxx.npy │ └── val_list.txt # 评估数据，格式: img_name_xxx.npy label_names_xxx.npy

train_list.txt与val_list.txt的每一行由"图像 npy 路径 + 空格 + 标签 npy 路径"组成，是数据加载器读取样本的唯一索引。仓库tools/目录下还提供了prepare_abdomen.py、prepare_acdc.py、prepare_mri_spine_seg.py、prepare_msd.py、prepare_msd_brain_seg.py、prepare_prostate.py等脚本，分别对应腹部、心脏、脊柱、MSD 等多个公开数据集，用法完全相同，只需运行对应脚本。

3. 训练与评估：一条命令全流程

配置与数据就绪后，运行 run-vnet.sh 即可依次完成训练、评估、导出与推理，实现"一键训练推理"：

# 设置使用的单卡 GPU id export CUDA_VISIBLE_DEVICES=3 # 设置配置文件名称和保存路径 config_name=vnet_lung_coronavirus_128_128_128_15k yml=lung_coronavirus/${config_name} save_dir_all=saved_model save_dir=saved_model/${config_name} mkdir -p $save_dir # 模型训练 python3 train.py --config configs/${yml}.yml \ --save_dir $save_dir \ --save_interval 500 --log_iters 100 \ --num_workers 6 --do_eval --use_vdl \ --keep_checkpoint_max 5 --seed 0 >> $save_dir/train.log # 模型评估 python3 val.py --config configs/${yml}.yml \ --save_dir $save_dir/best_model --model_path $save_dir/best_model/model.pdparams \ # 模型导出 python export.py --config configs/${yml}.yml \ --model_path $save_dir/best_model/model.pdparams # 模型预测 python deploy/python/infer.py --config output/deploy.yaml --image_path data/lung_coronavirus/lung_coronavirus_phase0/images/coronacases_org_007.npy --benchmark True

也可以只运行脚本的前半段单独训练与评估：

# 设置使用的单卡 GPU id export CUDA_VISIBLE_DEVICES=0 # 设置配置文件名称和保存路径 yml=vnet_lung_coronavirus_128_128_128_15k save_dir=saved_model/${yml} mkdir -p $save_dir # 训练模型 python3 train.py --config configs/lung_coronavirus/${yml}.yml \ --save_dir $save_dir \ --save_interval 500 --log_iters 100 \ --num_workers 6 --do_eval --use_vdl \ --keep_checkpoint_max 5 --seed 0 >> $save_dir/train.log # 评估模型 python3 val.py --config configs/lung_coronavirus/${yml}.yml \ --save_dir $save_dir/best_model --model_path $save_dir/best_model/model.pdparams

3.1 train.py 参数全解

train.py 的完整命令行参数如下，均可覆盖配置文件中的对应项：

值得注意的实现细节：train.py通过Config把命令行传入的learning_rate、iters、batch_size合并进配置字典后再构造数据集、损失与模型（见 train.py），因此这三个参数既可以在 YAML 中预设，也可以每次运行时按需覆盖；--do_eval开启后，训练过程中会自动执行验证，并把最优权重保存为best_model/model.pdparams，这正是后续评估、导出命令直接引用该路径的原因。

3.2 val.py 参数全解

val.py 负责加载训练好的权重进行离线评估：

评估的核心流程是：读取配置 → 加载权重（utils.load_entire_model）→ 在val_dataset上逐样本推理 → 输出逐类与总体指标，并将预测结果写入save_dir。--auc_roc对需要 ROC 曲线的分类/分割任务特别有用。

4. 模型部署：导出静态图并加速推理

训练完成后，export.py 会把动态图模型转换为 Paddle Inference 静态图（model.pdmodel+model.pdiparams），并生成配套的deploy.yaml部署描述文件。完整命令如下（详见 deploy/python/README.md）：

cd MedicalSeg/ # 用训练好的模型进行静态图导出 python export.py --config configs/lung_coronavirus/vnet_lung_coronavirus_128_128_128_15k.yml --model_path /path/to/your/trained/model # 使用 Paddle Inference 进行推理 python deploy/python/infer.py \ --config /path/to/model/deploy.yaml \ --image_path /path/to/image/path/or/dir/ \ --benchmark True # 在安装了 AutoLog 之后，打开benchmark可以看到推理速度等信息，安装方法可以见 deploy/python/README.md

如果有 "Finish" 输出，说明导出成功，并且可以进行推理加速。

4.1 export.py 的关键机制

从源码看，export.py 的导出流程为：

1. 从配置构建模型并加载--model_path权重；
2. 默认输入形状为[None, 1, None, None, None]（NCDHW 五维，通道数 1、空间维度可动态），也可用--input_shape指定固定形状以换取更优的算子融合；
3. 用paddle.jit.to_static+paddle.jit.save生成静态图model.pdmodel与model.pdiparams；
4. 自动写出deploy.yaml，其中登记了transforms、inference_helper、模型与参数字段名，推理端直接读取该文件即可复现预处理。

导出时还可通过两个开关定制网络尾部：--with_softmax在输出前追加 softmax（输出概率图），--without_argmax去掉默认的 argmax（输出原始 logits）。两者配合可以满足"输出类别索引"或"输出概率/连续值"两种下游需求。

4.2 推理与性能基准

deploy/python/infer.py接收deploy.yaml与--image_path（支持单张.npy文件或整个目录），--benchmark True时会在安装 AutoLog 的前提下打印推理耗时、吞吐等性能数据，方便对比不同硬件/不同输入尺寸下的加速效果。

5. 在自己的数据上训练：四步扩展新数据集

如果想在自有数据集上训练，需要按下面的模式新增四类文件：配置目录、数据预处理脚本、数据集类、训练脚本。下面以 COVID-19 CT scans 为参照模板，分步说明。

5.1 增加配置目录

首先，按照与lung_coronavirus相同的模式，新增一个与数据集对应的配置目录（参考 configs 目录结构）：

├── _base_ │ └── global_configs.yml ├── lung_coronavirus │ ├── lung_coronavirus.yml │ ├── README.md │ └── vnet_lung_coronavirus_128_128_128_15k.yml

其中二级配置负责数据、增强、优化器与损失；三级配置（继承二级配置）只写模型部分，这样未来换模型时无需改动数据/训练设置。

5.2 增加数据集预处理文件

所有数据需要经过预处理转换成 numpy 数据并进行数据集划分，参考 tools/prepare_lung_coronavirus.py。该脚本继承Prep基类，你只需重写四块内容：

• 数据下载地址与解压配置（urls、uncompress_params）；
• 预处理流水线（如 HU 归一化、重采样到固定尺寸，图像用order=1、标签用order=0）；
• generate_txt中train_list.txt/val_list.txt的生成逻辑与划分比例（默认train_split=0.75）；
• 通过generate_dataset_json登记模态与类别语义。

产物必须满足统一的 numpy 目录规范：

├── lung_coronavirus_phase0 # 预处理后的文件路径 │ ├── images │ │ ├── imagexx.npy │ │ ├── ... │ ├── labels │ │ ├── labelxx.npy │ │ ├── ... │ ├── train_list.txt # 训练数据，格式: /path/to/img_name_xxx.npy /path/to/label_names_xxx.npy │ └── val_list.txt # 评估数据，格式: img_name_xxx.npy label_names_xxx.npy

5.3 增加数据集文件

所有的数据集都继承MedicalDataset基类，并通过上一步生成的train_list.txt和val_list.txt来获取数据。代码示例见 medicalseg/datasets/lung_coronavirus.py。

以该文件为模板，新的数据集类需要：

1. 继承MedicalDataset，在__init__中透传dataset_root、result_dir、transforms、num_classes、mode、ignore_index、dataset_json_path等参数；
2. 使用@manager.DATASETS.add_component装饰器注册类名，使配置文件中type: YourDataset能正确解析到该类；
3. 无需自己实现复杂的文件遍历逻辑——基类会基于train_list.txt/val_list.txt完成样本加载，并配合配置中的 3D 增强流水线输出(1, D, H, W)的图像与(D, H, W)的标签。

5.4 增加训练脚本

训练脚本能自动化训练推理过程，我们提供了 run-vnet.sh 示例供参考，只需要复制并按照需要修改三处即可一键完成训练→评估→导出→推理：

1. CUDA_VISIBLE_DEVICES：改成你要使用的 GPU 编号；
2. config_name：改成你的三级配置文件名（不含.yml后缀）；
3. 按需调整--save_interval、--num_workers、--keep_checkpoint_max等训练超参。

修改后执行脚本，即可在自有数据上复现与 COVID-19 CT 分割完全一致的端到端流程：训练日志写入saved_model/<config_name>/train.log，最优权重保存在best_model/model.pdparams，最终静态图与deploy.yaml输出到output/目录，随后deploy/python/infer.py直接对新的.npy体数据做推理预测。

6. 小结

MedicalSeg 通过"三级配置解耦 + 一键脚本串联"的设计，把医学图像分割从数据准备到部署的全链路收敛为极低的操作成本：_base_级配置统一数据根目录，二级配置沉淀数据/损失/优化器，三级配置只换模型；prepare_*.py脚本一键完成下载、预处理、切分；run-vnet.sh一条命令打通训练、评估、导出、推理。对于自有数据集，只需按第 5 节的四步模板补齐配置、预处理脚本、数据集类与训练脚本，即可无缝复用 VNet、UNETR、nnUNet 等 3D 分割模型，实现从算法到落地的快速闭环。

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