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.42.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 mengodekan prompt dan gambar kondisi apa pun bersama dengan model Qwen3-VL, kemudian melakukan denoising pada gambar target dengan transformer block-causal single-stream. Lihat QwenImage21Transformer2DModel untuk perhatian block-causal, prosesor perhatian, dan causal_condition.

Nilai bawaan adalah nilai yang direkomendasikan oleh Qwen: 40 langkah dan tanpa panduan. Sertakan negative_prompt bersama dengan true_cfg_scale > 1 untuk mengaktifkan classifier-free guidance, yang menggandakan pekerjaan per langkah.

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

Gambar kondisi ganda

Lewatkan daftar ke image dan setiap entri menjadi blok tersendiri dalam urutan gabungan: encoder Qwen3-VL melihatnya sebagai konteks visual dan VAE menyumbang token laten mereka. Atensi blok-kausal menjaga setiap blok tetap bidireksional secara internal sambil memungkinkan blok-blok berikutnya dan gambar target untuk memperhatikan blok-blok sebelumnya, sehingga urutan yang Anda lewati adalah urutan yang dibaca model.

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

Perhatian lebih cepat dengan flex_attention

QwenImage21AttnProcessor default menjalankan prefill blok-kausal sebagai satu panggilan perhatian per segmen prefiks. Tidak memerlukan kompilasi dan berfungsi pada build PyTorch apa pun. QwenImage21FlexAttnProcessor mengekspresikan mask yang sama sebagai satu panggilan flex_attention, yang lebih cepat setelah model di-kompilasi.

Compile model saat Anda beralih ke flex processor. flex_attention yang tidak di-compile akan mematerialisasi matriks skor attention penuh dalam fp32, yang jauh lebih lambat dan kehabisan memori pada resolusi tinggi.

from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor

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

Memuat checkpoint file tunggal

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

Sigma sampling

Penulis model dapat mengonfigurasi grid sampling default dengan sample_sigmas dalam konfigurasi pipeline. Saat Anda memuat checkpoint yang dirilis, pengaturan grid dan scheduler defaultnya dipulihkan secara otomatis.

Untuk bereksperimen dengan grid yang berbeda saat runtime, berikan sigmas ke panggilan 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]

Grid kustom di atas mengilustrasikan API; kualitas generasi bergantung pada checkpoint dan grid. Daftar sigma mengecualikan sigma terminal, yang ditambahkan oleh scheduler. sigmas eksplisit menimpa sample_sigmas yang dikonfigurasi, dan salah satu daftar menentukan jumlah langkah alih-alih num_inference_steps. Jika keduanya tidak disediakan, pipeline menggunakan num_inference_steps untuk menghasilkan jadwal. Scheduler menerapkan pemrosesannya yang dikonfigurasi ke salah satu grid.

Modular

Qwen-Image 2.1 juga tersedia sebagai pipeline modular. Blok yang sama menjalankan generasi teks-ke-gambar dan generasi yang dikondisikan oleh gambar: berikan image untuk mengondisikan pada satu atau lebih gambar. Classifier-free guidance dikonfigurasi melalui komponen guider alih-alih argumen pemanggilan true_cfg_scale, dan cache KV prefix aktif secara default (use_kv_cache=False mematikannya).

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]

Checkpoint Turbo dipetakan ke blok-bloknya sendiri (QwenImage21TurboAutoBlocks): berjalan tanpa guider, tidak menerima negative_prompt, dan mengambil sampel dari grid sigma yang disertakan. ModularPipeline.from_pretrained memilih blok Turbo dari entri sample_sigmas dalam konfigurasi checkpoint, sehingga tidak ada yang perlu dikonfigurasi:

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

kelas diffusers.QwenImage21Pipeline

< >

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

