PaddleGAN 数据准备完全指南:数据集下载、路径配置与自制数据集构建

原创2026-09-26 22:26:061,636 阅读
文章标签:人工智能深度学习计算机视觉媒体生成图像处理视频处理

PaddleGAN 数据准备完全指南:数据集下载、路径配置与自制数据集构建

本文围绕 PaddleGAN 的数据准备环节展开,系统讲解数据集路径约定、官方数据集下载脚本、dataroot 配置项修改,以及面向 CycleGAN / Pix2Pix 两类模型的自制数据集目录规范。读完本文,你将能够独立完成从下载官方数据集、软链接到仓库、按需调整配置路径,到手工构建非成对 / 成对数据集的完整流程,并理解数据集在训练时被加载与预处理的具体机制。

1. 数据集路径约定:默认放在 $PaddleGAN/data 下

PaddleGAN 现有配置中,数据集路径的默认约定是放在 $PaddleGAN/data 目录下。以 CycleGAN 与 Pix2Pix 的常见数据集为例,推荐的目录结构如下:

PaddleGAN
|-- configs
|-- data
|   |-- cityscapes
|   |   ├── test
|   |   ├── testA
|   |   ├── testB
|   |   ├── train
|   |   ├── trainA
|   |   └── trainB
|   ├── horse2zebra
|   |   ├── testA
|   |   ├── testB
|   |   ├── trainA
|   |   └── trainB
|   └── facades
|       ├── test
|       ├── train
|       └── val
|-- docs
|-- ppgan
|-- tools

如果你已经自行下载好了数据集,官方建议的做法是:将数据集目录软链接到 $PaddleGAN/data 下,例如:

ln -s /your/real/dataset/path/horse2zebra data/horse2zebra

这样无需改动任何配置文件即可直接开始训练,符合大多数配置文件中 data/xxx 的默认写法。

配置文件中的 dataroot 参数

如果数据集放在其他位置,例如 your/data/path,可以通过修改配置文件中的 dataroot 参数来指定路径。以成对数据集(PairedDataset)为例:

dataset:
  train:
    name: PairedDataset
    dataroot: your/data/path
    num_workers: 4

dataroot 是数据集加载的核心路径参数。在 ppgan/datasets/paired_dataset.py 中,PairedDataset 的构造函数直接接收 dataroot,并通过 prepare_data_infos() 扫描该目录下的所有图片路径作为训练样本来源:

class PairedDataset(BaseDataset):
    def __init__(self, dataroot, preprocess):
        super(PairedDataset, self).__init__(preprocess)
        self.dataroot = dataroot
        self.data_infos = self.prepare_data_infos()

对应地,非成对数据集(UnpairedDataset)使用的是 dataroot_a 与 dataroot_b 两个参数,分别指向两个域的图片目录,详见 ppgan/datasets/unpaired_dataset.py。

除了直接改 YAML 文件,PaddleGAN 还支持在命令行通过 -o 参数覆盖配置项(实现见 ppgan/utils/config.py 的 override_config,以及 ppgan/utils/options.py 对 --opt 的解析):

python tools/main.py -c configs/cyclegan_horse2zebra.yaml \
    -o dataset.train.dataroot_a=/path/to/trainA dataset.train.dataroot_b=/path/to/trainB

-o 采用 key0.key1.key2=value 的点分键格式,可以逐层覆盖 dataset.train.dataroot 等任意配置项,非常适合在不修改配置文件的情况下切换不同数据集。

2. 下载官方数据集

2.1 CycleGAN 相关数据集

CycleGAN 模型常用的数据集有两个获取途径:

途径一:从网页下载

CycleGAN 官方数据集页面提供了 apple2orange、summer2winter_yosemite、horse2zebra、monet2photo、cezanne2photo、ukiyoe2photo、vangogh2photo、maps、cityscapes、facades、iphone2dslr_flower、ae_photos 等经典数据集压缩包。下载后记得将其软链接到 PaddleGAN/data/ 下,目录名需要与配置中 dataroot_a / dataroot_b 引用的路径一致。

途径二:使用仓库内置脚本下载(推荐)

