Diffusers documentation
Z-Image
Z-Image
Z-Image هو نموذج قوي وفعّال للغاية لتوليد الصور يحتوي على 6 مليارات من المعاملات. حاليًا، يتوفر نموذج واحد فقط، مع إطلاق نموذجين إضافيين قريبًا:
| النموذج | Hugging Face |
|---|---|
| Z-Image-Turbo | https://huggingface.co/Tongyi-MAI/Z-Image-Turbo |
Z-Image-Turbo
Z-Image-Turbo هي نسخة مُصغّرة من Z-Image تتساوى مع المنافسين الرئاسيين أو تتفوق عليهم باستخدام 8 NFEs (عدد تقييمات الدالة) فقط. توفر زمن استدلال أقل من ثانية على وحدات معالجة الرسوميات H800 بمستوى المؤسسات، وتعمل بسلاسة على أجهزة المستهلكين بذاكرة فيديو 16G. تتميز بتوليد صور واقعية، وعرض ثنائي اللغة للنصوص (الإنجليزية & الصينية)، والالتزام المتين بالتعليمات.
من صورة إلى صورة
استخدم ZImageImg2ImgPipeline لتحويل صورة موجودة بناءً على وصف نصي.
import torch
from diffusers import ZImageImg2ImgPipeline
from diffusers.utils import load_image
pipe = ZImageImg2ImgPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))
prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
image = pipe(
prompt,
image=init_image,
strength=0.6,
num_inference_steps=8,
guidance_scale=0.0,
generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_img2img.png")الترميم
استخدم ZImageInpaintPipeline لإعادة رسم مناطق محددة من صورة بناءً على وصف نصي وقناع.
import torch
import numpy as np
from PIL import Image
from diffusers import ZImageInpaintPipeline
from diffusers.utils import load_image
pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))
# Create a mask (white = inpaint, black = preserve)
mask = np.zeros((1024, 1024), dtype=np.uint8)
mask[256:768, 256:768] = 255 # Inpaint center region
mask_image = Image.fromarray(mask)
prompt = "A beautiful lake with mountains in the background"
image = pipe(
prompt,
image=init_image,
mask_image=mask_image,
strength=1.0,
num_inference_steps=8,
guidance_scale=0.0,
generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_inpaint.png")ZImagePipeline
فئة diffusers.ZImagePipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: ZImageTransformer2DModel )
__call__
< source >( prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 5.0cfg_normalization: bool = Falsecfg_truncation: float = 1.0negative_prompt: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: list[torch.FloatTensor] | None = Nonenegative_prompt_embeds: list[torch.FloatTensor] | None = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512 ) → ZImagePipelineOutput or tuple
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمريرprompt_embedsبدلاً من ذلك. - height (
int، اختياري، القيمة الافتراضية 1024) — ارتفاع الصورة المولّدة بالبكسل. - width (
int، اختياري، القيمة الافتراضية 1024) — عرض الصورة المولّدة بالبكسل. - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال. - sigmas (
list[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملsigmasفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. - guidance_scale (
float، اختياري، القيمة الافتراضية 5.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2. في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنصprompt، وعادةً على حساب انخفاض جودة الصورة. - cfg_normalization (
bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تطبيق تطبيع الإعدادات. - cfg_truncation (
float، اختياري، القيمة الافتراضية 1.0) — قيمة الاقتطاع للتكوين. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - num_images_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.FloatTensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كائن latents عن طريق الاستخراج باستخدام مولّد الأرقام العشوائيةgeneratorالمُقدَّم. - prompt_embeds (
list[torch.FloatTensor]، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
list[torch.FloatTensor]، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم يُقدَّم، سيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - output_type (
str، اختياري، القيمة الافتراضية"pil") — صيغة مخرجات توليد الصورة. اختر بين PIL:PIL.Image.Imageأوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع~pipelines.stable_diffusion.ZImagePipelineOutputبدلاً من tuple عادي. - joint_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.
يعيد
ZImagePipelineOutput أو tuple
ZImagePipelineOutput إذا كان
return_dict هو True، وإلا فسيكون tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على
الصور المولّدة.
الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.
أمثلة:
>>> import torch
>>> from diffusers import ZImagePipeline
>>> pipe = ZImagePipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> # Optionally, set the attention backend to flash-attn 2 or 3, default is SDPA in PyTorch.
>>> # (1) Use flash attention 2
>>> # pipe.transformer.set_attention_backend("flash")
>>> # (2) Use flash attention 3
>>> # pipe.transformer.set_attention_backend("_flash_3")
>>> prompt = "一幅为名为“造相「Z-IMAGE-TURBO」”的项目设计的创意海报。画面巧妙地将文字概念视觉化：一辆复古蒸汽小火车化身为巨大的拉链头，正拉开厚厚的冬日积雪，展露出一个生机盎然的春天。"
>>> image = pipe(
... prompt,
... height=1024,
... width=1024,
... num_inference_steps=8,
... guidance_scale=0.0,
... generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage.png")ZImageImg2ImgPipeline
فئة diffusers.ZImageImg2ImgPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: ZImageTransformer2DModel )
المعاملات
- scheduler (FlowMatchEulerDiscreteScheduler) —
جدول زمني يُستخدم بالاقتران مع
transformerلإزالة الضوضاء من كائنات الصورة المُرمّزة. - vae (AutoencoderKL) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.
- text_encoder (
PreTrainedModel) — نموذج لتشفير النص يُستخدم لتشفير أوامر النص. - tokenizer (
AutoTokenizer) — مُقسِّم (tokenizer) لتقسيم نصوص الأوامر. - transformer (ZImageTransformer2DModel) — نموذج ZImage transformer لإزالة الضوضاء من الكامنات المُرمّزة للصورة.
خط أنابيب ZImage لتوليد الصور من الصور.
__call__
< source >( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonestrength: float = 0.6height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 5.0cfg_normalization: bool = Falsecfg_truncation: float = 1.0negative_prompt: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: list[torch.FloatTensor] | None = Nonenegative_prompt_embeds: list[torch.FloatTensor] | None = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512 ) → ZImagePipelineOutput or tuple
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمريرprompt_embedsبدلاً من ذلك. - image (
torch.Tensor،PIL.Image.Image،np.ndarray،list[torch.Tensor]،list[PIL.Image.Image]، أوlist[np.ndarray]) —Image، مصفوفة numpy أو tensor تمثل دفعة من الصور لاستخدامها كنقطة انطلاق. لكل من مصفوفة numpy وtensor الخاص بـ pytorch، النطاق المتوقع للقيم هو بين[0, 1]. إذا كان tensor أو قائمة من tensors، فيجب أن يكون الشكل المتوقع(B, C, H, W)أو(C, H, W). إذا كانت مصفوفة numpy أو قائمة من المصفوفات، فيجب أن يكون الشكل المتوقع(B, H, W, C)أو(H, W, C). - strength (
float، اختياري، القيمة الافتراضية 0.6) — يشير إلى مدى تحويل الصورة المرجعيةimage. يجب أن تكون القيمة بين 0 و 1. تُستخدمimageكنقطة انطلاق، وكلما زادت قيمةstrengthزاد مقدار الضوضاء المضافة. يعتمد عدد خطوات إزالة الضوضاء على كمية الضوضاء المضافة في البداية. عندما تكونstrengthتساوي 1، تكون الضوضاء المضافة في أقصى حد، وتعمل عملية إزالة الضوضاء لعدد التكرارات الكامل المحدد فيnum_inference_steps. القيمة 1 تتجاهلimageبشكل أساسي. - height (
int، اختياري، القيمة الافتراضية 1024) — ارتفاع الصورة المولّدة بالبكسلات. إذا لم يُقدَّم، يُستخدم ارتفاع الصورة المُدخلة. - width (
int، اختياري، القيمة الافتراضية 1024) — عرض الصورة المولدة بالبكسل. إذا لم يُحدد، يُستخدم عرض الصورة المدخلة. - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال. - sigmas (
list[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملsigmasفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. - guidance_scale (
float، اختياري، القيمة الافتراضية 5.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2. في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنصprompt، وعادةً على حساب انخفاض جودة الصورة. - cfg_normalization (
bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تطبيق تطبيع الإعدادات. - cfg_truncation (
float، اختياري، القيمة الافتراضية 1.0) — قيمة الاقتطاع للتكوين. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - num_images_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.FloatTensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كائن latents عن طريق الاستخراج باستخدام مولّد الأرقام العشوائيةgeneratorالمُقدَّم. - prompt_embeds (
list[torch.FloatTensor]، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
list[torch.FloatTensor]، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم يُقدَّم، سيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - output_type (
str، اختياري، القيمة الافتراضية"pil") — صيغة مخرجات توليد الصورة. اختر بين PIL:PIL.Image.Imageأوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع~pipelines.stable_diffusion.ZImagePipelineOutputبدلاً من tuple عادي. - joint_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.
يعيد
ZImagePipelineOutput أو tuple
ZImagePipelineOutput إذا كان
return_dict هو True، وإلا فسيكون tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على
الصور المولّدة.
الدالة التي تُستدعى عند استدعاء خط الأنابيب لتوليد صورة من صورة.
أمثلة:
>>> import torch
>>> from diffusers import ZImageImg2ImgPipeline
>>> from diffusers.utils import load_image
>>> pipe = ZImageImg2ImgPipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
>>> init_image = load_image(url).resize((1024, 1024))
>>> prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
>>> image = pipe(
... prompt,
... image=init_image,
... strength=0.6,
... num_inference_steps=8,
... guidance_scale=0.0,
... generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage_img2img.png")ZImageInpaintPipeline
فئة diffusers.ZImageInpaintPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: ZImageTransformer2DModel )
المعاملات
- scheduler (FlowMatchEulerDiscreteScheduler) —
جدول زمني يُستخدم بالاقتران مع
transformerلإزالة الضوضاء من كائنات الصورة المُرمّزة. - vae (AutoencoderKL) — نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.
- text_encoder (
PreTrainedModel) — نموذج لتشفير النص يُستخدم لتشفير أوامر النص. - tokenizer (
AutoTokenizer) — مُقسِّم (tokenizer) لتقسيم نصوص الأوامر. - transformer (ZImageTransformer2DModel) — نموذج ZImage transformer لإزالة الضوضاء من الكامنات المُرمّزة للصورة.
خط أنابيب ZImage لإعادة التلوين.
__call__
< source >( prompt: typing.Union[str, typing.List[str]] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemasked_image_latents: typing.Optional[torch.FloatTensor] = Nonestrength: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 5.0cfg_normalization: bool = Falsecfg_truncation: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_images_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = Nonenegative_prompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = Noneoutput_type: str = 'pil'return_dict: bool = Truejoint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 512 ) → ZImagePipelineOutput or tuple
المعاملات
- prompt (
strأوList[str]، اختياري) — الموجّه أو الموجّهات التي توجّه توليد الصورة. إذا لم يُعرَّف، يجب تمريرprompt_embedsبدلاً من ذلك. - image (
torch.Tensor،PIL.Image.Image،np.ndarray،List[torch.Tensor]،List[PIL.Image.Image]، أوList[np.ndarray]) —Image، مصفوفة numpy أو tensor تمثل دفعة من الصور لاستخدامها كنقطة انطلاق. لكل من مصفوفة numpy وtensor الخاص بـ pytorch، النطاق المتوقع للقيم هو بين[0, 1]. إذا كان tensor أو قائمة من tensors، فيجب أن يكون الشكل المتوقع(B, C, H, W)أو(C, H, W). إذا كانت مصفوفة numpy أو قائمة من المصفوفات، فيجب أن يكون الشكل المتوقع(B, H, W, C)أو(H, W, C). - mask_image (
torch.Tensor،PIL.Image.Image،np.ndarray،List[torch.Tensor]، أوList[PIL.Image.Image]، أوList[np.ndarray]) —Image، مصفوفة numpy أو tensor تمثل صورة قناع لإعادة الرسم. سيتم إعادة رسم البكسلات البيضاء (القيمة 1) في القناع، بينما ستُحفظ البكسلات السوداء (القيمة 0) من الصورة الأصلية. - masked_image_latents (
torch.FloatTensor، اختياري) — كائنات الصورة المقنّعة المُرمّزة مسبقًا. إذا تم تقديمها، سيتم تجاوز خطوة ترميز الصورة المقنّعة. - strength (
float، اختياري، القيمة الافتراضية 1.0) — يشير إلى مدى تحويل الصورة المرجعيةimage. يجب أن يكون بين 0 و 1. تُستخدمimageكنقطة انطلاق، وكلما ارتفعت قيمةstrengthزاد مقدار الضوضاء المضافة. يعتمد عدد خطوات إزالة الضوضاء على كمية الضوضاء المضافة في البداية. عندما تكونstrengthتساوي 1، تكون الضوضاء المضافة في أقصى حد، وتعمل عملية إزالة الضوضاء لعدد التكرارات الكامل المحدد فيnum_inference_steps. القيمة 1 تتجاهلimageفعلياً في المنطقة المقنّعة. - height (
int، اختياري، القيمة الافتراضية 1024) — ارتفاع الصورة المولّدة بالبكسلات. إذا لم يُقدَّم، يُستخدم ارتفاع الصورة المُدخلة. - width (
int، اختياري، القيمة الافتراضية 1024) — عرض الصورة المولدة بالبكسل. إذا لم يُحدد، يُستخدم عرض الصورة المدخلة. - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال. - sigmas (
List[float]، اختياري) — قيم sigmas مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معاملsigmasفي طريقةset_timestepsالخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمريرnum_inference_steps. - guidance_scale (
float، اختياري، القيمة الافتراضية 5.0) — مقياس التوجيه كما هو مُعرَّف في Classifier-Free Diffusion Guidance. يُعرَّفguidance_scaleعلى أنهwمن المعادلة 2. في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيينguidance_scale > 1. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنصprompt، وعادةً على حساب انخفاض جودة الصورة. - cfg_normalization (
bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تطبيق تطبيع الإعدادات. - cfg_truncation (
float، اختياري، القيمة الافتراضية 1.0) — قيمة الاقتطاع للتكوين. - negative_prompt (
strأوList[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - num_images_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - generator (
torch.GeneratorأوList[torch.Generator]، اختياري) — مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.FloatTensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كائن latents عن طريق الاستخراج باستخدام مولّد الأرقام العشوائيةgeneratorالمُقدَّم. - prompt_embeds (
List[torch.FloatTensor], اختياري) — تضمينات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
List[torch.FloatTensor], اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم يُقدَّم، سيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - output_type (
str، اختياري، القيمة الافتراضية"pil") — صيغة مخرجات توليد الصورة. اختر بين PIL:PIL.Image.Imageأوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع~pipelines.stable_diffusion.ZImagePipelineOutputبدلاً من tuple عادي. - joint_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.
يعيد
ZImagePipelineOutput أو tuple
ZImagePipelineOutput إذا كان
return_dict هو True، وإلا فسيكون tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على
الصور المولّدة.
الدالة التي يتم استدعاؤها عند استدعاء خط الأنابيب (pipeline) لإعادة رسم الصور (inpainting).
أمثلة:
>>> import torch
>>> from diffusers import ZImageInpaintPipeline
>>> from diffusers.utils import load_image
>>> pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
>>> init_image = load_image(url).resize((1024, 1024))
>>> # Create a mask (white = inpaint, black = preserve)
>>> import numpy as np
>>> from PIL import Image
>>> mask = np.zeros((1024, 1024), dtype=np.uint8)
>>> mask[256:768, 256:768] = 255 # Inpaint center region
>>> mask_image = Image.fromarray(mask)
>>> prompt = "A beautiful lake with mountains in the background"
>>> image = pipe(
... prompt,
... image=init_image,
... mask_image=mask_image,
... strength=1.0,
... num_inference_steps=8,
... guidance_scale=0.0,
... generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage_inpaint.png")prepare_latents
< source >( imagetimestepbatch_sizenum_channels_latentsheightwidthdtypedevicegeneratorlatents = None ) → Tuple of (latents, noise, image_latents) where
يعيد
مجموعة (لاتنات، ضوضاء، لاتنات الصورة) حيث
- latents: كامنات الصورة المُضجّعة لإزالة الضوضاء
- noise: متجه الضوضاء المستخدم للدمج
- image_latents: كامنات صورة نظيفة للدمج
جهّز الكمونيات (latents) للتلوين الداخلي (inpainting)، مع إرجاع الضوضاء وimage_latents للمزج.
prepare_mask_latents
< source >( maskmasked_imagebatch_sizeheightwidthdtypedevicegenerator )
المعاملات
- mask — متجه قناع ثنائي حيث 1 = منطقة إعادة الرسم، 0 = منطقة الحفظ.
- masked_image — الصورة الأصلية مع تصفير المناطق المقنّعة.
- batch_size — عدد الصور التي سيتم توليدها.
- height — ارتفاع الصورة الناتجة.
- width — عرض الصورة الناتجة.
- dtype — نوع البيانات للتّنسورات.
- device — الجهاز الذي سيتم وضع المتجهات عليه.
- generator — مولّد عشوائي للتكرارية.
جهّز قناع الصورة (mask) والقيم الكامنة (latents) للصورة المقنّعة (masked image) لأغراض إعادة الرسم (inpainting).