---
license: openrail++
language:
- en
library_name: diffusers
tags:
- art
---
# amused
Images cherry-picked from 512 and 256 models. Images are degraded to load faster. See ./assets/collage_full.png for originals
📃 Paper: [aMUSEd: An Open MUSE Reproduction](https://huggingface.co/papers/2401.01808)
| Model | Params |
|-------|--------|
| [amused-256](https://huggingface.co/amused/amused-256) | 803M |
| [amused-512](https://huggingface.co/amused/amused-512) | 808M |
Amused is a lightweight text to image model based off of the [muse](https://arxiv.org/pdf/2301.00704.pdf) architecture. Amused is particularly useful in applications that require a lightweight and fast model such as generating many images quickly at once.
*The diagram shows the training and inference pipelines for aMUSEd. aMUSEd consists
of three separately trained components: a pre-trained CLIP-L/14 text encoder, a VQ-GAN, and a
U-ViT. During training, the VQ-GAN encoder maps images to a 16x smaller latent resolution. The
proportion of masked latent tokens is sampled from a cosine masking schedule, e.g. cos(r · π
2 )
with r ∼ Uniform(0, 1). The model is trained via cross-entropy loss to predict the masked tokens.
After the model is trained on 256x256 images, downsampling and upsampling layers are added, and
training is continued on 512x512 images. During inference, the U-ViT is conditioned on the text
encoder’s hidden states and iteratively predicts values for all masked tokens. The cosine masking
schedule determines a percentage of the most confident token predictions to be fixed after every
iteration. After 12 iterations, all tokens have been predicted and are decoded by the VQ-GAN into
image pixels.*
## 1. Usage
### Text to image
#### 256x256 model
```python
import torch
from diffusers import AmusedPipeline
pipe = AmusedPipeline.from_pretrained(
"amused/amused-256", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "cowboy"
image = pipe(prompt, generator=torch.Generator('cuda').manual_seed(8)).images[0]
image.save('text2image_256.png')
```
#### 512x512 model
```python
import torch
from diffusers import AmusedPipeline
pipe = AmusedPipeline.from_pretrained(
"amused/amused-512", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "summer in the mountains"
image = pipe(prompt, generator=torch.Generator('cuda').manual_seed(2)).images[0]
image.save('text2image_512.png')
```
### Image to image
#### 256x256 model
```python
import torch
from diffusers import AmusedImg2ImgPipeline
from diffusers.utils import load_image
pipe = AmusedImg2ImgPipeline.from_pretrained(
"amused/amused-256", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "apple watercolor"
input_image = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/image2image_256_orig.png"
)
.resize((256, 256))
.convert("RGB")
)
image = pipe(prompt, input_image, strength=0.7, generator=torch.Generator('cuda').manual_seed(3)).images[0]
image.save('image2image_256.png')
```
 
#### 512x512 model
```python
import torch
from diffusers import AmusedImg2ImgPipeline
from diffusers.utils import load_image
pipe = AmusedImg2ImgPipeline.from_pretrained(
"amused/amused-512", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "winter mountains"
input_image = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/image2image_512_orig.png"
)
.resize((512, 512))
.convert("RGB")
)
image = pipe(prompt, input_image, generator=torch.Generator('cuda').manual_seed(15)).images[0]
image.save('image2image_512.png')
```
 
### Inpainting
#### 256x256 model
```python
import torch
from diffusers import AmusedInpaintPipeline
from diffusers.utils import load_image
from PIL import Image
pipe = AmusedInpaintPipeline.from_pretrained(
"amused/amused-256", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "a man with glasses"
input_image = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/inpainting_256_orig.png"
)
.resize((256, 256))
.convert("RGB")
)
mask = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/inpainting_256_mask.png"
)
.resize((256, 256))
.convert("L")
)
for seed in range(20):
image = pipe(prompt, input_image, mask, generator=torch.Generator('cuda').manual_seed(seed)).images[0]
image.save(f'inpainting_256_{seed}.png')
```
  
#### 512x512 model
```python
import torch
from diffusers import AmusedInpaintPipeline
from diffusers.utils import load_image
pipe = AmusedInpaintPipeline.from_pretrained(
"amused/amused-512", variant="fp16", torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
prompt = "fall mountains"
input_image = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/inpainting_512_orig.jpeg"
)
.resize((512, 512))
.convert("RGB")
)
mask = (
load_image(
"https://raw.githubusercontent.com/huggingface/amused/main/assets/inpainting_512_mask.png"
)
.resize((512, 512))
.convert("L")
)
image = pipe(prompt, input_image, mask, generator=torch.Generator('cuda').manual_seed(0)).images[0]
image.save('inpainting_512.png')
```
## 2. Performance
Amused inherits performance benefits from original [muse](https://arxiv.org/pdf/2301.00704.pdf).
1. Parallel decoding: The model follows a denoising schedule that aims to unmask some percent of tokens at each denoising step. At each step, all masked tokens are predicted, and some number of tokens that the network is most confident about are unmasked. Because multiple tokens are predicted at once, we can generate a full 256x256 or 512x512 image in around 12 steps. In comparison, an autoregressive model must predict a single token at a time. Note that a 256x256 image with the 16x downsampled VAE that muse uses will have 256 tokens.
2. Fewer sampling steps: Compared to many diffusion models, muse requires fewer samples.
Additionally, amused uses the smaller CLIP as its text encoder instead of T5 compared to muse. Amused is also smaller with ~600M params compared the largest 3B param muse model. Note that being smaller, amused produces comparably lower quality results.
### Muse performance knobs
| | Uncompiled Transformer + regular attention | Uncompiled Transformer + flash attention (ms) | Compiled Transformer (ms) | Speed Up |
|---------------------|--------------------------------------------|-------------------------|----------------------|----------|
| 256 Batch Size 1 | 594.7 | 507.7 | 212.1 | 58% |
| 512 Batch Size 1 | 637 | 547 | 249.9 | 54% |
| 256 Batch Size 8 | 719 | 628.6 | 427.8 | 32% |
| 512 Batch Size 8 | 1000 | 917.7 | 703.6 | 23% |
Flash attention is enabled by default in the diffusers codebase through torch `F.scaled_dot_product_attention`
### torch.compile
To use torch.compile, simply wrap the transformer in torch.compile i.e.
```python
pipe.transformer = torch.compile(pipe.transformer)
```
Full snippet:
```python
import torch
from diffusers import AmusedPipeline
pipe = AmusedPipeline.from_pretrained(
"amused/amused-256", variant="fp16", torch_dtype=torch.float16
)
# HERE use torch.compile
pipe.transformer = torch.compile(pipe.transformer)
pipe = pipe.to("cuda")
prompt = "cowboy"
image = pipe(prompt, generator=torch.Generator('cuda').manual_seed(8)).images[0]
image.save('text2image_256.png')
```
## 3. Training
Amused can be finetuned on simple datasets relatively cheaply and quickly. Using 8bit optimizers, lora, and gradient accumulation, amused can be finetuned with as little as 5.5 GB. Here are a set of examples for finetuning amused on some relatively simple datasets. These training recipies are aggressively oriented towards minimal resources and fast verification -- i.e. the batch sizes are quite low and the learning rates are quite high. For optimal quality, you will probably want to increase the batch sizes and decrease learning rates.
All training examples use fp16 mixed precision and gradient checkpointing. We don't show 8 bit adam + lora as its about the same memory use as just using lora (bitsandbytes uses full precision optimizer states for weights below a minimum size).
### Finetuning the 256 checkpoint
These examples finetune on this [nouns](https://huggingface.co/datasets/m1guelpf/nouns) dataset.
Example results:
  
#### Full finetuning
Batch size: 8, Learning rate: 1e-4, Gives decent results in 750-1000 steps
| Batch Size | Gradient Accumulation Steps | Effective Total Batch Size | Memory Used |
|------------|-----------------------------|------------------|-------------|
| 8 | 1 | 8 | 19.7 GB |
| 4 | 2 | 8 | 18.3 GB |
| 1 | 8 | 8 | 17.9 GB |
```sh
accelerate launch training/training.py \
--output_dir