Hugging Face's logo

Diffusers documentation

Qwen-Image 2.1

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→