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

|

raw

111 kB

Apache Lisansı, 2.0 Sürümü ("Lisans") altında lisanslanmıştır;

bu dosyayı, Lisansa uygun olarak kullanabilirsiniz.

Lisansın bir kopyasını şu adresten edinebilirsiniz

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

Uygulanabilir yasa gerektirmedikçe veya yazılı olarak anlaşılmadıkça, yazılım

Lisans kapsamında dağıtılan, "OLDUĞU GİBİ" esasına göre dağıtılır,

HİÇBİR TÜR AÇIK VEYA ZIMMİ GARANTİ VEYA ŞART İÇERMEZ.

İzinleri ve

lisans kapsamındaki kısıtlamalar. -->

QwenImage

Qwen ekibinden Qwen-Image, Qwen serisinde karmaşık metin işleme ve hassas görüntü düzenleme alanlarında önemli ilerlemeler sağlayan bir görüntü oluşturma temel modelidir. Deneyler, hem görüntü oluşturma hem de düzenleme konusunda güçlü genel yetenekler gösterdiğini, özellikle Çin dili için metin işlemede olağanüstü performans sergilediğini ortaya koymaktadır.

Qwen-Image aşağıdaki varyantlarda gelir:

model türü	model kimliği
Qwen-Image	`Qwen/Qwen-Image`
Qwen-Image-Edit	`Qwen/Qwen-Image-Edit`
Qwen-Image-Edit Plus	Qwen/Qwen-Image-Edit-2509

Ara çıktıları depolayarak ve yeniden kullanarak çıkarımı hızlandırmak için Önbellekleme kılavuzuna bakın.

Daha hızlı çıkarım için LoRA

lightx2v/Qwen-Image-Lightning kaynaklı bir LoRA kullanarak adım sayısını azaltmak ve çıkarımı hızlandırmak için aşağıdaki kod parçasına bakın:

Kod

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

Pipeline'daki guidance_scale parametresi, ileride çıkacak guidance-distilled modelleri desteklemek için orada durmaktadır. Dikkat edin, pipeline'a guidance_scale geçirmek etkisizdir. Classifier-free guidance'ı etkinleştirmek için lütfen true_cfg_scale ve negative_prompt geçirin (boş bir negatif prompt bile, örneğin " ", classifier-free guidance hesaplamalarını etkinleştirmelidir).

QwenImageEditPlusPipeline ile çoklu görüntü referansı

QwenImageEditPlusPipeline ile birden fazla görüntü girdi referansı olarak sağlanabilir.

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]

Performans

torch.compile

Dönüştürücüde torch.compile kullanmak ~2.4x hızlanma sağlar (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]

Değişken Uzunlukta İfadelerle Toplu Çıkarım

Farklı uzunluklarda istemlerle classifier-free guidance (CFG) kullanıldığında, pipeline, attention masking yoluyla padding'i doğru şekilde işler. Bu, padding token'larının üretilen çıktıyı etkilememesini sağlar.

# 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]

Ayrıntılı kıyaslama betikleri ve sonuçları için bu gist'e bakın.

QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline[[diffusers.QwenImagePipeline]]

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

Kaynak

Parametreler:

transformer (QwenImageTransformer2DModel) : Kodlanmış görüntü latentlerini gürültüden arındırmak için kullanılan Koşullu Transformer (MMDiT) mimarisi.

scheduler (FlowMatchEulerDiscreteScheduler) : Kodlanmış görüntü latentlerini gürültüden arındırmak için transformer ile birlikte kullanılacak bir zamanlayıcı.

vae (AutoencoderKL) : Görüntüleri gizil (latent) temsillere kodlamak ve bu temsillerden görüntülere çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, özellikle Qwen2.5-VL-7B-Instruct varyantı.

tokenizer (Qwen2Tokenizer) : https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer sınıfının Tokenizer'ı

Metinden görüntüye üretim için QwenImage hattı.

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 = ['latents'], max_sequence_length: int = 512)

Kaynak

Parametreler:

prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmamışsa, bunun yerine prompt_embeds geçirilmelidir.

negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani true_cfg_scale, 1'den büyük olmadığında) yok sayılır.

