# Allegro

[أليغرو: فتح الصندوق الأسود لنموذج توليد الفيديو بمستوى تجاري](https://huggingface.co/papers/2410.15458) من RhymesAI، بقلم Yuan Zhou وQiuyue Wang وYuxuan Cai وHuan Yang.

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

*شهد مجال توليد الفيديو تقدماً كبيراً، حيث ساهمت مجتمع المصادر المفتوحة بكمية غنية من الأوراق البحثية والأدوات لتدريب نماذج عالية الجودة. ومع ذلك، على الرغم من هذه الجهود، تبقى المعلومات والموارد المتاحة غير كافية لتحقيق أداء بمستوى تجاري. في هذا التقرير، نفتح الصندوق الأسود ونقدّم Allegro، وهو نموذج متقدم لتوليد الفيديو يتفوق في كلٍّ من الجودة والاتساق الزمني. كما نسلّط الضوء على القيود الحالية في المجال ونقدّم منهجية شاملة لتدريب نماذج توليد فيديو عالية الأداء بمستوى تجاري، مع معالجة جوانب رئيسية مثل البيانات، وهيكلة النموذج، وخط التدريب، والتقييم. تُظهر دراستنا للمستخدمين أن Allegro يتفوق على النماذج مفتوحة المصدر الحالية ومعظم النماذج التجارية، حيث يحتل المرتبة مباشرةً خلف Hailuo وKling. الكود: https://github.com/rhymes-ai/Allegro ، النموذج: https://huggingface.co/rhymes-ai/Allegro ، المعرض: https://rhymes.ai/allegro_gallery .*

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

## التكميم

يساعد التكميم (Quantization) في تقليل متطلبات الذاكرة للنماذج الكبيرة جدًا من خلال تخزين أوزان النموذج في نوع بيانات بدقة أقل. ومع ذلك، قد يكون للتكميم تأثير متباين على جودة الفيديو اعتمادًا على نموذج الفيديو المستخدم.

راجع نظرة عامة حول [التكميم](../../quantization/overview) لمعرفة المزيد حول محركات التكميم المدعومة واختيار محرك تكميم يدعم حالتك الاستخدامية. يوضح المثال أدناه كيفية تحميل [AllegroPipeline](/docs/diffusers/main/ar/api/pipelines/allegro#diffusers.AllegroPipeline) مُكمَّم للاستدلال باستخدام bitsandbytes.

```py
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, AllegroTransformer3DModel, AllegroPipeline
from diffusers.utils import export_to_video
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "rhymes-ai/Allegro",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = AllegroTransformer3DModel.from_pretrained(
    "rhymes-ai/Allegro",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = AllegroPipeline.from_pretrained(
    "rhymes-ai/Allegro",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = (
    "A seaside harbor with bright sunlight and sparkling seawater, with many boats in the water. From an aerial view, "
    "the boats vary in size and color, some moving and some stationary. Fishing boats in the water suggest that this "
    "location might be a popular spot for docking fishing boats."
)
video = pipeline(prompt, guidance_scale=7.5, max_sequence_length=512).frames[0]
export_to_video(video, "harbor.mp4", fps=15)
```

## AllegroPipeline[[diffusers.AllegroPipeline]]

#### diffusers.AllegroPipeline[[diffusers.AllegroPipeline]]

```python
diffusers.AllegroPipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKLAllegro, transformer: AllegroTransformer3DModel, scheduler: KarrasDiffusionSchedulers)
```

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

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

vae (`AllegroAutoEncoderKL3D`) : نموذج الترميز التحويلي التبايني (VAE) لتشفير الفيديو وفك تشفيره إلى التمثيلات الكامنة ومنها.

text_encoder (`T5EncoderModel`) : مُشفِّر نص ثابت. يستخدم PixArt-Alpha [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 ([AllegroTransformer3DModel](/docs/diffusers/main/ar/api/models/allegro_transformer3d#diffusers.AllegroTransformer3DModel)) : نموذج `AllegroTransformer3DModel` مشروط بالنص، يُستخدم لإزالة الضوضاء من كامنات الفيديو المُرمّزة.

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

خط أنابيب لتوليد الفيديو من النص باستخدام Allegro.

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

#### __call__[[diffusers.AllegroPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 100, timesteps: list[int] = None, guidance_scale: float = 7.5, num_frames: int | None = None, height: int | None = None, width: int | None = None, num_videos_per_prompt: int = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = '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[str] = ['latents'], clean_caption: bool = True, max_sequence_length: int = 512)
```

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

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

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

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

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

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

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 7.5) : مقياس التوجيه كما هو مُعرَّف في [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_videos_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد مقاطع الفيديو التي سيتم توليدها لكل موجه.

num_frames : (`int`, *اختياري*، القيمة الافتراضية 88): يتحكم هذا العدد في عدد إطارات الفيديو المولّدة.

height (`int`، *اختياري*، الافتراضي هو self.unet.config.sample_size) : ارتفاع الفيديو المولّد بالبكسل.

width (`int`، *اختياري*، الافتراضي هو self.unet.config.sample_size) : عرض الفيديو المولّد بالبكسل.

eta (`float`، *اختياري*، القيمة الافتراضية 0.0) : يتوافق مع المعامل eta (η) في ورقة DDIM: https://huggingface.co/papers/2010.02502. ينطبق فقط على [schedulers.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.Tensor`، *اختياري*) : توليد. يمكن استخدامه لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم يُقدَّم، فسيتم إنشاء متجه latents مُولّد مسبقًا يحتوي على ضوضاء، مُستخلص من توزيع غاوسي، ليُستخدم كمدخلات لمتجه الفيديو، وذلك عن طريق أخذ عينات باستخدام مولد الأرقام العشوائية `generator` المُقدَّم.

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

prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع انتباه مُولّد مسبقًا لتضمينات النص.

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

negative_prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع انتباه مُولّد مسبقًا لتضمينات النصوص السلبية.

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

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.stable_diffusion.IFPipelineOutput` بدلاً من 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) الخاص بك.

clean_caption (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تنظيف الوصف قبل إنشاء التضمينات. يتطلب تثبيت `beautifulsoup4` و`ftfy`. إذا لم يتم تثبيت الاعتماديات، فسيتم إنشاء التضمينات من النص الخام.

max_sequence_length (`int` الافتراضي هو `512`) : أقصى طول تسلسل يُستخدم مع `prompt`.

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

إذا كان `return_dict` هو `True`، يُعاد [AllegroPipelineOutput](/docs/diffusers/main/ar/api/pipelines/allegro#diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput)، وإلا يُعاد `tuple` حيث يكون العنصر الأول قائمة بالفيديوهات المولّدة.

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

أمثلة:
```py
>>> import torch
>>> from diffusers import AutoencoderKLAllegro, AllegroPipeline
>>> from diffusers.utils import export_to_video

>>> vae = AutoencoderKLAllegro.from_pretrained("rhymes-ai/Allegro", subfolder="vae", torch_dtype=torch.float32)
>>> pipe = AllegroPipeline.from_pretrained("rhymes-ai/Allegro", vae=vae, torch_dtype=torch.bfloat16).to("cuda")
>>> pipe.vae.enable_tiling()

>>> prompt = (
...     "A seaside harbor with bright sunlight and sparkling seawater, with many boats in the water. From an aerial view, "
...     "the boats vary in size and color, some moving and some stationary. Fishing boats in the water suggest that this "
...     "location might be a popular spot for docking fishing boats."
... )
>>> video = pipe(prompt, guidance_scale=7.5, max_sequence_length=512).frames[0]
>>> export_to_video(video, "output.mp4", fps=15)
```

#### encode_prompt[[diffusers.AllegroPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_videos_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, clean_caption: bool = False, max_sequence_length: int = 512, **kwargs)
```

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

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

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

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

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

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

device : (`torch.device`, *اختياري*): جهاز torch لوضع التضمينات الناتجة عليه

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

negative_prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى PixArt-Alpha، يجب أن تكون تمثيلات السلسلة "".

clean_caption (`bool`، القيمة الافتراضية `False`) : إذا كانت `True`، سيقوم الدالة بمعالجة الوصف المقدم وتنظيفه قبل الترميز.

max_sequence_length (`int`، القيمة الافتراضية 512) : أقصى طول تسلسل يُستخدم للموجّه.

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

## AllegroPipelineOutput[[diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput]]

#### diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput[[diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput]]

```python
diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput(frames: typing.Union[torch.Tensor, numpy.ndarray, list[list[PIL.Image.Image]]])
```

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

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

frames (`torch.Tensor` أو `np.ndarray` أو list[list[PIL.Image.Image]]) : قائمة من مخرجات الفيديو - يمكن أن تكون قائمة متداخلة بطول `batch_size,` حيث تحتوي كل قائمة فرعية على تسلسلات من صور PIL منزوعة الضوضاء بطول `num_frames.` كما يمكن أن تكون مصفوفة NumPy أو متجه Torch بشكل `(batch_size, num_frames, channels, height, width)`.

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