PaddleGAN 数据准备完全指南:数据集目录结构、下载脚本与自制数据集

原创2026-09-25 17:31:531,953 阅读
文章标签:人工智能深度学习计算机视觉媒体生成图像处理视频处理

PaddleGAN 数据准备完全指南:数据集目录结构、下载脚本与自制数据集

导读

数据集的正确组织与路径配置,是 PaddleGAN 中 CycleGAN、Pix2Pix 等图像转换模型能够顺利训练和评估的前提。本文以 docs/en_US/data_prepare.md 为骨架,结合仓库内的下载脚本、数据集实现与配置文件,系统讲解 PaddleGAN 数据集路径配置、CycleGAN/Pix2Pix 官方数据集的两种下载方式、非成对与成对自制数据集的目录规范,以及底层数据读取原理。阅读完本文,你将能够独立完成 PaddleGAN 图像生成任务的从数据下载到目录组织、再到配置生效的完整流程。

1. 数据集路径配置:软链接与 dataroot

1.1 默认路径约定:$PaddleGAN/data

PaddleGAN 中所有官方配置文件(configs/ 目录下的 yaml)默认假设数据集位于项目根目录下的 data/ 目录中。仓库预期的标准目录结构如下:

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/data/path/horse2zebra $PaddleGAN/data/horse2zebra

1.2 自定义路径:修改配置中的 dataroot

如果数据集放在其他位置(例如 your/data/path),可以直接修改对应 yaml 配置文件中的 dataroot 参数。文档给出的示例片段如下:

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

注意两点:

  1. 该示例中的 dataroot 为**成对数据集(PairedDataset)**所用(Pix2Pix 等模型),此时数据集目录下应直接存放成对图片文件。
  2. 对于非成对数据集(UnpairedDataset)(CycleGAN 等模型),配置中同时存在 dataroot_a 与 dataroot_b 两个路径字段。以 configs/cyclegan_horse2zebra.yaml 为例:
dataset:
  train:
    name: UnpairedDataset
    dataroot_a: data/horse2zebra/trainA
    dataroot_b: data/horse2zebra/trainB
    num_workers: 0
    batch_size: 1
    is_train: True
    max_size: inf

dataroot_a 与 dataroot_b 分别指向 A 域与 B 域的图片目录,这一设计直接对应下方数据集的源码构造函数签名(见第 4 节)。相应地,Pix2Pix 使用的 configs/pix2pix_cityscapes.yaml 中则只有单个 dataroot 字段(data/cityscapes/train、data/cityscapes/val),因为成对数据集每个目录下存放的是左右拼接好的"AB 成对图"。

2. CycleGAN 数据集准备

CycleGAN 属于非成对图像转换模型,其官方数据集可从 Berkeley 的 CycleGAN 数据集页面下载,下载后记得软链接到 PaddleGAN/data/ 下。更便捷的方式是使用仓库自带的下载脚本。

2.1 脚本下载:download_cyclegan_data.py

仓库在 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。

脚本工作流程如下(对应 download_cyclegan_data.py 源码):

  1. 拼接下载地址:https://people.eecs.berkeley.edu/~taesung_park/CycleGAN/datasets/<name>.zip;
  2. 特殊处理 cityscapes:由于官方渠道对 cityscapes 的访问限制,脚本将其下载源切换到 https://paddlegan.bj.bcebos.com/datasets/cityscapes.zip(Baidu BOS 镜像);
  3. 调用 get_path_from_url 下载并解压到缓存目录 ~/.cache/ppgan;
  4. 将解压后的目录软链接到 PaddleGAN/data/<name>。

2.2 下载底层机制:ppgan.utils.download

下载与缓存逻辑由 ppgan/utils/download.py 统一实现,其中 get_path_from_url(url, md5sum=None, check_exist=True) 是核心函数,值得了解的几个关键行为:

  • 缓存根目录固定为 ~/.cache/ppgan(PPGAN_HOME),这也是文档所说"数据集被下载到 ~/.cache/ppgan"的由来;
  • 若目标文件已存在且(可选)md5 校验通过,直接复用本地文件,不会重复下载;
  • 下载失败自动重试,重试上限为 3 次(DOWNLOAD_RETRY_LIMIT = 3);
  • 下载采用"临时文件 + 完成后原子改名"的方式(先写 xxx_tmp 再 shutil.move),避免下载中断留下损坏文件;
  • 解压时自动识别 zip/tar 格式,并区分"单文件""单目录""多目录"三种压缩结构,返回正确的解压根路径;
  • 在多卡(ParallelEnv)场景下,仅 local_rank == 0 执行下载与解压,其他进程等待文件就绪,避免并发写冲突。

3. Pix2Pix 数据集准备

3.1 脚本下载:download_pix2pix_data.py

Pix2Pix 数据集同样可以通过仓库脚本一键下载,脚本为 download_pix2pix_data.py,用法:

python data/download_pix2pix_data.py --name cityscapes

该脚本支持的名称包括:cityscapes、night2day、edges2handbags、edges2shoes、facades、maps,下载源为 http://efrosgans.eecs.berkeley.edu/pix2pix/datasets/<name>.tar.gz。与 CycleGAN 脚本不同的是,Pix2Pix 数据以 .tar.gz 压缩包提供,解压后同样软链接到 PaddleGAN/data/<name>。

3.2 与 CycleGAN 脚本的异同

维度 download_cyclegan_data.py download_pix2pix_data.py
下载源 people.eecs.berkeley.edu 的 CycleGAN 目录 efrosgans.eecs.berkeley.edu 的 pix2pix 目录
压缩格式 .zip(cityscapes 走 bcebos 镜像) .tar.gz
解压后目录示例 horse2zebra/{trainA,trainB,testA,testB} cityscapes/{train,val,test}
与数据集类的配合 UnpairedDataset(dataroot_a / dataroot_b) PairedDataset(dataroot)

4. 自制数据集:目录规范与图片格式

4.1 非成对数据集(CycleGAN 类模型)

针对无需成对数据训练的模型(如 CycleGAN),自制数据集需要按以下目录结构组织:

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

关键约束:xxxA 与 xxxB 两个域之间的文件数量、文件内容无需一一对应。这一点由源码直接印证——ppgan/datasets/unpaired_dataset.py 的 __getitem__ 实现中,训练模式下 A 域图片按索引顺序取(idx % self.size_a),而 B 域图片通过 random.randint(0, self.size_b - 1) 随机抽取,两个域完全独立采样;非训练(测试/推理)模式下 A、B 才按索引一一对应(idx % self.size_b)。此外,__len__ 返回 max(self.size_a, self.size_b),即数据集长度取两个域中较大者,进一步印证了两域样本数无需相等。

4.2 成对数据集(Pix2Pix 类模型)

针对需要成对数据训练的模型(如 Pix2Pix),自制数据集需要按如下目录组织:

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

图片格式约束(重要):成对数据集中的每张图片应是"左图 + 右图"水平拼接的形式——左侧为一种风格(如语义分割标注图),右侧为对应的转换目标风格(如真实街景照片),原始示意图见 docs/imgs/1.jpg。训练时,LoadImageFromFile 以 key: pair 读入整张拼接图,随后由 SplitPairedImage 预处理在宽度方向对半切开。其源码位于 ppgan/datasets/preprocess/transforms.py:

class SplitPairedImage:
    def __init__(self, key, paired_keys=['A', 'B']):
        self.key = key
        self.paired_keys = paired_keys

    def __call__(self, datas):
        # split AB image into A and B
        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:, :]
        ...

即取左半 <a href="https://link.gitcode.com/i/f9fd8cc825e225e52d6493600378890f" target="_blank">:, :w2] 作为 A,右半 [:, w2:] 作为 B。因此自制成对图片务必保证左右两半内容对齐、宽度为偶数,否则切分后 A/B 无法准确对应。对应配置见 [configs/pix2pix_cityscapes.yaml:

preprocess:
  - name: LoadImageFromFile
    key: pair
  - name: SplitPairedImage
    key: pair
    paired_keys: [A, B]

5. 数据集读取与文件扫描的底层原理

5.1 支持的文件格式

数据集的图片扫描基于 ppgan/datasets/base_dataset.py 中定义的 IMG_EXTENSIONS:.jpg、.jpeg、.png、.ppm、.bmp(大小写均支持)。scan_folder 会递归扫描子目录,并断言目录下存在合法图片文件,否则抛出 '{} has no valid image file.' 错误——如果下载或解压失败导致目录为空,训练脚本会在数据集构建阶段直接报错,这也是排查数据问题时的首要检查点。

5.2 数据集类与预处理管线

  • UnpairedDataset(ppgan/datasets/unpaired_dataset.py):接收 dataroot_a、dataroot_b、is_train、max_size 与 preprocess 参数,通过 prepare_data_infos 分别扫描两个域得到 data_infos_a / data_infos_b;
  • PairedDataset(ppgan/datasets/paired_dataset.py):接收单个 dataroot,扫描该目录下的成对图片列表。

两者的预处理均由 BaseDataset.__getitem__ 统一触发:对每个样本调用 self.preprocess(datas)(base_dataset.py),预处理链由配置文件中的 preprocess 列表声明式构建。以 CycleGAN 为例,训练管线通常为:LoadImageFromFile 加载 A/B 图 → Resize 到 286×286 → RandomCrop 到 256×256 → 0.5 概率 RandomHorizontalFlip → Transpose 调整为 CHW → Normalize(mean/std 均为 127.5,将像素归一化到 -1, 1]),详见 [configs/cyclegan_horse2zebra.yaml。

5.3 数据集注册机制

UnpairedDataset、PairedDataset 等数据集类均通过 @DATASETS.register() 装饰器注册(见各文件头部),配置文件中 dataset.train.name: UnpairedDataset / PairedDataset 字符串即据此解析为对应类。若自定义数据集类,遵循同样的注册模式即可在配置中直接引用。

6. 端到端操作速查

按以下顺序即可完成 PaddleGAN 图像转换任务的数据准备:

  1. 下载官方数据集(二选一):
    python data/download_cyclegan_data.py --name horse2zebra
    python data/download_pix2pix_data.py --name cityscapes
    
    脚本会自动下载到 ~/.cache/ppgan 并软链接到 data/ 目录;
  2. 核对目录结构:确认 data/horse2zebra 下存在 trainA/trainB/testA/testB(CycleGAN),或 data/cityscapes 下存在 train/val/test(Pix2Pix),且目录非空;
  3. 选用配置文件:CycleGAN 用 configs/cyclegan_horse2zebra.yaml,Pix2Pix 用 configs/pix2pix_cityscapes.yaml;
  4. 自定义数据路径:将配置中 dataroot(成对)或 dataroot_a/dataroot_b(非成对)改为自己的数据路径,或直接将数据软链接到 data/ 下保持默认;
  5. 自制数据注意:非成对数据保证 A/B 目录存在即可(数量可不一致);成对数据必须为"左 A 右 B"拼接图,宽度为偶数,并按 train/val/test 组织。

完成以上步骤后,即可进入常规训练流程(如通过 tools/main.py 指定对应配置文件启动训练)。数据目录的规范性直接决定数据集能否被正确扫描与采样,任何路径或格式问题通常都会在训练启动阶段以明确的报错信息暴露出来,按第 5 节的底层机制即可快速定位。

登录后查看全文
PaddleGAN