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 encode le prompt et les images de condition avec un modèle Qwen3-VL, puis débruite l'image cible avec un transformer mono-flux à causalité par blocs. Consultez QwenImage21Transformer2DModel pour l'attention à causalité par blocs, les processeurs d'attention et causal_condition.

Les valeurs par défaut sont celles recommandées par Qwen : 40 étapes et aucun guidage. Passez un negative_prompt avec true_cfg_scale > 1 pour activer le guidage sans classifieur, ce qui double le travail par étape.

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

Images de conditions multiples

Passez une liste à image et chaque entrée devient son propre bloc dans la séquence jointe : l’encodeur Qwen3-VL les perçoit comme un contexte visuel et le VAE contribue par ses jetons latents. L’attention causale par blocs maintient chaque bloc bidirectionnel en interne tout en permettant aux blocs suivants et à l’image cible de se référer aux blocs antérieurs, de sorte que l’ordre dans lequel vous les passez est l’ordre dans lequel le modèle les lit.

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

Attention plus rapide avec flex_attention

Le QwenImage21AttnProcessor par défaut exécute le préremplissage causal par blocs en effectuant un appel d’attention par segment de préfixe. Il ne nécessite aucune compilation et fonctionne sur toute version de PyTorch. QwenImage21FlexAttnProcessor exprime le même masque sous la forme d’un unique appel flex_attention, ce qui est plus rapide une fois le modèle compilé.

Compilez le modèle lors du passage au processeur flex. Un flex_attention non compilé matérialise la matrice complète des scores d'attention en fp32, ce qui est beaucoup plus lent et épuise la mémoire à haute résolution.

from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor

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

Chargement de points de contrôle en fichier unique

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 d'échantillonnage

Les auteurs de modèles peuvent configurer une grille d'échantillonnage par défaut avec sample_sigmas dans la configuration du pipeline. Lors du chargement d'un point de contrôle publié, sa grille par défaut et ses paramètres de planificateur sont restaurés automatiquement.

Pour expérimenter avec une grille différente à l'exécution, passez sigmas à l'appel du 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]

La grille personnalisée ci-dessus illustre l’API ; la qualité de la génération dépend du point de contrôle et de la grille. Les listes de sigma excluent le sigma terminal, que le planificateur ajoute. Des sigmas explicites remplacent les sample_sigmas configurés, et l’une ou l’autre liste détermine le nombre d’étapes au lieu de num_inference_steps. Si aucune n’est fournie, le pipeline utilise num_inference_steps pour générer le plan. Le planificateur applique son traitement configuré à l’une ou l’autre grille.

Modulaire

Qwen-Image 2.1 est également disponible en tant que pipeline modulaire. Les mêmes blocs exécutent la génération texte-vers-image et la génération conditionnée par image : passez image pour conditionner sur une ou plusieurs images. Le guidage sans classifieur est configuré via le composant guider plutôt que par un argument d'appel true_cfg_scale, et le cache KV préfixe est activé par défaut (use_kv_cache=False le désactive).

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]

Le checkpoint Turbo correspond à ses propres blocs (QwenImage21TurboAutoBlocks) : il s’exécute sans guider, n’accepte pas de negative_prompt et échantillonne la grille de sigma fournie avec le checkpoint. ModularPipeline.from_pretrained sélectionne les blocs Turbo à partir de l’entrée sample_sigmas de la configuration du checkpoint, il n’est donc nécessaire de configurer quoi que ce soit :

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 )

Paramètres

  • scheduler (FlowMatchEulerDiscreteScheduler) — Planificateur utilisé pour débruyer les latents de l'image encodée.
  • vae (AutoencoderKLQwenImage21) — Auto-encodeur variationnel qui mappe les images vers et depuis l'espace latent à 64 canaux.
  • text_encoder (Qwen3VLForConditionalGeneration) — Modèle Qwen3-VL produisant les embeddings conjoints texte/image.
  • processor (Qwen3VLProcessor) — Processeur qui construit le modèle de discussion et tokenise le prompt et les images de condition.
  • transformer (QwenImage21Transformer2DModel) — Le transformer causal par blocs à flux unique qui débruite les latents.
  • sample_sigmas (list[float], facultatif) — Sigmas d'échantillonnage par défaut configurées par l'auteur du modèle, à l'exclusion de la sigma terminale. Leur longueur détermine le nombre d'étapes de débruitage. Pour expérimenter avec une grille différente à l'exécution, passez sigmas à __call__.

