# DiffusionPipeline

Os modelos de difusão consistem em vários componentes, como UNets ou transformadores de difusão (DiTs), codificadores de texto, autoencoders variacionais (VAEs) e agendadores. O [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline) encapsula todos esses componentes em uma única API fácil de usar, sem abrir mão da flexibilidade de modificar seus componentes.

Este guia mostrará como carregar um [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline).

## Carregando um pipeline

[DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline) é uma classe de pipeline base que seleciona e retorna automaticamente uma instância de uma subclasse de pipeline do modelo, como [QwenImagePipeline](/docs/diffusers/main/pt/api/pipelines/qwenimage#diffusers.QwenImagePipeline), ao varrer o arquivo `model_index.json` em busca do nome da classe.

Passe um id de modelo para [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para carregar um pipeline.

```py
import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

Cada modelo possui uma subclasse de pipeline específica que herda de [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Uma subclasse geralmente tem um foco restrito e é específica para uma tarefa. Veja um exemplo na tabela abaixo.

| subclasse de pipeline | tarefa |
|---|---|
| [QwenImagePipeline](/docs/diffusers/main/pt/api/pipelines/qwenimage#diffusers.QwenImagePipeline) | texto-para-imagem |
| [QwenImageImg2ImgPipeline](/docs/diffusers/main/pt/api/pipelines/qwenimage#diffusers.QwenImageImg2ImgPipeline) | imagem-para-imagem |
| [QwenImageInpaintPipeline](/docs/diffusers/main/pt/api/pipelines/qwenimage#diffusers.QwenImageInpaintPipeline) | inpaint |

Você pode usar a subclasse diretamente passando um id de modelo para [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

> [!TIP]
> Consulte a documentação de [Single file format](./other-formats#single-file-format) para aprender a carregar modelos de arquivo único.

### Pipelines locais

Os Pipelines também podem ser executados localmente. Use [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download) para baixar um repositório de modelo.

```py
from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="Qwen/Qwen-Image")
```

Passe esse caminho para [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para carregá-lo.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  local_dir, dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

O método [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) não baixa arquivos do Hub quando detecta um caminho local. Mas isso também significa que ele não baixará nem fará o cache de nenhuma atualização feita no modelo.

## Tipos de dados do Pipeline

Use o argumento `dtype` em [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para carregar um modelo com um tipo de dados específico. Isso permite carregar diferentes modelos em diferentes precisões. Por exemplo, carregar um modelo de transformer grande em meia precisão reduz a memória necessária.

Passe o tipo de dados de cada modelo como um dicionário para `dtype`. Use a chave `default` para definir o tipo de dados padrão. Se um modelo não estiver no dicionário e `default` não for fornecido, ele será carregado em precisão completa (`torch.float32`).

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype={"transformer": torch.bfloat16, "default": torch.float16},
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

Você não precisa usar um dicionário se estiver carregando todos os modelos no mesmo tipo de dados.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

## Colocação de dispositivo

O argumento `device_map` posiciona um pipeline em dispositivos. Em tempo de execução, o Diffusers aceita `"balanced"`, `"cpu"` e a string do acelerador da máquina em que você está (tipicamente `"cuda"`, `"mps"` ou `"xpu"`).

| parâmetro | descrição |
|---|---|
| string accelerator | Coloca o pipeline nesse dispositivo. Passe o acelerador que sua máquina suporta, como `"cuda"`, `"mps"` ou `"xpu"`. |
| `"balanced"` | Distribui os componentes do pipeline entre as GPUs visíveis. Use com `max_memory` quando precisar de limites por dispositivo. |
| `"cpu"` | Coloca o pipeline na CPU. |

Use o argumento `max_memory` em [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) para alocar uma quantidade máxima de memória a ser usada em cada dispositivo. Por padrão, o Diffusers usa a quantidade máxima disponível.

```py
import torch
from diffusers import DiffusionPipeline

max_memory = {0: "16GB", 1: "16GB"}
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  device_map="balanced",
  max_memory=max_memory,
)
```

O atributo `hf_device_map` permite acessar e visualizar o `device_map`.

```py
print(pipeline.hf_device_map)
# {'transformer': 1, 'vae': 1, 'text_encoder': 0}
```

Redefina o `device_map` de um pipeline com o método [reset_device_map()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.reset_device_map). Isso é necessário se você quiser usar métodos como `.to()`, [enable_sequential_cpu_offload()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.enable_sequential_cpu_offload) e [enable_model_cpu_offload()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload).

```py
pipeline.reset_device_map()
```

## Carregamento paralelo

Modelos grandes são frequentemente [divididos](../optimization/memory#sharded-checkpoints) em arquivos menores para facilitar o carregamento. O Diffusers suporta o carregamento paralelo de shards para acelerar o processo de carregamento.

Defina `HF_ENABLE_PARALLEL_LOADING` como `"YES"` para habilitar o carregamento paralelo de shards.

O argumento `device_map` deve ser definido como `"cuda"` para pré-alocar um grande bloco de memória com base no tamanho do modelo. Isso reduz substancialmente o tempo de carregamento do modelo, pois o aquecimento do alocador de memória evita muitas chamadas menores ao alocador posteriormente.

```py
import os
import torch
from diffusers import DiffusionPipeline

