# Pipelines

Pipelines oferecem uma maneira simples de executar modelos de difusão de ponta em inferência, agrupando todos os componentes necessários (múltiplos modelos treinados independentemente, agendadores e processadores) em uma única classe de ponta a ponta. Pipelines são flexíveis e podem ser adaptados para usar diferentes agendadores ou até mesmo componentes de modelo.

Todos os pipelines são construídos a partir da classe base [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline), que fornece a funcionalidade básica para carregar, baixar e salvar todos os componentes. Os tipos específicos de pipeline (por exemplo, [StableDiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline)) carregados com [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) são detectados automaticamente e os componentes do pipeline são carregados e passados para a função `__init__` do pipeline.

> [!WARNING]
> Você não deve usar a classe [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline) para treinamento. Os componentes individuais (por exemplo, [UNet2DModel](/docs/diffusers/v0.43.0/pt/api/models/unet2d#diffusers.UNet2DModel) e [UNet2DConditionModel](/docs/diffusers/v0.43.0/pt/api/models/unet2d-cond#diffusers.UNet2DConditionModel)) dos pipelines de difusão geralmente são treinados individualmente, então sugerimos trabalhar diretamente com eles.
>
> 
>
> Os Pipelines não oferecem nenhuma funcionalidade de treinamento. Você notará que o autograd do PyTorch é desativado decorando o método `__call__()` com o decorador [`torch.no_grad`](https://pytorch.org/docs/stable/generated/torch.no_grad.html), pois os pipelines não devem ser usados para treinamento. Se você estiver interessado em treinamento, consulte os guias de [Training](../../training/overview)!

Use **API > Pipelines** na barra lateral para navegar por todas as referências de pipelines por modalidade. Para fluxos de trabalho orientados a tarefas, comece pelo [Quickstart](../../quicktour) ou por um guia como [text-to-image](../../using-diffusers/conditional_image_generation), [image-to-image](../../using-diffusers/img2img), [inpainting](../../using-diffusers/inpaint) ou [video generation](../../using-diffusers/text-img2vid).

## DiffusionPipeline[[diffusers.DiffusionPipeline]]

#### diffusers.DiffusionPipeline[[diffusers.DiffusionPipeline]]

```python
diffusers.DiffusionPipeline()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L198)

Classe base para todos os pipelines.

[DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline) armazena todos os componentes (modelos, agendadores e processadores) para pipelines de difusão e fornece métodos para carregar, baixar e salvar modelos. Ele também inclui métodos para:

- move todos os módulos do PyTorch para o dispositivo de sua escolha
- ativar/desativar a barra de progresso para a iteração de desruidamento

Atributos de classe:

- **config_name** (`str`) -- O nome do arquivo de configuração que armazena os nomes de classe e módulo de todos os componentes do pipeline de difusão.
- **_optional_components** (`List[str]`) -- Lista de todos os componentes opcionais que não precisam ser passados para o pipeline para que ele funcione (deve ser sobrescrito pelas subclasses).

#### __call__[[diffusers.DiffusionPipeline.__call__]]

```python
__call__(*args, **kwargs)
```

Chame self como uma função.

#### device[[diffusers.DiffusionPipeline.device]]

```python
device()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L600)

**Retorna:** `torch.device`

O dispositivo torch no qual o pipeline está localizado. Quando os componentes são divididos entre dispositivos (por exemplo, codificadores de texto na CPU enquanto o backbone de desruidização é executado em um acelerador), o dispositivo do acelerador é retornado.

#### para[[diffusers.DiffusionPipeline.to]]

```python
to(*args, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L397)

**Parâmetros:**

dtype (`torch.dtype`, *opcional*) : Retorna um pipeline com o [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) especificado

device (`torch.Device`, *opcional*) : Retorna um pipeline com o [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) especificado

silence_dtype_warnings (`str`, *opcional*, padrão `False`) : Se deve omitir avisos quando o `dtype` de destino não é compatível com o `device` de destino.

**Retorna:** [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline)

O pipeline foi convertido para o `dtype` e/ou `dtype` especificado.

Executa a conversão de dtype e/ou device do Pipeline. Um torch.dtype e um torch.device são inferidos a partir dos argumentos de `self.to(*args, **kwargs).`

> [!TIP] > Se o pipeline já possui o torch.dtype e o torch.device corretos, ele é retornado como está.
Caso contrário, > o pipeline retornado é uma cópia de self com o torch.dtype e o torch.device desejados.

Aqui estão as formas de chamar `to`:

- `to(dtype, silence_dtype_warnings=False) → DiffusionPipeline` para retornar um pipeline com o [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) especificado
- `to(device, silence_dtype_warnings=False) → DiffusionPipeline` para retornar um pipeline com o [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) especificado
- `to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline` para retornar um pipeline com o [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) e o [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) especificados

#### componentes[[diffusers.DiffusionPipeline.components]]

```python
components()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1907)

A propriedade `self.components` pode ser útil para executar diferentes pipelines com os mesmos pesos e configurações sem alocar memória adicional.

Returns (`dict`): Um dicionário contendo todos os módulos necessários para inicializar o pipeline.

Exemplos:

```py
>>> from diffusers import (
...     StableDiffusionPipeline,
...     StableDiffusionImg2ImgPipeline,
...     StableDiffusionInpaintPipeline,
... )

>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)
```

#### disable_attention_slicing[[diffusers.DiffusionPipeline.disable_attention_slicing]]

```python
disable_attention_slicing()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2067)

Desativa o cálculo de atenção fatiado. Se `enable_attention_slicing` foi chamado anteriormente, a atenção é calculada em uma única etapa.

#### disable_xformers_memory_efficient_attention[[diffusers.DiffusionPipeline.disable_xformers_memory_efficient_attention]]

```python
disable_xformers_memory_efficient_attention()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2006)

