Hugging Face's logo

Diffusers documentation

Qwen-Image 2.1

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

and get access to the augmented documentation experience

to get started

Qwen-Image 2.1

Qwen-Image 2.1 codifica o prompt e quaisquer imagens de condição junto com um modelo Qwen3-VL e, em seguida, remove o ruído da imagem alvo com um transformer de bloco causal de fluxo único. Consulte QwenImage21Transformer2DModel para atenção de bloco causal, os processadores de atenção e causal_condition.

Os padrões são os valores recomendados pela Qwen: 40 passos e sem orientação. Passe um negative_prompt junto com true_cfg_scale > 1 para ativar a orientação sem classificador, o que dobra o trabalho por passo.

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16).to("cuda")

# Text-to-image
image = pipe("A capybara wearing a wizard hat, oil painting").images[0]
image.save("t2i.png")

# Image-conditioned editing
edited = pipe("Move it to a snowy mountain top", image=image).images[0]
edited.save("edit.png")

Várias imagens de condição

Passe uma lista para image e cada entrada se torna seu próprio bloco na sequência conjunta: o codificador do Qwen3-VL os enxerga como contexto visual e o VAE contribui com seus tokens latentes. A atenção causal por bloco mantém cada bloco internamente bidirecional, permitindo que blocos posteriores e a imagem de destino prestem atenção aos anteriores, de modo que a ordem em que você os passa é a ordem em que o modelo os lê.

edited = pipe("Put the flowers from the first image into the second scene", image=[flowers, scene]).images[0]

Atenção mais rápida com flex_attention

O QwenImage21AttnProcessor padrão executa o prefill causal por bloco como uma chamada de atenção por segmento de prefixo. Ele não requer compilação e funciona em qualquer build do PyTorch. O QwenImage21FlexAttnProcessor expressa a mesma máscara como uma única chamada de flex_attention, o que é mais rápido quando o modelo está compilado.

Compile o modelo ao alternar para o flex processor. Um flex_attention não compilado materializa a matriz completa de pontuações de atenção em fp32, o que é muito mais lento e esgota a memória em alta resolução.

from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor

pipe.transformer.set_attn_processor(QwenImage21FlexAttnProcessor())
pipe.transformer.compile()

Carregando checkpoints de arquivo único

import torch
from diffusers import QwenImage21Pipeline, QwenImage21Transformer2DModel

transformer = QwenImage21Transformer2DModel.from_single_file(
    "https://huggingface.co/Comfy-Org/Qwen-Image-2.1/blob/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
    dtype=torch.bfloat16,
)
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", transformer=transformer, dtype=torch.bfloat16).to(
    "cuda"
)

Sigmas de amostragem

Os autores de modelos podem configurar uma grade de amostragem padrão com sample_sigmas na configuração do pipeline. Ao carregar um checkpoint publicado, sua grade padrão e as configurações do agendador são restauradas automaticamente.

Para experimentar com uma grade diferente em tempo de execução, passe sigmas para a chamada do pipeline:

# Use the checkpoint's default sampling grid.
image = pipe(prompt).images[0]

# Override the default grid for this call.
image = pipe(prompt, sigmas=[1.0, 0.8, 0.5, 0.2]).images[0]

A grade personalizada acima ilustra a API; a qualidade da geração depende do checkpoint e da grade. As listas de sigma excluem o sigma terminal, que o scheduler adiciona. Valores explícitos de sigmas substituem o sample_sigmas configurado, e qualquer uma das listas determina o número de etapas em vez de num_inference_steps. Se nenhuma for fornecida, o pipeline usa num_inference_steps para gerar o agendamento. O scheduler aplica seu processamento configurado a qualquer uma das grades.

Modular

O Qwen-Image 2.1 também está disponível como um pipeline modular. Os mesmos blocos executam a geração de texto para imagem e a geração condicionada por imagem: passe image para condicionar em uma ou mais imagens. A orientação sem classificador é configurada por meio do componente guider em vez de um argumento de chamada true_cfg_scale, e o cache KV de prefixo está ativado por padrão (use_kv_cache=False desativa-o).

import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

# Turn classifier-free guidance on for an edit.
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=4.0))
edited = pipe(prompt="Move it to a snowy mountain top", negative_prompt="blurry", image=image).images[0]

