#
# مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")
# لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.
# يمكنك الحصول على نسخة من الترخيص في
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات
# تُوزَّع بموجب الرخصة على أساس "كما هي"،
# بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.
# راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و
# قيود بموجب الترخيص. -->

# PRX Pixel

PRXPixel هو نموذج لتوليد الصور من النص في فضاء البكسلات من تطوير Photoroom. يقوم نموذج `PRXTransformer2DModel` بحجم ~7B بإزالة الضوضاء من صور RGB الخام مباشرةً — دون الحاجة إلى VAE. يعتمد النموذج على مُشفّر نصي Qwen3-VL كشرط، ويستخدم مطابقة التدفق حيث يتنبأ الترانسفورمر بالصورة النظيفة في كل خطوة (تنبؤ x). يُدخل دقة التوليد في تعديل خطوة الزمن ليصبح النموذج على دراية بالحجم المستهدف.

## النماذج المتاحة

| النموذج | دقة | الوصف | المعلمات المقترحة | نوع البيانات الموصى به |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | نموذج في فضاء البكسل بحجم ~7B مع مشفّر نصوص Qwen3-VL | 28 خطوة، cfg=5.0 | `torch.bfloat16` |

## تحميل خط الأنابيب

يتطلب [PRXPixelPipeline](/docs/diffusers/main/ar/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline) استخدام `transformers >= 4.57` (الإصدار الذي أدخل `Qwen3VLTextModel`). حمّله باستخدام [from_pretrained()](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained):

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
image.save("prxpixel_output.png")
```

## تحسين الذاكرة

للمحيطات ذات القيود على الذاكرة:

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

# Or use sequential CPU offload for even lower memory
pipe.enable_sequential_cpu_offload()
```

## PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

#### diffusers.PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

```python
diffusers.PRXPixelPipeline(transformer: PRXTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder: PreTrainedModel, tokenizer: transformers.models.auto.tokenization_auto.AutoTokenizer | transformers.tokenization_utils_base.PreTrainedTokenizerBase, default_sample_size: int | None = 1024, prompt_max_tokens: int = 256, noise_scale: float = 2.0)
```

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

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

transformer (`PRXTransformer2DModel`) : مُزيل الضوضاء PRX الذي يحتوي على حوالي 7 مليارات من المعاملات. في حالة PRXPixel، يُبنى هذا النموذج باستخدام `in_channels=3`، وعنق زجاجة `img_in`، و`resolution_embeds=True`، ويُدرَّب للتنبؤ بالصورة النظيفة `x0`.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدول مطابقة التدفق (Flow-matching scheduler) المستخدم لإزالة الضوضاء من الكمونيات (latents) في (فضاء البكسلات).

text_encoder (`PreTrainedModel`) : العمود الفقري النصي لنموذج Qwen3-VL المستخدم لتشفير الأوامر (يتم استبعاد برج الرؤية). يجب أن يعيد `last_hidden_state`.

tokenizer (`PreTrainedTokenizerBase`) : مُجزِّئ لـ `text_encoder` (يُحمَّل عادةً عبر `AutoTokenizer`).

default_sample_size (`int`، *اختياري*، القيمة الافتراضية 1024) : الارتفاع/العرض الافتراضي المستخدم عندما لا يُمرَّر أيٌّ منهما إلى `__call__`.

prompt_max_tokens (`int`، *اختياري*، القيمة الافتراضية 256) : عدد رموز النص التي يتم ملؤها/قصّها إلى هذا العدد قبل الترميز.

noise_scale (`float`، *اختياري*، القيمة الافتراضية 2.0) : المقياس المطبَّق على الضوضاء الغاوسية الأولية. يتم تدريب PRXPixel بمقياس ضوضاء أولية غير وحدة، لذا يجب أن يبدأ أخذ العينات من `randn * noise_scale`.

خط أنابيب لتوليد الصور من النص باستخدام نموذج PRXPixel.

