diffusers/main/ar/api/pipelines/allegro.md

Allegro

أليغرو: فتح الصندوق الأسود لنموذج توليد الفيديو بمستوى تجاري من 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 .

تأكد من الاطلاع على دليل المجدولين لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم إعادة استخدام المكونات عبر خطوط الأنابيب لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

التكميم

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

راجع نظرة عامة حول التكميم لمعرفة المزيد حول محركات التكميم المدعومة واختيار محرك تكميم يدعم حالتك الاستخدامية. يوضح المثال أدناه كيفية تحميل AllegroPipeline مُكمَّم للاستدلال باستخدام bitsandbytes.

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]]

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

المصدر

المعاملات:

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

text_encoder (T5EncoderModel) : مُشفِّر نص ثابت. يستخدم PixArt-Alpha T5، وتحديداً النسخة t5-v1_1-xxl.

tokenizer (T5Tokenizer) : مُجزِّئ من الفئة T5Tokenizer.

transformer (AllegroTransformer3DModel) : نموذج AllegroTransformer3DModel مشروط بالنص، يُستخدم لإزالة الضوضاء من كامنات الفيديو المُرمّزة.

scheduler (SchedulerMixin) : مُجدول يُستخدم بالاقتران مع transformer لإزالة الضوضاء من كامنات الفيديو المُرمّزة.

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

يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع خطوط الأنابيب (مثل التنزيل أو الحفظ، أو التشغيل على جهاز معين، وما إلى ذلك).

call[[diffusers.AllegroPipeline.call]]

__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)

المصدر

المعاملات:

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. يُعرَّف guidance_scale على أنه w من المعادلة 2. في Imagen Paper. يتم تفعيل مقياس التوجيه عن طريق تعيين 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، وسيتم تجاهله في الحالات الأخرى.

generator (torch.Generator أو list[torch.Generator]، اختياري) : مولّد واحد أو قائمة من مولّدات torch لجعل التوليد حتميًا.

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: 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 أو tuple

إذا كان return_dict هو True، يُعاد AllegroPipelineOutput، وإلا يُعاد tuple حيث يكون العنصر الأول قائمة بالفيديوهات المولّدة.

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

أمثلة:

>>> 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]]

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)

المصدر

المعاملات:

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]]

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

المصدر

المعاملات:

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.