O checkpoint Turbo mapeia para seus próprios blocos (QwenImage21TurboAutoBlocks): ele é executado sem um guider, não aceita negative_prompt e amostra a grade de sigmas que ele distribui. O ModularPipeline.from_pretrained seleciona os blocos Turbo a partir da entrada sample_sigmas na configuração do checkpoint, portanto, nada precisa ser configurado:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]

QwenImage21Pipeline

classe diffusers.QwenImage21Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImage21text_encoder: Qwen3VLForConditionalGenerationprocessor: Qwen3VLProcessortransformer: QwenImage21Transformer2DModelsample_sigmas: list[float] | None = None )

Parâmetros

  • scheduler (FlowMatchEulerDiscreteScheduler) — Agendador usado para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKLQwenImage21) — Autoencoder variacional que mapeia imagens para e a partir do espaço latente de 64 canais.
  • text_encoder (Qwen3VLForConditionalGeneration) — Modelo Qwen3-VL que produz os embeddings conjuntos de texto e imagem.
  • processor (Qwen3VLProcessor) — Processor que monta o template de chat e tokeniza o prompt e as imagens de condição.
  • transformer (QwenImage21Transformer2DModel) — O transformer de fluxo único e causal por bloco que realiza a descompactação dos latentes.
  • sample_sigmas (list[float], opcional) — Sigmas de amostragem padrão configuradas pelo autor do modelo, excluindo a sigma terminal. Seu comprimento determina o número de etapas de desruido. Para experimentar com uma grade diferente em tempo de execução, passe sigmas para __call__.

Geração de texto para imagem e geração condicionada por imagem com Qwen-Image 2.1.

As imagens de prompt e de condição são codificadas juntas por um modelo Qwen3-VL, de modo que uma imagem de condição ocupa os slots de visão que o codificador reservou para ela e o transformer vê uma única sequência intercalada de texto/imagens.

__call__

< >

( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']output_resolution: int = 1024use_kv_cache: bool = True ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

Parâmetros

  • prompt (str ou list[str], opcional) — O prompt para orientar a geração de imagens. Passe prompt_embeds em vez disso para fornecer embeddings diretamente.
  • image (PipelineImageInput, opcional) — Uma ou mais imagens de condição, como uma imagem PIL ou um array numpy. Elas são codificadas pelo codificador de texto como contexto visual e pelo VAE em tokens latentes que são adicionados antes do ruído. Uma lista representa um conjunto de imagens compartilhado por todos os prompts do lote, não uma entrada por prompt.
  • negative_prompt (str ou list[str], opcional) — O prompt que não deve orientar a geração da imagem. Ignorado quando true_cfg_scale não é maior que 1.
  • true_cfg_scale (float, opcional, padrão 1.0) — Escala de orientação sem classificador. Ativada por true_cfg_scale > 1 em conjunto com um prompt negativo. O Qwen-Image 2.1 foi projetado para ser amostrado sem orientação, por isso o padrão é 1.0.
  • height (int, opcional) — Altura em pixels da imagem gerada. Derivada da proporção da imagem de condição, se omitida.
  • width (int, opcional) — Largura em pixels da imagem gerada. Derivada da proporção da imagem de condição, se omitida.
  • num_inference_steps (int, opcional, padrão 40) — Número de etapas de desruidamento. Ignorado quando sigmas ou o sample_sigmas configurado do pipeline é usado; o comprimento dessa agenda determina o número de etapas.
  • sigmas (list[float], opcional) — Sigmas de amostragem a serem testadas nesta chamada, excluindo o sigma terminal. Substitui o sample_sigmas configurado no pipeline e determina o número de etapas de desruido. O agendador aplica seu processamento configurado a esses valores.
  • num_images_per_prompt (int, opcional, padrão 1) — Número de imagens geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Gerador(es) para tornar a geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas, que pulam a codificação do prompt. Passe prompt_embeds_mask junto com elas.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara bool que marca as posições válidas de prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incorporações de texto negativo pré-geradas, usadas no lugar de negative_prompt. Passe negative_prompt_embeds_mask junto com elas.
  • negative_prompt_embeds_mask (torch.Tensor, opcional) — Máscara bool que marca as posições válidas de negative_prompt_embeds.
  • output_type (str, opcional, padrão "pil") — Formato de saída, "pil", "np", "pt" ou "latent".
  • return_dict (bool, opcional, padrão True) — Se deve retornar um ~pipelines.qwenimage.QwenImagePipelineOutput em vez de uma tupla simples.
  • attention_kwargs (dict, opcional) — Passado para o processador de atenção.
  • callback_on_step_end (Callable, opcional) — Chamado no final de cada etapa de desruidamento.
  • callback_on_step_end_tensor_inputs (list[str], opcional, padrão ["latents"]) — Tensores do loop de desruidamento para passar ao callback_on_step_end. Eles devem estar listados em _callback_tensor_inputs do pipeline.
  • output_resolution (int, opcional, padrão 1024) — Comprimento do lado de destino usado para derivar height/width e para redimensionar as imagens de condição.
  • use_kv_cache (bool, opcional, padrão é True) — Cacheia as chaves e valores do texto e da imagem de condição após o primeiro passo. Válido porque causal_condition modula esses tokens a partir de t = 0, tornando suas ativações independentes do passo. Alterar essa opção não reproduz a mesma imagem bit a bit em precisão reduzida. O cache faz com que o passo de decodificação atenda a um layout de sequência diferente do passo de pré-preenchimento, de modo que os dois são divididos em blocos de forma diferente e resultam em arredondamentos distintos; ambos concordam com uma referência em fp32 dentro da mesma tolerância. Uma diferença de um ULP no primeiro bloco é então amplificada por 32 blocos e por cada passo do amostrador, de modo que as duas configurações produzem amostras igualmente válidas, mas visivelmente distintas. Para fixar uma amostra, fixe esta flag.

    Alternar essa opção não reproduz a mesma imagem bit a bit em precisão reduzida. O cache faz com que a etapa de decodificação atenda a uma sequência com um layout diferente do da etapa de pré-preenchimento, de modo que as duas são divididas em blocos de forma diferente e resultam em arredondamentos distintos; ambas concordam com uma referência em fp32 dentro da mesma tolerância. Uma diferença de um ULP no primeiro bloco é então amplificada pelos 32 blocos e por cada etapa do amostrador, de modo que as duas configurações produzem amostras igualmente válidas, porém visivelmente distintas. Para fixar uma amostra, fixe essa flag.

Retorna

~pipelines.qwenimage.QwenImagePipelineOutput ou tuple

~pipelines.qwenimage.QwenImagePipelineOutput se return_dict for True, caso contrário, uma tuple cujo primeiro elemento é uma lista com as imagens geradas.

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

Exemplos:

>>> import torch
>>> from diffusers import QwenImage21Pipeline

>>> pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A capybara wearing a wizard hat, reading a book by candlelight, oil painting"
>>> image = pipe(prompt).images[0]
>>> image.save("qwenimage21.png")

encode_prompt

< >

( prompt: str | list[str]image: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneimage_pad_mask: typing.Optional[torch.Tensor] = None )

Parâmetros

  • prompt (str ou list[str], opcional) — Prompt a ser codificado.
  • image (list[PipelineImageInput], opcional) — Imagens de condição para codificar junto com o prompt.
  • device (torch.device) — Dispositivo Torch.
  • num_images_per_prompt (int) — Número de imagens geradas por prompt.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Pula a codificação quando fornecidas.

QwenImagePipelineOutput

classe diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

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

QwenImage21ModularPipeline

classe diffusers.QwenImage21ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Uma ModularPipeline para Qwen-Image 2.1.

QwenImage21AutoBlocks

classe diffusers.QwenImage21AutoBlocks

< >

( )

Pipeline modular automático para geração de texto para imagem e geração condicionada por imagem usando Qwen-Image 2.1.

  • para a geração de texto para imagem, tudo o que você precisa fornecer é prompt
  • para geração condicionada por imagem, você precisa fornecer prompt e image (uma imagem ou uma lista)

Fluxos de trabalho suportados:

  • text2image: requer prompt
  • image_conditioned: requer prompt, image

Componentes: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) guider (ClassifierFreeGuidance) transformer (QwenImage21Transformer2DModel)

