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

# CogView3Plus

[كوج فيو 3: توليد صور أدق وأسرع من النص عبر الانتشار المتتابع](https://huggingface.co/papers/2403.05121) من جامعة تسينغهوا و ZhipuAI، بقلم Wendi Zheng و Jiayan Teng و Zhuoyi Yang و Weihan Wang و Jidong Chen و Xiaotao Gu و Yuxiao Dong و Ming Ding و Jie Tang.

ملخص الورقة البحثية هو:

*دفع التقدم الأخير في أنظمة توليد الصور من النص إلى الصورة بشكل كبير بواسطة نماذج الانتشار. ومع ذلك، لا تزال نماذج الانتشار أحادية المرحلة لتوليد الصور من النص تواجه تحديات من حيث الكفاءة الحسابية وتحسين تفاصيل الصورة. لمعالجة هذه المشكلة، نقترح CogView3، وهو إطار متسلسل مبتكر يعزز أداء توليد الصور من النص إلى الصورة عبر الانتشار. CogView3 هو أول نموذج يطبّق الانتشار المتتابع في مجال توليد الصور من النص، حيث ينفذ المهمة أولاً بإنشاء صور منخفضة الدقة، ثم تطبيق فائق الدقة القائم على التتابع. لا تؤدي هذه المنهجية فقط إلى مخرجات تنافسية لتوليد الصور من النص، بل تقلل أيضاً بشكل كبير من تكاليف التدريب والاستدلال. تُظهر نتائجنا التجريبية أن CogView3 يتفوق على SDXL، وهو نموذج الانتشار المفتوح المصدر الحالي لتوليد الصور من النص الذي يمثل أحدث ما توصلت إليه التقنية، بنسبة 77.0% في التقييمات البشرية، بينما يتطلب فقط حوالي 1/2 من وقت الاستدلال. يحقق المتغير المُقطّر من CogView3 أداءً مماثلاً بينما يستخدم فقط 1/10 من وقت الاستدلال الذي يتطلبه SDXL.*

> [!TIP]
> تأكد من الاطلاع على [دليل المجدولين](../../using-diffusers/schedulers) لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

تمت مساهمة خط المعالجة هذا بواسطة [zRzRzRzRzRzRzR](https://github.com/zRzRzRzRzRzRzR). يمكن العثور على قاعدة الكود الأصلية [هنا](https://huggingface.co/THUDM). يمكن العثور على الأوزان الأصلية تحت [hf.co/THUDM](https://huggingface.co/THUDM).

## CogView3PlusPipeline[[diffusers.CogView3PlusPipeline]]

#### diffusers.CogView3PlusPipeline[[diffusers.CogView3PlusPipeline]]

```python
diffusers.CogView3PlusPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKL, transformer: CogView3PlusTransformer2DModel, scheduler: diffusers.schedulers.scheduling_ddim_cogvideox.CogVideoXDDIMScheduler | diffusers.schedulers.scheduling_dpm_cogvideox.CogVideoXDPMScheduler)
```

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

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

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

text_encoder (`T5EncoderModel`) : مُشفِّر نص ثابت. يستخدم CogView3Plus [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel)؛ وتحديداً النسخة [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

tokenizer (`T5Tokenizer`) : مُجزِّئ من الفئة [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

transformer ([CogView3PlusTransformer2DModel](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.CogView3PlusTransformer2DModel)) : نموذج `CogView3PlusTransformer2DModel` مشروط بالنص، يُستخدم لإزالة الضوضاء من الكامنات المُرمّزة للصورة.

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

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

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

#### __call__[[diffusers.CogView3PlusPipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, negative_prompt: str | list[str] | None = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] | None = None, guidance_scale: float = 5.0, num_images_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, original_size: tuple[int, int] | None = None, crops_coords_top_left: tuple = (0, 0), output_type: str = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 224)
```

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

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

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

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

height (`int`، *اختياري*، القيمة الافتراضية هي self.transformer.config.sample_size * self.vae_scale_factor) : ارتفاع الصورة المولّدة بالبكسلات. إذا لم يُقدَّم، يتم تعيينه إلى 1024.

width (`int`، *اختياري*، القيمة الافتراضية هي self.transformer.config.sample_size * self.vae_scale_factor) : عرض الصورة المولدة بالبكسلات. إذا لم يُحدد، فسيتم ضبطه على 1024.

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

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

guidance_scale (`float`، *اختياري*، القيمة الافتراضية `5.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`) : عدد الصور التي سيتم توليدها لكل موجه.

eta (`float`، *اختياري*، القيمة الافتراضية 0.0) : يتوافق مع المعامل eta (η) من ورقة [DDIM](https://arxiv.org/abs/2010.02502). ينطبق فقط على [DDIMScheduler](/docs/diffusers/main/ar/api/schedulers/ddim#diffusers.DDIMScheduler)، ويُتجاهل في المجدولين الآخرين.

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

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

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

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

original_size (`tuple[int]`، *اختياري*، القيمة الافتراضية (1024, 1024)) : إذا لم تكن `original_size` مطابقة لـ `target_size`، فسيبدو أن الصورة قد خضعت لتقليل أو زيادة حجمها. القيمة الافتراضية لـ `original_size` هي `(height, width)` إذا لم تُحدد. جزء من التكييف الدقيق (micro-conditioning) الخاص بـ SDXL كما هو موضح في القسم 2.2 من [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

crops_coords_top_left (`tuple[int]`، *اختياري*، القيمة الافتراضية (0, 0)) : يمكن استخدام `crops_coords_top_left` لتوليد صورة تبدو وكأنها "مقتطعة" من الموضع `crops_coords_top_left` إلى الأسفل. عادةً ما يتم تحقيق صور مفضلة ومركزة جيدًا عن طريق تعيين `crops_coords_top_left` إلى (0, 0). جزء من micro-conditioning الخاص بـ SDXL كما هو موضح في القسم 2.2 من [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

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

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput` بدلاً من tuple عادي.

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`، القيمة الافتراضية هي `224`) : الحد الأقصى لطول التسلسل في الموجه المُرمَّز. يمكن ضبطه على قيم أخرى، لكن قد يؤدي ذلك إلى نتائج أقل جودة.

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

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

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

أمثلة:
```python
>>> import torch
>>> from diffusers import CogView3PlusPipeline

>>> pipe = CogView3PlusPipeline.from_pretrained("THUDM/CogView3-Plus-3B", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A photo of an astronaut riding a horse on mars"
>>> image = pipe(prompt).images[0]
>>> image.save("output.png")
```

#### encode_prompt[[diffusers.CogView3PlusPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 224, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

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

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

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

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

do_classifier_free_guidance (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم استخدام classifier free guidance أم لا.

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

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

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

max_sequence_length (`int`، القيمة الافتراضية هي `224`) : الحد الأقصى لطول التسلسل في الموجه المُرمَّز. يمكن ضبطه على قيم أخرى، لكن قد يؤدي ذلك إلى نتائج أقل جودة.

device : (`torch.device`, *اختياري*): جهاز torch

dtype : (`torch.dtype`, *اختياري*): torch dtype

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.

## CogView3PipelineOutput[[diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput]]

#### diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput[[diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput]]

```python
diffusers.pipelines.cogview3.pipeline_output.CogView3PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

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

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

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

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