diffusers/v0.43.0/pt/api/models/controlnet_sd3.md

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 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 deve ser carregado com from_pretrained().

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]]

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

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.

enable_forward_chunking[[diffusers.SD3ControlNetModel.enable_forward_chunking]]

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

Fonte

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.

forward[[diffusers.SD3ControlNetModel.forward]]

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

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.

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.

fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

fuse_qkv_projections()

Fonte

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.

> Esta API é 🧪 experimental.

unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

Fonte

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

> Esta API é 🧪 experimental.

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

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

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

Fonte