# Stable Cascade

تم بناء هذا النموذج على بنية [Würstchen](https://openreview.net/forum?id=gU58d5QeGv)، والفارق الرئيسي بينه وبين النماذج الأخرى مثل Stable Diffusion هو أنه يعمل في مساحة كامنة أصغر بكثير. لماذا هذا مهم؟ كلما كانت المساحة الكامنة أصغر، كان بإمكانك تشغيل الاستدلال **بسرعة أكبر** وأصبح التدريب **أرخص**. ما مدى صغر المساحة الكامنة؟ يستخدم Stable Diffusion معامل ضغط قدره 8، مما يؤدي إلى ترميز صورة 1024x1024 إلى 128x128. يحقق Stable Cascade معامل ضغط قدره 42، مما يعني أنه من الممكن ترميز صورة 1024x1024 إلى 24x24، مع الحفاظ على إعادة بناء حادة. ثم يتم تدريب النموذج الشرطي النصي في المساحة الكامنة المضغوطة بشدة. حققت الإصدارات السابقة من هذه البنية خفضاً في التكلفة بنسبة 16x مقارنةً بـ Stable Diffusion 1.5.

لذلك، يناسب هذا النوع من النماذج الاستخدامات التي تكون فيها الكفاءة مهمة. علاوة على ذلك، جميع الامتدادات المعروفة مثل الضبط الدقيق (finetuning) وLoRA وControlNet وIP-Adapter وLCM وغيرها ممكنة أيضًا باستخدام هذه الطريقة.

يمكن العثور على قاعدة الكود الأصلية في [Stability-AI/StableCascade](https://github.com/Stability-AI/StableCascade).

## نظرة عامة على النموذج
يتألف Stable Cascade من ثلاثة نماذج: المرحلة A، والمرحلة B، والمرحلة C، وتمثل تدرجًا لتوليد الصور، ومن هنا جاء اسم "Stable Cascade".

تُستخدم المرحلتان A و B لضغط الصور، على غرار الدور الذي تؤديه وحدة VAE في Stable Diffusion. ومع ذلك، يتيح هذا الإعداد تحقيق نسبة ضغط أعلى بكثير للصور. في حين أن نماذج Stable Diffusion تستخدم عامل ضغط مكاني قدره 8، حيث تُشفَّر صورة بدقة 1024 x 1024 إلى 128 x 128، فإن Stable Cascade يحقق عامل ضغط قدره 42. وهذا يُشفّر صورة بدقة 1024 x 1024 إلى 24 x 24، مع القدرة على فك تشفير الصورة بدقة. ويأتي ذلك بفائدة كبيرة تتمثل في انخفاض تكلفة التدريب والاستدلال. علاوة على ذلك، تتولى المرحلة C توليد الكميات الكامنة الصغيرة ذات الأبعاد 24 x 24 بناءً على وصف نصي.

يعمل نموذج المرحلة C على الكمونيات الصغيرة ذات الأبعاد 24 x 24، ويقوم بإزالة الضوضاء من الكمونيات بناءً على تلميحات النص. كما يُعد هذا النموذج أكبر مكوّن في خط سير عمل التسلسل (Cascade)، وهو مصمَّم للاستخدام مع `StableCascadePriorPipeline`

تُستخدم نماذج المرحلة B والمرحلة A مع `StableCascadeDecoderPipeline` وهي مسؤولة عن توليد الصورة النهائية بناءً على الكميات الكامنة الصغيرة ذات الأبعاد 24 x 24.

> [!WARNING]
> توجد بعض القيود على أنواع البيانات التي يمكن استخدامها مع نماذج Stable Cascade. لا تدعم نقاط التفتيش الرسمية لـ `StableCascadePriorPipeline` نوع البيانات `torch.float16`. يُرجى استخدام `torch.bfloat16` بدلاً من ذلك.
>
> للاستخدام من نوع البيانات `torch.bfloat16` مع `StableCascadeDecoderPipeline`، يجب أن يكون لديك PyTorch 2.2.0 أو إصدار أحدث مثبّتًا. وهذا يعني أيضًا أن استخدام `StableCascadeCombinedPipeline` مع `torch.bfloat16` يتطلب PyTorch 2.2.0 أو إصدار أحدث، نظرًا لأنه يستدعي `StableCascadeDecoderPipeline` داخليًا.
>
> إذا لم يكن من الممكن تثبيت PyTorch 2.2.0 أو إصدار أحدث في بيئتك، يمكن استخدام `StableCascadeDecoderPipeline` بشكل مستقل مع نوع البيانات `torch.float16`. يمكنك تنزيل أوزان الدقة الكاملة أو أوزان النسخة `bf16` للخط.pipe وتحويل الأوزان إلى `torch.float16`.

## مثال على الاستخدام

```python
import torch
from diffusers import StableCascadeDecoderPipeline, StableCascadePriorPipeline

prompt = "an image of a shiba inu, donning a spacesuit and helmet"
negative_prompt = ""

prior = StableCascadePriorPipeline.from_pretrained("stabilityai/stable-cascade-prior", variant="bf16", dtype=torch.bfloat16)
decoder = StableCascadeDecoderPipeline.from_pretrained("stabilityai/stable-cascade", variant="bf16", dtype=torch.float16)

prior.enable_model_cpu_offload()
prior_output = prior(
    prompt=prompt,
    height=1024,
    width=1024,
    negative_prompt=negative_prompt,
    guidance_scale=4.0,
    num_images_per_prompt=1,
    num_inference_steps=20
)

decoder.enable_model_cpu_offload()
decoder_output = decoder(
    image_embeddings=prior_output.image_embeddings.to(torch.float16),
    prompt=prompt,
    negative_prompt=negative_prompt,
    guidance_scale=0.0,
    output_type="pil",
    num_inference_steps=10
).images[0]
decoder_output.save("cascade.png")
```

## استخدام الإصدارات الخفيفة من نماذج المرحلة ب والمرحلة ج

```python
import torch
from diffusers import (
    StableCascadeDecoderPipeline,
    StableCascadePriorPipeline,
    StableCascadeUNet,
)

prompt = "an image of a shiba inu, donning a spacesuit and helmet"
negative_prompt = ""

prior_unet = StableCascadeUNet.from_pretrained("stabilityai/stable-cascade-prior", subfolder="prior_lite")
decoder_unet = StableCascadeUNet.from_pretrained("stabilityai/stable-cascade", subfolder="decoder_lite")

prior = StableCascadePriorPipeline.from_pretrained("stabilityai/stable-cascade-prior", prior=prior_unet)
decoder = StableCascadeDecoderPipeline.from_pretrained("stabilityai/stable-cascade", decoder=decoder_unet)

prior.enable_model_cpu_offload()
prior_output = prior(
    prompt=prompt,
    height=1024,
    width=1024,
    negative_prompt=negative_prompt,
    guidance_scale=4.0,
    num_images_per_prompt=1,
    num_inference_steps=20
)

decoder.enable_model_cpu_offload()
decoder_output = decoder(
    image_embeddings=prior_output.image_embeddings,
    prompt=prompt,
    negative_prompt=negative_prompt,
    guidance_scale=0.0,
    output_type="pil",
    num_inference_steps=10
).images[0]
decoder_output.save("cascade.png")
```

## تحميل نقاط التفتيش الأصلية باستخدام `from_single_file`

يُؤمَّن دعم تحميل نقاط التفتيش بالصيغة الأصلية عبر طريقة `from_single_file` في StableCascadeUNet.

```python
import torch
from diffusers import (
    StableCascadeDecoderPipeline,
    StableCascadePriorPipeline,
    StableCascadeUNet,
)

prompt = "an image of a shiba inu, donning a spacesuit and helmet"
negative_prompt = ""

prior_unet = StableCascadeUNet.from_single_file(
    "https://huggingface.co/stabilityai/stable-cascade/resolve/main/stage_c_bf16.safetensors",
    dtype=torch.bfloat16
)
decoder_unet = StableCascadeUNet.from_single_file(
    "https://huggingface.co/stabilityai/stable-cascade/blob/main/stage_b_bf16.safetensors",
    dtype=torch.bfloat16
)

prior = StableCascadePriorPipeline.from_pretrained("stabilityai/stable-cascade-prior", prior=prior_unet, dtype=torch.bfloat16)
decoder = StableCascadeDecoderPipeline.from_pretrained("stabilityai/stable-cascade", decoder=decoder_unet, dtype=torch.bfloat16)

prior.enable_model_cpu_offload()
prior_output = prior(
    prompt=prompt,
    height=1024,
    width=1024,
    negative_prompt=negative_prompt,
    guidance_scale=4.0,
    num_images_per_prompt=1,
    num_inference_steps=20
)

decoder.enable_model_cpu_offload()
decoder_output = decoder(
    image_embeddings=prior_output.image_embeddings,
    prompt=prompt,
    negative_prompt=negative_prompt,
    guidance_scale=0.0,
    output_type="pil",
    num_inference_steps=10
).images[0]
decoder_output.save("cascade-single-file.png")
```

## الاستخدامات

### الاستخدام المباشر

يُعدّ النموذج مخصصًا لأغراض البحث حاليًا. وتشمل مجالات البحث والمهام المحتملة

- أبحاث حول النماذج التوليدية.
- النشر الآمن للنماذج التي لديها القدرة على توليد محتوى ضار.
- استكشاف وفهم القيود والتحيزات في النماذج التوليدية.
- إنشاء الأعمال الفنية واستخدامها في التصميم وعمليات فنية أخرى.
- التطبيقات في الأدوات التعليمية أو الإبداعية.

يُوصف الاستخدام المستثنى أدناه.

### الاستخدام خارج النطاق

لم يتم تدريب النموذج ليكون تمثيلاً دقيقاً أو حقيقياً للأشخاص أو الأحداث، وبالتالي فإن استخدام النموذج لتوليد مثل هذا المحتوى يقع خارج نطاق قدرات هذا النموذج. يجب عدم استخدام النموذج بأي طريقة تنتهك [سياسة الاستخدام المقبولة](https://stability.ai/use-policy) لشركة Stability AI.

## القيود والتحيز

### القيود
- قد لا يتم توليد الوجوه والأشخاص بشكل عام بشكل صحيح.
- جزء الترميز التلقائي في النموذج يفقد بعض البيانات.

## StableCascadeCombinedPipeline[[diffusers.StableCascadeCombinedPipeline]]

#### diffusers.StableCascadeCombinedPipeline[[diffusers.StableCascadeCombinedPipeline]]

```python
diffusers.StableCascadeCombinedPipeline(tokenizer: CLIPTokenizer, text_encoder: CLIPTextModelWithProjection, decoder: StableCascadeUNet, scheduler: DDPMWuerstchenScheduler, vqgan: PaellaVQModel, prior_prior: StableCascadeUNet, prior_text_encoder: CLIPTextModelWithProjection, prior_tokenizer: CLIPTokenizer, prior_scheduler: DDPMWuerstchenScheduler, prior_feature_extractor: transformers.models.clip.image_processing_pil_clip.CLIPImageProcessorPil | None = None, prior_image_encoder: transformers.models.clip.modeling_clip.CLIPVisionModelWithProjection | None = None)
```

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

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

tokenizer (`CLIPTokenizer`) : مُرمِّز فك الترميز الذي يُستخدم للمدخلات النصية.

text_encoder (`CLIPTextModelWithProjection`) : مُشفِّر النص المُفكِّك الذي يُستخدم للمدخلات النصية.

decoder (`StableCascadeUNet`) : نموذج المُفكِّك (decoder) المستخدم في خط أنابيب توليد الصور عبر المُفكِّك.

scheduler (`DDPMWuerstchenScheduler`) : المجدول المستخدم في خط أنابيب توليد صور المُفكِّك.

vqgan (`PaellaVQModel`) : نموذج VQGAN الذي سيُستخدم في خط أنابيب توليد الصور عبر المُفكِّك.

prior_prior (`StableCascadeUNet`) : النموذج المسبق الذي سيُستخدم في خط أنابيب المسبق.

prior_text_encoder (`CLIPTextModelWithProjection`) : مُشفِّر النص السابق الذي يُستخدم للمدخلات النصية.

prior_tokenizer (`CLIPTokenizer`) : مُجزِّئ الرموز السابق الذي يُستخدم للمدخلات النصية.

prior_scheduler (`DDPMWuerstchenScheduler`) : المجدول الذي سيتم استخدامه في خط أنابيب المسبق.

prior_feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPImageProcessor)) : نموذج يستخرج الميزات من الصور المولّدة لاستخدامها كمدخلات لـ `image_encoder`.

prior_image_encoder (`CLIPVisionModelWithProjection`) : مُشفِّر صور CLIP مجمّد ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)).

