Hugging Face's logo

Diffusers documentation

ControlNet com Stable Diffusion 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNet com Stable Diffusion 3

LoRA

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

ControlNet foi introduzido em Adding Conditional Control to Text-to-Image Diffusion Models por Lvmin Zhang, Anyi Rao e Maneesh Agrawala.

Com um modelo ControlNet, você pode fornecer uma imagem de controle adicional para condicionar e controlar a geração do Stable Diffusion. Por exemplo, se você fornecer um mapa de profundidade, o modelo ControlNet gera uma imagem que preservará as informações espaciais do mapa de profundidade. É uma maneira mais flexível e precisa de controlar o processo de geração de imagens.

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 por “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.

Este código de controlnet foi implementado principalmente por The InstantX Team. O código relacionado a inpainting foi desenvolvido por The Alimama Creative Team. Você pode encontrar checkpoints pré-treinados para SD3-ControlNet na tabela abaixo:

Tipo de ControlNetDesenvolvedorLink
CannyA Equipe InstantXLink
ProfundidadeA Equipe InstantXLink
PoseA Equipe InstantXLink
TileA Equipe InstantXLink
InpaintingA Equipe AlimamaCreativelink

Certifique-se de consultar o guia de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção reutilização de componentes entre pipelines para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

StableDiffusion3ControlNetPipeline

classe diffusers.StableDiffusion3ControlNetPipeline

< >

( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizercontrolnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModelimage_encoder: transformers.models.siglip.modeling_siglip.SiglipVisionModel | None = Nonefeature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None )

Parâmetros

  • transformer (SD3Transformer2DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKL) — Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.
  • text_encoder (CLIPTextModelWithProjection) — CLIP, especificamente a variante clip-vit-large-patch14, com uma camada de projeção adicional que é inicializada com uma matriz diagonal com hidden_size como sua dimensão.
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP, especificamente a variante laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.
  • text_encoder_3 (T5EncoderModel) — Codificador de texto congelado. O Stable Diffusion 3 usa T5, especificamente a variante t5-v1_1-xxl.
  • tokenizer (CLIPTokenizer) — Tokenizer da classe CLIPTokenizer.
  • tokenizer_2 (CLIPTokenizer) — Segundo Tokenizer da classe CLIPTokenizer.
  • tokenizer_3 (T5TokenizerFast) — Tokenizer da classe T5Tokenizer.
  • controlnet (SD3ControlNetModel ou list[SD3ControlNetModel] ou SD3MultiControlNetModel) — Fornece condicionamento adicional ao unet durante o processo de desruidamento. Se você definir múltiplos ControlNets como uma lista, as saídas de cada ControlNet são somadas para criar um único condicionamento adicional combinado.
  • image_encoder (SiglipVisionModel, opcional) — Modelo de Visão pré-treinado para IP Adapter.
  • feature_extractor (SiglipImageProcessor, opcional) — Processador de imagem para IP Adapter.

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneprompt_3: str | list[str] | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0control_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = Nonenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