PaddleGAN 在 data 目录下提供了脚本 data/download_cyclegan_data.py,一条命令即可完成"下载 + 解压 + 软链接"全流程:

python data/download_cyclegan_data.py --name horse2zebra

脚本目前支持的数据集名称包括:

apple2orange, summer2winter_yosemite, horse2zebra, monet2photo, cezanne2photo, ukiyoe2photo, vangogh2photo, maps, cityscapes, facades, iphone2dslr_flower, ae_photos

执行后,数据集会先被下载并解压到 ~/.cache/ppgan(该路径定义于 ppgan/utils/download.py 的 PPGAN_HOME),随后脚本自动在 PaddleGAN/data/ 下建立指向它的软链接:

path = get_path_from_url(data_url)
dst = os.path.join('data', args.name)
print('symlink {} to {}'.format(path, dst))
os.symlink(path, dst)

从源码可以确认几个实现细节:

  • get_path_from_url 会先检查 ~/.cache/ppgan 下是否已存在同名文件(含 md5 校验),存在则直接复用,避免重复下载;
  • 下载过程支持断点续传保护(先写 _tmp 临时文件,完成后原子移动),并带有最多 3 次重试的 DOWNLOAD_RETRY_LIMIT 机制;
  • 下载完成后自动识别 zip / tar 压缩包并解压,见 ppgan/utils/download.py 的 _decompress;
  • 多进程(分布式)训练场景下,只有 ParallelEnv().local_rank == 0 的进程执行实际下载,其他进程会等待文件就绪,见 ppgan/utils/download.py。

一个值得注意的细节:cityscapes 数据集由于体积较大,脚本对其做了特殊处理,改用 PaddleGAN 自托管地址下载(见 data/download_cyclegan_data.py)。

2.2 Pix2Pix 相关数据集

Pix2Pix 模型的数据集同样提供网页下载与脚本下载两种方式。

途径一:从网页下载

Pix2Pix 官方数据集页面提供了 cityscapes、night2day、edges2handbags、edges2shoes、facades、maps 等成对数据集。下载后同样记得软链接到 PaddleGAN/data/ 下。

途径二:使用脚本下载(推荐)

仓库提供了对应的脚本 data/download_pix2pix_data.py:

python data/download_pix2pix_data.py --name cityscapes

脚本支持的名称包括:

cityscapes, night2day, edges2handbags, edges2shoes, facades, maps

其工作方式与 CycleGAN 脚本一致:先通过 get_path_from_url 下载到 ~/.cache/ppgan 并解压,再在 data/ 下建立软链接。区别在于 Pix2Pix 数据集使用 .tar.gz 压缩格式(见 data/download_pix2pix_data.py),而 CycleGAN 数据集使用 .zip 格式,下载器会依据实际压缩类型自动选择解压方式。

3. 自制数据集

当需要用自己的数据训练时,需要按照模型的训练范式组织目录结构。PaddleGAN 主要区分两类:非成对数据集与成对数据集。

3.1 非成对数据集(适用于 CycleGAN 等)

CycleGAN 这类模型不需要成对(A 与 B 一一对应)的训练数据,只需要两个域各自的图片集合。自制数据时请构造成如下目录格式:

custom_datasets
├── testA
├── testB
├── trainA
└── trainB

需要注意:xxxA 与 xxxB 的图片文件数量、文件内容无需一一对应。

这一点在源码中有明确印证。在 ppgan/datasets/unpaired_dataset.py 的 __getitem__ 中,训练模式下 A 域图片按索引顺序取,而 B 域图片通过 random.randint(0, self.size_b - 1) 随机抽取,两个域完全独立采样:

def __getitem__(self, idx):
    if self.is_train:
        img_a_path = self.data_infos_a[idx % self.size_a]['path']
        idx_b = random.randint(0, self.size_b - 1)
        img_b_path = self.data_infos_b[idx_b]['path']
        datas = dict(A_path=img_a_path, B_path=img_b_path)

同时,UnpairedDataset.__len__ 返回 max(self.size_a, self.size_b),即以两个域中图片数量较多的一方为准,进一步体现了两个域无需等量、无需配对的特性。