خط أنابيب مجمّع لتوليد الصور من النص باستخدام Stable Cascade.

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

#### __call__[[diffusers.StableCascadeCombinedPipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, images: typing.Union[torch.Tensor, list[torch.Tensor], PIL.Image.Image, list[PIL.Image.Image]] = None, height: int = 512, width: int = 512, prior_num_inference_steps: int = 60, prior_guidance_scale: float = 4.0, num_inference_steps: int = 12, decoder_guidance_scale: float = 0.0, negative_prompt: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, prior_callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, prior_callback_on_step_end_tensor_inputs: list[str] = ['latents'], callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

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

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

prompt (`str` أو `list[str]`) : الأمر أو الأوامر التي تُوجّه توليد الصورة للمُقدِّم والمُفكِّك.

images (`torch.Tensor`، `PIL.Image.Image`، `list[torch.Tensor]`، `list[PIL.Image.Image]`، *اختياري*) : الصور التي تُوجّه توليد الصور للسابق.

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

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

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

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

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

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

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

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

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

prior_num_inference_steps (`int | dict[float, int]`، *اختياري*، القيمة الافتراضية 60) : عدد خطوات إزالة الضوضاء السابقة. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال. للحصول على توزيع أكثر تحديدًا للخطوات الزمنية، يمكنك تمرير `prior_timesteps` مخصصة

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

