hf-doc-build/doc / diffusers /main /id /api /pipelines /qwenimage.md

|

raw

108 kB

Berlisensi di bawah Apache License, Versi 2.0 ("Lisensi");

Anda mungkin tidak dapat menggunakan file ini kecuali sesuai dengan Lisensi.

Anda dapat memperoleh salinan Lisensi di

http://www.apache.org/licenses/LICENSE-2.0

Kecuali diwajibkan oleh hukum yang berlaku atau disepakati secara tertulis, perangkat lunak

distribusikan di bawah Lisensi berdasarkan basis "SEBAGAIMANA ADANYA",

TANPA JAMINAN ATAU SYARAT DALAM BENTUK APAPUN, baik yang dinyatakan maupun yang tersirat.

Lihat Lisensi untuk bahasa tertentu yang mengatur izin dan

batasan di bawah Lisensi. -->

QwenImage

Qwen-Image dari tim Qwen adalah model dasar generasi gambar dalam seri Qwen yang mencapai kemajuan signifikan dalam render teks kompleks dan pengeditan gambar yang presisi. Eksperimen menunjukkan kemampuan umum yang kuat dalam generasi dan pengeditan gambar, dengan kinerja luar biasa dalam render teks, terutama untuk bahasa Mandarin.

Qwen-Image hadir dalam varian berikut:

tipe model	id model
Qwen-Image	`Qwen/Qwen-Image`
Qwen-Image-Edit	`Qwen/Qwen-Image-Edit`
Qwen-Image-Edit Plus	Qwen/Qwen-Image-Edit-2509

Lihat panduan Caching untuk mempercepat inferensi dengan menyimpan dan menggunakan kembali output antara.

LoRA untuk inferensi yang lebih cepat

Gunakan LoRA dari lightx2v/Qwen-Image-Lightning untuk mempercepat inferensi dengan mengurangi jumlah langkah. Lihat cuplikan kode di bawah:

Kode

from diffusers import DiffusionPipeline, FlowMatchEulerDiscreteScheduler
import torch 
import math

ckpt_id = "Qwen/Qwen-Image"

# From
# https://github.com/ModelTC/Qwen-Image-Lightning/blob/342260e8f5468d2f24d084ce04f55e101007118b/generate_with_diffusers.py#L82C9-L97C10
scheduler_config = {
    "base_image_seq_len": 256,
    "base_shift": math.log(3),  # We use shift=3 in distillation
    "invert_sigmas": False,
    "max_image_seq_len": 8192,
    "max_shift": math.log(3),  # We use shift=3 in distillation
    "num_train_timesteps": 1000,
    "shift": 1.0,
    "shift_terminal": None,  # set shift_terminal to None
    "stochastic_sampling": False,
    "time_shift_type": "exponential",
    "use_beta_sigmas": False,
    "use_dynamic_shifting": True,
    "use_exponential_sigmas": False,
    "use_karras_sigmas": False,
}
scheduler = FlowMatchEulerDiscreteScheduler.from_config(scheduler_config)
pipe = DiffusionPipeline.from_pretrained(
    ckpt_id, scheduler=scheduler, dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
pipe.load_lora_weights(
    "lightx2v/Qwen-Image-Lightning", weight_name="Qwen-Image-Lightning-8steps-V1.0.safetensors"
)

prompt = "a tiny astronaut hatching from an egg on the moon, Ultra HD, 4K, cinematic composition."
negative_prompt = " "
image = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1024,
    height=1024,
    num_inference_steps=8,
    true_cfg_scale=1.0,
    generator=torch.manual_seed(0),
).images[0]
image.save("qwen_fewsteps.png")

Parameter guidance_scale dalam pipeline ada untuk mendukung model guidance-distilled di masa depan ketika model tersebut tersedia. Perhatikan bahwa meneruskan guidance_scale ke pipeline tidak efektif. Untuk mengaktifkan classifier-free guidance, silakan teruskan true_cfg_scale dan negative_prompt (bahkan negative prompt kosong seperti " ") untuk mengaktifkan komputasi classifier-free guidance.

Referensi multi-gambar dengan QwenImageEditPlusPipeline

Dengan QwenImageEditPlusPipeline, pengguna dapat menyediakan beberapa gambar sebagai referensi input.

import torch
from PIL import Image
from diffusers import QwenImageEditPlusPipeline
from diffusers.utils import load_image

pipe = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2509", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

image_1 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/grumpy.jpg")
image_2 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/peng.png")
image = pipe(
    image=[image_1, image_2],
    prompt='''put the penguin and the cat at a game show called "Qwen Edit Plus Games"''',
    num_inference_steps=50
).images[0]

Kinerja

torch.compile

Menggunakan torch.compile pada transformer memberikan percepatan ~2,4x (A100 80GB: 4,70s → 1,93s):

import torch
from diffusers import QwenImagePipeline

pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
pipe.transformer = torch.compile(pipe.transformer)

# First call triggers compilation (~7s overhead)
# Subsequent calls run at ~2.4x faster
image = pipe("a cat", num_inference_steps=50).images[0]

Inferensi Berbatch dengan Prompt Berpanjang Variabel

Saat menggunakan classifier-free guidance (CFG) dengan prompt yang panjangnya berbeda, pipeline menangani padding dengan benar melalui attention masking. Hal ini memastikan token padding tidak memengaruhi output yang dihasilkan.

# CFG with different prompt lengths works correctly
image = pipe(
    prompt="A cat",
    negative_prompt="blurry, low quality, distorted",
    true_cfg_scale=3.5,
    num_inference_steps=50,
).images[0]

Untuk skrip dan hasil benchmark yang lebih rinci, lihat gist ini.

QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

Sumber

Parameter:

