# T2I-Adapter

[T2I-Adapter](https://hf.co/papers/2302.08453) é um modelo de adaptador leve que fornece uma imagem de entrada adicional para condicionamento (line art, canny, sketch, depth, pose) para controlar melhor a geração de imagens. Ele é semelhante a um ControlNet, mas é muito menor (~77M parâmetros e ~300MB de tamanho de arquivo) porque ele apenas insere pesos no UNet em vez de copiá-lo e treiná-lo.

O T2I-Adapter está disponível apenas para treinamento com o modelo Stable Diffusion XL (SDXL).

Este guia explorará o script de treinamento [train_t2i_adapter_sdxl.py](https://github.com/huggingface/diffusers/blob/main/examples/t2i_adapter/train_t2i_adapter_sdxl.py) para ajudá-lo a se familiarizar com ele e com a forma de adaptá-lo ao seu próprio caso de uso.

Antes de executar o script, certifique-se de instalar a biblioteca a partir do código-fonte:

```bash
git clone https://github.com/huggingface/diffusers
cd diffusers
pip install .
```

Em seguida, navegue até a pasta de exemplo que contém o script de treinamento e instale as dependências necessárias para o script que você está usando:

```bash
cd examples/t2i_adapter
pip install -r requirements.txt
```

> [!TIP]
> 🤗 Accelerate é uma biblioteca para ajudar você a treinar em múltiplos GPUs/TPUs ou com precisão mista. Ela configura automaticamente seu ambiente de treinamento com base no seu hardware e ambiente. Dê uma olhada no [Quick tour](https://huggingface.co/docs/accelerate/quicktour) do 🤗 Accelerate para saber mais.

Inicialize um ambiente do 🤗 Accelerate:

```bash
accelerate config
```

Para configurar um ambiente padrão do 🤗 Accelerate sem escolher nenhuma configuração:

```bash
accelerate config default
```

Ou, se o seu ambiente não suporta um shell interativo, como um notebook, você pode usar:

```py
from accelerate.utils import write_basic_config

write_basic_config()
```

Por fim, se você deseja treinar um modelo em seu próprio conjunto de dados, consulte o guia [Criar um conjunto de dados para treinamento](create_dataset) para aprender a criar um conjunto de dados que funcione com o script de treinamento.

> [!TIP]
> As seções a seguir destacam partes do script de treinamento que são importantes para entender como modificá-lo, mas não cobrem todos os aspectos do script em detalhes. Se você tiver interesse em aprender mais, sinta-se à vontade para ler o [script](https://github.com/huggingface/diffusers/blob/main/examples/t2i_adapter/train_t2i_adapter_sdxl.py) e nos informar caso tenha alguma dúvida ou preocupação.

## Parâmetros do script

O script de treinamento fornece muitos parâmetros para ajudar você a personalizar sua execução de treinamento. Todos os parâmetros e suas descrições estão encontrados na função [`parse_args()`](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L233). Ele fornece valores padrão para cada parâmetro, como o tamanho do lote de treinamento e a taxa de aprendizado, mas você também pode definir seus próprios valores no comando de treinamento, se desejar.

Por exemplo, para ativar o acúmulo de gradientes, adicione o parâmetro `--gradient_accumulation_steps` ao comando de treinamento:

```bash
accelerate launch train_t2i_adapter_sdxl.py \
  ----gradient_accumulation_steps=4
```

Muitos dos parâmetros básicos e importantes são descritos no guia de treinamento de [Texto para imagem](text2image#script-parameters), portanto, este guia se concentra apenas nos parâmetros relevantes do T2I-Adapter:

- `--pretrained_vae_model_name_or_path`: caminho para um VAE pré-treinado; o VAE do SDXL é conhecido por sofrer de instabilidade numérica, portanto, este parâmetro permite especificar um [VAE](https://huggingface.co/madebyollin/sdxl-vae-fp16-fix) melhor
- `--crops_coords_top_left_h` e `--crops_coords_top_left_w`: coordenadas de altura e largura para incluir nos embeddings de coordenadas de recorte do SDXL
- `--conditioning_image_column`: a coluna das imagens de condicionamento no conjunto de dados
- `--proportion_empty_prompts`: a proporção de prompts de imagem a serem substituídos por strings vazias

## Script de treinamento

Assim como com os parâmetros do script, um passo a passo do script de treinamento é fornecido no guia de treinamento [Text-to-image](text2image#training-script). Em vez disso, este guia examina as partes do script relevantes para o T2I-Adapter.

O script de treinamento começa preparando o conjunto de dados. Isso inclui [tokenizar](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L674) o prompt e [aplicar transformações](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L714) às imagens e às imagens de condicionamento.

```py
conditioning_image_transforms = transforms.Compose(
    [
        transforms.Resize(args.resolution, interpolation=transforms.InterpolationMode.BILINEAR),
        transforms.CenterCrop(args.resolution),
        transforms.ToTensor(),
    ]
)
```

Dentro da função [`main()`](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L770), o T2I-Adapter é carregado de um adaptador pré-treinado ou inicializado aleatoriamente:

```py
if args.adapter_model_name_or_path:
    logger.info("Loading existing adapter weights.")
    t2iadapter = T2IAdapter.from_pretrained(args.adapter_model_name_or_path)
else:
    logger.info("Initializing t2iadapter weights.")
    t2iadapter = T2IAdapter(
        in_channels=3,
        channels=(320, 640, 1280, 1280),
        num_res_blocks=2,
        downscale_factor=16,
        adapter_type="full_adapter_xl",
    )
```

O [optimizer](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L952) é inicializado para os parâmetros do T2I-Adapter:

```py
params_to_optimize = t2iadapter.parameters()
optimizer = optimizer_class(
    params_to_optimize,
    lr=args.learning_rate,
    betas=(args.adam_beta1, args.adam_beta2),
    weight_decay=args.adam_weight_decay,
    eps=args.adam_epsilon,
)
```

Por fim, no [loop de treinamento](https://github.com/huggingface/diffusers/blob/aab6de22c33cc01fb7bc81c0807d6109e2c998c9/examples/t2i_adapter/train_t2i_adapter_sdxl.py#L1086), a imagem de condicionamento do adaptador e os embeddings de texto são passados para a UNet para prever o resíduo de ruído:

```py
t2iadapter_image = batch["conditioning_pixel_values"].to(dtype=weight_dtype)
down_block_additional_residuals = t2iadapter(t2iadapter_image)
down_block_additional_residuals = [
    sample.to(dtype=weight_dtype) for sample in down_block_additional_residuals
]

model_pred = unet(
    inp_noisy_latents,
    timesteps,
    encoder_hidden_states=batch["prompt_ids"],
    added_cond_kwargs=batch["unet_added_conditions"],
    down_block_additional_residuals=down_block_additional_residuals,
).sample
```

Se você quiser saber mais sobre como funciona o loop de treinamento, confira o tutorial [Entendendo pipelines, modelos e agendadores](../using-diffusers/write_own_pipeline), que detalha o padrão básico do processo de remoção de ruído.

## Inicie o script

Agora você está pronto para iniciar o script de treinamento! 🚀

Para este exemplo de treinamento, você usará o conjunto de dados [fusing/fill50k](https://huggingface.co/datasets/fusing/fill50k). Você também pode criar e usar seu próprio conjunto de dados, se desejar (veja o guia [Criar um conjunto de dados para treinamento](create_dataset)).

Defina a variável de ambiente `MODEL_DIR` para um id de modelo no Hub ou um caminho para um modelo local e `OUTPUT_DIR` para onde você deseja salvar o modelo.

Baixe as seguintes imagens para condicionar seu treinamento com:

```bash
wget https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/controlnet_training/conditioning_image_1.png
wget https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/controlnet_training/conditioning_image_2.png
```

> [!TIP]
> Para monitorar o progresso do treinamento com Weights & Biases, adicione o parâmetro `--report_to=wandb` ao comando de treinamento. Você também precisará adicionar `--validation_image`, `--validation_prompt` e `--validation_steps` ao comando de treinamento para acompanhar os resultados. Isso pode ser muito útil para depurar o modelo e visualizar resultados intermediários.

```bash
export MODEL_DIR="stabilityai/stable-diffusion-xl-base-1.0"
export OUTPUT_DIR="path to save model"

accelerate launch train_t2i_adapter_sdxl.py \
 --pretrained_model_name_or_path=$MODEL_DIR \
 --output_dir=$OUTPUT_DIR \
 --dataset_name=fusing/fill50k \
 --mixed_precision="fp16" \
 --resolution=1024 \
 --learning_rate=1e-5 \
 --max_train_steps=15000 \
 --validation_image "./conditioning_image_1.png" "./conditioning_image_2.png" \
 --validation_prompt "red circle with blue background" "cyan circle with brown floral background" \
 --validation_steps=100 \
 --train_batch_size=1 \
 --gradient_accumulation_steps=4 \
 --report_to="wandb" \
 --seed=42 \
 --push_to_hub
```

Quando o treinamento estiver concluído, você pode usar seu T2I-Adapter para inferência:

```py
from diffusers import StableDiffusionXLAdapterPipeline, T2IAdapter, EulerAncestralDiscreteSchedulerTest
from diffusers.utils import load_image
import torch

adapter = T2IAdapter.from_pretrained("path/to/adapter", dtype=torch.float16)
pipeline = StableDiffusionXLAdapterPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", adapter=adapter, dtype=torch.float16
)

pipeline.scheduler = EulerAncestralDiscreteSchedulerTest.from_config(pipe.scheduler.config)
pipeline.enable_xformers_memory_efficient_attention()
pipeline.enable_model_cpu_offload()

control_image = load_image("./conditioning_image_1.png")
prompt = "pale golden rod circle with old lace background"

generator = torch.manual_seed(0)
image = pipeline(
    prompt, image=control_image, generator=generator
).images[0]
image.save("./output.png")
```

## Próximas etapas

Parabéns por treinar um modelo T2I-Adapter! 🎉 Para saber mais:

- Leia o post no blog [Efficient Controllable Generation for SDXL with T2I-Adapters](https://huggingface.co/blog/t2i-sdxl-adapters) para saber mais detalhes sobre os resultados experimentais da equipe T2I-Adapter.