Parameter

  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan untuk menghilangkan noise dari latens gambar yang telah dikodekan.
  • vae (AutoencoderKLQwenImage21) — Variational auto-encoder yang memetakan gambar ke dan dari ruang laten 64 kanal.
  • text_encoder (Qwen3VLForConditionalGeneration) — Model Qwen3-VL yang menghasilkan embedding teks/gambar gabungan.
  • processor (Qwen3VLProcessor) — Processor yang membangun template chat dan melakukan tokenisasi prompt serta gambar kondisi.
  • transformer (QwenImage21Transformer2DModel) — Transformer blok-kausal single-stream yang melakukan denoising pada latents.
  • sample_sigmas (list[float], opsional) — Sigma sampling default yang dikonfigurasi oleh pengembang model, tidak termasuk sigma terminal. Panjangnya menentukan jumlah langkah denoising. Untuk bereksperimen dengan grid yang berbeda saat runtime, berikan sigmas ke __call__.

Generasi teks-ke-gambar dan berbasis kondisi gambar dengan Qwen-Image 2.1.

Gambar prompt dan kondisi dikodekan bersama oleh model Qwen3-VL, sehingga gambar kondisi menempati slot visi yang dialokasikan encoder untuknya dan transformer melihat satu urutan teks/gambar yang berselang-seling.

__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 = ['latents']output_resolution: int = 1024use_kv_cache: bool = True ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple

Parameter

  • prompt (str atau list[str], opsional) — Prompt untuk memandu generasi gambar. Gunakan prompt_embeds sebagai gantinya untuk menyediakan embedding secara langsung.
  • image (PipelineImageInput, opsional) — Satu atau lebih gambar kondisi, berupa gambar PIL atau array numpy. Gambar-gambar ini dikodekan oleh text encoder sebagai konteks visual dan oleh VAE menjadi token laten yang ditambahkan di depan noise. Sebuah list adalah satu set gambar yang dibagikan oleh setiap prompt dalam batch, bukan satu entri per prompt.
  • negative_prompt (str atau list[str], opsional) — Prompt yang tidak digunakan untuk mengarahkan generasi gambar. Diabaikan ketika true_cfg_scale tidak lebih besar dari 1.
  • true_cfg_scale (float, opsional, default 1.0) — Skala panduan bebas klasifikator. Diaktifkan oleh true_cfg_scale > 1 bersamaan dengan prompt negatif. Qwen-Image 2.1 dimaksudkan untuk disampelkan tanpa panduan, sehingga default-nya 1.0.
  • height (int, opsional) — Tinggi gambar yang dihasilkan dalam piksel. Diturunkan dari rasio aspek gambar kondisi jika diabaikan.
  • width (int, opsional) — Lebar gambar yang dihasilkan dalam piksel. Diturunkan dari rasio aspek gambar kondisi jika diabaikan.
  • num_inference_steps (int, opsional, default 40) — Jumlah langkah denoising. Diabaikan ketika sigmas atau sample_sigmas yang dikonfigurasi pada pipeline digunakan; panjang jadwal tersebut menentukan jumlah langkah.
  • sigmas (list[float], opsional) — Sigmas sampling yang akan dicoba untuk panggilan ini, tidak termasuk sigma terminal. Menimpa sample_sigmas yang dikonfigurasi pada pipeline dan menentukan jumlah langkah denoising. Scheduler menerapkan pemrosesannya yang telah dikonfigurasi ke nilai-nilai ini.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Generator untuk membuat proses generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya, yang melewati proses encoding prompt. Sertakan prompt_embeds_mask bersamanya.
  • prompt_embeds_mask (torch.Tensor, opsional) — Mask bool yang menandai posisi valid dari prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya, digunakan sebagai pengganti negative_prompt. Sertakan negative_prompt_embeds_mask bersamanya.
  • negative_prompt_embeds_mask (torch.Tensor, opsional) — Mask bool yang menandai posisi valid dari negative_prompt_embeds.
  • output_type (str, opsional, default "pil") — Format output, "pil", "np", "pt" atau "latent".
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~pipelines.qwenimage.QwenImagePipelineOutput alih-alih tuple biasa.
  • attention_kwargs (dict, opsional) — Diteruskan ke pemroses perhatian.
  • callback_on_step_end (Callable, opsional) — Dipanggil di akhir setiap langkah denoising.
  • callback_on_step_end_tensor_inputs (list[str], opsional, default ["latents"]) — Tensor dari loop denoising yang akan diteruskan ke callback_on_step_end. Mereka harus terdaftar dalam _callback_tensor_inputs pipeline.
  • output_resolution (int, opsional, default 1024) — Panjang sisi target yang digunakan untuk menurunkan height/width dan untuk mengubah ukuran gambar kondisi.
  • use_kv_cache (bool, opsional, default ke True) — Cache kunci dan nilai teks serta gambar kondisi setelah langkah pertama. Valid karena causal_condition memodulasi token tersebut dari t = 0, membuat aktivasi mereka tidak bergantung pada langkah. Mengubah ini tidak mereproduksi gambar yang sama bit-per-bit dalam presisi yang dikurangi. Caching membuat langkah decode memperhatikan dengan tata letak urutan yang berbeda dari langkah prefill, sehingga keduanya di-tile dengan cara yang berbeda dan menghasilkan pembulatan yang berbeda; keduanya sesuai dengan referensi fp32 hingga toleransi yang sama. Perbedaan satu-ULP pada blok pertama kemudian diperkuat oleh 32 blok dan setiap langkah sampler, sehingga kedua pengaturan memberikan sampel yang sama validnya tetapi terlihat berbeda. Perbaiki sampel dengan memperbaiki flag ini.

    Mengubah flag ini tidak mereproduksi gambar yang sama secara bit-per-bit dalam presisi yang dikurangi. Caching membuat langkah decode memperhatikan dengan tata letak urutan yang berbeda dari langkah prefill, sehingga keduanya di-tile secara berbeda dan mendarat pada pembulatan yang berbeda; keduanya sesuai dengan referensi fp32 hingga toleransi yang sama. Perbedaan satu-ULP pada blok pertama kemudian diperkuat oleh 32 blok dan setiap langkah sampler, sehingga kedua pengaturan memberikan sampel yang sama-sama valid tetapi terlihat berbeda. Perbaiki sampel dengan memperbaiki flag ini.

