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

|

raw

128 kB

مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")

لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.

يمكنك الحصول على نسخة من الترخيص في

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

ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات

تُوزَّع بموجب الرخصة على أساس "كما هي"،

بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.

راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و

قيود بموجب الترخيص. -->

QwenImage

نموذج Qwen-Image من فريق Qwen هو نموذج أساسي لتوليد الصور ضمن سلسلة Qwen، يحقق تقدماً كبيراً في عرض النصوص المعقدة والتحرير الدقيق للصور. تُظهر التجارب قدرات عامة قوية في كل من توليد الصور وتحريرها، مع أداء استثنائي في عرض النصوص، لا سيما باللغة الصينية.

يتوفر Qwen-Image في النسخ التالية:

نوع النموذج	معرف النموذج
Qwen-Image	`Qwen/Qwen-Image`
Qwen-Image-Edit	`Qwen/Qwen-Image-Edit`
Qwen-Image-Edit Plus	Qwen/Qwen-Image-Edit-2509

راجع دليل التخزين المؤقت لتسريع الاستدلال من خلال تخزين المخرجات الوسيطة وإعادة استخدامها.

LoRA للاستدلال الأسرع

استخدم LoRA من lightx2v/Qwen-Image-Lightning لتسريع الاستدلال عن طريق تقليل عدد الخطوات. راجع مقتطف الشيفرة أدناه:

Code

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

يوجد معامل guidance_scale في خط الأنابيب لدعم النماذج المُقطّرة للإرشاد المستقبلية عند ظهورها. لاحظ أن تمرير guidance_scale إلى خط الأنابيب لا يُحقق أي أثر. لتفعيل الإرشاد الحر من المُصنِّف، يُرجى تمرير true_cfg_scale وnegative_prompt (حتى مُوجِّه سلبي فارغ مثل " ") لتفعيل حسابات الإرشاد الحر من المُصنِّف.

مرجع متعدد الصور باستخدام QwenImageEditPlusPipeline

باستخدام QwenImageEditPlusPipeline، يمكن تقديم صور متعددة كمرجع للإدخال.

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]

الأداء

torch.compile

يوفر استخدام torch.compile على المحوّل تسريعًا بنسبة ~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]

الاستدلال الدُفعي مع المُوجِّهات ذات الأطوال المتغيرة

عند استخدام التوجيه الحر من التصنيف (CFG) مع أوامر ذات أطوال مختلفة، يتعامل خط الأنابيب بشكل صحيح مع الحشو عبر قناع الانتباه. وهذا يضمن أن رموز الحشو لا تؤثر على المخرجات المولّدة.

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

لمعرفة المزيد من التفاصيل حول سكربتات النتائج المرجعية ونتائجها، راجع هذا الملخص.

QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline[[diffusers.QwenImagePipeline]]

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

المصدر

المعاملات:

transformer (QwenImageTransformer2DModel) : معمارية Transformer الشرطية (MMDiT) لإزالة الضوضاء من كامنات الصورة المُرمّزة.

scheduler (FlowMatchEulerDiscreteScheduler) : مُجدوِل يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

vae (AutoencoderKL) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct، وتحديداً النسخة Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : مُجزِّئ من الفئة https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

خط أنابيب QwenImage لتوليد الصور من النص.

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)

المصدر

المعاملات:

prompt (str أو list[str]، اختياري) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.

negative_prompt (str أو list[str]، اختياري) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا لم يكن true_cfg_scale أكبر من 1).

true_cfg_scale (float, اختياري, القيمة الافتراضية 1.0) : مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف true_cfg_scale على أنه w من المعادلة 2. في Imagen Paper. يتم تفعيل التوجيه الحر من التصنيف عن طريق تعيين true_cfg_scale > 1 وتوفير negative_prompt. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص prompt، وعادةً على حساب انخفاض جودة الصورة.

