# Allegro

[Allegro: Membuka Kotak Hitam Model Generasi Video Tingkat Komersial](https://huggingface.co/papers/2410.15458) dari RhymesAI, oleh Yuan Zhou, Qiuyue Wang, Yuxuan Cai, Huan Yang.

Abstrak dari makalah tersebut adalah:

*Progres signifikan telah dicapai di bidang generasi video, dengan komunitas open-source menyumbangkan banyak makalah penelitian dan alat untuk melatih model berkualitas tinggi. Namun, terlepas dari upaya tersebut, informasi dan sumber daya yang tersedia masih belum memadai untuk mencapai performa tingkat komersial. Dalam laporan ini, kami membuka kotak hitam dan memperkenalkan Allegro, model generasi video canggih yang unggul dalam hal kualitas dan konsistensi temporal. Kami juga menyoroti keterbatasan saat ini di bidang ini dan menyajikan metodologi komprehensif untuk melatih model generasi video berperforma tinggi dan tingkat komersial, dengan membahas aspek-aspek kunci seperti data, arsitektur model, pipeline pelatihan, dan evaluasi. Studi pengguna kami menunjukkan bahwa Allegro melampaui model open-source yang ada dan sebagian besar model komersial, hanya berada di belakang Hailuo dan Kling. Kode: https://github.com/rhymes-ai/Allegro , Model: https://huggingface.co/rhymes-ai/Allegro , Galeri: https://rhymes.ai/allegro_gallery .*

> [!TIP]
> Pastikan untuk melihat [panduan](../../using-diffusers/schedulers) Schedulers untuk mempelajari cara mengeksplorasi tradeoff antara kecepatan dan kualitas scheduler, serta lihat bagian [reuse components across pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) untuk mempelajari cara memuat komponen yang sama secara efisien ke dalam beberapa pipeline.

## Kuantisasi

Quantization membantu mengurangi kebutuhan memori untuk model yang sangat besar dengan menyimpan bobot model dalam tipe data presisi yang lebih rendah. Namun, quantization dapat memiliki dampak yang bervariasi terhadap kualitas video tergantung pada model video yang digunakan.

Lihat ringkasan [Quantization](../../quantization/overview) untuk mempelajari lebih lanjut tentang backend kuantisasi yang didukung dan memilih backend kuantisasi yang mendukung kasus penggunaan Anda. Contoh di bawah ini menunjukkan cara memuat [AllegroPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/allegro#diffusers.AllegroPipeline) terkuantisasi untuk inferensi dengan 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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/allegro/pipeline_allegro.py#L144)

**Parameter:**

vae (`AllegroAutoEncoderKL3D`) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan video ke dan dari representasi laten.

text_encoder (`T5EncoderModel`) : Text-encoder yang dibekukan. PixArt-Alpha menggunakan [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), khususnya varian [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

tokenizer (`T5Tokenizer`) : Tokenizer dari kelas [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

transformer ([AllegroTransformer3DModel](/docs/diffusers/v0.43.0/id/api/models/allegro_transformer3d#diffusers.AllegroTransformer3DModel)) : `AllegroTransformer3DModel` yang dikondisikan teks untuk mendenoise latens video yang telah dikodekan.

scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/id/api/schedulers/overview#diffusers.SchedulerMixin)) : Penjadwal yang digunakan bersama `transformer` untuk menghilangkan noise dari latens video yang telah dikodekan.

Pipeline untuk generasi teks-ke-video menggunakan Allegro.

Model ini mewarisi dari [DiffusionPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/overview#diffusers.DiffusionPipeline). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua pipeline (seperti mengunduh atau menyimpan, menjalankan pada perangkat tertentu, dll.)

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/allegro/pipeline_allegro.py#L665)

**Parameter:**

prompt (`str` atau `list[str]`, *opsional*) : Prompt atau prompt-prompt untuk mengarahkan generasi video. Jika tidak didefinisikan, Anda harus meneruskan `prompt_embeds` sebagai gantinya.

negative_prompt (`str` atau `list[str]`, *opsional*) : Prompt atau prompt-prompt yang tidak akan memandu generasi video. Jika tidak didefinisikan, Anda harus meneruskan `negative_prompt_embeds` sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika `guidance_scale` kurang dari `1`).

num_inference_steps (`int`, *opsional*, default 100) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan video dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.

timesteps (`list[int]`, *opsional*) : Timesteps kustom untuk digunakan dalam proses denoising. Jika tidak didefinisikan, timesteps `num_inference_steps` yang berjarak sama akan digunakan. Harus dalam urutan menurun.

guidance_scale (`float`, *opsional*, default 7.5) : Skala panduan seperti yang didefinisikan dalam [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` didefinisikan sebagai `w` dari persamaan 2. pada [Imagen Paper](https://huggingface.co/papers/2205.11487). Skala panduan diaktifkan dengan mengatur `guidance_scale > 1`. Skala panduan yang lebih tinggi mendorong generasi video yang sangat terkait dengan `prompt` teks, biasanya dengan mengorbankan kualitas video yang lebih rendah.

num_videos_per_prompt (`int`, *opsional*, default 1) : Jumlah video yang akan dihasilkan per prompt.

num_frames : (`int`, *opsional*, default 88): Jumlah ini mengontrol frame video yang dihasilkan.

height (`int`, *opsional*, defaultnya self.unet.config.sample_size) : Tinggi video yang dihasilkan dalam piksel.

width (`int`, *opsional*, defaultnya self.unet.config.sample_size) : Lebar video yang dihasilkan dalam piksel.

eta (`float`, *opsional*, default 0.0) : Bersesuaian dengan parameter eta (η) dalam paper DDIM: https://huggingface.co/papers/2010.02502. Hanya berlaku untuk [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/id/api/schedulers/ddim#diffusers.DDIMScheduler), akan diabaikan untuk yang lain.

generator (`torch.Generator` atau `list[torch.Generator]`, *opsional*) : Satu atau daftar [generator torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) untuk membuat proses generasi menjadi deterministik.

latents (`torch.Tensor`, *opsional*) : generasi. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latens berisak yang telah dibuat sebelumnya, yang diambil dari distribusi Gaussian, akan digunakan sebagai input untuk video. Tensor ini akan dihasilkan dengan pengambilan sampel menggunakan `generator` acak yang diberikan.

prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, *misalnya* penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input `prompt`.

prompt_attention_mask (`torch.Tensor`, *opsional*) : Mask perhatian yang telah dibuat sebelumnya untuk embedding teks.

negative_prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks negatif yang telah dibuat sebelumnya. Untuk PixArt-Sigma, prompt negatif ini harus "". Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input `negative_prompt`.

negative_prompt_attention_mask (`torch.Tensor`, *opsional*) : Mask perhatian yang telah dibuat sebelumnya untuk embedding teks negatif.

output_type (`str`, *opsional*, defaultnya `"pil"`) : Format output dari generate video. Pilih antara [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` atau `np.array`.

return_dict (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengembalikan `~pipelines.stable_diffusion.IFPipelineOutput` alih-alih tuple biasa.

callback_on_step_end (`Callable`, *opsional*) : Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` akan berisi daftar semua tensor sesuai yang ditentukan oleh `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`List`, *opsional*) : Daftar input tensor untuk fungsi `callback_on_step_end`. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen `callback_kwargs`. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut `._callback_tensor_inputs` dari kelas pipeline Anda.

clean_caption (`bool`, *opsional*, defaultnya `True`) : Apakah caption akan dibersihkan sebelum membuat embeddings. Memerlukan `beautifulsoup4` dan `ftfy` terpasang. Jika dependensi tidak terpasang, embeddings akan dibuat dari prompt mentah.

max_sequence_length (`int` defaultnya `512`) : Panjang maksimum urutan yang digunakan dengan `prompt`.

**Mengembalikan:** [AllegroPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/allegro#diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput) atau `tuple`

Jika `return_dict` adalah `True`, [AllegroPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/allegro#diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput) dikembalikan, selain itu sebuah `tuple` dikembalikan di mana elemen pertama adalah daftar dengan video yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:
```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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/allegro/pipeline_allegro.py#L215)

**Parameter:**

prompt (`str` atau `list[str]`, *opsional*) : prompt yang akan dienkod

negative_prompt (`str` atau `list[str]`, *opsional*) : Prompt yang tidak digunakan untuk memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan `negative_prompt_embeds` sebagai gantinya. Diabaikan saat tidak menggunakan panduan (yaitu, diabaikan jika `guidance_scale` kurang dari `1`). Untuk PixArt-Alpha, ini harus berupa "".

do_classifier_free_guidance (`bool`, *opsional*, defaultnya `True`) : apakah akan menggunakan classifier free guidance atau tidak

num_videos_per_prompt (`int`, *opsional*, default 1) : jumlah gambar yang harus dihasilkan per prompt

device : (`torch.device`, *opsional*): perangkat torch untuk menempatkan embedding yang dihasilkan

prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, *misalnya* penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks negatif yang telah dibuat sebelumnya. Untuk PixArt-Alpha, ini seharusnya berupa embedding dari string "".

clean_caption (`bool`, defaultnya `False`) : Jika `True`, fungsi akan memproses pra dan membersihkan caption yang diberikan sebelum pengkodean.

max_sequence_length (`int`, defaultnya 512) : Panjang maksimum urutan yang digunakan untuk prompt.

Mengkodekan prompt menjadi hidden states dari text encoder.

## 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]]])
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/allegro/pipeline_output.py#L11)

**Parameter:**

frames (`torch.Tensor`, `np.ndarray`, atau list[list[PIL.Image.Image]]) : daftar output video - Dapat berupa daftar bersarang dengan panjang `batch_size,` di mana setiap sub-daftar berisi urutan gambar PIL yang telah didenoise dengan panjang `num_frames.` Dapat juga berupa array NumPy atau tensor Torch dengan bentuk `(batch_size, num_frames, channels, height, width)`.

Kelas output untuk pipeline Allegro.