From a4b73459781c927852b19fdb1f2f2e1d5ce23334 Mon Sep 17 00:00:00 2001
From: maito1201 <itomasa0915@gmail.com>
Date: Sat, 3 Sep 2022 23:48:54 +0900
Subject: [PATCH] feat(example): add conditional image generation

---
 .../conditional_image_generation/README.md    | 103 +++++++
 .../dataset_example/huggingface.png           | Bin 0 -> 25476 bytes
 .../requirements.txt                          |   3 +
 .../train_conditional.py                      | 265 ++++++++++++++++++
 4 files changed, 371 insertions(+)
 create mode 100644 examples/conditional_image_generation/README.md
 create mode 100644 examples/conditional_image_generation/dataset_example/huggingface.png
 create mode 100644 examples/conditional_image_generation/requirements.txt
 create mode 100644 examples/conditional_image_generation/train_conditional.py

diff --git a/examples/conditional_image_generation/README.md b/examples/conditional_image_generation/README.md
new file mode 100644
index 000000000000..9cd10c35a621
--- /dev/null
+++ b/examples/conditional_image_generation/README.md
@@ -0,0 +1,103 @@
+## Training examples
+
+Creating a training image set is [described in a different document](https://huggingface.co/docs/datasets/image_process#image-datasets).
+
+### Installing the dependencies
+
+Before running the scipts, make sure to install the library's training dependencies:
+
+```bash
+pip install diffusers[training] accelerate datasets
+```
+
+And initialize an [🤗Accelerate](https://github.com/huggingface/accelerate/) environment with:
+
+```bash
+accelerate config
+```
+
+### conditional example  
+
+TODO: prepare examples
+
+### Using your own data
+
+To use your own dataset, there are 2 ways:
+- you can either provide your own folder as `--train_data_dir`
+- or you can upload your dataset to the hub (possibly as a private repo, if you prefer so), and simply pass the `--dataset_name` argument.
+
+Below, we explain both in more detail.
+
+#### Provide the dataset as a folder
+
+If you provide your own folders with images, the script expects the following directory structure:
+
+```bash
+data_dir/xxx.png
+data_dir/xxy.png
+data_dir/[...]/xxz.png
+```
+
+In other words, the script will take care of gathering all images inside the folder. You can then run the script like this:
+
+```bash
+accelerate launch train_conditional.py \
+    --train_data_dir <path-to-train-directory> \
+    <other-arguments>
+```
+
+Internally, the script will use the [`ImageFolder`](https://huggingface.co/docs/datasets/v2.0.0/en/image_process#imagefolder) feature which will automatically turn the folders into 🤗 Dataset objects.
+
+#### Upload your data to the hub, as a (possibly private) repo
+
+It's very easy (and convenient) to upload your image dataset to the hub using the [`ImageFolder`](https://huggingface.co/docs/datasets/v2.0.0/en/image_process#imagefolder) feature available in 🤗 Datasets. Simply do the following:
+
+```python
+from datasets import load_dataset
+
+# example 1: local folder
+dataset = load_dataset("imagefolder", data_dir="path_to_your_folder")
+
+# example 2: local files (suppoted 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"]})
+```
+
+`ImageFolder` will create an `image` column containing the PIL-encoded images.
+
+Next, push it to the hub!
+
+```python
+# assuming you have ran the huggingface-cli 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)
+```
+
+and that's it! You can now train your model by simply setting the `--dataset_name` argument to the name of your dataset on the hub.
+
+More on this can also be found in [this blog post](https://huggingface.co/blog/image-search-datasets).
+
+#### How to use in the pipeline
+
+```python
+# make sure you're logged in with `huggingface-cli login`
+from torch import autocast
+from diffusers import StableDiffusionPipeline
+
+# Replace it to model that you want to use.
+unet = UNet2DConditionModel.from_pretrained("CompVis/stable-diffusion-v1-4", subfolder="unet", use_auth_token=True)
+
+pipe = StableDiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4", unet=unet use_auth_token=True)
+pipe = pipe.to("cuda")
+
+prompt = "a photo of an astronaut riding a horse on mars"
+with autocast("cuda"):
+    image = pipe(prompt)["sample"][0]  
+```
\ No newline at end of file
diff --git a/examples/conditional_image_generation/dataset_example/huggingface.png b/examples/conditional_image_generation/dataset_example/huggingface.png
new file mode 100644
index 0000000000000000000000000000000000000000..c4f5bbd66df2bbb0c80b739d57afe16b8d97a6b8
GIT binary patch
literal 25476
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

literal 0
HcmV?d00001

diff --git a/examples/conditional_image_generation/requirements.txt b/examples/conditional_image_generation/requirements.txt
new file mode 100644
index 000000000000..bbc690556020
--- /dev/null
+++ b/examples/conditional_image_generation/requirements.txt
@@ -0,0 +1,3 @@
+accelerate
+torchvision
+datasets
diff --git a/examples/conditional_image_generation/train_conditional.py b/examples/conditional_image_generation/train_conditional.py
new file mode 100644
index 000000000000..eb333c86779f
--- /dev/null
+++ b/examples/conditional_image_generation/train_conditional.py
@@ -0,0 +1,265 @@
+import argparse
+import math
+import os
+
+import torch
+import torch.nn.functional as F
+
+from accelerate import Accelerator
+from accelerate.logging import get_logger
+from datasets import load_dataset
+# from diffusers import DDPMPipeline, DDPMScheduler, UNet2DModel
+from diffusers import DDPMPipeline, DDPMScheduler, UNet2DConditionModel
+from diffusers.hub_utils import init_git_repo, push_to_hub
+from diffusers.optimization import get_scheduler
+from diffusers.training_utils import EMAModel
+from torchvision.transforms import (
+    CenterCrop,
+    Compose,
+    InterpolationMode,
+    Normalize,
+    RandomHorizontalFlip,
+    Resize,
+    ToTensor,
+)
+from tqdm.auto import tqdm
+from transformers import CLIPTextModel, CLIPTokenizer
+
+
+logger = get_logger(__name__)
+
+def main(args):
+    logging_dir = os.path.join(args.output_dir, args.logging_dir)
+    accelerator = Accelerator(
+        gradient_accumulation_steps=args.gradient_accumulation_steps,
+        mixed_precision=args.mixed_precision,
+        log_with="tensorboard",
+        logging_dir=logging_dir,
+    )
+
+    # FIXME implement training script
+    model = UNet2DConditionModel(
+        sample_size=args.resolution,
+        in_channels=3,
+        out_channels=3,
+        layers_per_block=2,
+        block_out_channels=(128, 128, 256, 256, 512, 512),
+        down_block_types=(
+            "DownBlock2D",
+            "DownBlock2D",
+            "DownBlock2D",
+            "DownBlock2D",
+            "AttnDownBlock2D",
+            "DownBlock2D",
+        ),
+        up_block_types=(
+            "UpBlock2D",
+            "AttnUpBlock2D",
+            "UpBlock2D",
+            "UpBlock2D",
+            "UpBlock2D",
+            "UpBlock2D",
+        ),
+    )
+
+    noise_scheduler = DDPMScheduler(num_train_timesteps=1000, tensor_format="pt")
+    optimizer = torch.optim.AdamW(
+        model.parameters(),
+        lr=args.learning_rate,
+        betas=(args.adam_beta1, args.adam_beta2),
+        weight_decay=args.adam_weight_decay,
+        eps=args.adam_epsilon,
+    )
+
+    # it is needed to generate tokenized input to train.
+    text_encoder = CLIPTextModel.from_pretrained("openai/clip-vit-base-patch32")
+    tokenizer = CLIPTokenizer.from_pretrained("openai/clip-vit-base-patch32")
+
+    augmentations = Compose(
+        [
+            Resize(args.resolution, interpolation=InterpolationMode.BILINEAR),
+            CenterCrop(args.resolution),
+            RandomHorizontalFlip(),
+            ToTensor(),
+            Normalize([0.5], [0.5]),
+        ]
+    )
+
+    if args.dataset_name is not None:
+        dataset = load_dataset(
+            args.dataset_name,
+            args.dataset_config_name,
+            cache_dir=args.cache_dir,
+            use_auth_token=True if args.use_auth_token else None,
+            split="train",
+        )
+    else:
+        dataset = load_dataset("imagefolder", data_dir=args.train_data_dir, cache_dir=args.cache_dir, split="train")
+
+    def transforms(examples):
+        images = [augmentations(image.convert("RGB")) for image in examples["image"]]
+        return {"input": images}
+
+    dataset.set_transform(transforms)
+    train_dataloader = torch.utils.data.DataLoader(dataset, batch_size=args.train_batch_size, shuffle=True)
+
+    lr_scheduler = get_scheduler(
+        args.lr_scheduler,
+        optimizer=optimizer,
+        num_warmup_steps=args.lr_warmup_steps,
+        num_training_steps=(len(train_dataloader) * args.num_epochs) // args.gradient_accumulation_steps,
+    )
+
+    model, optimizer, train_dataloader, lr_scheduler = accelerator.prepare(
+        model, optimizer, train_dataloader, lr_scheduler
+    )
+
+    num_update_steps_per_epoch = math.ceil(len(train_dataloader) / args.gradient_accumulation_steps)
+
+    ema_model = EMAModel(model, inv_gamma=args.ema_inv_gamma, power=args.ema_power, max_value=args.ema_max_decay)
+
+    if args.push_to_hub:
+        repo = init_git_repo(args, at_init=True)
+
+    if accelerator.is_main_process:
+        run = os.path.split(__file__)[-1].split(".")[0]
+        accelerator.init_trackers(run)
+
+    global_step = 0
+    for epoch in range(args.num_epochs):
+        model.train()
+        progress_bar = tqdm(total=num_update_steps_per_epoch, disable=not accelerator.is_local_main_process)
+        progress_bar.set_description(f"Epoch {epoch}")
+        for step, batch in enumerate(train_dataloader):
+            clean_images = batch["input"]
+            # Sample noise that we'll add to the images
+            noise = torch.randn(clean_images.shape).to(clean_images.device)
+            bsz = clean_images.shape[0]
+            # Sample a random timestep for each image
+            timesteps = torch.randint(
+                0, noise_scheduler.num_train_timesteps, (bsz,), device=clean_images.device
+            ).long()
+
+            # FIXME The input should probably select the appropriate one from the dataset.
+            # Sample a text input
+            uncond_input = tokenizer(
+                [""] * args.eval_batch_size, padding="max_length", max_length=77, return_tensors="pt"
+            )
+            uncond_embeddings = text_encoder(uncond_input.input_ids.to(clean_images.device))[0]
+            hidden_state = uncond_embeddings
+
+            # Add noise to the clean images according to the noise magnitude at each timestep
+            # (this is the forward diffusion process)
+            noisy_images = noise_scheduler.add_noise(clean_images, noise, timesteps)
+
+            with accelerator.accumulate(model):
+                # Predict the noise residual
+                # FIXME Implement a successfully trainable model and training script
+                noise_pred = model(noisy_images, timesteps, encoder_hidden_states=hidden_state)["sample"]
+                loss = F.mse_loss(noise_pred, noise)
+                accelerator.backward(loss)
+
+                accelerator.clip_grad_norm_(model.parameters(), 1.0)
+                optimizer.step()
+                lr_scheduler.step()
+                if args.use_ema:
+                    ema_model.step(model)
+                optimizer.zero_grad()
+
+            # Checks if the accelerator has performed an optimization step behind the scenes
+            if accelerator.sync_gradients:
+                progress_bar.update(1)
+                global_step += 1
+
+            logs = {"loss": loss.detach().item(), "lr": lr_scheduler.get_last_lr()[0], "step": global_step}
+            if args.use_ema:
+                logs["ema_decay"] = ema_model.decay
+            progress_bar.set_postfix(**logs)
+            accelerator.log(logs, step=global_step)
+        progress_bar.close()
+
+        accelerator.wait_for_everyone()
+
+        # Generate sample images for visual inspection
+        if accelerator.is_main_process:
+            if epoch % args.save_images_epochs == 0 or epoch == args.num_epochs - 1:
+                pipeline = DDPMPipeline(
+                    unet=accelerator.unwrap_model(ema_model.averaged_model if args.use_ema else model),
+                    scheduler=noise_scheduler,
+                )
+
+                generator = torch.manual_seed(0)
+                # run pipeline in inference (sample random noise and denoise)
+                images = pipeline(generator=generator, batch_size=args.eval_batch_size, output_type="numpy")["sample"]
+
+                # denormalize the images and save to tensorboard
+                images_processed = (images * 255).round().astype("uint8")
+                accelerator.trackers[0].writer.add_images(
+                    "test_samples", images_processed.transpose(0, 3, 1, 2), epoch
+                )
+
+            if epoch % args.save_model_epochs == 0 or epoch == args.num_epochs - 1:
+                # save the model
+                if args.push_to_hub:
+                    push_to_hub(args, pipeline, repo, commit_message=f"Epoch {epoch}", blocking=False)
+                else:
+                    pipeline.save_pretrained(args.output_dir)
+        accelerator.wait_for_everyone()
+
+    accelerator.end_training()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Simple example of a training script.")
+    parser.add_argument("--local_rank", type=int, default=-1)
+    parser.add_argument("--dataset_name", type=str, default=None)
+    parser.add_argument("--dataset_config_name", type=str, default=None)
+    parser.add_argument("--train_data_dir", type=str, default=None, help="A folder containing the training data.")
+    parser.add_argument("--output_dir", type=str, default="ddpm-model-64")
+    parser.add_argument("--overwrite_output_dir", action="store_true")
+    parser.add_argument("--cache_dir", type=str, default=None)
+    parser.add_argument("--resolution", type=int, default=64)
+    parser.add_argument("--train_batch_size", type=int, default=16)
+    parser.add_argument("--eval_batch_size", type=int, default=16)
+    parser.add_argument("--num_epochs", type=int, default=100)
+    parser.add_argument("--save_images_epochs", type=int, default=10)
+    parser.add_argument("--save_model_epochs", type=int, default=10)
+    parser.add_argument("--gradient_accumulation_steps", type=int, default=1)
+    parser.add_argument("--learning_rate", type=float, default=1e-4)
+    parser.add_argument("--lr_scheduler", type=str, default="cosine")
+    parser.add_argument("--lr_warmup_steps", type=int, default=500)
+    parser.add_argument("--adam_beta1", type=float, default=0.95)
+    parser.add_argument("--adam_beta2", type=float, default=0.999)
+    parser.add_argument("--adam_weight_decay", type=float, default=1e-6)
+    parser.add_argument("--adam_epsilon", type=float, default=1e-08)
+    parser.add_argument("--use_ema", action="store_true", default=True)
+    parser.add_argument("--ema_inv_gamma", type=float, default=1.0)
+    parser.add_argument("--ema_power", type=float, default=3 / 4)
+    parser.add_argument("--ema_max_decay", type=float, default=0.9999)
+    parser.add_argument("--push_to_hub", action="store_true")
+    parser.add_argument("--use_auth_token", action="store_true")
+    parser.add_argument("--hub_token", type=str, default=None)
+    parser.add_argument("--hub_model_id", type=str, default=None)
+    parser.add_argument("--hub_private_repo", action="store_true")
+    parser.add_argument("--logging_dir", type=str, default="logs")
+    parser.add_argument(
+        "--mixed_precision",
+        type=str,
+        default="no",
+        choices=["no", "fp16", "bf16"],
+        help=(
+            "Whether to use mixed precision. Choose"
+            "between fp16 and bf16 (bfloat16). Bf16 requires PyTorch >= 1.10."
+            "and an Nvidia Ampere GPU."
+        ),
+    )
+
+    args = parser.parse_args()
+    env_local_rank = int(os.environ.get("LOCAL_RANK", -1))
+    if env_local_rank != -1 and env_local_rank != args.local_rank:
+        args.local_rank = env_local_rank
+
+    if args.dataset_name is None and args.train_data_dir is None:
+        raise ValueError("You must specify either a dataset name from the hub or a train data directory.")
+
+    main(args)