Génération de texte en image et génération conditionnée par image avec Qwen-Image 2.1.

Les images de prompt et de condition sont encodées ensemble par un modèle Qwen3-VL, de sorte qu'une image de condition occupe les emplacements visuels que l'encodeur lui a réservés et que le transformateur perçoit une seule séquence texte/image entrelacée.

__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

Paramètres

  • prompt (str ou list[str], facultatif) — Le prompt pour guider la génération d’image. Passez prompt_embeds à la place pour fournir directement des embeddings.
  • image (PipelineImageInput, facultatif) — Une ou plusieurs images de conditionnement, sous forme d’image PIL ou de tableau numpy. Elles sont encodées par l’encodeur de texte comme contexte visuel et par le VAE en jetons latents préfixés au bruit. Une liste représente un ensemble d’images partagé par tous les prompts du lot, et non une entrée par prompt.
  • negative_prompt (str ou list[str], facultatif) — Le prompt à ne pas utiliser pour guider la génération d’image. Ignoré lorsque true_cfg_scale n’est pas supérieur à 1.
  • true_cfg_scale (float, facultatif, valeur par défaut 1.0) — Échelle de guidage sans classifieur. Activée par true_cfg_scale > 1 en combinaison avec un prompt négatif. Qwen-Image 2.1 est conçu pour être échantillonné sans guidage, d’où la valeur par défaut de 1.0.
  • height (int, facultatif) — Hauteur en pixels de l’image générée. Si omise, elle est dérivée du ratio d’aspect de l’image de condition.
  • width (int, facultatif) — Largeur en pixels de l’image générée. Si omis, dérivé du ratio d’aspect de l’image de condition.
  • num_inference_steps (int, facultatif, valeur par défaut 40) — Nombre d’étapes de débruitage. Ignoré lorsque sigmas ou le sample_sigmas configuré du pipeline est utilisé ; la longueur de ce calendrier détermine le nombre d’étapes.
  • sigmas (list[float], facultatif) — Sigmas d’échantillonnage à essayer pour cet appel, à l’exclusion du sigma terminal. Remplace les sample_sigmas configurés du pipeline et détermine le nombre d’étapes de débruitage. Le planificateur applique son traitement configuré à ces valeurs.
  • num_images_per_prompt (int, facultatif, valeur par défaut 1) — Nombre d'images générées par invite.
  • generator (torch.Generator ou list[torch.Generator], facultatif) — Générateur(s) pour rendre la génération déterministe.
  • latents (torch.Tensor, facultatif) — Latents bruités pré-générés.
  • prompt_embeds (torch.Tensor, facultatif) — Embeddings de texte pré-générés, qui permettent de passer outre l’encodage du prompt. Transmettez prompt_embeds_mask avec eux.
  • prompt_embeds_mask (torch.Tensor, facultatif) — Masque booléen indiquant les positions valides de prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, facultatif) — Embeddings de texte négatifs pré-générés, utilisés à la place de negative_prompt. Passez negative_prompt_embeds_mask avec eux.
  • negative_prompt_embeds_mask (torch.Tensor, facultatif) — Masque booléen indiquant les positions valides de negative_prompt_embeds.
  • output_type (str, facultatif, par défaut "pil") — Format de sortie, "pil", "np", "pt" ou "latent".
  • return_dict (bool, facultatif, valeur par défaut True) — Indique s'il faut retourner un ~pipelines.qwenimage.QwenImagePipelineOutput plutôt qu'un simple tuple.
  • attention_kwargs (dict, facultatif) — Transmis au processeur d'attention.
  • callback_on_step_end (Callable, facultatif) — Appelé à la fin de chaque étape de débruitage.
  • callback_on_step_end_tensor_inputs (list[str], facultatif, par défaut ["latents"]) — Tenseurs de la boucle de débruitage à transmettre à callback_on_step_end. Ils doivent être listés dans _callback_tensor_inputs du pipeline.
  • output_resolution (int, facultatif, par défaut 1024) — Longueur du côté cible utilisée pour dériver height/width et pour redimensionner les images de conditionnement.
  • use_kv_cache (bool, facultatif, par défaut True) — Mettre en cache les clés et valeurs du texte et de l'image de condition après la première étape. Valide car causal_condition module ces jetons à partir de t = 0, rendant leurs activations indépendantes de l'étape. La modification de ce paramètre ne reproduit pas la même image bit pour bit en précision réduite. La mise en cache fait que l'étape de décodage porte attention avec une disposition de séquence différente de celle de l'étape de préremplissage, de sorte que les deux sont tuilés différemment et aboutissent à des arrondis différents ; les deux concordent avec une référence fp32 à la même tolérance. Une différence d'un ULP au premier bloc est ensuite amplifiée par 32 blocs et chaque étape de l'échantillonneur, de sorte que les deux configurations donnent des échantillons également valides mais visiblement distincts. Pour fixer un échantillon, fixez ce drapeau.

    Basculer ce paramètre ne reproduit pas l’image identique bit par bit en précision réduite. La mise en cache fait que l’étape de décodage utilise une disposition de séquence différente de celle de l’étape de préremplissage, si bien que les deux sont tuilées différemment et aboutissent à des arrondis distincts ; les deux concordent avec une référence fp32 à la même tolérance. Une différence d’un ULP au premier bloc est ensuite amplifiée par 32 blocs et chaque étape de l’échantillonneur, de sorte que les deux réglages produisent des échantillons tout aussi valides mais visiblement distincts. Pour obtenir un échantillon déterministe, il faut fixer ce drapeau.