Parâmetros

  • prompt (str ou list[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • prompt_2 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, prompt será usado no lugar
  • prompt_3 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, prompt será usado no lugar
  • height (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A altura em pixels da imagem gerada. Isso é definido como 1024 por padrão para os melhores resultados.
  • width (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A largura em pixels da imagem gerada. O padrão é 1024 para os melhores resultados.
  • num_inference_steps (int, opcional, padrão 50) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • sigmas (list[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento sigmas em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado.
  • guidance_scale (float, opcional, padrão 5.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance. guidance_scale é definido como w da equação 2 do Imagen Paper. A escala de orientação é ativada ao definir guidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao prompt de texto, geralmente em detrimento de uma menor qualidade de imagem.
  • control_guidance_start (float ou list[float], opcional, padrão 0.0) — A porcentagem dos passos totais em que o ControlNet começa a ser aplicado.
  • control_guidance_end (float ou list[float], opcional, padrão 1.0) — A porcentagem do total de etapas em que o ControlNet para de ser aplicado.
  • control_image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], list[np.ndarray], — list[list[torch.Tensor]], list[list[np.ndarray]] ou list[list[PIL.Image.Image]]): A condição de entrada do ControlNet para fornecer orientação ao unet na geração. Se o tipo for especificado como torch.Tensor, ele é passado ao ControlNet como está. PIL.Image.Image também pode ser aceito como imagem. As dimensões da imagem de saída são, por padrão, as dimensões de image. Se altura e/ou largura forem passadas, image será redimensionada de acordo. Se múltiplos ControlNets forem especificados em init, as imagens devem ser passadas como uma lista, de modo que cada elemento da lista possa ser corretamente agrupado para entrada em um único ControlNet.
  • controlnet_conditioning_scale (float ou list[float], opcional, padrão 1.0) — As saídas do ControlNet são multiplicadas por controlnet_conditioning_scale antes de serem adicionadas ao residual no unet original. Se múltiplos ControlNets forem especificados em init, você pode definir a escala correspondente como uma lista.
  • controlnet_pooled_projections (torch.FloatTensor de forma (batch_size, projection_dim)) — Embeddings projetados a partir dos embeddings das condições de entrada do controlnet.
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
  • negative_prompt_2 (str ou list[str], opcional) — O prompt ou os prompts que não devem guiar a geração da imagem a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, negative_prompt é usado no lugar
  • negative_prompt_3 (str ou list[str], opcional) — O prompt ou os prompts que não devem guiar a geração da imagem a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, negative_prompt é usado no lugar
  • num_images_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística.
  • latents (torch.FloatTensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o generator aleatório fornecido.
  • prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto agrupados pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não fornecidos, os embeddings de texto agrupados serão gerados a partir do argumento de entrada prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto negativo pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompt. Se não for fornecido, os pooled negative_prompt_embeds serão gerados a partir do argumento de entrada negative_prompt.
  • ip_adapter_image (PipelineImageInput, opcional) — Entrada de imagem opcional para trabalhar com IP Adapters.
  • ip_adapter_image_embeds (torch.Tensor, opcional) — Incorporações de imagem pré-geradas para IP-Adapter. Deve ser um tensor de forma (batch_size, num_images, emb_dim). Deve conter a incorporação de imagem negativa se do_classifier_free_guidance estiver definido como True. Se não for fornecido, as incorporações são calculadas a partir do argumento de entrada ip_adapter_image.
  • output_type (str, opcional, padrão "pil") — O formato de saída da imagem gerada. Escolha entre PIL: PIL.Image.Image ou np.array.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput em vez de uma tupla simples.
  • joint_attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, é passado ao AttentionProcessor conforme definido em self.processor em diffusers.models.attention_processor.
  • clip_skip (int, opcional) — Número de camadas a serem ignoradas do CLIP ao calcular os embeddings do prompt. Um valor de 1 significa que a saída da camada pré-final será usada para calcular os embeddings do prompt.
  • callback_on_step_end (Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.
  • max_sequence_length (int padrão 256) — Comprimento máximo da sequência a ser usado com o prompt.

Retorna

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput ou tuple

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput se return_dict for True, caso contrário, uma tuple. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:

>>> import torch
>>> from diffusers import StableDiffusion3ControlNetPipeline
>>> from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
>>> from diffusers.utils import load_image

>>> controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny", torch_dtype=torch.float16)

>>> pipe = StableDiffusion3ControlNetPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> control_image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png"
... )
>>> prompt = "A bird in space"
>>> image = pipe(
...     prompt, control_image=control_image, height=1024, width=768, controlnet_conditioning_scale=0.7
... ).images[0]
>>> image.save("sd3.png")

encode_image

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]device: device ) → torch.Tensor

Parâmetros

  • image (PipelineImageInput) — Imagem de entrada a ser codificada.
  • device — (torch.device): Dispositivo Torch.

Retorna

torch.Tensor

A representação de características da imagem codificada.

Codifica a imagem fornecida em uma representação de características usando um codificador de imagem pré-treinado.

encode_prompt

< >

( prompt: str | list[str]prompt_2: str | list[str]prompt_3: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneclip_skip: int | None = Nonemax_sequence_length: int = 256lora_scale: float | None = None )

Parâmetros

  • prompt (str ou list[str], opcional) — prompt a ser codificado
  • prompt_2 (str ou list[str], opcional) — O prompt ou prompts a serem enviados para o tokenizer_2 e o text_encoder_2. Se não definido, prompt é usado em todos os text-encoders
  • prompt_3 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para o tokenizer_3 e o text_encoder_3. Se não definido, prompt é usado em todos os text-encoders
  • device — (torch.device): dispositivo torch
  • num_images_per_prompt (int) — número de imagens que devem ser geradas por prompt
  • do_classifier_free_guidance (bool) — se deve usar classifier free guidance ou não
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
  • negative_prompt_2 (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, negative_prompt é usado em todos os text-encoders.
  • negative_prompt_3 (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, negative_prompt é usado em todos os text-encoders.
  • prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto agrupados pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não fornecidos, os embeddings de texto agrupados serão gerados a partir do argumento de entrada prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto negativo pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompt. Se não for fornecido, os pooled negative_prompt_embeds serão gerados a partir do argumento de entrada negative_prompt.
  • clip_skip (int, opcional) — Número de camadas a serem ignoradas do CLIP ao calcular os embeddings do prompt. Um valor de 1 significa que a saída da camada pré-final será usada para calcular os embeddings do prompt.
  • lora_scale (float, opcional) — Uma escala LoRA que será aplicada a todas as camadas LoRA do codificador de texto, caso as camadas LoRA sejam carregadas.

prepare_ip_adapter_image_embeds

< >

( ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = True )

Parâmetros

  • ip_adapter_image (PipelineImageInput, opcional) — A imagem de entrada para extrair os recursos para o IP-Adapter.
  • ip_adapter_image_embeds (torch.Tensor, opcional) — Incorporações de imagem pré-computadas.
  • device — (torch.device, opcional): Dispositivo Torch.
  • num_images_per_prompt (int, padrão 1) — Número de imagens que devem ser geradas por prompt.
  • do_classifier_free_guidance (bool, padrão True) — Se deve ou não usar classifier free guidance.

Prepara embeddings de imagem para uso no IP-Adapter.

É necessário passar ip_adapter_image ou ip_adapter_image_embeds.

StableDiffusion3ControlNetInpaintingPipeline

classe diffusers.StableDiffusion3ControlNetInpaintingPipeline

< >

( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizercontrolnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModelimage_encoder: SiglipModel = Nonefeature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None )

Parâmetros

  • transformer (SD3Transformer2DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKL) — Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.
  • text_encoder (CLIPTextModelWithProjection) — CLIP, especificamente a variante clip-vit-large-patch14, com uma camada de projeção adicional que é inicializada com uma matriz diagonal com hidden_size como sua dimensão.
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP, especificamente a variante laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.
  • text_encoder_3 (T5EncoderModel) — Codificador de texto congelado. O Stable Diffusion 3 usa T5, especificamente a variante t5-v1_1-xxl.
  • tokenizer (CLIPTokenizer) — Tokenizer da classe CLIPTokenizer.
  • tokenizer_2 (CLIPTokenizer) — Segundo Tokenizer da classe CLIPTokenizer.
  • tokenizer_3 (T5TokenizerFast) — Tokenizer da classe T5Tokenizer.
  • controlnet (SD3ControlNetModel ou list[SD3ControlNetModel] ou SD3MultiControlNetModel) — Fornece condicionamento adicional ao transformer durante o processo de remoção de ruído. Se você definir múltiplos ControlNets como uma lista, as saídas de cada ControlNet são somadas para criar um único condicionamento adicional combinado.
  • image_encoder (PreTrainedModel, opcional) — Modelo de Visão pré-treinado para IP Adapter.
  • feature_extractor (BaseImageProcessor, opcional) — Processador de imagem para IP Adapter.

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneprompt_3: str | list[str] | None = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0control_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_mask: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = Nonenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

Parâmetros

  • prompt (str ou list[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • prompt_2 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, prompt será usado no lugar
  • prompt_3 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, prompt será usado no lugar
  • height (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A altura em pixels da imagem gerada. Isso é definido como 1024 por padrão para os melhores resultados.
  • width (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A largura em pixels da imagem gerada. O padrão é 1024 para os melhores resultados.
  • num_inference_steps (int, opcional, padrão 50) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • sigmas (list[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento sigmas em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado.
  • guidance_scale (float, opcional, padrão 5.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance. guidance_scale é definido como w da equação 2 do Imagen Paper. A escala de orientação é ativada ao definir guidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao prompt de texto, geralmente em detrimento de uma menor qualidade de imagem.
  • control_guidance_start (float ou list[float], opcional, padrão 0.0) — A porcentagem dos passos totais em que o ControlNet começa a ser aplicado.
  • control_guidance_end (float ou list[float], opcional, padrão 1.0) — A porcentagem do total de etapas em que o ControlNet para de ser aplicado.
  • control_image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], list[np.ndarray]) — Image, array numpy ou tensor representando um lote de imagens a serem inpaintadas (quais partes da imagem devem ser mascaradas com control_mask e repintadas de acordo com prompt). Para arrays numpy e tensors pytorch, o intervalo de valores esperado é entre [0, 1] Se for um tensor ou uma lista de tensors, a forma esperada deve ser (B, C, H, W). Se for um array numpy ou uma lista de arrays, a forma esperada deve ser (B, H, W, C) ou (H, W, C).
  • control_mask (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], list[np.ndarray]) — Image, array numpy ou tensor representando um lote de imagens para mascarar image. Os pixels brancos na máscara são repintados, enquanto os pixels pretos são preservados. Se mask_image for uma imagem PIL, ela é convertida para um canal único (luminância) antes do uso. Se for um array numpy ou tensor pytorch, deve conter um único canal de cor (L) em vez de 3, de modo que a forma esperada para um tensor pytorch seria (B, 1, H, W). E para um array numpy seria (B, H, W, 1), (B, H, W), (H, W, 1) ou (H, W).
  • controlnet_conditioning_scale (float ou list[float], opcional, padrão 1.0) — As saídas do ControlNet são multiplicadas por controlnet_conditioning_scale antes de serem adicionadas ao residual no unet original. Se múltiplos ControlNets forem especificados em init, você pode definir a escala correspondente como uma lista.
  • controlnet_pooled_projections (torch.FloatTensor de forma (batch_size, projection_dim)) — Embeddings projetados a partir dos embeddings das condições de entrada do controlnet.
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
  • negative_prompt_2 (str ou list[str], opcional) — O prompt ou os prompts que não devem guiar a geração da imagem a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, negative_prompt é usado no lugar
  • negative_prompt_3 (str ou list[str], opcional) — O prompt ou os prompts que não devem guiar a geração da imagem a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, negative_prompt é usado no lugar
  • num_images_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística.
  • latents (torch.FloatTensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o generator aleatório fornecido.
  • prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto agrupados pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não fornecidos, os embeddings de texto agrupados serão gerados a partir do argumento de entrada prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto negativo pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompt. Se não for fornecido, os pooled negative_prompt_embeds serão gerados a partir do argumento de entrada negative_prompt.
  • ip_adapter_image (PipelineImageInput, opcional) — Entrada de imagem opcional para trabalhar com IP Adapters.
  • ip_adapter_image_embeds (torch.Tensor, opcional) — Incorporações de imagem pré-geradas para IP-Adapter. Deve ser um tensor de forma (batch_size, num_images, emb_dim). Deve conter a incorporação de imagem negativa se do_classifier_free_guidance estiver definido como True. Se não for fornecido, as incorporações são calculadas a partir do argumento de entrada ip_adapter_image.
  • output_type (str, opcional, padrão "pil") — O formato de saída da imagem gerada. Escolha entre PIL: PIL.Image.Image ou np.array.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput em vez de uma tupla simples.
  • joint_attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, é passado ao AttentionProcessor conforme definido em self.processor em diffusers.models.attention_processor.
  • clip_skip (int, opcional) — Número de camadas a serem ignoradas do CLIP ao calcular os embeddings do prompt. Um valor de 1 significa que a saída da camada pré-final será usada para calcular os embeddings do prompt.
  • callback_on_step_end (Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.
  • max_sequence_length (int padrão 256) — Comprimento máximo da sequência a ser usado com o prompt.

Retorna

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput ou tuple

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput se return_dict for True, caso contrário, uma tuple. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:

>>> import torch
>>> from diffusers.utils import load_image, check_min_version
>>> from diffusers.pipelines import StableDiffusion3ControlNetInpaintingPipeline
>>> from diffusers.models.controlnet_sd3 import SD3ControlNetModel

>>> controlnet = SD3ControlNetModel.from_pretrained(
...     "alimama-creative/SD3-Controlnet-Inpainting", use_safetensors=True, extra_conditioning_channels=1
... )
>>> pipe = StableDiffusion3ControlNetInpaintingPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers",
...     controlnet=controlnet,
...     torch_dtype=torch.float16,
... )
>>> pipe.text_encoder.to(torch.float16)
>>> pipe.controlnet.to(torch.float16)
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog.png"
... )
>>> mask = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog_mask.png"
... )
>>> width = 1024
>>> height = 1024
>>> prompt = "A cat is sitting next to a puppy."
>>> generator = torch.Generator(device="cuda").manual_seed(24)
>>> res_image = pipe(
...     negative_prompt="deformed, distorted, disfigured, poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, mutated hands and fingers, disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation, NSFW",
...     prompt=prompt,
...     height=height,
...     width=width,
...     control_image=image,
...     control_mask=mask,
...     num_inference_steps=28,
...     generator=generator,
...     controlnet_conditioning_scale=0.95,
...     guidance_scale=7,
... ).images[0]
>>> res_image.save(f"sd3.png")

encode_image

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]device: device ) → torch.Tensor

Parâmetros

  • image (PipelineImageInput) — Imagem de entrada a ser codificada.
  • device — (torch.device): Dispositivo Torch.

Retorna

torch.Tensor

A representação de características da imagem codificada.

Codifica a imagem fornecida em uma representação de características usando um codificador de imagem pré-treinado.

encode_prompt

< >

( prompt: str | list[str]prompt_2: str | list[str]prompt_3: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneclip_skip: int | None = Nonemax_sequence_length: int = 256lora_scale: float | None = None )

Parâmetros

  • prompt (str ou list[str], opcional) — prompt a ser codificado
  • prompt_2 (str ou list[str], opcional) — O prompt ou prompts a serem enviados para o tokenizer_2 e o text_encoder_2. Se não definido, prompt é usado em todos os text-encoders
  • prompt_3 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para o tokenizer_3 e o text_encoder_3. Se não definido, prompt é usado em todos os text-encoders
  • device — (torch.device): dispositivo torch
  • num_images_per_prompt (int) — número de imagens que devem ser geradas por prompt
  • do_classifier_free_guidance (bool) — se deve usar classifier free guidance ou não
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
  • negative_prompt_2 (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, negative_prompt é usado em todos os text-encoders.
  • negative_prompt_3 (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem a serem enviados para tokenizer_3 e text_encoder_3. Se não definido, negative_prompt é usado em todos os text-encoders.
  • prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto agrupados pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não fornecidos, os embeddings de texto agrupados serão gerados a partir do argumento de entrada prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto negativo pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompt. Se não for fornecido, os pooled negative_prompt_embeds serão gerados a partir do argumento de entrada negative_prompt.
  • clip_skip (int, opcional) — Número de camadas a serem ignoradas do CLIP ao calcular os embeddings do prompt. Um valor de 1 significa que a saída da camada pré-final será usada para calcular os embeddings do prompt.
  • lora_scale (float, opcional) — Uma escala LoRA que será aplicada a todas as camadas LoRA do codificador de texto, caso as camadas LoRA sejam carregadas.

prepare_ip_adapter_image_embeds

< >

( ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = True )

Parâmetros

  • ip_adapter_image (PipelineImageInput, opcional) — A imagem de entrada para extrair os recursos para o IP-Adapter.
  • ip_adapter_image_embeds (torch.Tensor, opcional) — Incorporações de imagem pré-computadas.
  • device — (torch.device, opcional): Dispositivo Torch.
  • num_images_per_prompt (int, padrão 1) — Número de imagens que devem ser geradas por prompt.
  • do_classifier_free_guidance (bool, padrão True) — Se deve ou não usar classifier free guidance.

Prepara embeddings de imagem para uso no IP-Adapter.

É necessário passar ip_adapter_image ou ip_adapter_image_embeds.

StableDiffusion3PipelineOutput

classe diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

Parâmetros

  • images (list[PIL.Image.Image] ou np.ndarray) — lista de imagens PIL desruidas de comprimento batch_size ou array numpy de forma (batch_size, height, width, num_channels). As imagens PIL ou o array numpy apresentam as imagens desruidas do pipeline de difusão.

Classe de saída para pipelines do Stable Diffusion.

Update on GitHub

←ControlNet com Hunyuan-DiT ControlNet com Stable Diffusion XL→