# Z-Image

  

[Z-Image](https://huggingface.co/papers/2511.22699) هو نموذج قوي وفعّال للغاية لتوليد الصور يحتوي على 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](/docs/diffusers/main/ar/api/pipelines/z_image#diffusers.ZImageImg2ImgPipeline) لتحويل صورة موجودة بناءً على وصف نصي.

```python
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](/docs/diffusers/main/ar/api/pipelines/z_image#diffusers.ZImageInpaintPipeline) لإعادة رسم مناطق محددة من صورة بناءً على وصف نصي وقناع.

```python
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]]

#### diffusers.ZImagePipeline[[diffusers.ZImagePipeline]]

```python
diffusers.ZImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image.py#L141)

#### __call__[[diffusers.ZImagePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image.py#L297)

**المعاملات:**

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](https://arxiv.org/abs/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). يتم تفعيل مقياس التوجيه عن طريق تعيين `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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

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

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

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

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

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

أمثلة:
```py
>>> 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]]

#### diffusers.ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

```python
diffusers.ZImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L154)

**المعاملات:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

vae ([AutoencoderKL](/docs/diffusers/main/ar/api/models/autoencoderkl#diffusers.AutoencoderKL)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder (`PreTrainedModel`) : نموذج مُشفِّر للنص يُستخدم لتشفير أوامر النص.

tokenizer (`AutoTokenizer`) : مُجزِّئ (tokenizer) لتجزئة نصوص الأوامر.

transformer ([ZImageTransformer2DModel](/docs/diffusers/main/ar/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : نموذج تحويل ZImage لإزالة الضوضاء من الكامنات المُرمّزة للصورة.

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

#### __call__[[diffusers.ZImageImg2ImgPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.6, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L369)

**المعاملات:**

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](https://arxiv.org/abs/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). يتم تفعيل مقياس التوجيه عن طريق تعيين `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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

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

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

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

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

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

أمثلة:
```py
>>> 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]]

#### diffusers.ZImageInpaintPipeline[[diffusers.ZImageInpaintPipeline]]

```python
diffusers.ZImageInpaintPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L170)

**المعاملات:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

vae ([AutoencoderKL](/docs/diffusers/main/ar/api/models/autoencoderkl#diffusers.AutoencoderKL)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder (`PreTrainedModel`) : نموذج مُشفِّر للنص يُستخدم لتشفير أوامر النص.

tokenizer (`AutoTokenizer`) : مُجزِّئ (tokenizer) لتجزئة نصوص الأوامر.

transformer ([ZImageTransformer2DModel](/docs/diffusers/main/ar/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : نموذج تحويل ZImage لإزالة الضوضاء من الكامنات المُرمّزة للصورة.

خط أنابيب ZImage لإعادة التلوين.

#### __call__[[diffusers.ZImageInpaintPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str]] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, masked_image_latents: typing.Optional[torch.FloatTensor] = None, strength: float = 1.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_images_per_prompt: typing.Optional[int] = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = None, negative_prompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = None, output_type: str = 'pil', return_dict: bool = True, joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], max_sequence_length: int = 512)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L535)

**المعاملات:**

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 تمثل دفعة من الصور (image batch) تُستخدم كنقطة انطلاق. لكل من مصفوفة 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](https://arxiv.org/abs/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). يتم تفعيل مقياس التوجيه عن طريق تعيين `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](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

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

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

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

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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

أمثلة:
```py
>>> 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[[diffusers.ZImageInpaintPipeline.prepare_latents]]

```python
prepare_latents(image, timestep, batch_size, num_channels_latents, height, width, dtype, device, generator, latents = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L386)

**يعيد:** `Tuple of (latents, noise, image_latents) where`

- latents: كامنات الصورة المُضجّعة لإزالة الضوضاء
- noise: متجه الضوضاء المستخدم للدمج
- image_latents: كامنات صورة نظيفة للدمج

جهّز الكمونيات (latents) للتلوين الداخلي (inpainting)، مع إرجاع الضوضاء وimage_latents للمزج.

#### prepare_mask_latents[[diffusers.ZImageInpaintPipeline.prepare_mask_latents]]

```python
prepare_mask_latents(mask, masked_image, batch_size, height, width, dtype, device, generator)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L318)

**المعاملات:**

mask : متجه قناع ثنائي حيث 1 = منطقة إعادة الرسم، 0 = منطقة الحفظ.

masked_image : الصورة الأصلية مع المناطق المقنّعة مُصفَّرة.

batch_size : عدد الصور التي سيتم توليدها.

height : ارتفاع الصورة الناتجة.

width : عرض الصورة الناتجة.

dtype : نوع البيانات للموترات.

device : الجهاز الذي سيتم وضع المتجهات عليه.

generator : مولّد عشوائي للتكرارية.

**يعيد:**

مجموعة (tuple) من (القناع، كامنات الصورة المقنّعة) مُعدّة لحلقة إزالة الضوضاء.

جهّز قناع الصورة (mask) والقيم الكامنة (latents) للصورة المقنّعة (masked image) لأغراض إعادة الرسم (inpainting).