# SD3ControlNetModel

SD3ControlNetModel es una implementación de ControlNet para Stable Diffusion 3.

El modelo ControlNet se presentó en [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) de Lvmin Zhang, Anyi Rao y Maneesh Agrawala. Ofrece un mayor grado de control sobre la generación de imágenes a partir de texto al condicionar el modelo con entradas adicionales, como mapas de bordes, mapas de profundidad, mapas de segmentación y puntos clave para la detección de pose.

El resumen del artículo es:

*Presentamos ControlNet, una arquitectura de red neuronal para añadir controles de condicionamiento espacial a grandes modelos de difusión de texto a imagen preentrenados. ControlNet bloquea los grandes modelos de difusión listos para producción y reutiliza sus capas de codificación profundas y robustas, preentrenadas con miles de millones de imágenes, como una base sólida para aprender un conjunto diverso de controles condicionales. La arquitectura neuronal se conecta mediante "convoluciones cero" (capas de convolución inicializadas en cero) que hacen crecer progresivamente los parámetros desde cero y garantizan que ningún ruido perjudicial pueda afectar el ajuste fino. Probamos varios controles de condicionamiento, por ejemplo, bordes, profundidad, segmentación, pose humana, etc., con Stable Diffusion, utilizando una o varias condiciones, con o sin indicaciones. Mostramos que el entrenamiento de ControlNets es robusto con conjuntos de datos pequeños (<50k) y grandes (>1m). Resultados extensos muestran que ControlNet puede facilitar aplicaciones más amplias para controlar los modelos de difusión de imágenes.*

## Carga desde el formato original

Por defecto, el [SD3ControlNetModel](/docs/diffusers/v0.43.0/es/api/models/controlnet_sd3#diffusers.SD3ControlNetModel) debe cargarse con [from_pretrained()](/docs/diffusers/v0.43.0/es/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)
```

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

**Parámetros:**

sample_size (`int`, por defecto `128`) : El ancho/alto de los latentes. Esto se fija durante el entrenamiento, ya que se utiliza para aprender un número de embeddings de posición.

patch_size (`int`, por defecto `2`) : Tamaño del parche para convertir los datos de entrada en pequeños parches.

in_channels (`int`, por defecto `16`) : El número de canales latentes en la entrada.

num_layers (`int`, por defecto `18`) : El número de bloques de transformador a utilizar.

attention_head_dim (`int`, por defecto `64`) : El número de canales en cada cabeza.

num_attention_heads (`int`, por defecto `18`) : El número de cabezas a utilizar para la atención multi-cabeza.

joint_attention_dim (`int`, por defecto `4096`) : La dimensión de embedding a utilizar para la atención conjunta de texto e imagen.

caption_projection_dim (`int`, por defecto `1152`) : La dimensión de los embeddings de las descripciones.

pooled_projection_dim (`int`, por defecto `2048`) : La dimensión de incrustación de las proyecciones de texto agrupadas.

out_channels (`int`, por defecto `16`) : El número de canales latentes en la salida.

pos_embed_max_size (`int`, por defecto `96`) : La altura/ancho máximo latente de las incorporaciones posicionales.

extra_conditioning_channels (`int`, por defecto `0`) : El número de canales adicionales para usar en la condicional para la incrustación de parches.

dual_attention_layers (`tuple[int, ...]`, por defecto `()`) : El número de bloques de transformador de doble flujo a utilizar.

qk_norm (`str`, *opcional*, valor predeterminado `None`) : La normalización que se utilizará para la consulta y la clave en la capa de atención. Si es `None`, no se utiliza ninguna normalización.

pos_embed_type (`str`, por defecto `"sincos"`) : El tipo de incrustación posicional a utilizar. Elija entre `"sincos"` y `None`.

use_pos_embed (`bool`, por defecto `True`) : Si se deben usar embeddings posicionales.

force_zeros_for_pooled_projection (`bool`, por defecto `True`) : Si se deben forzar ceros para las incrustaciones de proyección agrupada. Esto se gestiona en las tuberías leyendo el valor de configuración del 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)
```

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

**Parámetros:**

chunk_size (`int`, *opcional*) : El tamaño de bloque de las capas feed-forward. Si no se especifica, se ejecutará la capa feed-forward de forma individual sobre cada tensor con dim=`dim`.

dim (`int`, *opcional*, valor predeterminado `0`) : La dimensión sobre la cual se debe dividir en bloques el cálculo de la red feed-forward. Elija entre dim=0 (lote) o dim=1 (longitud de la secuencia).

Establece el procesador de atención 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)
```

[Fuente](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`) : El tensor de entrada condicional de forma `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, por defecto `1.0`) : El factor de escala para las salidas de ControlNet.

encoder_hidden_states (`torch.Tensor` de forma `(batch size, sequence_len, embed_dims)`) : Embeddings condicionales (embeddings calculados a partir de las condiciones de entrada, como los prompts) a utilizar.

pooled_projections (`torch.Tensor` de forma `(batch_size, projection_dim)`) : Embeddings proyectados a partir de los embeddings de las condiciones de entrada.

timestep ( `torch.LongTensor`) : Se utiliza para indicar el paso de desruido.

joint_attention_kwargs (`dict`, *opcional*) : Un diccionario de kwargs que, si se especifica, se pasa al `AttentionProcessor` tal como se define bajo `self.processor` en [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un `~models.transformer_2d.Transformer2DModelOutput` en lugar de una tupla simple.

**Devuelve:**

Si `return_dict` es True, se devuelve un `~models.transformer_2d.Transformer2DModelOutput`; en caso contrario, se devuelve una `tuple` cuyo primer elemento es el tensor de la muestra.

El método forward de [SD3Transformer2DModel](/docs/diffusers/v0.43.0/es/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel).

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

```python
fuse_qkv_projections()
```

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

Habilita las proyecciones QKV fusionadas. Para los módulos de autoatención, todas las matrices de proyección (es decir, consulta, clave y valor) se fusionan. Para los módulos de atención cruzada, las matrices de proyección de clave y valor se fusionan.

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

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

```python
unfuse_qkv_projections()
```

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

Desactiva la proyección QKV fusionada si está habilitada.

> [!WARNING] > Esta API es 🧪 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])
```

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