Mengembalikan

~pipelines.qwenimage.QwenImagePipelineOutput atau tuple

~pipelines.qwenimage.QwenImagePipelineOutput jika return_dict bernilai True, selain itu berupa tuple yang elemen pertamanya adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

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

Parameter

  • prompt (str atau list[str], opsional) — Prompt yang akan dienkod.
  • image (list[PipelineImageInput], opsional) — Gambar kondisi untuk di-encode bersama prompt.
  • device (torch.device) — Perangkat Torch.
  • num_images_per_prompt (int) — Jumlah gambar yang dihasilkan per prompt.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Melompati proses encoding jika disediakan.

QwenImagePipelineOutput

kelas diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput

< >

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

Parameter

  • images (list[PIL.Image.Image] atau np.ndarray) — daftar gambar PIL yang telah didenoise dengan panjang batch_size atau array numpy dengan bentuk (batch_size, height, width, num_channels). Gambar PIL atau array numpy menyajikan gambar-gambar yang telah didenoise dari pipeline difusi.

Kelas output untuk pipeline Stable Diffusion.

QwenImage21ModularPipeline

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

ModularPipeline untuk Qwen-Image 2.1.

QwenImage21AutoBlocks

kelas diffusers.QwenImage21AutoBlocks

< >

( )

Pipeline modular otomatis untuk pembuatan teks-ke-gambar dan pembuatan yang dikondisikan oleh gambar menggunakan Qwen-Image 2.1.

  • untuk generasi teks-ke-gambar, yang perlu Anda berikan hanyalah prompt
  • untuk generasi yang dikondisikan oleh gambar, Anda perlu menyediakan prompt dan image (satu gambar atau daftar)

Alur kerja yang didukung:

  • text2image: membutuhkan prompt
  • image_conditioned: membutuhkan prompt, image

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