3.2 成对数据集(适用于 Pix2Pix 等)

Pix2Pix 这类模型要求输入与输出是严格对应的图像对,自制数据时需要构造成如下目录格式:

facades
├── test
├── train
└── val

其中每张图片本身必须是"拼接对"的形式:图片左半边为一种风格(域 A),右半边为对应的另一种风格(域 B),即一张图同时包含输入与监督信号,训练时再由预处理环节将其切分为左右两半。

下图展示了成对图像的典型拼接方式——左侧为一种风格,右侧为对应的转换风格:

成对数据集图像拼接示例:左半边为源风格图像,右半边为对应目标风格图像

这种"拼图式"组织方式对应的切分逻辑实现在 ppgan/datasets/preprocess/transforms.py 的 SplitPairedImage 中:读取整张拼接图后,按宽度中点 w2 = int(w / 2) 将左半部分作为 A、右半部分作为 B:

class SplitPairedImage:
    def __call__(self, datas):
        h, w = datas[self.key].shape[:2]
        w2 = int(w / 2)
        a, b = self.paired_keys
        datas[a] = datas[self.key][:h, :w2, :]
        datas[b] = datas[self.key][:h, w2:, :]

在 configs/pix2pix_cityscapes.yaml 的 train 预处理流水线中可以看到完整调用链:LoadImageFromFile 加载拼接图 → SplitPairedImage 切成 A/B 两域 → Transforms 对 A、B 同时执行 Resize、PairedRandomCrop、PairedRandomHorizontalFlip、Transpose、Normalize。其中 PairedRandomCrop 与 PairedRandomHorizontalFlip 是专门为成对数据设计的"配对增强"变换——对 A、B 使用完全相同的裁剪坐标和翻转策略,保证两域图像始终空间对齐(实现见 ppgan/datasets/preprocess/transforms.py)。

4. 数据集在训练时的加载与校验机制

理解了目录结构之后,有必要了解数据集是如何被扫描与加载的,这有助于排查"数据集路径正确但报错"的问题。

所有数据集的基类 ppgan/datasets/base_dataset.py 提供了统一的目录扫描逻辑 scan_folder:

  • 支持的图片格式为 .jpg/.jpeg/.png/.ppm/.bmp(含大小写变体),定义于 IMG_EXTENSIONS;
  • 扫描是递归的,即子目录下的图片也会被纳入;
  • 若目录下没有任何合法图片文件,会直接断言报错 '{} has no valid image file.'。

因此,自制数据集时请确保:

  1. 目录名与配置中 dataroot / dataroot_a / dataroot_b 完全一致;
  2. 目录内图片使用上述受支持的格式;
  3. 目录不为空,且成对数据集的每张图都是左右拼接的完整对。

在 configs/cyclegan_horse2zebra.yaml 中可以看到一个完整的非成对数据集配置参考:训练集使用 UnpairedDataset 并分别指定 dataroot_a: data/horse2zebra/trainA、dataroot_b: data/horse2zebra/trainB,测试集指向 testA / testB。训练时通过 tools/main.py 入口读取配置文件,将 dataset 字段交给 Trainer 构建数据加载器。

5. 小结:数据准备三步走

综合以上内容,PaddleGAN 的数据准备可以归纳为三步:

  1. 确定范式:先确认模型需要成对数据(如 Pix2Pix)还是非成对数据(如 CycleGAN),据此决定目录结构与图片组织方式;
  2. 获取数据:优先使用仓库脚本一键下载(python data/download_cyclegan_data.py --name xxx 或 python data/download_pix2pix_data.py --name xxx),下载后自动软链接到 data/ 下;自制数据则严格按 trainA/trainB/testA/testB(非成对)或 train/test/val + 左右拼接图(成对)组织;
  3. 确认路径:保持默认的 data/ 布局即可零配置运行;若放在其他位置,通过修改 YAML 中的 dataroot(或 dataroot_a/dataroot_b)或使用 -o dataset.train.dataroot=... 命令行覆盖,确保路径与目录结构准确无误后即可开始训练。
登录后查看全文
PaddleGAN