🤗 Diffusers provides pretrained diffusion models across multiple modalities, such as vision and audio, and serves
as a modular toolbox for inference and training of diffusion models.
More precisely, 🤗 Diffusers offers:
State-of-the-art diffusion pipelines that can be run in inference with just a couple of lines of code (see src/diffusers/pipelines). Check this overview to see all supported pipelines and their corresponding official papers.
Various noise schedulers that can be used interchangeably for the preferred speed vs. quality trade-off in inference (see src/diffusers/schedulers).
Multiple types of models, such as UNet, can be used as building blocks in an end-to-end diffusion system (see src/diffusers/models).
We ❤️ contributions from the open-source community!
If you want to contribute to this library, please check out our Contribution guide.
You can look out for issues you'd like to tackle to contribute to the library.
notebook, which showcases an end-to-end example of usage for diffusion models, schedulers and pipelines.
Take a look at this notebook to learn how to use the pipeline abstraction, which takes care of everything (model, scheduler, noise handling) for you, and also to understand each independent building block in the library.
notebook summarizes diffusion models training methods. This notebook takes a step-by-step approach to training your
diffusion models on an image dataset, with explanatory graphics.
Stable Diffusion is fully compatible with diffusers!
Stable Diffusion is a text-to-image latent diffusion model created by the researchers and engineers from CompVis, Stability AI, LAION and RunwayML. It's trained on 512x512 images from a subset of the LAION-5B database. This model uses a frozen CLIP ViT-L/14 text encoder to condition the model on text prompts. With its 860M UNet and 123M text encoder, the model is relatively lightweight and runs on a GPU with at least 4GB VRAM.
See the model card for more information.
You need to accept the model license before downloading or using the Stable Diffusion weights. Please, visit the model card, read the license carefully and tick the checkbox if you agree. You have to be a registered user in 🤗 Hugging Face Hub, and you'll also need to use an access token for the code to work. For more information on access tokens, please refer to this section of the documentation.
Run this command to log in with your HF Hub token if you haven't before (you can skip this step if you prefer to run the model locally, follow this instead)
huggingface-cli login
We recommend using the model in half-precision (fp16) as it gives almost always the same results as full
precision while being roughly twice as fast and requiring half the amount of GPU RAM.
python
1import torch
2from diffusers import StableDiffusionPipeline
34pipe = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5", torch_dtype=torch.float16, revision="fp16")5pipe = pipe.to("cuda")67prompt ="a photo of an astronaut riding a horse on mars"8image = pipe(prompt).images[0]
Running the model locally
If you don't want to login to Hugging Face, you can also simply download the model folder
(after having accepted the license) and pass
the path to the local folder to the StableDiffusionPipeline.
Assuming the folder is stored locally under ./stable-diffusion-v1-5, you can also run stable diffusion
without requiring an authentication token:
python
1pipe = StableDiffusionPipeline.from_pretrained("./stable-diffusion-v1-5")2pipe = pipe.to("cuda")34prompt ="a photo of an astronaut riding a horse on mars"5image = pipe(prompt).images[0]
If you are limited by GPU memory, you might want to consider chunking the attention computation in addition
to using fp16.
The following snippet should result in less than 4GB VRAM.
python
1pipe = StableDiffusionPipeline.from_pretrained(2"runwayml/stable-diffusion-v1-5",3 revision="fp16",4 torch_dtype=torch.float16,5)6pipe = pipe.to("cuda")78prompt ="a photo of an astronaut riding a horse on mars"9pipe.enable_attention_slicing()10image = pipe(prompt).images[0]
If you wish to use a different scheduler (e.g.: DDIM, LMS, PNDM/PLMS), you can instantiate
it before the pipeline and pass it to from_pretrained.
python
1from diffusers import LMSDiscreteScheduler
23pipe.scheduler = LMSDiscreteScheduler.from_config(pipe.scheduler.config)45prompt ="a photo of an astronaut riding a horse on mars"6image = pipe(prompt).images[0]78image.save("astronaut_rides_horse.png")
If you want to run Stable Diffusion on CPU or you want to have maximum precision on GPU,
please run the model in the default full-precision setting:
python
1# make sure you're logged in with `huggingface-cli login`2from diffusers import StableDiffusionPipeline
34pipe = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")56# disable the following line if you run on CPU7pipe = pipe.to("cuda")89prompt ="a photo of an astronaut riding a horse on mars"10image = pipe(prompt).images[0]1112image.save("astronaut_rides_horse.png")
JAX/Flax
Diffusers offers a JAX / Flax implementation of Stable Diffusion for very fast inference. JAX shines specially on TPU hardware because each TPU server has 8 accelerators working in parallel, but it runs great on GPUs too.
Running the pipeline with the default PNDMScheduler:
Note:
If you are limited by TPU memory, please make sure to load the FlaxStableDiffusionPipeline in bfloat16 precision instead of the default float32 precision as done above. You can do so by telling diffusers to load the weights from "bf16" branch.
The StableDiffusionInpaintPipeline lets you edit specific parts of an image by providing a mask and a text prompt. It uses a model optimized for this particular task, whose license you need to accept before use.
Please, visit the model card, read the license carefully and tick the checkbox if you agree. Note that this is an additional license, you need to accept it even if you accepted the text-to-image Stable Diffusion license in the past. You have to be a registered user in 🤗 Hugging Face Hub, and you'll also need to use an access token for the code to work. For more information on access tokens, please refer to this section of the documentation.
python
1import PIL
2import requests
3import torch
4from io import BytesIO
56from diffusers import StableDiffusionInpaintPipeline
78defdownload_image(url):9 response = requests.get(url)10return PIL.Image.open(BytesIO(response.content)).convert("RGB")1112img_url ="https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo.png"13mask_url ="https://raw.githubusercontent.com/CompVis/latent-diffusion/main/data/inpainting_examples/overture-creations-5sI6fQgYIuo_mask.png"1415init_image = download_image(img_url).resize((512,512))16mask_image = download_image(mask_url).resize((512,512))1718pipe = StableDiffusionInpaintPipeline.from_pretrained(19"runwayml/stable-diffusion-inpainting",20 revision="fp16",21 torch_dtype=torch.float16,22)23pipe = pipe.to("cuda")2425prompt ="Face of a yellow cat, high resolution, sitting on a park bench"26image = pipe(prompt=prompt, image=init_image, mask_image=mask_image).images[0]
Tweak prompts reusing seeds and latents
You can generate your own latents to reproduce results, or tweak your prompt on a specific result you liked. This notebook shows how to do it step by step. You can also run it in Google Colab
Fine-tuning techniques make it possible to adapt Stable Diffusion to your own dataset, or add new subjects to it. These are some of the techniques supported in diffusers:
Textual Inversion is a technique for capturing novel concepts from a small number of example images in a way that can later be used to control text-to-image pipelines. It does so by learning new 'words' in the embedding space of the pipeline's text encoder. These special words can then be used within text prompts to achieve very fine-grained control of the resulting images.
Textual Inversion. Capture novel concepts from a small set of sample images, and associate them with new "words" in the embedding space of the text encoder. Please, refer to our training examples or documentation to try for yourself.
Dreambooth. Another technique to capture new concepts in Stable Diffusion. This method fine-tunes the UNet (and, optionally, also the text encoder) of the pipeline to achieve impressive results. Please, refer to our training example and training report for additional details and training recommendations.
The release of Stable Diffusion as an open source model has fostered a lot of interesting ideas and experimentation.
Our Community Examples folder contains many ideas worth exploring, like interpolating to create animated videos, using CLIP Guidance for additional prompt fidelity, term weighting, and much more! Take a look and contribute your own.
Other Examples
There are many ways to try running Diffusers! Here we outline code-focused tools (primarily using DiffusionPipelines and Google Colab) and interactive web-tools.
Running Code
If you want to run the code yourself 💻, you can try out:
1# !pip install diffusers["torch"] transformers2from diffusers import DiffusionPipeline
34device ="cuda"5model_id ="CompVis/ldm-text2im-large-256"67# load model and scheduler8ldm = DiffusionPipeline.from_pretrained(model_id)9ldm = ldm.to(device)1011# run pipeline in inference (sample random noise and denoise)12prompt ="A painting of a squirrel eating a burger"13image = ldm([prompt], num_inference_steps=50, eta=0.3, guidance_scale=6).images[0]1415# save image16image.save("squirrel.png")
1# !pip install diffusers["torch"]2from diffusers import DDPMPipeline, DDIMPipeline, PNDMPipeline
34model_id ="google/ddpm-celebahq-256"5device ="cuda"67# load model and scheduler8ddpm = DDPMPipeline.from_pretrained(model_id)# you can replace DDPMPipeline with DDIMPipeline or PNDMPipeline for faster inference9ddpm.to(device)1011# run pipeline in inference (sample random noise and denoise)12image = ddpm().images[0]1314# save image15image.save("ddpm_generated_image.png")
Models: Neural network that models $p_\theta(\mathbf{x}_{t-1}|\mathbf{x}_t)$ (see image below) and is trained end-to-end to denoise a noisy input to an image.
Examples: UNet, Conditioned UNet, 3D UNet, Transformer UNet
Figure from DDPM paper (https://arxiv.org/abs/2006.11239).
Schedulers: Algorithm class for both inference and training.
The class provides functionality to compute previous image according to alpha, beta schedule as well as predict noise for training. Also known as Samplers.
Examples: DDPM, DDIM, PNDM, DEIS
Sampling and training algorithms. Figure from DDPM paper (https://arxiv.org/abs/2006.11239).
Diffusion Pipeline: End-to-end pipeline that includes multiple diffusion models, possible text encoders, ...
Examples: Glide, Latent-Diffusion, Imagen, DALL-E 2
Figure from ImageGen (https://imagen.research.google/).
Philosophy
Readability and clarity is preferred over highly optimized code. A strong importance is put on providing readable, intuitive and elementary code design. E.g., the provided schedulers are separated from the provided models and provide well-commented code that can be read alongside the original paper.
Diffusers is modality independent and focuses on providing pretrained models and tools to build systems that generate continuous outputs, e.g. vision and audio.
Diffusion models and schedulers are provided as concise, elementary building blocks. In contrast, diffusion pipelines are a collection of end-to-end diffusion systems that can be used out-of-the-box, should stay as close as possible to their original implementation and can include components of another library, such as text-encoders. Examples for diffusion pipelines are Glide and Latent Diffusion.
In the works
For the first release, 🤗 Diffusers focuses on text-to-image diffusion techniques. However, diffusers can be used for much more than that! Over the upcoming releases, we'll be focusing on:
A few pipeline components are already being worked on, namely:
BDDMPipeline for spectrogram-to-sound vocoding
GLIDEPipeline to support OpenAI's GLIDE model
Grad-TTS for text to audio generation / conditional audio generation
We want diffusers to be a toolbox useful for diffusers models in general; if you find yourself limited in any way by the current API, or would like to see additional models, schedulers, or techniques, please open a GitHub issue mentioning what you would like to see.
Credits
This library concretizes previous work by many different authors and would not have been possible without their great research and implementations. We'd like to thank, in particular, the following implementations which have helped us in our development and without which the API could not have been as polished today:
@CompVis' latent diffusion models library, available here
@hojonathanho original DDPM implementation, available here as well as the extremely useful translation into PyTorch by @pesser, available here
@ermongroup's DDIM implementation, available here.
@yang-song's Score-VE and Score-VP implementations, available here
We also want to thank @heejkoo for the very helpful overview of papers, code and resources on diffusion models, available here as well as @crowsonkb and @rromb for useful discussions and insights.
Citation
bibtex
1@misc{von-platen-etal-2022-diffusers,
2 author = {Patrick von Platen and Suraj Patil and Anton Lozhkov and Pedro Cuenca and Nathan Lambert and Kashif Rasul and Mishig Davaadorj and Thomas Wolf},
3 title = {Diffusers: State-of-the-art diffusion models},
4 year = {2022},
5 publisher = {GitHub},
6 journal = {GitHub repository},
7 howpublished = {\url{https://github.com/huggingface/diffusers}}
8}