Entradas: image (Image | list, opcional): Imagem(ns) de referência para o desruido. Pode ser uma única imagem ou uma lista de imagens. output_resolution (int, opcional, padrão 1024): Comprimento do lado alvo usado para derivar o tamanho de saída e para redimensionar as imagens de condição. prompt (str): O prompt ou os prompts para orientar a geração de imagem. negative_prompt (str, opcional): O prompt ou os prompts que não devem orientar a geração de imagem. generator (Generator, opcional): Gerador do Torch para geração determinística. num_images_per_prompt (int, opcional, padrão 1): O número de imagens a serem geradas por prompt. height (int, opcional): A altura em pixels da imagem gerada. width (int, opcional): A largura em pixels da imagem gerada. image_latents (list, opcional): Latentes normalizados de cada imagem de condição. Podem ser gerados a partir da etapa vae_encoder. latents (Tensor): Latentes ruidosos pré-gerados para a geração de imagem. num_inference_steps (int): O número de etapas de desruido. sigmas (list, opcional): Sigmas personalizados para o processo de desruido. use_kv_cache (bool, opcional, padrão True): Armazena em cache as chaves e valores do texto e da imagem de condição após a primeira etapa. Válido porque causal_condition modula esses tokens a partir de t = 0, tornando suas ativações independentes da etapa. Alterar essa opção não reproduz a mesma imagem bit a bit em precisão reduzida. attention_kwargs (dict, opcional): Kwargs adicionais para os processadores de atenção. *denoiser_input_fields (None,opcional): entradas do modelo condicional para o desruidador: por exemplo, prompt_embeds, negative_prompt_embeds, etc. output_type (str,opcional*, padrão pil): Formato de saída: ‘pil’, ‘np’, ‘pt’.

Saídas: imagens (list): Imagens geradas.

QwenImage21TurboModularPipeline

classe diffusers.QwenImage21TurboModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Uma ModularPipeline para o Qwen-Image 2.1 Turbo, o checkpoint acelerado que amostra em poucas etapas sem orientação.

QwenImage21TurboAutoBlocks

classe diffusers.QwenImage21TurboAutoBlocks

< >

( )

Pipeline modular automático para geração de texto para imagem e geração condicionada por imagem usando Qwen-Image 2.1 Turbo, o checkpoint acelerado que amostra sua grade de sigma incluída em poucas etapas sem orientação.

  • para a geração de texto para imagem, tudo o que você precisa fornecer é prompt
  • para geração condicionada por imagem, você precisa fornecer prompt e image (uma imagem ou uma lista)

Fluxos de trabalho suportados:

  • text2image: requer prompt
  • image_conditioned: requer prompt, image

Componentes: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor (Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) transformer (QwenImage21Transformer2DModel)

Configs: sample_sigmas (padrão: None): Grade de amostragem que acompanha o checkpoint, usada quando sigmas não é passado.

Entradas: image (Image | list, opcional): Imagem(ns) de referência para o desruido. Pode ser uma única imagem ou uma lista de imagens. output_resolution (int, opcional, padrão 1024): Comprimento do lado alvo usado para derivar o tamanho de saída e para redimensionar as imagens de condição. prompt (str): O prompt ou os prompts para orientar a geração de imagens. generator (Generator, opcional): Gerador do Torch para geração determinística. num_images_per_prompt (int, opcional, padrão 1): O número de imagens a serem geradas por prompt. height (int, opcional): A altura em pixels da imagem gerada. width (int, opcional): A largura em pixels da imagem gerada. image_latents (list, opcional): Latentes normalizados de cada imagem de condição. Podem ser gerados a partir da etapa vae_encoder. latents (Tensor): Latentes ruidosos pré-gerados para a geração de imagens. num_inference_steps (int): O número de etapas de desruido. sigmas (list, opcional): Sigmas personalizados para o processo de desruido. use_kv_cache (bool, opcional, padrão True): Armazena em cache as chaves e valores do texto e da imagem de condição após a primeira etapa. Válido porque causal_condition modula esses tokens a partir de t = 0, tornando suas ativações independentes da etapa. Alternar essa opção não reproduz a mesma imagem bit a bit em precisão reduzida. attention_kwargs (dict, opcional): Kwargs adicionais para os processadores de atenção. *denoiser_input_fields (None,opcional): entradas do modelo condicional para o desruidador: por exemplo, prompt_embeds, negative_prompt_embeds, etc. output_type (str,opcional*, padrão pil): Formato de saída: ‘pil’, ‘np’, ‘pt’.

Saídas: imagens (list): Imagens geradas.

Update on GitHub

←PRX Pixel QwenImage→