transformer (QwenImageTransformer2DModel) : Arsitektur Conditional Transformer (MMDiT) untuk mendenoise latens gambar yang telah dikodekan.

scheduler (FlowMatchEulerDiscreteScheduler) : Penjadwal yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.

vae (AutoencoderKL) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, khususnya varian Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : Tokenizer dari kelas https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

Pipeline QwenImage untuk generasi teks-ke-gambar.

call[[diffusers.QwenImagePipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: 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 = 512)

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus melewatkan prompt_embeds sebagai gantinya.

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika true_cfg_scale tidak lebih besar dari 1).

true_cfg_scale (float, opsional, default 1.0) : Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. true_cfg_scale didefinisikan sebagai w dari persamaan 2. pada Imagen Paper. Classifier-free guidance diaktifkan dengan mengatur true_cfg_scale > 1 dan menyediakan negative_prompt. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.

height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Tinggi gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.

width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.

num_inference_steps (int, opsional, defaultnya 50) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.

sigmas (list[float], opsional) : Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas di metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.

guidance_scale (float, opsional, defaultnya None) : Nilai skala panduan untuk model yang telah melalui distilasi panduan. Berbeda dengan panduan bebas-klasifikator tradisional di mana skala panduan diterapkan selama inferensi melalui penskalaan ulang prediksi noise, model yang telah melalui distilasi panduan mengambil skala panduan secara langsung sebagai parameter input selama langkah maju. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah. Parameter ini dalam pipeline ada untuk mendukung model distilasi panduan di masa depan ketika mereka muncul. Parameter ini diabaikan ketika tidak menggunakan model distilasi panduan. Untuk mengaktifkan panduan bebas-klasifikator tradisional, silakan lewati true_cfg_scale > 1.0 dan negative_prompt (bahkan prompt negatif kosong seperti " " harus mengaktifkan komputasi panduan bebas-klasifikator).

num_images_per_prompt (int, opsional, default 1) : Jumlah gambar yang akan dihasilkan per prompt.

generator (torch.Generator atau list[torch.Generator], opsional) : Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.

latents (torch.Tensor, opsional) : Laten berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor laten akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.

prompt_embeds (torch.Tensor, opsional) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

prompt_embeds_mask (torch.Tensor, opsional) : Attention mask untuk prompt_embeds.

negative_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.

negative_prompt_embeds_mask (torch.Tensor, opsional) : Attention mask untuk negative_prompt_embeds.

output_type (str, opsional, defaultnya "pil") : Format output dari gambar yang dihasilkan. Pilih antara PIL: PIL.Image.Image atau np.array.

return_dict (bool, opsional, defaultnya True) : Apakah akan mengembalikan ~pipelines.qwenimage.QwenImagePipelineOutput alih-alih tuple biasa.

attention_kwargs (dict, opsional) : Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.

callback_on_step_end (Callable, opsional) : Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (list, opsional) : Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.

max_sequence_length (int defaultnya 512) : Panjang maksimum sekuens yang digunakan dengan prompt.

Mengembalikan: ~pipelines.qwenimage.QwenImagePipelineOutput atau tuple

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

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> import torch
>>> from diffusers import QwenImagePipeline

>>> pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50).images[0]
>>> image.save("qwenimage.png")

encode_prompt[[diffusers.QwenImagePipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024)

Sumber

Parameter:

prompt (str atau list[str], opsional) : prompt yang akan dienkod

device : (torch.device): perangkat torch

num_images_per_prompt (int) : jumlah gambar yang harus dihasilkan per prompt

prompt_embeds (torch.Tensor, opsional) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

Sumber

Parameter:

transformer (QwenImageTransformer2DModel) : Arsitektur Conditional Transformer (MMDiT) untuk mendenoise latens gambar yang telah dikodekan.

scheduler (FlowMatchEulerDiscreteScheduler) : Penjadwal yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.

vae (AutoencoderKL) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, khususnya varian Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : Tokenizer dari kelas https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

Pipeline QwenImage untuk generasi teks-ke-gambar.

call[[diffusers.QwenImageImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, strength: float = 0.6, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: 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 = 512)

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus melewatkan prompt_embeds sebagai gantinya.

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika true_cfg_scale tidak lebih besar dari 1).

image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], atau list[np.ndarray]) : Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk digunakan sebagai titik awal. Untuk array numpy dan tensor pytorch, rentang nilai yang diharapkan adalah antara [0, 1] Jika berupa tensor atau daftar tensor, bentuk (shape) yang diharapkan adalah (B, C, H, W) atau (C, H, W). Jika berupa array numpy atau daftar array, bentuk yang diharapkan adalah (B, H, W, C) atau (H, W, C) Parameter ini juga dapat menerima latents gambar sebagai image, namun jika latents dilewatkan secara langsung, latents tersebut tidak akan di-encode ulang.

true_cfg_scale (float, opsional, default 1.0) : Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. true_cfg_scale didefinisikan sebagai w dari persamaan 2. pada Imagen Paper. Classifier-free guidance diaktifkan dengan mengatur true_cfg_scale > 1 dan menyediakan negative_prompt. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.

height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Tinggi gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.

width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.

strength (float, opsional, default 1.0) : Menunjukkan sejauh mana transformasi dilakukan pada image referensi. Nilai harus berada di antara 0 dan 1. image digunakan sebagai titik awal, dan semakin tinggi nilai strength, semakin banyak noise yang ditambahkan. Jumlah langkah denoising bergantung pada jumlah noise yang ditambahkan di awal. Ketika strength bernilai 1, noise yang ditambahkan maksimal dan proses denoising berjalan untuk jumlah iterasi penuh yang ditentukan dalam num_inference_steps. Nilai 1 pada dasarnya mengabaikan image.