Retourne

~pipelines.qwenimage.QwenImagePipelineOutput ou tuple

~pipelines.qwenimage.QwenImagePipelineOutput si return_dict est True, sinon un tuple dont le premier élément est une liste contenant les images générées.

Fonction appelée lors de l'appel du pipeline pour la génération.

Exemples :

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

Paramètres

  • prompt (str ou list[str], facultatif) — Prompt à encoder.
  • image (list[PipelineImageInput], facultatif) — Images de condition à encoder avec le prompt.
  • device (torch.device) — Appareil Torch.
  • num_images_per_prompt (int) — Nombre d'images générées par invite.
  • prompt_embeds (torch.Tensor, facultatif) — Embeddings de texte pré-générés. L’encodage est ignoré lorsqu’ils sont fournis.

QwenImagePipelineOutput

classe diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

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

Paramètres

  • images (list[PIL.Image.Image] ou np.ndarray) — liste d'images PIL débruitées de longueur batch_size ou tableau numpy de forme (batch_size, height, width, num_channels). Les images PIL ou le tableau numpy présentent les images débruitées du pipeline de diffusion.

Classe de sortie pour les pipelines 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 )

Un ModularPipeline pour Qwen-Image 2.1.

QwenImage21AutoBlocks

classe diffusers.QwenImage21AutoBlocks

< >

( )

Pipeline Auto modulaire pour la génération texte-vers-image et conditionnée par image à l'aide de Qwen-Image 2.1.

  • pour la génération d'images à partir de texte, il vous suffit de fournir prompt
  • pour la génération conditionnée par image, vous devez fournir prompt et image (une image ou une liste)

Workflows pris en charge :

  • text2image : nécessite prompt
  • image_conditioned : nécessite prompt, image

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