decoder_guidance_scale (`float`، *اختياري*، القيمة الافتراضية 0.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`، وعادةً على حساب انخفاض جودة الصورة.

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

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

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر من بين: `"pil"` (`PIL.Image.Image`)، `"np"` (`np.array`) أو `"pt"` (`torch.Tensor`).

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

prior_callback_on_step_end (`Callable`، *اختياري*) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: `prior_callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`.

prior_callback_on_step_end_tensor_inputs (`list`، *اختياري*) : قائمة مدخلات المصفوفات (tensors) لدالة `prior_callback_on_step_end`. سيتم تمرير المصفوفات المحددة في القائمة كحجة `callback_kwargs`. لن تتمكن من تضمين متغيرات غير مدرجة في خاصية `._callback_tensor_inputs` لفئة خط الأنابيب (pipeline) الخاص بك.

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) الخاص بك.

**يعيد:**

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

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

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

>>> pipe = StableCascadeCombinedPipeline.from_pretrained(
...     "stabilityai/stable-cascade", variant="bf16", torch_dtype=torch.bfloat16
... )
>>> pipe.enable_model_cpu_offload()
>>> prompt = "an image of a shiba inu, donning a spacesuit and helmet"
>>> images = pipe(prompt=prompt)
```

#### enable_model_cpu_offload[[diffusers.StableCascadeCombinedPipeline.enable_model_cpu_offload]]

```python
enable_model_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```

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

ينقل جميع النماذج إلى وحدة المعالجة المركزية (CPU) باستخدام accelerate، مما يقلل من استهلاك الذاكرة مع تأثير ضئيل على الأداء. مقارنةً بـ `enable_sequential_cpu_offload`، تنقل هذه الطريقة نموذجًا كاملًا واحدًا في كل مرة إلى وحدة معالجة الرسوميات (GPU) عند استدعاء طريقة `forward` الخاصة به، ويبقى النموذج في وحدة معالجة الرسوميات حتى تشغيل النموذج التالي. تكون وفورات الذاكرة أقل مما هي عليه مع `enable_sequential_cpu_offload`، لكن الأداء يكون أفضل بكثير بسبب التنفيذ التكراري لـ `unet`.

#### enable_sequential_cpu_offload[[diffusers.StableCascadeCombinedPipeline.enable_sequential_cpu_offload]]

```python
enable_sequential_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```

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

ينقل جميع النماذج (قواميس الحالة الخاصة بـ `unet` و`text_encoder` و`vae` و`safety checker`) إلى وحدة المعالجة المركزية (CPU) باستخدام 🤗 Accelerate، مما يقلل من استهلاك الذاكرة بشكل كبير. يتم نقل النماذج إلى `torch.device('meta')` وتحميلها على وحدة معالجة الرسوميات (GPU) فقط عند استدعاء طريقة `forward` الخاصة بالوحدة الفرعية المعنية. يتم تنفيذ النقل على أساس الوحدات الفرعية. تكون وفورات الذاكرة أعلى مما هي عليه عند استخدام `enable_model_cpu_offload`، لكن الأداء يكون أدنى.

## StableCascadePriorPipeline[[diffusers.StableCascadePriorPipeline]]

#### diffusers.StableCascadePriorPipeline[[diffusers.StableCascadePriorPipeline]]

```python
diffusers.StableCascadePriorPipeline(tokenizer: CLIPTokenizer, text_encoder: CLIPTextModelWithProjection, prior: StableCascadeUNet, scheduler: DDPMWuerstchenScheduler, resolution_multiple: float = 42.67, feature_extractor: transformers.models.clip.image_processing_pil_clip.CLIPImageProcessorPil | None = None, image_encoder: transformers.models.clip.modeling_clip.CLIPVisionModelWithProjection | None = None)
```

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

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

prior (`StableCascadeUNet`) : الشبكة العصبية التوليدية (UNet) الخاصة بنموذج Stable Cascade، والتي تُستخدم لتقريب تمثيل الصورة (embedding) من تمثيل النص و/أو تمثيل الصورة.

text_encoder (`CLIPTextModelWithProjection`) : مُشفِّر نص ثابت ([laion/CLIP-ViT-bigG-14-laion2B-39B-b160k](https://huggingface.co/laion/CLIP-ViT-bigG-14-laion2B-39B-b160k)).

feature_extractor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPImageProcessor)) : نموذج يستخرج الميزات من الصور المولّدة لاستخدامها كمدخلات لـ `image_encoder`.

image_encoder (`CLIPVisionModelWithProjection`) : مُشفِّر صور CLIP مجمّد ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)).

