e0118ade2f
* [LoRA] add LoRA training for Qwen Image 2.1 Add DreamBooth LoRA training for Qwen-Image 2.1, text-to-image and image-to-image, with fast tests and a README section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * default rank and alpha to 16 and document the ratio `--rank` and `--lora_alpha` are independent arguments, so raising the rank alone leaves the update scaled by `lora_alpha / rank`. Default both to 16, which keeps the scale at 1, and add a README section explaining the ratio. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * fix validation when embeddings are precomputed or only the final pass runs Two fixes from review: `QwenImage21ValidationPipeline` substituted the cached image-pad mask after calling the base `encode_prompt`, but that call raises for a missing mask when it is handed `prompt_embeds` together with a condition image, so the substitution never ran and image-to-image validation failed. Pass the mask in before the call instead. `--final_validation_prompt` was accepted by the final-inference guard, but the prompt embeddings were only built under `--validation_prompt`, so the final pass reached a pipeline whose text encoder is `None` with no prompt at all. Build the embeddings for whichever prompt is set. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * fix encoding under --offload without --cache_latents `vae.encode` sat outside the `offload_models` block, so the context manager had already moved the VAE back to the CPU by the time it ran, while the prepared dataloader hands the batch over on the accelerator: RuntimeError: Input type (torch.cuda.FloatTensor) and weight type (torch.FloatTensor) should be the same Move the call inside the block and cover that flag combination, which is the only path that encodes pixels inside the training loop. The image-to-image trainer already had it right. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * add LoRA tests for the Qwen-Image 2.1 pipeline Follow the Flux layout and reuse `LoraTesterMixin` and `LoraMemoryTesterMixin`, so the adapters these trainers produce are covered by the pipeline's own loading, fusing and memory-offload tests. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * fix caching a prompt mask that `encode_prompt` returns as None `encode_prompt` drops the prompt mask when nothing in the batch is padded, which is the common case for `--caption_column` datasets since captions in a bucket often tokenize to the same length. The cache is filled per sample, so slicing that `None` raised during latent caching: prompt_embeds_mask_cache[idx] = prompt_embeds_mask[i : i + 1] TypeError: 'NoneType' object is not subscriptable Materialize the mask before filling the cache, and cover the path with a test: none of the existing ones passed `--caption_column`, which is why this only showed up on a real dataset. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * pass rank and alpha explicitly in the README dog example The dog example was written for the old 4/4 defaults; now that both default to 16, spell out 4/4 so the documented command keeps training the size it was tuned for. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * drop copy-paste leftovers from other trainers `--output_dir` defaulted to `hidream-dreambooth-lora`, the weight-decay help mentioned UNet params, and the VAE cast comment talked about the Flux VAE. All three were inherited verbatim from the trainer this was derived from. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * lower the README dog example to lr 1e-4 At 2e-4 the example memorizes the five training images: prompted scenes collapse to the training backdrop rather than following the prompt. 1e-4 is what the image-to-image example already uses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011qnMKe5MVc7B4XXHGPvXuZ * skip the LoRA scale test for the Qwen-Image 2.1 dummy Halving the LoRA scale moves this dummy transformer's output by less than the tolerance the assertion allows, so the two outputs compare equal and the test fails on CPU. Skip it with the measurement recorded rather than loosening a tolerance shared with every other pipeline's LoRA tests. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
🧨 Diffusers Examples
Diffusers examples are a collection of scripts to demonstrate how to effectively use the diffusers library
for a variety of use cases involving training or fine-tuning.
Note: If you are looking for official examples on how to use diffusers for inference, please have a look at src/diffusers/pipelines.
Our examples aspire to be self-contained, easy-to-tweak, beginner-friendly and for one-purpose-only. More specifically, this means:
- Self-contained: An example script shall only depend on "pip-install-able" Python packages that can be found in a
requirements.txtfile. Example scripts shall not depend on any local files. This means that one can simply download an example script, e.g. train_unconditional.py, install the required dependencies, e.g. requirements.txt and execute the example script. - Easy-to-tweak: While we strive to present as many use cases as possible, the example scripts are just that - examples. It is expected that they won't work out-of-the box on your specific problem and that you will be required to change a few lines of code to adapt them to your needs. To help you with that, most of the examples fully expose the preprocessing of the data and the training loop to allow you to tweak and edit them as required.
- Beginner-friendly: We do not aim for providing state-of-the-art training scripts for the newest models, but rather examples that can be used as a way to better understand diffusion models and how to use them with the
diffuserslibrary. We often purposefully leave out certain state-of-the-art methods if we consider them too complex for beginners. - One-purpose-only: Examples should show one task and one task only. Even if a task is from a modeling point of view very similar, e.g. image super-resolution and image modification tend to use the same model and training method, we want examples to showcase only one task to keep them as readable and easy-to-understand as possible.
We provide official examples that cover the most popular tasks of diffusion models.
Official examples are actively maintained by the diffusers maintainers and we try to rigorously follow our example philosophy as defined above.
If you feel like another important example should exist, we are more than happy to welcome a Feature Request or directly a Pull Request from you!
Training examples show how to pretrain or fine-tune diffusion models for a variety of tasks. Currently we support:
| Task | 🤗 Accelerate | 🤗 Datasets | Colab |
|---|---|---|---|
| Unconditional Image Generation | ✅ | ✅ |  |
| Text-to-Image fine-tuning | ✅ | ✅ | |
| Textual Inversion | ✅ | - | |
| Dreambooth | ✅ | - | |
| ControlNet | ✅ | ✅ | Notebook |
| InstructPix2Pix | ✅ | ✅ | Notebook |
| Reinforcement Learning for Control | - | - | Notebook1, Notebook2 |
Community
In addition, we provide community examples, which are examples added and maintained by our community.
Community examples can consist of both training examples or inference pipelines.
For such examples, we are more lenient regarding the philosophy defined above and also cannot guarantee to provide maintenance for every issue.
Examples that are useful for the community, but are either not yet deemed popular or not yet following our above philosophy should go into the community examples folder. The community folder therefore includes training examples and inference pipelines.
Note: Community examples can be a great first contribution to show to the community how you like to use diffusers 🪄.
Research Projects
We also provide research_projects examples that are maintained by the community as defined in the respective research project folders. These examples are useful and offer the extended capabilities which are complementary to the official examples. You may refer to research_projects for details.
Important note
To make sure you can successfully run the latest versions of the example scripts, you have to install the library from source and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:
git clone https://github.com/huggingface/diffusers
cd diffusers
pip install .
Then cd in the example folder of your choice and run
pip install -r requirements.txt