企业官网建设流程全解析

Diffusers 训练数据集构建实战：本地 ImageFolder 与 Hub 数据集两种方案全解析

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers

本篇指南基于 Diffusers 官方文档 Create a dataset for training 展开，讲清楚如何为扩散模型微调准备训练数据：你可以选择把本地图片目录直接传给训练脚本的--train_data_dir参数，也可以用 🤗 Datasets 库把数据集上传到 Hub 后通过--dataset_name参数引用。读完本文，你将掌握数据集目录结构的组织方式、load_dataset("imagefolder")的各种加载姿势，以及两条路径在 train_text_to_image.py 和 train_unconditional.py 中的真实数据加载链路。

数据集结构取决于训练任务

Diffusers 支持多种训练范式，不同范式对数据集的要求不同。官方文档给出了两种最基本的数据集组织形态：

• 无监督（unconditional）图像生成：最简单，只需一个图片目录，目录下直接存放图片文件；
• 文生图（text-to-image）生成：需要图片目录加上一个存放对应文本描述（captions）的文本文件（如metadata.jsonl），让每张图片与它的描述文字关联起来。

也就是说，数据集的"骨架"由你要训练的任务决定：纯图片目录服务于无监督训练，图片 + 文本描述对服务于条件生成训练。

方案一：把本地文件夹直接交给训练脚本

目录结构要求

以无监督生成为例，你的数据目录结构应当形如：

data_dir/xxx.png data_dir/xxy.png data_dir/[...]/xxz.png

即图片可以平铺在data_dir下，也可以放在其子目录中。训练脚本会调用 🤗 Datasets 的ImageFolderbuilder 自动把文件夹构建成数据集，你不需要手动写任何数据读取代码。

从源码看，这一行为发生在 train_unconditional.py：

dataset = load_dataset("imagefolder", data_dir=args.train_data_dir, cache_dir=args.cache_dir, split="train")

--train_data_dir参数的帮助文本（train_unconditional.py）明确要求文件夹内容遵循ImageFolder规范；对于文生图脚本 train_text_to_image.py，帮助文本进一步指出：该目录下必须存在一个metadata.jsonl文件来提供图片的文本描述，且当--dataset_name已指定时该参数会被忽略。

启动训练

把数据集目录路径传给--train_data_dir即可开始训练，例如（摘自 unconditional_image_generation/README.md）：

accelerate launch train_unconditional.py \ --train_data_dir <path-to-train-directory> \ <other-arguments>

加载之后，脚本会对数据集挂上一套预处理 transform。以 train_unconditional.py 为例，流程是：按--resolution做 Resize（默认 64），根据--center_crop/--random_flip选择 CenterCrop 或 RandomCrop、是否水平翻转，随后ToTensor并用Normalize([0.5], [0.5])把像素值归一化到[-1, 1]区间，最后通过dataset.set_transform(transform_images)在 DataLoader 取样时动态应用。

方案二：上传数据集到 Hub 后按名称引用

用 ImageFolder 特性构建数据集

对于文生图这类带文本描述的任务，推荐用 🤗 Datasets 的ImageFolder特性来构建数据集——它会生成一个包含 PIL 编码图像的image列。

构建时可以通过data_dir或data_files参数指定数据位置。其中data_files支持把具体文件映射到train、test等数据集 split，也支持 tar、gzip、zip、xz、rar、zstd 等压缩格式：

from datasets import load_dataset # example 1: local folder dataset = load_dataset("imagefolder", data_dir="path_to_your_folder") # example 2: local files (supported formats are tar, gzip, zip, xz, rar, zstd) dataset = load_dataset("imagefolder", data_files="path_to_zip_file") # example 3: remote files (supported formats are tar, gzip, zip, xz, rar, zstd) dataset = load_dataset( "imagefolder", data_files="https://download.microsoft.com/download/3/E/1/3E1C3F21-ECDB-4869-8368-6DEBA77B919F/kagglecatsanddogs_3367a.zip", ) # example 4: providing several splits dataset = load_dataset( "imagefolder", data_files={"train": ["path/to/file1", "path/to/file2"], "test": ["path/to/file3", "path/to/file4"]} )

上传到 Hub

构建好之后，用push_to_hub方法上传（前提是在终端执行过hf auth login完成认证）：

# assuming you have ran the hf auth login command in a terminal dataset.push_to_hub("name_of_your_dataset") # if you want to push to a private repo, simply pass private=True: dataset.push_to_hub("name_of_your_dataset", private=True)