Desative a atenção eficiente em memória do [xFormers](https://facebookresearch.github.io/xformers/).

#### download[[diffusers.DiffusionPipeline.download]]

```python
download(pretrained_model_name, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1483)

**Parâmetros:**

pretrained_model_name (`str` ou `os.PathLike`, *opcional*) : Uma string, o *id do repositório* (por exemplo, `CompVis/ldm-text2im-large-256`) de um pipeline pré-treinado hospedado no Hub.

custom_pipeline (`str`, *opcional*) : Pode ser:  - Uma string, o *id do repositório* (por exemplo `CompVis/ldm-text2im-large-256`) de um pipeline pré-treinado hospedado no Hub. O repositório deve conter um arquivo chamado `pipeline.py` que define o pipeline personalizado.  - Uma string, o *nome do arquivo* de um pipeline da comunidade hospedado no GitHub sob [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Os nomes de arquivo válidos devem corresponder ao nome do arquivo e não ao script do pipeline (`clip_guided_stable_diffusion` em vez de `clip_guided_stable_diffusion.py`). Os pipelines da comunidade são sempre carregados da branch `main` atual do GitHub.  - Um caminho para um *diretório* (`./my_pipeline_directory/`) contendo um pipeline personalizado. O diretório deve conter um arquivo chamado `pipeline.py` que define o pipeline personalizado.  > [!WARNING] > 🧪 Este é um recurso experimental e pode mudar no futuro.  Para mais informações sobre como carregar e criar pipelines personalizados, veja [Como contribuir com um pipeline da comunidade](https://huggingface.co/docs/diffusers/main/en/using-diffusers/contribute_pipeline).

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

proxies (`Dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

output_loading_info(`bool`, *opcional*, padrão `False`) : Indica se deve ou não retornar também um dicionário contendo chaves ausentes, chaves inesperadas e mensagens de erro.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

custom_revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser um nome de branch, um nome de tag ou um id de commit, semelhante a `revision` ao carregar um pipeline personalizado do Hub. Pode ser uma versão do 🤗 Diffusers ao carregar um pipeline personalizado do GitHub; caso contrário, o padrão é `"main"` ao carregar do Hub.

mirror (`str`, *opcional*) : Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a pontualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.

variant (`str`, *opcional*) : Carrega os pesos de um nome de arquivo de variante especificado, como `"fp16"` ou `"ema"`.

use_safetensors (`bool`, *opcional*, padrão `None`) : Se definido como `None`, os pesos em safetensors são baixados se estiverem disponíveis **e** se a biblioteca safetensors estiver instalada. Se definido como `True`, o modelo é carregado forçadamente a partir dos pesos em safetensors. Se definido como `False`, os pesos em safetensors não são carregados.

use_onnx (`bool`, *opcional*, padrão `False`) : Se definido como `True`, os pesos ONNX sempre serão baixados, se presentes. Se definido como `False`, os pesos ONNX nunca serão baixados. Por padrão, `use_onnx` assume o valor do atributo de classe `_is_onnx`, que é `False` para pipelines não-ONNX e `True` para pipelines ONNX. Os pesos ONNX incluem tanto arquivos terminados em `.onnx` quanto `.pb`.

trust_remote_code (`bool`, *opcional*, padrão `False`) : Se permite ou não o uso de pipelines e componentes personalizados definidos no Hub em seus próprios arquivos. Essa opção deve ser definida como `True` apenas para repositórios nos quais você confia e cujo código você leu, pois isso executará o código presente no Hub na sua máquina local.

use_flashpack (`bool`, *opcional*, padrão `False`) : Se definido como `True`, os pesos do FlashPack sempre serão baixados, caso estejam presentes. Se definido como `False`, os pesos do FlashPack nunca serão baixados.

**Retorna:** `os.PathLike`

Um caminho para o pipeline baixado.

Baixe e faça o cache de um pipeline de difusão do PyTorch a partir de pesos de pipeline pré-treinados.

> [!TIP] > Para usar modelos privados ou [gated models](https://huggingface.co/docs/hub/models-gated#gated-models), faça login
com `hf > auth login

#### enable_attention_slicing[[diffusers.DiffusionPipeline.enable_attention_slicing]]

```python
enable_attention_slicing(slice_size: str | int = 'auto')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2030)

**Parâmetros:**

slice_size (`str` ou `int`, *opcional*, padrão `"auto"`) : Quando `"auto"`, divide a entrada dos cabeçalhos de atenção pela metade, de modo que a atenção será calculada em duas etapas. Se `"max"`, a quantidade máxima de memória será economizada executando apenas uma fatia por vez. Se um número for fornecido, usa tantas fatias quanto `attention_head_dim // slice_size`. Nesse caso, `attention_head_dim` deve ser um múltiplo de `slice_size`.

Ativa o cálculo de atenção fatiado. Quando esta opção está ativada, o módulo de atenção divide o tensor de entrada em fatias para calcular a atenção em várias etapas. Para mais de uma cabeça de atenção, o cálculo é executado sequencialmente em cada cabeça. Isso é útil para economizar memória em troca de uma pequena diminuição na velocidade.

> [!WARNING] > ⚠️ Não ative o fatiamento de atenção se você já estiver usando `scaled_dot_product_attention` (SDPA)
do PyTorch > 2.0 ou xFormers. Esses cálculos de atenção já são muito eficientes em termos de memória, portanto, você não precisará habilitar > esta função. Se você habilitar o fatiamento de atenção com SDPA ou xFormers, isso pode levar a uma desaceleração significativa!

Exemplos:

```py
>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]
```

#### enable_group_offload[[diffusers.DiffusionPipeline.enable_group_offload]]

```python
enable_group_offload(onload_device: device, offload_device: device = torch.device(), offload_type: str = 'block_level', num_blocks_per_group: int | None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage = False, offload_to_disk_path: str | None = None, exclude_modules: str | list[str] | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1343)

**Parâmetros:**

onload_device (`torch.device`) : O dispositivo para o qual o grupo de módulos é carregado.

offload_device (`torch.device`, padrão `torch.device("cpu")`) : O dispositivo para o qual o grupo de módulos é descarregado. Isso deve ser tipicamente a CPU. O padrão é CPU.

offload_type (`str` ou `GroupOffloadingType`, padrão "block_level") : O tipo de offloading a ser aplicado. Pode ser "block_level" ou "leaf_level". O padrão é "block_level".

offload_to_disk_path (`str`, *opcional*, padrão `None`) : O caminho para o diretório onde os parâmetros serão descarregados. Definir esta opção pode ser útil em ambientes com RAM limitada, onde se deseja um equilíbrio razoável entre velocidade e memória.

num_blocks_per_group (`int`, *opcional*) : O número de blocos por grupo ao usar offload_type="block_level". Isso é obrigatório ao usar offload_type="block_level".

non_blocking (`bool`, padrão `False`) : Se True, o offloading e o onloading são realizados com transferência de dados não bloqueante.

use_stream (`bool`, padrão `False`) : Se True, o offloading e o onloading são feitos de forma assíncrona usando um stream CUDA. Isso pode ser útil para sobrepor o cálculo e a transferência de dados.

record_stream (`bool`, padrão `False`) : Quando habilitado com `use_stream`, marca o tensor atual como tendo sido usado por este stream. É mais rápido, à custa de um uso ligeiramente maior de memória. Consulte os [documentos oficiais do PyTorch](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html) para mais detalhes.

low_cpu_mem_usage (`bool`, padrão `False`) : Se True, o uso de memória da CPU é minimizado ao fixar os tensores em tempo de execução, em vez de fixá-los previamente. Esta opção só é relevante ao usar offloading de CPU em streaming (ou seja, `use_stream=True`). Isso pode ser útil quando a memória da CPU é um gargalo, mas pode contrariar os benefícios do uso de streams.

exclude_modules (`Union[str, List[str]]`, padrão `None`) : Lista de módulos a serem excluídos do offloading.

Aplica o group offloading às camadas internas de um torch.nn.Module. Para entender o que é o group offloading e onde ele é vantajoso, precisamos primeiro fornecer algum contexto sobre como funcionam os outros métodos de offloading suportados.

Normalmente, o offloading é feito em dois níveis:
- Nível de módulo: No Diffusers, isso pode ser ativado usando o método `ModelMixin::enable_model_cpu_offload()`. Ele
funciona ao descarregar cada componente de um pipeline para a CPU para armazenamento e recarregá-lo no dispositivo de acelerador quando necessário para o cálculo. Este método é mais eficiente em termos de memória do que manter todos os componentes no acelerador, mas os requisitos de memória ainda são bastante altos. Para que este método funcione, é necessário ter memória equivalente ao tamanho do modelo no dtype de tempo de execução + ao tamanho dos maiores tensores de ativação intermediários para poder completar a passagem para frente.
- Nível de folha: no Diffusers, isso pode ser ativado usando o método `ModelMixin::enable_sequential_cpu_offload()`. Ele
funciona transferindo para a CPU, para armazenamento, os parâmetros de nível de folha mais baixos do grafo de computação, e transferindo de volta para o dispositivo de acelerador apenas as folhas para a computação. Isso utiliza a menor quantidade de memória do acelerador, mas pode ser mais lento devido ao número excessivo de sincronizações de dispositivo.

O offloading por grupos é um meio-termo entre os dois métodos. Ele funciona transferindo grupos de camadas internas (seja `torch.nn.ModuleList` ou `torch.nn.Sequential`). Este método usa menos memória que o offloading em nível de módulo. Ele também é mais rápido que o offloading em nível de folha/sequencial, pois o número de sincronizações de dispositivo é reduzido.

Outro recurso suportado (para dispositivos CUDA com suporte a streams de transferência de dados assíncrona) é a capacidade de sobrepor a transferência de dados e o cálculo para reduzir o tempo de execução geral em comparação com o offloading sequencial. Isso é habilitado usando prefetching de camadas com streams, ou seja, a camada que será executada a seguir inicia o onloading para o dispositivo de acelerador enquanto a camada atual está sendo executada - isso aumenta ligeiramente os requisitos de memória. Observe que esta implementação também suporta offloading em nível de folha, mas pode ser muito mais rápida ao usar streams.

Exemplo:
```python
>>> from diffusers import DiffusionPipeline
>>> import torch

>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)

>>> pipe.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]
```

#### enable_model_cpu_offload[[diffusers.DiffusionPipeline.enable_model_cpu_offload]]

```python
enable_model_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1152)

**Parâmetros:**

gpu_id (`int`, *opcional*) : O ID do acelerador que deve ser usado na inferência. Se não for especificado, o valor padrão será 0.

device (`torch.Device` ou `str`, *opcional*, padrão None) : O tipo de dispositivo PyTorch do acelerador que deve ser usado na inferência. Se não for especificado, ele detectará automaticamente o acelerador disponível e o usará.

Desloca todos os modelos para a CPU usando accelerate, reduzindo o uso de memória com baixo impacto no desempenho. Em comparação com `enable_sequential_cpu_offload`, este método move um modelo inteiro de cada vez para o acelerador quando seu método `forward` é chamado, e o modelo permanece no acelerador até que o próximo modelo seja executado. As economias de memória são menores do que com `enable_sequential_cpu_offload`, mas o desempenho é muito melhor devido à execução iterativa do `unet`.

#### enable_sequential_cpu_offload[[diffusers.DiffusionPipeline.enable_sequential_cpu_offload]]

```python
enable_sequential_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1273)

**Parâmetros:**

gpu_id (`int`, *opcional*) : O ID do acelerador que deve ser usado na inferência. Se não for especificado, o valor padrão será 0.

device (`torch.Device` ou `str`, *opcional*, padrão None) : O tipo de dispositivo PyTorch do acelerador que deve ser usado na inferência. Se não for especificado, ele detectará automaticamente o acelerador disponível e o usará.

Desloca todos os modelos para a CPU usando 🤗 Accelerate, reduzindo significativamente o uso de memória. Quando chamado, os state dicts de todos os componentes `torch.nn.Module` (exceto aqueles em `self._exclude_from_cpu_offload`) são salvos na CPU e então movidos para `torch.device('meta')` e carregados no acelerador apenas quando o método `forward` do submódulo específico é chamado. O offloading ocorre em nível de submódulo. As economias de memória são maiores do que com `enable_model_cpu_offload`, mas o desempenho é menor.

#### enable_xformers_memory_efficient_attention[[diffusers.DiffusionPipeline.enable_xformers_memory_efficient_attention]]

```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1975)

**Parâmetros:**

attention_op (`Callable`, *opcional*) : Substitui o operador padrão `None` para uso como argumento `op` da função [`memory_efficient_attention()`](https://facebookresearch.github.io/xformers/components/ops.html#xformers.ops.memory_efficient_attention) do xFormers.

Ative a atenção eficiente em memória do [xFormers](https://facebookresearch.github.io/xformers/). Quando essa opção estiver ativada, você deve observar um menor uso de memória de GPU e uma possível aceleração durante a inferência. A aceleração durante o treinamento não é garantida.

> [!WARNING] > ⚠️ Quando a atenção eficiente em memória e a atenção fatiada estão ambas habilitadas, a atenção eficiente
attention tem > precedência.

Exemplos:

```py
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)
```

#### from_pipe[[diffusers.DiffusionPipeline.from_pipe]]

```python
from_pipe(pipeline, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2083)

**Parâmetros:**

pipeline (`DiffusionPipeline`) : O pipeline a partir do qual criar um novo pipeline.

**Retorna:** `DiffusionPipeline`

Um novo pipeline com os mesmos pesos e configurações que `pipeline`.

Crie um novo pipeline a partir de um pipeline dado. Este método é útil para criar um novo pipeline a partir dos componentes de um pipeline existente, sem alocar memória adicional.

Exemplos:

```py
>>> from diffusers import StableDiffusionPipeline, StableDiffusionSAGPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> new_pipe = StableDiffusionSAGPipeline.from_pipe(pipe)
```

#### from_pretrained[[diffusers.DiffusionPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L638)

**Parâmetros:**

pretrained_model_name_or_path (`str` ou `os.PathLike`, *opcional*) : Pode ser:  - Uma string, o *repo id* (por exemplo `CompVis/ldm-text2im-large-256`) de um pipeline pré-treinado hospedado no Hub. - Um caminho para um *diretório* (por exemplo `./my_pipeline_directory/`) contendo pesos de pipeline salvos usando [save_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` ou `dict[str, Union[str, torch.dtype]]`, *opcional*) : Substitui o `torch.dtype` padrão e carrega o modelo com outro dtype. Para carregar submodelos com dtypes diferentes, passe um `dict` (por exemplo, `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Defina o dtype padrão para componentes não especificados com `default` (por exemplo, `{'transformer': torch.bfloat16, 'default': torch.float16}`). Se um componente não for especificado e nenhum padrão for definido, `torch.float32` será usado.

custom_pipeline (`str`, *opcional*) : > [!WARNING] > 🧪 Este é um recurso experimental e pode mudar no futuro.  Pode ser:  - Uma string, o *repo id* (por exemplo `hf-internal-testing/diffusers-dummy-pipeline`) de um pipeline personalizado hospedado no Hub. O repositório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado. - Uma string, o *nome do arquivo* de um pipeline da comunidade hospedado no GitHub sob [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Os nomes de arquivo válidos devem corresponder ao nome do arquivo e não ao script do pipeline (`clip_guided_stable_diffusion` em vez de `clip_guided_stable_diffusion.py`). Os pipelines da comunidade são sempre carregados da branch main atual do GitHub. - Um caminho para um diretório (`./my_pipeline_directory/`) contendo um pipeline personalizado. O diretório deve conter um arquivo chamado `pipeline.py` que define o pipeline personalizado.  Para mais informações sobre como carregar e criar pipelines personalizados, consulte [Carregando e Adicionando Pipelines Personalizados](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

cache_dir (`Union[str, os.PathLike]`, *opcional*) : Caminho para um diretório onde a configuração de um modelo pré-treinado baixado é armazenada em cache, caso o cache padrão não seja utilizado.

proxies (`Dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

output_loading_info(`bool`, *opcional*, padrão `False`) : Indica se deve ou não retornar também um dicionário contendo chaves ausentes, chaves inesperadas e mensagens de erro.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

custom_revision (`str`, *opcional*) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag ou um id de commit, semelhante a `revision` ao carregar um pipeline personalizado do Hub. O padrão é a versão estável mais recente do 🤗 Diffusers.

mirror (`str`, *opcional*) : Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a pontualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.

device_map (`str`, *opcional*) : Estratégia que determina como os diferentes componentes de um pipeline devem ser alocados nos dispositivos disponíveis. Atualmente, apenas o `device_map` "balanced" é suportado. Consulte [este](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) para saber mais.

max_memory (`Dict`, *opcional*) : Um dicionário com o identificador de dispositivo para a memória máxima. Se não for definido, o padrão será a memória máxima disponível para cada GPU e a RAM disponível na CPU.

offload_folder (`str` ou `os.PathLike`, *opcional*) : O caminho para descarregar os pesos se device_map contiver o valor `"disk"`.

offload_state_dict (`bool`, *opcional*) : Se `True`, descarrega temporariamente o state dict da CPU para o disco rígido para evitar a falta de RAM na CPU caso o peso do state dict da CPU + o maior shard do checkpoint não caiba. O padrão é `True` quando há algum offload para o disco.

low_cpu_mem_usage (`bool`, *opcional*, padrão é `True` se a versão do torch >= 1.9.0, caso contrário `False`) : Acelera o carregamento do modelo carregando apenas os pesos pré-treinados e não inicializando os pesos. Isso também tenta não usar mais do que 1x o tamanho do modelo na memória de CPU (incluindo a memória de pico) durante o carregamento do modelo. Suportado apenas para PyTorch >= 1.9.0. Se você estiver usando uma versão mais antiga do PyTorch, definir este argumento como `True` causará um erro.

use_safetensors (`bool`, *opcional*, padrão `None`) : Se definido como `None`, os pesos em safetensors são baixados se estiverem disponíveis **e** se a biblioteca safetensors estiver instalada. Se definido como `True`, o modelo é carregado forçadamente a partir dos pesos em safetensors. Se definido como `False`, os pesos em safetensors não são carregados.

use_onnx (`bool`, *opcional*, padrão `None`) : Se definido como `True`, os pesos ONNX sempre serão baixados, se presentes. Se definido como `False`, os pesos ONNX nunca serão baixados. Por padrão, `use_onnx` assume o valor do atributo de classe `_is_onnx`, que é `False` para pipelines não-ONNX e `True` para pipelines ONNX. Os pesos ONNX incluem tanto arquivos terminados em `.onnx` quanto `.pb`.

kwargs (dicionário restante de argumentos de palavra-chave, *opcional*) : Pode ser usado para sobrescrever variáveis de carregamento e salvamento (os componentes do pipeline da classe de pipeline específica). Os componentes sobrescritos são passados diretamente para o método `__init__` dos pipelines. Veja o exemplo abaixo para mais informações.

variant (`str`, *opcional*) : Carrega os pesos de um nome de arquivo de variante especificado, como `"fp16"` ou `"ema"`.

disable_mmap ('bool', *opcional*, padrão 'False') : Se deve desabilitar o mmap ao carregar um modelo Safetensors. Essa opção pode ter um desempenho melhor quando o modelo está em uma montagem de rede ou em um disco rígido, que podem não lidar bem com a natureza de buscas do mmap.

Instanciar um pipeline de difusão do PyTorch a partir de pesos de pipeline pré-treinados.

O pipeline é definido no modo de avaliação (`model.eval()`) por padrão.

Se você receber a mensagem de erro abaixo, é necessário ajustar os pesos para sua tarefa de destino:

```
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
```

> [!TIP] > Para usar modelos privados ou [gated](https://huggingface.co/docs/hub/models-gated#gated-models), faça login
com `hf > auth login`.

Exemplos:

```py
>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler
```

#### maybe_free_model_hooks[[diffusers.DiffusionPipeline.maybe_free_model_hooks]]

```python
maybe_free_model_hooks()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1250)

Método que executa o seguinte:
- Desloca todos os componentes.
- Remove todos os hooks do modelo que foram adicionados ao usar `enable_model_cpu_offload` e, em seguida, os aplica novamente. Caso o modelo não tenha sido offloaded, esta função é um no-op.
- Redefine os hooks com estado dos componentes de denoiser do diffusers, caso tenham sido adicionados com `register_hook()`.

Certifique-se de adicionar esta função ao final da função `__call__` do seu pipeline para que ela funcione corretamente ao aplicar `enable_model_cpu_offload`.

#### numpy_to_pil[[diffusers.DiffusionPipeline.numpy_to_pil]]

```python
numpy_to_pil(images)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1945)

Converte uma imagem NumPy ou um lote de imagens em uma imagem PIL.

#### remove_all_hooks[[diffusers.DiffusionPipeline.remove_all_hooks]]

```python
remove_all_hooks()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1143)

Remove todos os hooks que foram adicionados ao usar `enable_sequential_cpu_offload` ou `enable_model_cpu_offload`.

#### reset_device_map[[diffusers.DiffusionPipeline.reset_device_map]]

```python
reset_device_map()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L1470)

Redefine os mapas de dispositivos (se houver) para None.

#### save_pretrained[[diffusers.DiffusionPipeline.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, safe_serialization: bool = True, variant: str | None = None, max_shard_size: int | str | None = None, push_to_hub: bool = False, use_flashpack: bool = False, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L254)

**Parâmetros:**

save_directory (`str` ou `os.PathLike`) : Diretório para salvar um pipeline. Será criado se não existir.

safe_serialization (`bool`, *opcional*, padrão `True`) : Se o modelo deve ser salvo usando `safetensors` ou da maneira tradicional do PyTorch com `pickle`.

variant (`str`, *opcional*) : Se especificado, os pesos são salvos no formato `pytorch_model.<variant>.bin`.

max_shard_size (`int` ou `str`, padrão `None`) : O tamanho máximo de um checkpoint antes de ser fragmentado. Os fragmentos do checkpoint terão, então, cada um um tamanho menor que esse valor. Se expresso como uma string, deve ser composto por dígitos seguidos por uma unidade (como `"5GB"`). Se expresso como um inteiro, a unidade é bytes. Observe que esse limite será reduzido após um certo período de tempo (a partir de outubro de 2024) para permitir que os usuários façam o upgrade para a versão mais recente do `diffusers`. Isso visa estabelecer um tamanho padrão comum para este argumento entre as diferentes bibliotecas do ecossistema Hugging Face (`transformers` e `accelerate`, por exemplo).

push_to_hub (`bool`, *opcional*, padrão `False`) : Se deve ou não enviar seu modelo para o hub de modelos do Hugging Face após salvá-lo. Você pode especificar o repositório para o qual deseja enviar com `repo_id` (o padrão será o nome de `save_directory` no seu namespace).

kwargs (`Dict[str, Any]`, *opcional*) : Argumentos de palavra-chave adicionais passados ao método [push_to_hub()](/docs/diffusers/v0.43.0/pt/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub).

Salva todas as variáveis salveis do pipeline em um diretório. Uma variável do pipeline pode ser salva e carregada se sua classe implementar tanto um método de salvamento quanto um método de carregamento. O pipeline é facilmente recarregado usando o método de classe [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

#### diffusers.StableDiffusionMixin.enable_freeu[[diffusers.StableDiffusionMixin.enable_freeu]]

```python
diffusers.StableDiffusionMixin.enable_freeu(s1: float, s2: float, b1: float, b2: float)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2267)

**Parâmetros:**

s1 (`float`) : Fator de escala para a etapa 1 para atenuar as contribuições dos recursos de skip. Isso é feito para mitigar o "efeito de sobre-suavização" no processo aprimorado de remoção de ruído.

s2 (`float`) : Fator de escala para a etapa 2 para atenuar as contribuições dos recursos de skip. Isso é feito para mitigar o "efeito de sobre-suavização" no processo aprimorado de remoção de ruído.

b1 (`float`) : Fator de escala para a etapa 1 para amplificar as contribuições dos recursos do backbone.

b2 (`float`) : Fator de escala para a etapa 2 para amplificar as contribuições dos recursos do backbone.

Ativa o mecanismo FreeU, conforme descrito em https://huggingface.co/papers/2309.11497.

Os sufixos após os fatores de escala representam as etapas em que eles estão sendo aplicados.

Consulte o [repositório oficial](https://github.com/ChenyangSi/FreeU) para as combinações de valores que são conhecidas por funcionar bem em diferentes pipelines, como Stable Diffusion v1, v2 e Stable Diffusion XL.

#### diffusers.StableDiffusionMixin.disable_freeu[[diffusers.StableDiffusionMixin.disable_freeu]]

```python
diffusers.StableDiffusionMixin.disable_freeu()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L2289)

Desativa o mecanismo FreeU, se estiver ativado.

## PushToHubMixin[[diffusers.utils.PushToHubMixin]]

#### diffusers.utils.PushToHubMixin[[diffusers.utils.PushToHubMixin]]

```python
diffusers.utils.PushToHubMixin()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/hub_utils.py#L491)

Um Mixin para enviar um modelo, agendador ou pipeline para o Hugging Face Hub.

#### push_to_hub[[diffusers.utils.PushToHubMixin.push_to_hub]]

```python
push_to_hub(repo_id: str, commit_message: str | None = None, private: bool | None = None, token: str | None = None, create_pr: bool = False, safe_serialization: bool = True, variant: str | None = None, subfolder: str | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/utils/hub_utils.py#L526)

**Parâmetros:**

repo_id (`str`) : O nome do repositório para o qual você deseja enviar os arquivos do seu modelo, agendador ou pipeline. Deve conter o nome da sua organização ao enviar para uma organização. `repo_id` também pode ser um caminho para um diretório local.

commit_message (`str`, *opcional*) : Mensagem para commit ao fazer push. Padrão é `"Upload {object}"`.

private (`bool`, *opcional*) : Se deve tornar o repositório privado. Se `None` (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir.

token (`str`, *opcional*) : O token a ser usado como autorização de bearer HTTP para arquivos remotos. O token gerado ao executar `hf auth login` (armazenado em `~/.huggingface`).

create_pr (`bool`, *opcional*, padrão `False`) : Se deve ou não criar um PR com os arquivos enviados ou fazer o commit diretamente.

safe_serialization (`bool`, *opcional*, padrão `True`) : Se os pesos do modelo devem ou não ser convertidos para o formato `safetensors`.

variant (`str`, *opcional*) : Se especificado, os pesos são salvos no formato `pytorch_model.<variant>.bin`.

Envie arquivos de modelo, agendador ou pipeline para o 🤗 Hugging Face Hub.

Exemplos:

```python
from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")
```

## Callbacks[[diffusers.callbacks.PipelineCallback]]

#### diffusers.callbacks.PipelineCallback[[diffusers.callbacks.PipelineCallback]]

```python
diffusers.callbacks.PipelineCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L7)

Classe base para todos os callbacks oficiais usados em um pipeline. Esta classe fornece uma estrutura para implementar callbacks personalizados e garante que todos os callbacks tenham uma interface consistente.

Implemente o seguinte: `tensor_inputs`: este deve retornar uma lista de entradas de tensor específicas para o seu callback. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline. `callback_fn`: este método define a funcionalidade central do seu callback.

#### diffusers.callbacks.SDCFGCutoffCallback[[diffusers.callbacks.SDCFGCutoffCallback]]

```python
diffusers.callbacks.SDCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L69)

Função de callback para Pipelines de Stable Diffusion. Após um determinado número de etapas (definido por `cutoff_step_ratio` ou `cutoff_step_index`), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo `_guidance_scale` para 0.0 após o passo de corte.

#### diffusers.callbacks.SDXLCFGCutoffCallback[[diffusers.callbacks.SDXLCFGCutoffCallback]]

```python
diffusers.callbacks.SDXLCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L98)

Função de callback para os Pipelines base do Stable Diffusion XL. Após um determinado número de etapas (definido por `cutoff_step_ratio` ou `cutoff_step_index`), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo `_guidance_scale` para 0.0 após o passo de corte.

#### diffusers.callbacks.SDXLControlnetCFGCutoffCallback[[diffusers.callbacks.SDXLControlnetCFGCutoffCallback]]

```python
diffusers.callbacks.SDXLControlnetCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L140)

Função de callback para os Pipelines do Controlnet Stable Diffusion XL. Após um determinado número de etapas (definido por `cutoff_step_ratio` ou `cutoff_step_index`), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo `_guidance_scale` para 0.0 após o passo de corte.

#### diffusers.callbacks.IPAdapterScaleCutoffCallback[[diffusers.callbacks.IPAdapterScaleCutoffCallback]]

```python
diffusers.callbacks.IPAdapterScaleCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L188)

Função de callback para qualquer pipeline que herda de `IPAdapterMixin`. Após um determinado número de etapas (definido por `cutoff_step_ratio` ou `cutoff_step_index`), este callback definirá a escala do IP Adapter como `0.0`.

Nota: Este callback altera os processadores de atenção do IP Adapter definindo a escala como 0.0 após o passo de corte.

#### diffusers.callbacks.SD3CFGCutoffCallback[[diffusers.callbacks.SD3CFGCutoffCallback]]

```python
diffusers.callbacks.SD3CFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/callbacks.py#L212)

Função de callback para os pipelines do Stable Diffusion 3. Após um determinado número de etapas (definido por `cutoff_step_ratio` ou `cutoff_step_index`), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo `_guidance_scale` para 0.0 após o passo de corte.