# SD3ControlNetModel

SD3ControlNetModel é uma implementação do ControlNet para o Stable Diffusion 3.

O modelo ControlNet foi introduzido em [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) por Lvmin Zhang, Anyi Rao e Maneesh Agrawala. Ele oferece um maior grau de controle sobre a geração de imagens a partir de texto ao condicionar o modelo em entradas adicionais, como mapas de bordas, mapas de profundidade, mapas de segmentação e pontos-chave para detecção de pose.

O resumo do artigo é:

*Apresentamos o ControlNet, uma arquitetura de rede neural para adicionar controles de condicionamento espacial a grandes modelos de difusão de texto para imagem pré-treinados. O ControlNet trava os grandes modelos de difusão prontos para produção e reutiliza suas camadas de codificação profundas e robustas, pré-treinadas com bilhões de imagens, como uma base forte para aprender um conjunto diversificado de controles condicionais. A arquitetura neural é conectada com "convoluções zero" (camadas de convolução inicializadas em zero) que crescem progressivamente os parâmetros a partir de zero e garantem que nenhum ruído prejudicial possa afetar o ajuste fino. Testamos vários controles de condicionamento, por exemplo, bordas, profundidade, segmentação, pose humana, etc., com o Stable Diffusion, usando condições únicas ou múltiplas, com ou sem prompts. Mostramos que o treinamento dos ControlNets é robusto com conjuntos de dados pequenos (<50k) e grandes (>1m). Resultados extensos mostram que o ControlNet pode facilitar aplicações mais amplas para controlar modelos de difusão de imagem.*

## Carregando do formato original

Por padrão, o [SD3ControlNetModel](/docs/diffusers/v0.43.0/pt/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) deve ser carregado com [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/models/overview#diffusers.ModelMixin.from_pretrained).

```py
from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel

controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)
```

## SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

#### diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

```python
diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, attention_head_dim: int = 64, num_attention_heads: int = 18, joint_attention_dim: int = 4096, caption_projection_dim: int = 1152, pooled_projection_dim: int = 2048, out_channels: int = 16, pos_embed_max_size: int = 96, extra_conditioning_channels: int = 0, dual_attention_layers: tuple[int, ...] = (), qk_norm: str | None = None, pos_embed_type: str | None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L42)

**Parâmetros:**

sample_size (`int`, padrão `128`) : A largura/altura dos latentes. Isso é fixo durante o treinamento, pois é usado para aprender um número de embeddings de posição.

patch_size (`int`, padrão `2`) : Tamanho do patch para dividir os dados de entrada em pequenos patches.

in_channels (`int`, padrão `16`) : O número de canais latentes na entrada.

num_layers (`int`, padrão `18`) : O número de blocos de transformadores a serem usados.

attention_head_dim (`int`, padrão `64`) : O número de canais em cada head.

num_attention_heads (`int`, padrão `18`) : O número de cabeças a serem usadas para a atenção multi-cabeça.

joint_attention_dim (`int`, padrão `4096`) : A dimensão de incorporação a ser usada para a atenção conjunta de texto e imagem.

caption_projection_dim (`int`, padrão `1152`) : A dimensão de incorporação das incorporações de legenda.

pooled_projection_dim (`int`, padrão `2048`) : A dimensão de incorporação das projeções de texto agrupadas.

out_channels (`int`, padrão `16`) : O número de canais latentes na saída.

pos_embed_max_size (`int`, padrão `96`) : A altura/largura máxima latente dos embeddings posicionais.

extra_conditioning_channels (`int`, padrão `0`) : O número de canais extras a serem usados para condicionamento na incorporação de patches.

dual_attention_layers (`tuple[int, ...]`, padrão `()`) : O número de blocos de transformador de fluxo duplo a serem usados.

qk_norm (`str`, *opcional*, padrão `None`) : A normalização a ser usada para a consulta e a chave na camada de atenção. Se `None`, nenhuma normalização é usada.

pos_embed_type (`str`, padrão `"sincos"`) : O tipo de incorporação posicional a ser usado. Escolha entre `"sincos"` e `None`.

use_pos_embed (`bool`, padrão `True`) : Se deve usar embeddings posicionais.

force_zeros_for_pooled_projection (`bool`, padrão `True`) : Se deve forçar zeros para as embeddings de projeção agrupada. Isso é tratado nos pipelines lendo o valor de configuração do modelo ControlNet.

Modelo ControlNet para [Stable Diffusion 3](https://huggingface.co/papers/2403.03206).

#### enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]

```python
enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L178)

**Parâmetros:**

chunk_size (`int`, *opcional*) : O tamanho do bloco das camadas feed-forward. Se não for especificado, a camada feed-forward será executada individualmente sobre cada tensor com dim=`dim`.

dim (`int`, *opcional*, padrão `0`) : A dimensão sobre a qual o cálculo feed-forward deve ser dividido em blocos. Escolha entre dim=0 (lote) ou dim=1 (comprimento da sequência).

Define o processador de atenção para usar [feed forward chunking](https://huggingface.co/blog/reformer#2-chunked-feed-forward-layers).

#### forward[[diffusers.SD3ControlNetModel.forward]]

```python
forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L272)

**Parâmetros:**

hidden_states (`torch.Tensor` de forma `(batch size, channel, height, width)`) : `hidden_states` de entrada.

controlnet_cond (`torch.Tensor`) : O tensor de entrada condicional com forma `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, padrão `1.0`) : O fator de escala para as saídas do ControlNet.

encoder_hidden_states (`torch.Tensor` de forma `(batch size, sequence_len, embed_dims)`) : Embeddings condicionais (embeddings calculados a partir das condições de entrada, como prompts) a serem usados.

pooled_projections (`torch.Tensor` de forma `(batch_size, projection_dim)`) : Embebimentos projetados a partir dos embebimentos das condições de entrada.

timestep ( `torch.LongTensor`) : Usado para indicar o passo de remoção de ruído.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

return_dict (`bool`, *opcional*, padrão `True`) : Indica se deve retornar um `~models.transformer_2d.Transformer2DModelOutput` em vez de uma tupla simples.

**Retorna:**

Se `return_dict` for True, um `~models.transformer_2d.Transformer2DModelOutput` é retornado; caso contrário, uma `tuple` onde o primeiro elemento é o tensor da amostra.

O método forward do [SD3Transformer2DModel](/docs/diffusers/v0.43.0/pt/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel).

#### fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L208)

Ativa as projeções QKV fundidas. Para os módulos de autoatenção, todas as matrizes de projeção (ou seja, query, key, value) são fundidas. Para os módulos de atenção cruzada, as matrizes de projeção de key e value são fundidas.

> [!WARNING] > Esta API é 🧪 experimental.

#### unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L230)

Desativa a projeção QKV fundida, se estiver habilitada.

> [!WARNING] > Esta API é 🧪 experimental.

## SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

#### diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

```python
diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple[torch.Tensor])
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sd3.py#L38)