私有仓库同样受支持，只需传入private=True。

用 --dataset_name 启动训练

数据集上传后，把仓库 ID 传给--dataset_name参数即可在训练时自动下载并使用：

accelerate launch --mixed_precision="fp16" train_text_to_image.py \ --pretrained_model_name_or_path="stable-diffusion-v1-5/stable-diffusion-v1-5" \ --dataset_name="name_of_your_dataset" \ <other-arguments>

从源码看，--dataset_name的取值范围比"Hub 仓库 ID"更宽：train_text_to_image.py 的帮助文本说明它既可以是 HuggingFace Hub 上的数据集名（可以是自己的、甚至私有的），也可以是指向本地文件系统数据集副本的路径，或指向 Datasets 库能理解的文件夹。

源码深读：两条加载路径如何分流

理解训练脚本内部的数据加载逻辑，有助于排查数据集相关问题。train_text_to_image.py 中的分流逻辑如下：

if args.dataset_name is not None: # Downloading and loading a dataset from the hub. dataset = load_dataset( args.dataset_name, args.dataset_config_name, cache_dir=args.cache_dir, data_dir=args.train_data_dir, ) else: data_files = {} if args.train_data_dir is not None: data_files["train"] = os.path.join(args.train_data_dir, "**") dataset = load_dataset( "imagefolder", data_files=data_files, cache_dir=args.cache_dir, )

可以确认几个关键行为：

1. --dataset_name优先级更高：一旦指定，--train_data_dir会被作为该数据集的data_dir（子目录）传入，而不是独立的图片目录；
2. 本地路径走 imagefolder：未指定--dataset_name时，脚本把--train_data_dir下所有内容（**通配）映射到trainsplit，再交给imagefolderbuilder 解析；
3. 两者都没给会直接报错：train_text_to_image.py 处有if args.dataset_name is None and args.train_data_dir is None的参数校验，无监督脚本 train_unconditional.py 同样如此。

列名的确定与校验

数据集加载后，脚本还要定位"图片列"和"文本列"。train_text_to_image.py 内置了一个映射表处理知名数据集：

DATASET_NAME_MAPPING = { "lambdalabs/naruto-blip-captions": ("image", "text"), }

其后的处理逻辑（第 761-778 行）：如果你显式传了--image_column/--caption_column（默认分别是image和text），且该列名不存在于数据集列中，脚本会抛出ValueError并列出所有可用列名——这是数据集列名不匹配时报错信息的主要来源。若未显式指定，则依次回退到DATASET_NAME_MAPPING和按列顺序取第一、第二列。

文本描述的 tokenization 细节

对于文生图训练，tokenize_captions 函数处理 caption 列：字符串直接使用；如果某张图片对应多条描述（list），训练时会随机抽取一条，非训练场景则取第一条。图片侧则统一经过Resize → (Center/Random)Crop → 可选 RandomHorizontalFlip → ToTensor → Normalize([0.5], [0.5])的 transform 链（第 807-815 行），--resolution默认 512。

测试用例中的真实用法参考

如果你想要一个可直接运行的最小参数组合，仓库的示例测试 test_unconditional.py 展示了用 Hub 上的 dummy 数据集做冒烟训练的方式：

examples/unconditional_image_generation/train_unconditional.py \ --dataset_name hf-internal-testing/dummy_image_class_data \ --model_config_name_or_path diffusers/ddpm_dummy \ --resolution 64 \ --train_batch_size 2 \ --num_epochs 1

它验证了--dataset_name路径训练完成后，输出目录中应生成unet/diffusion_pytorch_model.safetensors与scheduler/scheduler_config.json，可作为"数据集是否被正确加载并跑通训练"的验收标准。

前置准备与依赖安装

按 unconditional_image_generation/README.md 的说明，运行示例训练脚本前建议从源码安装 diffusers 并保持更新，再安装示例目录的依赖并初始化 Accelerate 环境：

pip install . # 在 diffusers 源码根目录下 cd examples/unconditional_image_generation pip install -r requirements.txt accelerate config

下一步

数据集就绪后，就可以按数据所在位置选择接入方式：本地数据集传--train_data_dir，Hub 上的数据集传--dataset_name。随后可以参考官方教程继续训练——无监督生成见 Unconditional diffusion training，文生图微调见 Text-to-image training。

【免费下载链接】diffusers🤗 Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers