PaddleGAN 数据准备完全指南:数据集下载、路径配置与自制数据集构建
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.'。
因此,自制数据集时请确保:
- 目录名与配置中
dataroot/dataroot_a/dataroot_b完全一致; - 目录内图片使用上述受支持的格式;
- 目录不为空,且成对数据集的每张图都是左右拼接的完整对。
在 configs/cyclegan_horse2zebra.yaml 中可以看到一个完整的非成对数据集配置参考:训练集使用 UnpairedDataset 并分别指定 dataroot_a: data/horse2zebra/trainA、dataroot_b: data/horse2zebra/trainB,测试集指向 testA / testB。训练时通过 tools/main.py 入口读取配置文件,将 dataset 字段交给 Trainer 构建数据加载器。
5. 小结:数据准备三步走
综合以上内容,PaddleGAN 的数据准备可以归纳为三步:
- 确定范式:先确认模型需要成对数据(如 Pix2Pix)还是非成对数据(如 CycleGAN),据此决定目录结构与图片组织方式;
- 获取数据:优先使用仓库脚本一键下载(
python data/download_cyclegan_data.py --name xxx或python data/download_pix2pix_data.py --name xxx),下载后自动软链接到data/下;自制数据则严格按trainA/trainB/testA/testB(非成对)或train/test/val+ 左右拼接图(成对)组织; - 确认路径:保持默认的
data/布局即可零配置运行;若放在其他位置,通过修改 YAML 中的dataroot(或dataroot_a/dataroot_b)或使用-o dataset.train.dataroot=...命令行覆盖,确保路径与目录结构准确无误后即可开始训练。