height (int، اختياري، الافتراضي هو self.unet.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

width (int، اختياري، القيمة الافتراضية هي self.unet.config.sample_size * self.vae_scale_factor) : عرض الصورة المولدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

num_inference_steps (int، اختياري، القيمة الافتراضية 50) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال.

sigmas (list[float]، اختياري) : قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل sigmas في طريقة set_timesteps الخاصة بهم. إذا لم تُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير num_inference_steps.

guidance_scale (float, اختياري، القيمة الافتراضية None) : قيمة مقياس التوجيه (guidance scale) للنماذج المُقطّرة للتوجيه. على عكس التوجيه الحر من التصنيف التقليدي حيث يُطبَّق مقياس التوجيه أثناء الاستدلال من خلال إعادة تحجيم تنبؤ الضوضاء، فإن النماذج المُقطّرة للتوجيه تتخذ مقياس التوجيه مباشرةً كمدخل معياري أثناء المرور الأمامي. يتم تفعيل مقياس التوجيه عن طريق تعيين guidance_scale > 1. يشجّع مقياس توجيه أعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص prompt، وعادةً على حساب انخفاض جودة الصورة. يوجد هذا المعامل في خط الأنابيب لدعم النماذج المُقطّرة للتوجيه المستقبلية عند ظهورها. يتم تجاهله عند عدم استخدام النماذج المُقطّرة للتوجيه. لتفعيل التوجيه الحر من التصنيف التقليدي، يرجى تمرير true_cfg_scale > 1.0 و negative_prompt (حتى سطر سالب فارغ مثل " " يجب أن يُفعّل حسابات التوجيه الحر من التصنيف).

num_images_per_prompt (int، اختياري، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

generator (torch.Generator أو list[torch.Generator]، اختياري) : مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.

latents (torch.Tensor، اختياري) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كامنات من خلال الاستخراج باستخدام generator العشوائي المُقدَّم.

prompt_embeds (torch.Tensor، اختياري) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال prompt.

prompt_embeds_mask (torch.Tensor، اختياري) : قناع الانتباه لـ prompt_embeds.

negative_prompt_embeds (torch.Tensor, اختياري) : تمثيلات نصية سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال negative_prompt.

negative_prompt_embeds_mask (torch.Tensor، اختياري) : قناع الانتباه (Attention mask) الخاص بـnegative_prompt_embeds.

output_type (str، اختياري، القيمة الافتراضية "pil") : صيغة الصورة الناتجة عن عملية التوليد. اختر بين PIL: PIL.Image.Image أو np.array.

return_dict (bool، اختياري، الافتراضي True) : ما إذا كان يجب إرجاع ~pipelines.qwenimage.QwenImagePipelineOutput بدلاً من tuple عادي.

attention_kwargs (dict، اختياري) : قاموس kwargs يُمرَّر إلى AttentionProcessor إذا تم تحديده، كما هو معرَّف تحت self.processor في diffusers.models.attention_processor.

callback_on_step_end (Callable، اختياري) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). سيتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (list، اختياري) : قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجة callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.

max_sequence_length (int الافتراضي 512) : أقصى طول تسلسل يُستخدم مع prompt.

يعيد: ~pipelines.qwenimage.QwenImagePipelineOutput أو tuple

~pipelines.qwenimage.QwenImagePipelineOutput إذا كان return_dict هو True، وإلا tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:

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

المصدر

المعاملات:

prompt (str أو list[str]، اختياري) : النص الذي سيتم ترميزه

device : (torch.device): جهاز torch

num_images_per_prompt (int) : عدد الصور التي يجب توليدها لكل موجه

prompt_embeds (torch.Tensor، اختياري) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال prompt.

QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

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

المصدر

المعاملات:

transformer (QwenImageTransformer2DModel) : معمارية Transformer الشرطية (MMDiT) لإزالة الضوضاء من كامنات الصورة المُرمّزة.

scheduler (FlowMatchEulerDiscreteScheduler) : مُجدوِل يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

vae (AutoencoderKL) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct، وتحديداً النسخة Qwen2.5-VL-7B-Instruct.

tokenizer (Qwen2Tokenizer) : مُجزِّئ من الفئة https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer

خط أنابيب QwenImage لتوليد الصور من النص.

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)

المصدر

المعاملات:

prompt (str أو list[str]، اختياري) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير prompt_embeds بدلاً من ذلك.

negative_prompt (str أو list[str]، اختياري) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير negative_prompt_embeds بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا لم يكن true_cfg_scale أكبر من 1).

image (torch.Tensor، PIL.Image.Image، np.ndarray، list[torch.Tensor]، list[PIL.Image.Image]، أو list[np.ndarray]) : Image، مصفوفة numpy أو tensor تمثل دفعة من الصور (image batch) لاستخدامها كنقطة انطلاق. لكل من مصفوفة numpy وtensor الخاص بـ pytorch، النطاق المتوقع للقيم هو بين [0, 1] إذا كان tensor أو قائمة من tensors، فيجب أن يكون الشكل المتوقع (B, C, H, W) أو (C, H, W). إذا كانت مصفوفة numpy أو قائمة من المصفوفات، فيجب أن يكون الشكل المتوقع (B, H, W, C) أو (H, W, C) كما يمكنه قبول كامنات الصور (image latents) كـ image، ولكن إذا تم تمرير الكامنات مباشرةً فلن يتم ترميزها مرة أخرى.

true_cfg_scale (float, اختياري, القيمة الافتراضية 1.0) : مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّف true_cfg_scale على أنه w من المعادلة 2. في Imagen Paper. يتم تفعيل التوجيه الحر من التصنيف عن طريق تعيين true_cfg_scale > 1 وتوفير negative_prompt. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص prompt، وعادةً على حساب انخفاض جودة الصورة.

height (int، اختياري، الافتراضي هو self.unet.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

width (int، اختياري، القيمة الافتراضية هي self.unet.config.sample_size * self.vae_scale_factor) : عرض الصورة المولدة بالبكسلات. يتم ضبطه على 1024 افتراضيًا للحصول على أفضل النتائج.

strength (float، اختياري، القيمة الافتراضية 1.0) : يحدد مدى تحويل الصورة المرجعية image. يجب أن يكون بين 0 و 1. تُستخدم image كنقطة انطلاق، وكلما ارتفعت قيمة strength زاد مقدار الضوضاء المضافة. يعتمد عدد خطوات إزالة الضوضاء على كمية الضوضاء المضافة في البداية. عندما تكون strength تساوي 1، تكون الضوضاء المضافة في أقصى حد، وتعمل عملية إزالة الضوضاء لعدد التكرارات الكامل المحدد في num_inference_steps. القيمة 1 تتجاهل image بشكل أساسي.