diffusers/main/pt/api/pipelines/controlnet_sana.md

ControlNet

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

Este pipeline foi contribuído por ishan24. ❤️ A base de código original pode ser encontrada em NVlabs/Sana, e você pode encontrar checkpoints oficiais do ControlNet no perfil do Hub de Efficient-Large-Model.

SanaControlNetPipeline[[diffusers.SanaControlNetPipeline]]

diffusers.SanaControlNetPipeline[[diffusers.SanaControlNetPipeline]]

diffusers.SanaControlNetPipeline(tokenizer: GemmaTokenizer, text_encoder: Gemma2PreTrainedModel, vae: AutoencoderDC, transformer: SanaTransformer2DModel, controlnet: SanaControlNetModel, scheduler: DPMSolverMultistepScheduler)

Fonte

Pipeline para geração de texto para imagem usando Sana.

call[[diffusers.SanaControlNetPipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 20, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 4.5, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, controlnet_conditioning_scale: float | list[float] = 1.0, num_images_per_prompt: int | None = 1, height: int = 1024, width: int = 1024, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, clean_caption: bool = False, use_resolution_binning: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 300, complex_human_instruction: list[str] = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for image generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, and spatial relationships to create vivid and concrete scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat curled up in a round shape, sleeping peacefully on a warm sunny windowsill, surrounded by pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps, a diverse crowd of people in colorful clothing, and a double-decker bus passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: '])

Fonte

Parâmetros:

prompt (str ou list[str], opcional) : O prompt ou os prompts para orientar a geração da imagem. Se não definido, é necessário passar prompt_embeds em vez disso.

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 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).

num_inference_steps (int, opcional, padrão 20) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em uma imagem de maior qualidade, às custas de uma inferência mais lenta.

timesteps (list[int], opcional) : Passos de tempo personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumento timesteps em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado. Deve estar em ordem decrescente.

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 4.5) : 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_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 para a 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 uma imagem. As dimensões da imagem de saída padrão sã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 (batched) 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.

num_images_per_prompt (int, opcional, padrão 1) : O número de imagens a serem geradas por prompt.

height (int, opcional, padrão é self.unet.config.sample_size) : A altura em pixels da imagem gerada.

width (int, opcional, padrão é self.unet.config.sample_size) : A largura em pixels da imagem gerada.

eta (float, opcional, padrão 0.0) : Corresponde ao parâmetro eta (η) no paper DDIM: https://huggingface.co/papers/2010.02502. Aplica-se apenas a schedulers.DDIMScheduler, será ignorado para os demais.

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.Tensor, 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.Tensor, opcional) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada prompt.

prompt_attention_mask (torch.Tensor, opcional) : Máscara de atenção pré-gerada para embeddings de texto.

negative_prompt_embeds (torch.Tensor, opcional) : Embeddings de texto negativo pré-gerados. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.

negative_prompt_attention_mask (torch.Tensor, opcional) : Máscara de atenção pré-gerada para embeddings de texto negativo.

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.IFPipelineOutput em vez de uma tupla simples.

attention_kwargs : Um dicionário de kwargs que, se especificado, é passado para o AttentionProcessor definido em self.processor em diffusers.models.attention_processor.

clean_caption (bool, opcional, padrão True) : Se deve ou não limpar a legenda antes de criar os embeddings. Exige que beautifulsoup4 e ftfy estejam instalados. Se as dependências não estiverem instaladas, os embeddings serão criados a partir do prompt bruto.

use_resolution_binning (bool padrão é True) : Se definido como True, a altura e a largura solicitadas são primeiro mapeadas para as resoluções mais próximas usando ASPECT_RATIO_1024_BIN. Após os latentes produzidos serem decodificados em imagens, eles são redimensionados de volta para a resolução solicitada. Útil para gerar imagens não quadradas.

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 é 300) : Comprimento máximo da sequência a ser usado com o prompt.

complex_human_instruction (list[str], opcional) : Instruções para atenção humana complexa: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55.

Retorna: SanaPipelineOutput ou tuple

Se return_dict for True, SanaPipelineOutput é retornado; caso contrário, uma tuple é retornada, onde 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 SanaControlNetPipeline
>>> from diffusers.utils import load_image

>>> pipe = SanaControlNetPipeline.from_pretrained(
...     "ishan24/Sana_600M_1024px_ControlNetPlus_diffusers",
...     variant="fp16",
...     torch_dtype={"default": torch.bfloat16, "controlnet": torch.float16, "transformer": torch.float16},
...     device_map="balanced",
... )
>>> cond_image = load_image(
...     "https://huggingface.co/ishan24/Sana_600M_1024px_ControlNet_diffusers/resolve/main/hed_example.png"
... )
>>> prompt = 'a cat with a neon sign that says "Sana"'
>>> image = pipe(
...     prompt,
...     control_image=cond_image,
... ).images[0]
>>> image.save("output.png")

encode_prompt[[diffusers.SanaControlNetPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, clean_caption: bool = False, max_sequence_length: int = 300, complex_human_instruction: list[str] | None = None, lora_scale: float | None = None)

Fonte

Parâmetros:

prompt (str ou list[str], opcional) : prompt a ser codificado

negative_prompt (str ou list[str], opcional) : O prompt para não orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds no lugar. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1). Para o PixArt-Alpha, isso deve ser "".

do_classifier_free_guidance (bool, opcional, padrão True) : se deve ou não usar classifier free guidance

num_images_per_prompt (int, opcional, padrão 1) : número de imagens que devem ser geradas por prompt

device : (torch.device, opcional): dispositivo torch onde os embeddings resultantes serão colocados

prompt_embeds (torch.Tensor, opcional) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada prompt.

negative_prompt_embeds (torch.Tensor, opcional) : Embebidings de texto negativo pré-gerados. Para o Sana, deve ser os embebidings da string "".

clean_caption (bool, padrão False) : Se True, a função pré-processará e limpará a legenda fornecida antes da codificação.

max_sequence_length (int, padrão 300) : Comprimento máximo da sequência a ser usado para o prompt.

complex_human_instruction (list[str], padrão complex_human_instruction) : Se complex_human_instruction não estiver vazio, a função usará a instrução complexa do Humano para o prompt.

Codifica o prompt em estados ocultos do codificador de texto.

SanaPipelineOutput[[diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput]]

diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput[[diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput]]

diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)

Fonte

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 Sana.