Inputs: image (Image | list, optional): Reference image(s) for denoising. Can be a single image or list of images. output_resolution (int, optional, defaults to 1024): Target side length used to derive the output size and to resize condition images. prompt (str): The prompt or prompts to guide image generation. negative_prompt (str, optional): The prompt or prompts not to guide the image generation. generator (Generator, optional): Torch generator for deterministic generation. num_images_per_prompt (int, optional, defaults to 1): The number of images to generate per prompt. height (int, optional): The height in pixels of the generated image. width (int, optional): The width in pixels of the generated image. image_latents (list, optional): Normalized latents of each condition image. Can be generated from vae_encoder step. latents (Tensor): Pre-generated noisy latents for image generation. num_inference_steps (int): The number of denoising steps. sigmas (list, optional): Custom sigmas for the denoising process. use_kv_cache (bool, optional, defaults to True): Cache the text and condition-image keys and values after the first step. Valid because causal_condition modulates those tokens from t = 0, making their activations step-independent. Toggling it does not reproduce the same image bit-for-bit in reduced precision. attention_kwargs (dict, optional): Additional kwargs for attention processors. *denoiser_input_fields (None,optional): conditional model inputs for the denoiser: e.g. prompt_embeds, negative_prompt_embeds, etc. output_type (str,optional*, defaults to pil): Output format: ‘pil’, ‘np’, ‘pt’.

Output: images (list): Gambar yang dihasilkan.

QwenImage21TurboModularPipeline

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

ModularPipeline untuk Qwen-Image 2.1 Turbo, checkpoint yang dipercepat dan melakukan sampling dalam beberapa langkah tanpa panduan.

QwenImage21TurboAutoBlocks

kelas diffusers.QwenImage21TurboAutoBlocks

< >

( )

Auto Modular pipeline untuk text-to-image dan generasi yang dikondisikan oleh gambar menggunakan Qwen-Image 2.1 Turbo, checkpoint yang dipercepat yang mengambil sampel grid sigma bawaannya dalam beberapa langkah tanpa guidance.

  • untuk generasi teks-ke-gambar, yang perlu Anda berikan hanyalah prompt
  • untuk generasi yang dikondisikan oleh gambar, Anda perlu menyediakan prompt dan image (satu gambar atau daftar)

Alur kerja yang didukung:

  • text2image: membutuhkan prompt
  • image_conditioned: membutuhkan prompt, image

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

Konfigurasi: sample_sigmas (default: None): Grid sampling yang disertakan bersama checkpoint, digunakan ketika sigmas tidak diteruskan.

Inputs: image (Image | list, optional): Reference image(s) for denoising. Can be a single image or list of images. output_resolution (int, optional, defaults to 1024): Target side length used to derive the output size and to resize condition images. prompt (str): The prompt or prompts to guide image generation. generator (Generator, optional): Torch generator for deterministic generation. num_images_per_prompt (int, optional, defaults to 1): The number of images to generate per prompt. height (int, optional): The height in pixels of the generated image. width (int, optional): The width in pixels of the generated image. image_latents (list, optional): Normalized latents of each condition image. Can be generated from vae_encoder step. latents (Tensor): Pre-generated noisy latents for image generation. num_inference_steps (int): The number of denoising steps. sigmas (list, optional): Custom sigmas for the denoising process. use_kv_cache (bool, optional, defaults to True): Cache the text and condition-image keys and values after the first step. Valid because causal_condition modulates those tokens from t = 0, making their activations step-independent. Toggling it does not reproduce the same image bit-for-bit in reduced precision. attention_kwargs (dict, optional): Additional kwargs for attention processors. *denoiser_input_fields (None,optional): conditional model inputs for the denoiser: e.g. prompt_embeds, negative_prompt_embeds, etc. output_type (str,optional*, defaults to pil): Output format: ‘pil’, ‘np’, ‘pt’.

Output: images (list): Gambar yang dihasilkan.

Update on GitHub

←PRX Pixel QwenImage→