true_cfg_scale (float, opsiyonel, varsayılan 1.0) : Classifier-Free Diffusion Guidance'de tanımlandığı gibi yönlendirme ölçeği. true_cfg_scale, Imagen Paper'daki 2. denklemindeki w olarak tanımlanır. Sınıflandırıcı-özgür yönlendirme, true_cfg_scale > 1 olarak ayarlanarak ve bir negative_prompt sağlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, prompt ile yakından ilişkili görsellerin üretilmesini teşvik eder, genellikle daha düşük görsel kalitesi pahasına.

height (int, isteğe bağlı, varsayılan olarak self.unet.config.sample_size * self.vae_scale_factor) : Üretilen görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.

width (int, isteğe bağlı, varsayılan olarak self.unet.config.sample_size * self.vae_scale_factor) : Üretilen görüntünün piksel cinsinden genişliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.

num_inference_steps (int, isteğe bağlı, varsayılan 50) : Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.

sigmas (list[float], isteğe bağlı) : set_timesteps metodunda sigmas argümanını destekleyen zamanlayıcılarla gürültü azaltma süreci için kullanılacak özel sigmalar. Tanımlanmamışsa, num_inference_steps geçirildiğinde varsayılan davranış kullanılacaktır.

guidance_scale (float, opsiyonel, varsayılan değeri None) : Rehberlik damıtılmış modeller için bir rehberlik ölçeği değeri. Geleneksel sınıflandırıcı-ücretsiz rehberlikte rehberlik ölçeğinin gürültü tahmini yeniden ölçekleme yoluyla çıkarım sırasında uygulanmasının aksine, rehberlik damıtılmış modeller rehberlik ölçeğini ileri geçiş sırasında doğrudan bir girdi parametresi olarak alır. Rehberlik ölçeği, guidance_scale > 1 olarak ayarlanarak etkinleştirilir. Daha yüksek rehberlik ölçeği, genellikle daha düşük görüntü kalitesi pahasına, prompt ile yakından ilişkili görüntülerin üretilmesini teşvik eder. Pipeline'daki bu parametre, rehberlik damıtılmış modeller ortaya çıktığında onları desteklemek için oradadır. Rehberlik damıtılmış modeller kullanılmadığında yok sayılır. Geleneksel sınıflandırıcı-ücretsiz rehberliği etkinleştirmek için lütfen true_cfg_scale > 1.0 ve negative_prompt (boş bir negatif prompt bile, örneğin " ", sınıflandırıcı-ücretsiz rehberlik hesaplamalarını etkinleştirmelidir) iletin.

num_images_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek görsel sayısı.

generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Üretimi deterministik hale getirmek için bir veya torch üreteci(leri) listesi.

latents (torch.Tensor, isteğe bağlı) : Görsel üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latentler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latent tensörü oluşturulur.

prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.

prompt_embeds_mask (torch.Tensor, isteğe bağlı) : prompt_embeds için dikkat maskesi.

negative_prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş negatif metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, negative_prompt_embeds, negative_prompt girdi argümanından oluşturulur.

negative_prompt_embeds_mask (torch.Tensor, isteğe bağlı) : negative_prompt_embeds için dikkat maskesi.

output_type (str, isteğe bağlı, varsayılan "pil") : Üretilen görüntünün çıktı biçimi. PIL: PIL.Image.Image veya np.array arasında seçim yapın.

return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ~pipelines.qwenimage.QwenImagePipelineOutput döndürülecek mi?

attention_kwargs (dict, isteğe bağlı) : Belirtilirse, diffusers.models.attention_processor içinde self.processor altında tanımlanan AttentionProcessor'a iletilen bir kwargs sözlüğü.

callback_on_step_end (Callable, isteğe bağlı) : Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.

callback_on_step_end_tensor_inputs (list, isteğe bağlı) : callback_on_step_end işlevi için girdi tensörlerinin listesi. Listede belirtilen tensörler, callback_kwargs argümanı olarak geçirilir. Yalnızca pipeline sınıfınızın ._callback_tensor_inputs özniteliğinde listelenen değişkenleri dahil edebilirsiniz.

max_sequence_length (int varsayılanı 512) : prompt ile kullanılacak maksimum dizi uzunluğu.

Dönüş: ~pipelines.qwenimage.QwenImagePipelineOutput veya tuple

return_dict True ise ~pipelines.qwenimage.QwenImagePipelineOutput, aksi halde tuple. Tuple döndürüldüğünde, ilk öğe üretilen görsellerin listesidir.

Üretim için pipeline çağrıldığında tetiklenen işlev.