tokenizer (`CLIPTokenizer`) : مُقسِّم من الفئة [CLIPTokenizer](https://huggingface.co/docs/transformers/v4.21.0/en/model_doc/clip#transformers.CLIPTokenizer).

scheduler (`DDPMWuerstchenScheduler`) : مُجدوِل يُستخدم بالاقتران مع `prior` لتوليد تضمين الصورة.

resolution_multiple ('float', *اختياري*، القيمة الافتراضية 42.67) : الدقة الافتراضية لصور متعددة يتم توليدها.

خط أنابيب لتوليد المسبق (prior) للصور في Stable Cascade.

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

#### __call__[[diffusers.StableCascadePriorPipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, images: typing.Union[torch.Tensor, list[torch.Tensor], PIL.Image.Image, list[PIL.Image.Image]] = None, height: int = 1024, width: int = 1024, num_inference_steps: int = 20, timesteps: list[float] = None, guidance_scale: float = 4.0, negative_prompt: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, image_embeds: typing.Optional[torch.Tensor] = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pt', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

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

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

prompt (`str` أو `list[str]`) : الأمر أو الأوامر التي تُوجّه توليد الصورة.

images (`torch.Tensor` أو `PIL.Image.Image` أو `list[torch.Tensor]` أو `list[PIL.Image.Image]`، *اختياري*) : صورة مرجعية أو صور مرجعية تُستخدم لتكييف توليد المسبق. عند تقديمها، تُشتق تمثيلات الصور من الصورة وتُدمج مع موجه النص.

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

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

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

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

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

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

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

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

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

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

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

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` العشوائي المُقدَّم.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر من بين: `"pil"` (`PIL.Image.Image`)، `"np"` (`np.array`) أو `"pt"` (`torch.Tensor`).

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [ImagePipelineOutput](/docs/diffusers/main/ar/api/pipelines/consistency_models#diffusers.ImagePipelineOutput) بدلاً من 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) الخاص بك.

**يعيد:**

`StableCascadePriorPipelineOutput` أو `tuple` `StableCascadePriorPipelineOutput` إذا كان `return_dict` صحيحًا، وإلا فسيكون `tuple`. عند إرجاع tuple، يكون العنصر الأول قائمة تضم تمثيلات الصور المولّدة.

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

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

>>> prior_pipe = StableCascadePriorPipeline.from_pretrained(
...     "stabilityai/stable-cascade-prior", torch_dtype=torch.bfloat16
... ).to("cuda")

>>> prompt = "an image of a shiba inu, donning a spacesuit and helmet"
>>> prior_output = pipe(prompt)
```

## StableCascadePriorPipelineOutput[[diffusers.pipelines.stable_cascade.pipeline_stable_cascade_prior.StableCascadePriorPipelineOutput]]

#### diffusers.pipelines.stable_cascade.pipeline_stable_cascade_prior.StableCascadePriorPipelineOutput[[diffusers.pipelines.stable_cascade.pipeline_stable_cascade_prior.StableCascadePriorPipelineOutput]]

```python
diffusers.pipelines.stable_cascade.pipeline_stable_cascade_prior.StableCascadePriorPipelineOutput(image_embeddings: typing.Union[torch.Tensor, numpy.ndarray], prompt_embeds: typing.Union[torch.Tensor, numpy.ndarray], prompt_embeds_pooled: typing.Union[torch.Tensor, numpy.ndarray], negative_prompt_embeds: typing.Union[torch.Tensor, numpy.ndarray], negative_prompt_embeds_pooled: typing.Union[torch.Tensor, numpy.ndarray])
```

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

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

image_embeddings (`torch.Tensor` أو `np.ndarray`) : تمثيلات الصور السابقة لموجّه النص

prompt_embeds (`torch.Tensor`) : تمثيلات نصية للموجّه.

negative_prompt_embeds (`torch.Tensor`) : تمثيلات نصية (Text embeddings) للتلميح السلبي.

فئة الإخراج لـ WuerstchenPriorPipeline.

## StableCascadeDecoderPipeline[[diffusers.StableCascadeDecoderPipeline]]

#### diffusers.StableCascadeDecoderPipeline[[diffusers.StableCascadeDecoderPipeline]]

```python
diffusers.StableCascadeDecoderPipeline(decoder: StableCascadeUNet, tokenizer: CLIPTokenizer, text_encoder: CLIPTextModelWithProjection, scheduler: DDPMWuerstchenScheduler, vqgan: PaellaVQModel, latent_dim_scale: float = 10.67)
```

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

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

tokenizer (`CLIPTokenizer`) : مُجزِّئ CLIP.

text_encoder (`CLIPTextModelWithProjection`) : مُشفِّر النص في CLIP.

decoder (`StableCascadeUNet`) : شبكة unet لفك ترميز Stable Cascade.

vqgan (`PaellaVQModel`) : نموذج VQGAN.

scheduler (`DDPMWuerstchenScheduler`) : مُجدوِل يُستخدم بالاقتران مع `prior` لتوليد تضمين الصورة.

latent_dim_scale (float, `optional`, الافتراضي 10.67) : مُضاعِف لتحديد حجم فضاء VQ الكامن من تضمينات الصورة. إذا كانت تضمينات الصورة بارتفاع=24 وعرض=24، فيجب أن يكون شكل VQ الكامن بارتفاع=int(24*10.67)=256 وعرض=int(24*10.67)=256 من أجل مطابقة شروط التدريب.

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

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

#### __call__[[diffusers.StableCascadeDecoderPipeline.__call__]]

```python
__call__(image_embeddings: typing.Union[torch.Tensor, list[torch.Tensor]], prompt: str | list[str] = None, num_inference_steps: int = 10, guidance_scale: float = 0.0, negative_prompt: str | list[str] | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_pooled: typing.Optional[torch.Tensor] = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

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

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

image_embeddings (`torch.Tensor` أو `list[torch.Tensor]`) : تمثيلات الصور (Image Embeddings) إما مستخرجة من صورة أو مولّدة بواسطة نموذج مسبق (Prior Model).

prompt (`str` أو `list[str]`) : الأمر أو الأوامر التي تُوجّه توليد الصورة.

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

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

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

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

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

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

negative_prompt_embeds_pooled (`torch.Tensor`, *اختياري*) : تمثيلات نصية مجمعة سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds_pooled من معامل الإدخال `negative_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` العشوائي المُقدَّم.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر من بين: `"pil"` (`PIL.Image.Image`)، `"np"` (`np.array`) أو `"pt"` (`torch.Tensor`).

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [ImagePipelineOutput](/docs/diffusers/main/ar/api/pipelines/consistency_models#diffusers.ImagePipelineOutput) بدلاً من 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) الخاص بك.

**يعيد:**

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

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

أمثلة:
```py
>>> import torch
>>> from diffusers import StableCascadePriorPipeline, StableCascadeDecoderPipeline

>>> prior_pipe = StableCascadePriorPipeline.from_pretrained(
...     "stabilityai/stable-cascade-prior", torch_dtype=torch.bfloat16
... ).to("cuda")
>>> gen_pipe = StableCascadeDecoderPipeline.from_pretrain(
...     "stabilityai/stable-cascade", torch_dtype=torch.float16
... ).to("cuda")

>>> prompt = "an image of a shiba inu, donning a spacesuit and helmet"
>>> prior_output = pipe(prompt)
>>> images = gen_pipe(prior_output.image_embeddings, prompt=prompt)
```