os.environ["HF_ENABLE_PARALLEL_LOADING"] = "YES"

pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-I2V-A14B-Diffusers", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## Substituindo modelos em um pipeline

[DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline) é flexível e permite carregar outros modelos ou agendadores. Você pode experimentar diferentes agendadores para otimizar a velocidade ou a qualidade da geração, e pode substituir modelos por outros mais eficientes.

O exemplo abaixo usa uma versão mais estável do VAE.

```py
import torch
from diffusers import DiffusionPipeline, AutoModel

vae = AutoModel.from_pretrained(
  "madebyollin/sdxl-vae-fp16-fix", dtype=torch.float16
)

pipeline = DiffusionPipeline.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0",
  vae=vae,
  dtype=torch.float16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## Reutilizando modelos em vários pipelines

Ao trabalhar com vários pipelines que usam o mesmo modelo, o método [from_pipe()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) permite reutilizar um modelo em vez de recarregá-lo a cada vez. Isso permite usar vários pipelines sem aumentar o uso de memória.

O uso de memória é determinado pelo pipeline com o maior requisito de memória, independentemente do número de pipelines.

[from_pipe()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) compartilha modelos na memória. Chamadas separadas de [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) compartilham arquivos no disco quando dois repositórios contêm arquivos idênticos, como o mesmo text encoder. Veja [Compartilhar arquivos entre repositórios](../installation#share-files-across-repositories) para mais detalhes.

O exemplo abaixo carrega um pipeline e, em seguida, carrega um segundo pipeline com [from_pipe()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) para usar [perturbed-attention guidance (PAG)](../api/pipelines/pag) para melhorar a qualidade da geração.

> [!WARNING]
> Use [AutoPipelineForText2Image](/docs/diffusers/main/pt/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Image) porque [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline) não suporta PAG. Consulte a documentação de [AutoPipeline](../tutorials/autopipeline) para saber mais.

```py
import torch
from diffusers import AutoPipelineForText2Image

pipeline_sdxl = AutoPipelineForText2Image.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline_sdxl(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

Defina `enable_pag=True` no segundo pipeline para habilitar o PAG. O segundo pipeline usa a mesma quantidade de memória porque compartilha os pesos do modelo com o primeiro.

```py
pipeline = AutoPipelineForText2Image.from_pipe(
  pipeline_sdxl, enable_pag=True
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

> [!WARNING]
> Os pipelines criados por [from_pipe()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) compartilham os mesmos modelos e *state*. Modificar o estado de um modelo em um pipeline afeta todos os outros pipelines que compartilham o mesmo modelo.

Alguns métodos podem não funcionar corretamente em pipelines criados com [from_pipe()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe). Por exemplo, [enable_model_cpu_offload()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload) depende de uma ordem de execução única do modelo, que pode diferir no novo pipeline. Para garantir o funcionamento adequado, reaplique esses métodos no novo pipeline.

## Próximas etapas

Quando um pipeline é carregado, você geralmente ajusta o agendamento de desruidamento, troca os formatos de pesos ou anexa adaptadores.

- [Schedulers](./schedulers) aborda a troca e a configuração do algoritmo de remoção de ruído.
- [Formatos de modelo](./other-formats) aborda GGUF, checkpoints de arquivo único e outros layouts de pesos.
- [Reduzir o uso de memória](../optimization/memory) aborda o offloading e outras ferramentas de memória.
- [LoRA](../tutorials/using_peft_for_inference) aborda o carregamento de adaptadores em um pipeline.
- [Legacy checkpoints](./legacy_checkpoints#safety-checker) aborda o verificador de segurança para checkpoints mais antigos do Stable Diffusion.