PRXPixel هو خط أنابيب مستقل لتوليد الصور من النص في فضاء البكسل. يقوم بإزالة الضوضاء من بيانات RGB الخام مباشرةً باستخدام نموذج `PRXTransformer2DModel` بحجم حوالي 7 مليارات معامل، ولا يحتوي على VAE (حيث يحدث التوليد بالكامل في فضاء البكسل، لذا فإن المخرج بعد إزالة الضوضاء *هو* الصورة نفسها). يتم ترميز الأوامر النصية باستخدام مشفر نصوص Qwen3-VL (مع استبعاد برج الرؤية). على عكس [PRXPipeline](/docs/diffusers/main/ar/api/pipelines/prx#diffusers.PRXPipeline)، يتم تدريب المحوّل باستخدام التنبؤ بـ x: ففي كل خطوة يتنبأ بالصورة النظيفة `x0`، والتي يتم تحويلها إلى سرعة مطابقة للتدفق قبل خطوة المجدول. يبدأ العينة من `randn * noise_scale` (القيمة الافتراضية لـ `noise_scale=2.0`)، والدقة الافتراضية هي 1024 بكسل.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع خطوط الأنابيب (مثل التنزيل أو الحفظ، أو التشغيل على جهاز معين، وما إلى ذلك).

أمثلة:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### __call__[[diffusers.PRXPixelPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', height: int | None = None, width: int | None = None, num_inference_steps: int = 28, timesteps: list = None, guidance_scale: float = 4.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, use_resolution_binning: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'])
```

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

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

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

negative_prompt (`str`، *اختياري*، القيمة الافتراضية `""`) : الأمر أو الأوامر التي لا ينبغي أن توجّه توليد الصورة. يتم تجاهلها عند عدم استخدام التوجيه (أي يتم تجاهلها إذا كانت قيمة `guidance_scale` أقل من `1`).

height (`int`، *اختياري*، القيمة الافتراضية هي `default_sample_size`) : ارتفاع الصورة المولّدة بالبكسل.

width (`int`، *اختياري*، القيمة الافتراضية هي `default_sample_size`) : عرض الصورة المولدة بالبكسل.

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

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

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 4.0) : مقياس التوجيه كما هو مُعرَّف في [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة.

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

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : مولّد واحد أو قائمة من [مولّدات torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

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

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

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

prompt_attention_mask (`torch.BoolTensor`، *اختياري*) : قناع الانتباه المُولَّد مسبقًا لـ`prompt_embeds`. إذا لم يُقدَّم، فسيتم توليد قناع الانتباه من معامل الإدخال `prompt`.

negative_prompt_attention_mask (`torch.BoolTensor`، *اختياري*) : قناع انتباه مُولّد مسبقًا لـ`negative_prompt_embeds`. إذا لم يُقدَّم وكان `guidance_scale > 1`، فسيتم توليد قناع الانتباه من نص فارغ.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [PRXPipelineOutput](/docs/diffusers/main/ar/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) بدلاً من tuple عادي.

use_resolution_binning (`bool`، *اختياري*، القيمة الافتراضية `True`) : إذا تم ضبطه على `True`، فإن الارتفاع والعرض المطلوبين يُخضعان أولاً لعملية إسقاط إلى أقرب دقة باستخدام صناديق نسبة العرض إلى الارتفاع المحددة مسبقاً. وبعد فك ترميز الكمّيات الكامنة الناتجة إلى صور، يتم تغيير حجمها مرة أخرى إلى الدقة المطلوبة. مفيد لتوليد صور غير مربعة بأدق دقة ممكنة.

callback_on_step_end (`Callable`، *اختياري*) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: `callback_on_step_end(self, step, timestep, callback_kwargs)`. ستتضمن `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`.

**يعيد:** [PRXPipelineOutput](/docs/diffusers/main/ar/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) أو `tuple`

[PRXPipelineOutput](/docs/diffusers/main/ar/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) إذا كان `return_dict` هو True، وإلا فسيكون `tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

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

أمثلة:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### check_inputs[[diffusers.PRXPixelPipeline.check_inputs]]

```python
check_inputs(prompt: str | list[str], height: int, width: int, guidance_scale: float, callback_on_step_end_tensor_inputs: list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None)
```

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

تحقق من أن جميع المدخلات بصيغة صحيحة.

#### encode_prompt[[diffusers.PRXPixelPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, tokenizer_max_length: int | None = None, skip_text_cleaning: bool = False)
```

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

ترميز موجه النص باستخدام مُرمِّز النص ومُجزِّئ النص القياسيين، أو استخدام التضمينات المحسوبة مسبقًا.

#### prepare_latents[[diffusers.PRXPixelPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, dtype: dtype, device: device, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
```

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

جهّز الكمونيات الأولية لعملية الانتشار.

تتدرّب PRXPixel باستخدام مقياس ضوضاء أولي غير موحد، لذا تُضرب الضوضاء المُستخرجة في `self.config.noise_scale`.

## PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

#### diffusers.pipelines.prx.PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

```python
diffusers.pipelines.prx.PRXPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

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

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

images (`list[PIL.Image.Image]` أو `np.ndarray`) : قائمة من صور PIL منزوعة الضوضاء بطول `batch_size` أو مصفوفة numpy بأبعاد `(batch_size, height, width, num_channels)`. تمثل صور PIL أو مصفوفة numpy صورًا منزوعة الضوضاء من خط أنابيب الانتشار.

فئة الإخراج لخطوط أنابيب PRX.