Örnekler:

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

Kaynak

Parametreler:

prompt (str veya list[str], isteğe bağlı) : kodlanacak istem

device : (torch.device): torch cihazı

num_images_per_prompt (int) : her istem için oluşturulacak görsel sayısı

prompt_embeds (torch.Tensor, isteğe bağlı) : Ön oluşturulmuş metin gömme değerleri. Metin girdilerini kolayca ayarlamak için kullanılabilir, ör. istem ağırlıklandırması. Sağlanmazsa, metin gömme değerleri prompt girdi argümanından oluşturulur.

QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

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

Kaynak

Parametreler:

transformer (QwenImageTransformer2DModel) : Kodlanmış görüntü latentlerini gürültüden arındırmak için kullanılan Koşullu Transformer (MMDiT) mimarisi.

scheduler (FlowMatchEulerDiscreteScheduler) : Kodlanmış görüntü latentlerini gürültüden arındırmak için transformer ile birlikte kullanılacak bir zamanlayıcı.

vae (AutoencoderKL) : Görüntüleri gizil (latent) temsillere kodlamak ve bu temsillerden görüntülere çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) Modeli.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct, özellikle Qwen2.5-VL-7B-Instruct varyantı.

tokenizer (Qwen2Tokenizer) : https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer sınıfının Tokenizer'ı

Metinden görüntüye üretim için QwenImage hattı.

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 = ['latents'], max_sequence_length: int = 512)

Kaynak

Parametreler:

prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmek için istem veya istemler. Tanımlanmamışsa, bunun yerine prompt_embeds geçirilmelidir.

negative_prompt (str veya list[str], isteğe bağlı) : Görsel üretimi yönlendirmemek için kullanılan istem veya istemler. Tanımlanmamışsa bunun yerine negative_prompt_embeds parametresinin geçirilmesi gerekir. Yönlendirme kullanılmadığında (yani true_cfg_scale, 1'den büyük olmadığında) yok sayılır.

image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image] veya list[np.ndarray]) : Başlangıç noktası olarak kullanılacak bir görüntü partisyonunu temsil eden Image, numpy dizisi veya tensör. Hem numpy dizisi hem de pytorch tensörü için beklenen değer aralığı [0, 1] arasındadır. Tensör veya tensör listesi olması durumunda beklenen şekil (B, C, H, W) veya (C, H, W) olmalıdır. Numpy dizisi veya dizi listesi olması durumunda beklenen şekil (B, H, W, C) veya (H, W, C) olmalıdır. Ayrıca image olarak görüntü latentlerini de kabul edebilir, ancak latentler doğrudan geçirildiğinde tekrar kodlanmaz.

true_cfg_scale (float, opsiyonel, varsayılan 1.0) : Classifier-Free Diffusion Guidance'de tanımlandığı gibi yönlendirme ölçeği. true_cfg_scale, Imagen Paper'daki 2. denklemindeki w olarak tanımlanır. Sınıflandırıcı-özgür yönlendirme, true_cfg_scale > 1 olarak ayarlanarak ve bir negative_prompt sağlanarak etkinleştirilir. Daha yüksek yönlendirme ölçeği, prompt ile yakından ilişkili görsellerin üretilmesini teşvik eder, genellikle daha düşük görsel kalitesi pahasına.

height (int, isteğe bağlı, varsayılan olarak self.unet.config.sample_size * self.vae_scale_factor) : Üretilen görüntünün piksel cinsinden yüksekliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.

width (int, isteğe bağlı, varsayılan olarak self.unet.config.sample_size * self.vae_scale_factor) : Üretilen görüntünün piksel cinsinden genişliği. En iyi sonuçlar için varsayılan olarak 1024 olarak ayarlanır.

strength (float, opsiyonel, varsayılan 1.0) : Referans image'in ne ölçüde dönüştürüleceğini belirtir. 0 ile 1 arasında olmalıdır. image bir başlangıç noktası olarak kullanılır ve strength değeri arttıkça daha fazla gürültü eklenir. Gürültü azaltma adımlarının sayısı, başlangıçta eklenen gürültü miktarına bağlıdır. strength 1 olduğunda eklenen gürültü maksimumdur ve gürültü azaltma süreci, num_inference_steps içinde belirtilen tam tekrar sayısı kadar çalışır. 1 değeri, image'ı fiilen yok sayar.