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

# PRX

يولّد PRX صورًا عالية الجودة من النصوص باستخدام معمارية MMDIT مبسطة لا يتم فيها تحديث رموز النص عبر كتل التحويل. ويعتمد على مطابقة التدفق مع جدولة منفصلة للعينة بكفاءة، ويستخدم نموذج T5Gemma-2B-2B-UL2 من Google لتشفير النصوص متعددة اللغات. ويقدّم التحويلي بحجم حوالي 1.3 مليار معامل استنتاجًا سريعًا دون التضحية بالجودة. يمكنك الاختيار بين Flux VAE (ضغط 8x، 16 قناة كامنة) لجودة وسرعة متوازنتين، أو DC-AE (ضغط 32x، 32 قناة كامنة) للضغط الكامن ومعالجة أسرع.

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

توفر PRX عدة نسخ بإعدادات مختلفة لـ VAE، حيث تم تحسين كل نسخة لدقة محددة. تتفوق النماذج الأساسية عند استخدام الأوامر النصية المفصّلة، إذ تلتقط التكوينات المعقدة والتفاصيل الدقيقة. أما النماذج المُحسّنة عبر التدريب على [مجموعة بيانات Alchemist](https://huggingface.co/datasets/yandex/alchemist) فتحسّن الجودة الجمالية، لا سيما عند استخدام أوامر نصية أبسط.

| النموذج | دقة | تم ضبطها | مُصغَّر | الوصف | الموجّهات المقترحة | المعلمات المقترحة | نوع البيانات الموصى به |
|:-----:|:-----------------:|:----------:|:----------:|:----------:|:----------:|:----------:|:----------:|
| [`Photoroom/prx-256-t2i`](https://huggingface.co/Photoroom/prx-256-t2i)| 256 | لا | لا | نموذج أساسي مُدرَّب مسبقًا عند 256 باستخدام Flux VAE|يعمل بشكل أفضل مع الأوامر التفصيلية بلغة طبيعية|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-256-t2i-sft`](https://huggingface.co/Photoroom/prx-256-t2i-sft)| 512 | نعم | لا | تمت الضبط الدقيق على مجموعة بيانات [Alchemist dataset](https://huggingface.co/datasets/yandex/alchemist) باستخدام Flux VAE | يمكنه التعامل مع أوامر أقل تفصيلاً|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i`](https://huggingface.co/Photoroom/prx-512-t2i)| 512 | لا | لا | نموذج أساسي مُدرَّب مسبقًا عند 512 باستخدام Flux VAE |يعمل بشكل أفضل مع الأوامر التفصيلية بلغة طبيعية|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i-sft`](https://huggingface.co/Photoroom/prx-512-t2i-sft)| 512 | نعم | لا | تمت الضبط الدقيق على مجموعة بيانات [Alchemist dataset](https://huggingface.co/datasets/yandex/alchemist) باستخدام Flux VAE | يمكنه التعامل مع أوامر أقل تفصيلاً بلغة طبيعية|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i-sft-distilled`](https://huggingface.co/Photoroom/prx-512-t2i-sft-distilled)| 512 | نعم | نعم | نموذج مُقطّر من 8 خطوات من [`Photoroom/prx-512-t2i-sft`](https://huggingface.co/Photoroom/prx-512-t2i-sft) | يمكنه التعامل مع أوامر أقل تفصيلاً بلغة طبيعية|8 خطوات، cfg=1.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i-dc-ae`](https://huggingface.co/Photoroom/prx-512-t2i-dc-ae)| 512 | لا | لا | النموذج الأساسي المُدرَّب مسبقًا عند 512 باستخدام [Deep Compression Autoencoder (DC-AE)](https://hanlab.mit.edu/projects/dc-ae)|يعمل بشكل أفضل مع الأوامر التفصيلية بلغة طبيعية|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i-dc-ae-sft`](https://huggingface.co/Photoroom/prx-512-t2i-dc-ae-sft)| 512 | نعم | لا | تم ضبطه بدقة على مجموعة بيانات [Alchemist dataset](https://huggingface.co/datasets/yandex/alchemist) باستخدام [Deep Compression Autoencoder (DC-AE)](https://hanlab.mit.edu/projects/dc-ae) | يمكنه التعامل مع أوامر أقل تفصيلاً بلغة طبيعية|28 خطوة، cfg=5.0| `torch.bfloat16` |
| [`Photoroom/prx-512-t2i-dc-ae-sft-distilled`](https://huggingface.co/Photoroom/prx-512-t2i-dc-ae-sft-distilled)| 512 | نعم | نعم | نموذج مُقطّر من 8 خطوات من [`Photoroom/prx-512-t2i-dc-ae-sft-distilled`](https://huggingface.co/Photoroom/prx-512-t2i-dc-ae-sft-distilled) | يمكنه التعامل مع الأوامر الأقل تفصيلاً باللغة الطبيعية|8 خطوات، cfg=1.0| `torch.bfloat16` |s

راجع [هذه](https://huggingface.co/collections/Photoroom/prx-models-68e66254c202ebfab99ad38e) المجموعة لمزيد من المعلومات.

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

حمّل خط الأنابيب باستخدام [from_pretrained()](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

```py
from diffusers.pipelines.prx import PRXPipeline

# Load pipeline - VAE and text encoder will be loaded from HuggingFace
pipe = PRXPipeline.from_pretrained("Photoroom/prx-512-t2i-sft", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

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

### تحميل المكونات يدويًا

حمّل المكونات بشكل فردي لتخصيص خط الأنابيب، على سبيل المثال لاستخدام نماذج مُكمّاة.

```py
import torch
from diffusers.pipelines.prx import PRXPipeline
from diffusers.models import AutoencoderKL, AutoencoderDC
from diffusers.models.transformers.transformer_prx import PRXTransformer2DModel
from diffusers.schedulers import FlowMatchEulerDiscreteScheduler
from transformers import T5GemmaModel, GemmaTokenizerFast
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig
from transformers import BitsAndBytesConfig as BitsAndBytesConfig

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
# Load transformer
transformer = PRXTransformer2DModel.from_pretrained(
    "checkpoints/prx-512-t2i-sft",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.bfloat16,
)

# Load scheduler
scheduler = FlowMatchEulerDiscreteScheduler.from_pretrained(
    "checkpoints/prx-512-t2i-sft", subfolder="scheduler"
)

# Load T5Gemma text encoder
t5gemma_model = T5GemmaModel.from_pretrained("google/t5gemma-2b-2b-ul2",
                                            quantization_config=quant_config,
                                            dtype=torch.bfloat16)
text_encoder = t5gemma_model.encoder.to(dtype=torch.bfloat16)
tokenizer = GemmaTokenizerFast.from_pretrained("google/t5gemma-2b-2b-ul2")
tokenizer.model_max_length = 256

# Load VAE - choose either Flux VAE or DC-AE
# Flux VAE
vae = AutoencoderKL.from_pretrained("black-forest-labs/FLUX.1-dev",
                                    subfolder="vae",
                                    quantization_config=quant_config,
                                    dtype=torch.bfloat16)

pipe = PRXPipeline(
    transformer=transformer,
    scheduler=scheduler,
    text_encoder=text_encoder,
    tokenizer=tokenizer,
    vae=vae
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"
```

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

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

```py
import torch
from diffusers.pipelines.prx import PRXPipeline

pipe = PRXPipeline.from_pretrained("Photoroom/prx-512-t2i-sft", dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()  # Offload components to CPU when not in use

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

## PRXPipeline[[diffusers.PRXPipeline]]

#### diffusers.PRXPipeline[[diffusers.PRXPipeline]]

```python
diffusers.PRXPipeline(transformer: PRXTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder: T5GemmaEncoder, tokenizer: transformers.models.t5.tokenization_t5.T5Tokenizer | transformers.models.gemma.tokenization_gemma.GemmaTokenizer | transformers.models.auto.tokenization_auto.AutoTokenizer, vae: diffusers.models.autoencoders.autoencoder_kl.AutoencoderKL | diffusers.models.autoencoders.autoencoder_dc.AutoencoderDC | None = None, default_sample_size: int | None = 512)
```

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

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

transformer (`PRXTransformer2DModel`) : نموذج PRX transformer لإزالة الضوضاء من كائنات الصورة المشفرة.

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

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

tokenizer ([`T5TokenizerFast` أو `GemmaTokenizerFast`]) : مُرمِّز (Tokenizer) لمُشفِّر النص.

vae ([AutoencoderKL](/docs/diffusers/main/ar/api/models/autoencoderkl#diffusers.AutoencoderKL) أو [AutoencoderDC](/docs/diffusers/main/ar/api/models/autoencoder_dc#diffusers.AutoencoderDC)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها. يدعم كلا من AutoencoderKL (ضغط 8x) وAutoencoderDC (ضغط 32x).

خط أنابيب لتوليد الصور من النص باستخدام PRX Transformer.

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

#### __call__[[diffusers.PRXPipeline.__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[int] = 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[str] = ['latents'], tokenizer_max_length: int | None = None, skip_text_cleaning: bool = False)
```

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

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

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

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

height (*int*، *optional*، القيمة الافتراضية هي self.transformer.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسل.

width (*int*، *optional*، القيمة الافتراضية هي self.transformer.config.sample_size * self.vae_scale_factor) : عرض الصورة المولّدة بالبكسل.

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

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

guidance_scale (*float*، *optional*، القيمة الافتراضية 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*.

tokenizer_max_length (*int*، *اختياري*) : تجاوز الحد الأقصى لعدد الرموز المستخدمة عند تحويل النص إلى رموز (tokenization) للموجّه (prompt). الافتراضي هو `model_max_length` الخاص بمحوّل الرموز (tokenizer) نفسه عند عدم التعيين.

skip_text_cleaning (*bool*، *اختياري*، القيمة الافتراضية *False*) : إذا كانت *True*، يتم استخدام تنظيف خفيف فقط للموجّه (إصلاح الترميز + إلغاء هروب HTML) بدلاً من خط أنابيب تنظيف DeepFloyd الكامل.

return_dict (*bool*، *اختياري*، القيمة الافتراضية *True*) : ما إذا كان يجب إرجاع [*~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*، *optional*) : قائمة مدخلات المصفوفات (tensors) لدالة *callback_on_step_end*. سيتم تمرير المصفوفات المحددة في القائمة كحجة *callback_kwargs*. لن تتمكن من تضمين سوى المصفوفات المدرجة في خاصية *._callback_tensor_inputs*.

**يعيد:** [*~pipelines.prx.PRXPipelineOutput*] أو *tuple`

[*~pipelines.prx.PRXPipelineOutput*] إذا كان *return_dict* هو True، وإلا فسيكون *tuple. عند إرجاع tuple، يكون العنصر الأول قائمة تحتوي على الصور المولّدة.

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

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

>>> # Load pipeline with from_pretrained
>>> pipe = PRXPipeline.from_pretrained("Photoroom/prx-512-t2i-sft")
>>> pipe.to("cuda")

>>> prompt = "A digital painting of a rusty, vintage tram on a sandy beach"
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prx_output.png")
```

#### check_inputs[[diffusers.PRXPipeline.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.py#L500)

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

#### encode_prompt[[diffusers.PRXPipeline.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.py#L376)

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

#### get_default_resolution[[diffusers.PRXPipeline.get_default_resolution]]

```python
get_default_resolution()
```

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

**يعيد:** `int`

حجم العينة الافتراضي (الارتفاع/العرض) المستخدم للتوليد.

حدد الدقة الافتراضية بناءً على VAE المُحمّل والإعدادات.

#### prepare_latents[[diffusers.PRXPipeline.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.py#L352)

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

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