# Allegro

[Allegro : ouvrir la boîte noire du modèle de génération vidéo de niveau commercial](https://huggingface.co/papers/2410.15458) de RhymesAI, par Yuan Zhou, Qiuyue Wang, Yuxuan Cai, Huan Yang.

L'abstract de l'article est :

*D’importants progrès ont été réalisés dans le domaine de la génération de vidéos, la communauté open source ayant contribué une multitude de papiers de recherche et d’outils pour l’entraînement de modèles de haute qualité. Toutefois, malgré ces efforts, les informations et ressources disponibles restent insuffisantes pour atteindre des performances de niveau commercial. Dans ce rapport, nous levons le voile sur la boîte noire et présentons Allegro, un modèle avancé de génération de vidéos qui excelle tant en termes de qualité que de cohérence temporelle. Nous mettons également en lumière les limites actuelles du domaine et proposons une méthodologie complète pour l’entraînement de modèles de génération de vidéos haute performance et de niveau commercial, en abordant des aspects clés tels que les données, l’architecture du modèle, le pipeline d’entraînement et l’évaluation. Notre étude utilisateur montre qu’Allegro surpasse les modèles open source existants et la plupart des modèles commerciaux, se classant juste derrière Hailuo et Kling. Code : https://github.com/rhymes-ai/Allegro , Modèle : https://huggingface.co/rhymes-ai/Allegro , Galerie : https://rhymes.ai/allegro_gallery .*

> [!TIP]
> Pensez à consulter le [guide des Schedulers](../../using-diffusers/schedulers) pour apprendre à explorer le compromis entre la vitesse et la qualité du scheduler, et à consulter la section [réutilisation des composants entre les pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) pour apprendre à charger efficacement les mêmes composants dans plusieurs pipelines.

## Quantification

La quantification aide à réduire les besoins en mémoire des très grands modèles en stockant les poids du modèle dans un type de données de précision inférieure. Cependant, la quantification peut avoir un impact variable sur la qualité de la vidéo selon le modèle vidéo.

Reportez-vous à l'aperçu de la [Quantization](../../quantization/overview) pour en savoir plus sur les backends de quantification pris en charge et sur la sélection d'un backend de quantification adapté à votre cas d'usage. L'exemple ci-dessous montre comment charger un [AllegroPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/allegro#diffusers.AllegroPipeline) quantifié pour l'inférence avec 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)
```

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

**Paramètres :**

vae (`AllegroAutoEncoderKL3D`) : modèle Variational Auto-Encoder (VAE) permettant d’encoder et de décoder des vidéos à partir de représentations latentes et inversement.

text_encoder (`T5EncoderModel`) : encodeur de texte figé. PixArt-Alpha utilise [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), plus précisément la variante [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

tokenizer (`T5Tokenizer`) : Tokenizer de la classe [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

transformer ([AllegroTransformer3DModel](/docs/diffusers/v0.43.0/fr/api/models/allegro_transformer3d#diffusers.AllegroTransformer3DModel)) : un `AllegroTransformer3DModel` conditionné par le texte pour débruyer les latents vidéo encodés.

scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/fr/api/schedulers/overview#diffusers.SchedulerMixin)) : un planificateur à utiliser en combinaison avec `transformer` pour débruyer les latents vidéo encodés.

Pipeline pour la génération de vidéos à partir de texte utilisant Allegro.

Ce modèle hérite de [DiffusionPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous les pipelines (téléchargement ou sauvegarde, exécution sur un appareil particulier, etc.).

#### __appel__[[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)
```

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

**Paramètres :**

prompt (`str` ou `list[str]`, *facultatif*) : Le prompt ou les prompts pour guider la génération de la vidéo. S'il n'est pas défini, il faut passer `prompt_embeds` à la place.

negative_prompt (`str` ou `list[str]`, *facultatif*) : Le prompt ou les prompts à ne pas utiliser pour guider la génération de la vidéo. S'il n'est pas défini, il faut passer `negative_prompt_embeds` à la place. Ignoré lorsque le guidage n'est pas utilisé (c'est-à-dire ignoré si `guidance_scale` est inférieur à `1`).

num_inference_steps (`int`, *facultatif*, valeur par défaut 100) : Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une vidéo de meilleure qualité, au prix d'une inférence plus lente.

timesteps (`list[int]`, *facultatif*) : Étapes de temps personnalisées à utiliser pour le processus de débruitage. Si non définies, des étapes de temps `num_inference_steps` équidistantes sont utilisées. Doivent être dans l'ordre décroissant.

guidance_scale (`float`, *facultatif*, valeur par défaut 7,5) : Échelle de guidage telle que définie dans [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` est défini comme `w` de l'équation 2. de [Imagen Paper](https://huggingface.co/papers/2205.11487). L'échelle de guidage est activée en définissant `guidance_scale > 1`. Une échelle de guidage plus élevée encourage la génération de vidéos étroitement liées au `prompt` texte, généralement au détriment de la qualité de la vidéo.

num_videos_per_prompt (`int`, *facultatif*, valeur par défaut 1) : Le nombre de vidéos à générer par invite.

num_frames : (`int`, *facultatif*, valeur par défaut 88) : Ce nombre contrôle les images de la vidéo générée.

height (`int`, *facultatif*, par défaut self.unet.config.sample_size) : La hauteur en pixels de la vidéo générée.

width (`int`, *facultatif*, par défaut self.unet.config.sample_size) : La largeur en pixels de la vidéo générée.

eta (`float`, *facultatif*, valeur par défaut 0.0) : Correspond au paramètre eta (η) du papier DDIM : https://huggingface.co/papers/2010.02502. S'applique uniquement à [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/fr/api/schedulers/ddim#diffusers.DDIMScheduler), sera ignoré pour les autres.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Un ou une liste de [générateurs torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) pour rendre la génération déterministe.

latents (`torch.Tensor`, *facultatif*) : génération. Peut être utilisé pour ajuster la même génération avec différents prompts. S'il n'est pas fourni, un tenseur de latents pré-générés, bruités et échantillonnés à partir d'une distribution gaussienne, à utiliser comme entrées pour la vidéo, sera généré par échantillonnage à l'aide du `generator` aléatoire fourni.

prompt_embeds (`torch.Tensor`, *facultatif*) : Incrustations de texte pré-générées. Peut être utilisé pour ajuster facilement les entrées de texte, *par ex.* pondération des prompts. Si non fourni, les incrustations de texte seront générées à partir de l'argument d'entrée `prompt`.

prompt_attention_mask (`torch.Tensor`, *facultatif*) : Masque d'attention pré-généré pour les embeddings de texte.

negative_prompt_embeds (`torch.Tensor`, *facultatif*) : Incrustations de texte négatif pré-générées. Pour PixArt-Sigma, ce prompt négatif doit être "". S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entrée `negative_prompt`.

negative_prompt_attention_mask (`torch.Tensor`, *facultatif*) : Masque d'attention pré-généré pour les embeddings de texte négatif.

output_type (`str`, *facultatif*, par défaut `"pil"`) : Le format de sortie de la vidéo générée. Choisissez entre [PIL](https://pillow.readthedocs.io/en/stable/) : `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un `~pipelines.stable_diffusion.IFPipelineOutput` plutôt qu'un simple tuple.

callback_on_step_end (`Callable`, *facultatif*) : une fonction appelée à la fin de chaque étape de débruitage pendant l’inférence. La fonction est appelée avec les arguments suivants : `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` contiendra une liste de tous les tenseurs, tels que spécifiés par `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`List`, *facultatif*) : La liste des entrées de tenseurs pour la fonction `callback_on_step_end`. Les tenseurs spécifiés dans la liste seront passés en tant qu'argument `callback_kwargs`. Vous ne pourrez inclure que les variables listées dans l'attribut `._callback_tensor_inputs` de votre classe de pipeline.

clean_caption (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut nettoyer la légende avant de créer les embeddings. Nécessite l'installation de `beautifulsoup4` et `ftfy`. Si les dépendances ne sont pas installées, les embeddings seront créés à partir du prompt brut.

max_sequence_length (`int` par défaut `512`) : Longueur maximale de la séquence à utiliser avec le `prompt`.

**Retourne :** [AllegroPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/allegro#diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput) ou `tuple`

Si `return_dict` est `True`, [AllegroPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/allegro#diffusers.pipelines.allegro.pipeline_output.AllegroPipelineOutput) est retourné, sinon un `tuple` est retourné dont le premier élément est une liste contenant les vidéos générées.

Fonction appelée lors de l'appel du pipeline pour la génération.

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

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

**Paramètres :**

prompt (`str` ou `list[str]`, *facultatif*) : invite à encoder

negative_prompt (`str` ou `list[str]`, *facultatif*) : Le prompt à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passer `negative_prompt_embeds` à la place. Ignoré lorsque la guidance n’est pas utilisée (c’est-à-dire ignoré si `guidance_scale` est inférieur à `1`). Pour PixArt-Alpha, cela doit être "".

do_classifier_free_guidance (`bool`, *facultatif*, par défaut `True`) : indique s'il faut utiliser le guidage sans classifieur ou non

num_videos_per_prompt (`int`, *facultatif*, valeur par défaut 1) : nombre d'images à générer par invite

device : (`torch.device`, *facultatif*) : le torch device sur lequel placer les embeddings résultants

prompt_embeds (`torch.Tensor`, *facultatif*) : Incrustations de texte pré-générées. Peut être utilisé pour ajuster facilement les entrées de texte, *par ex.* pondération des prompts. Si non fourni, les incrustations de texte seront générées à partir de l'argument d'entrée `prompt`.

negative_prompt_embeds (`torch.Tensor`, *facultatif*) : Embeddings de texte négatif pré-générés. Pour PixArt-Alpha, il doit s'agir des embeddings de la chaîne "".

clean_caption (`bool`, par défaut `False`) : Si `True`, la fonction prétraite et nettoie la légende fournie avant l'encodage.

max_sequence_length (`int`, par défaut 512) : Longueur maximale de séquence à utiliser pour le prompt.

Encode le prompt dans les états cachés de l'encodeur de texte.

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

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

**Paramètres :**

frames (`torch.Tensor`, `np.ndarray` ou list[list[PIL.Image.Image]]) : liste de sorties vidéo - Il peut s'agir d'une liste imbriquée de longueur `batch_size,` où chaque sous-liste contient des séquences d'images PIL débruitées de longueur `num_frames.` Il peut également s'agir d'un tableau NumPy ou d'un tenseur Torch de forme `(batch_size, num_frames, channels, height, width)`.

Classe de sortie pour les pipelines Allegro.