Entrées : image (Image | list, facultatif) : Image(s) de référence pour le débruitage. Peut s'agir d'une image unique ou d'une liste d'images. output_resolution (int, facultatif, par défaut 1024) : Longueur du côté cible utilisée pour dériver la taille de sortie et pour redimensionner les images de conditionnement. prompt (str) : Le prompt ou les prompts pour guider la génération d'image. negative_prompt (str, facultatif) : Le prompt ou les prompts à ne pas utiliser pour guider la génération d'image. generator (Generator, facultatif) : Générateur Torch pour une génération déterministe. num_images_per_prompt (int, facultatif, par défaut 1) : Le nombre d'images à générer par prompt. height (int, facultatif) : La hauteur en pixels de l'image générée. width (int, facultatif) : La largeur en pixels de l'image générée. image_latents (list, facultatif) : Latents normalisés de chaque image de conditionnement. Peut être généré à partir de l'étape vae_encoder. latents (Tensor) : Latents bruités pré-générés pour la génération d'image. num_inference_steps (int) : Le nombre d'étapes de débruitage. sigmas (list, facultatif) : Sigmas personnalisés pour le processus de débruitage. use_kv_cache (bool, facultatif, par défaut True) : Mettre en cache les clés et valeurs du texte et des images de conditionnement après la première étape. Valide car causal_condition module ces jetons à partir de t = 0, rendant leurs activations indépendantes de l'étape. La désactivation ne reproduit pas la même image bit à bit en précision réduite. attention_kwargs (dict, facultatif) : Kwargs supplémentaires pour les processeurs d'attention. *denoiser_input_fields (None,facultatif) : Entrées du modèle conditionnel pour le débruiteur : par exemple prompt_embeds, negative_prompt_embeds, etc. output_type (str,facultatif*, par défaut pil) : Format de sortie : ‘pil’, ‘np’, ‘pt’.

Sorties : images (list) : Images générées.

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 )

Un ModularPipeline pour Qwen-Image 2.1 Turbo, le point de contrôle accéléré qui échantillonne en quelques étapes sans guidage.

QwenImage21TurboAutoBlocks

classe diffusers.QwenImage21TurboAutoBlocks

< >

( )

Pipeline Auto modulaire pour la génération texte-vers-image et conditionnée par image à l'aide de Qwen-Image 2.1 Turbo, le point de contrôle accéléré qui échantillonne sa grille sigma intégrée en quelques étapes sans guidage.

  • pour la génération d'images à partir de texte, il vous suffit de fournir prompt
  • pour la génération conditionnée par image, vous devez fournir prompt et image (une image ou une liste)

Workflows pris en charge :

  • text2image : nécessite prompt
  • image_conditioned : nécessite prompt, image

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

Configurations : sample_sigmas (par défaut : None) : Grille d'échantillonnage fournie avec le point de contrôle, utilisée lorsque sigmas n'est pas transmis.

Entrées : image (Image | list, facultatif) : Image(s) de référence pour le débruitage. Peut s'agir d'une image unique ou d'une liste d'images. output_resolution (int, facultatif, par défaut 1024) : Longueur du côté cible utilisée pour dériver la taille de sortie et pour redimensionner les images de conditionnement. prompt (str) : Le prompt ou les prompts pour guider la génération d'images. generator (Generator, facultatif) : Générateur Torch pour une génération déterministe. num_images_per_prompt (int, facultatif, par défaut 1) : Le nombre d'images à générer par prompt. height (int, facultatif) : La hauteur en pixels de l'image générée. width (int, facultatif) : La largeur en pixels de l'image générée. image_latents (list, facultatif) : Latents normalisés de chaque image de conditionnement. Peut être généré à partir de l'étape vae_encoder. latents (Tensor) : Latents bruités pré-générés pour la génération d'images. num_inference_steps (int) : Le nombre d'étapes de débruitage. sigmas (list, facultatif) : Sigmas personnalisés pour le processus de débruitage. use_kv_cache (bool, facultatif, par défaut True) : Mettre en cache les clés et valeurs du texte et des images de conditionnement après la première étape. Valide car causal_condition module ces jetons à partir de t = 0, rendant leurs activations indépendantes de l'étape. La désactivation ne reproduit pas la même image bit par bit en précision réduite. attention_kwargs (dict, facultatif) : Arguments supplémentaires pour les processeurs d'attention. *denoiser_input_fields (None,facultatif) : Entrées du modèle conditionnel pour le débruiteur : par exemple prompt_embeds, negative_prompt_embeds, etc. output_type (str,facultatif*, par défaut pil) : Format de sortie : ‘pil’, ‘np’, ‘pt’.

Sorties : images (list) : Images générées.

Update on GitHub

←PRX Pixel QwenImage→