#
# Sous licence Apache License, Version 2.0 (la « Licence ») ;
# vous ne pouvez utiliser ce fichier que conformément à la Licence.
# Vous pouvez obtenir un exemplaire de la Licence à
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Sauf exigence légale ou accord écrit
# distribué sous la Licence est distribué sur une base « EN L'ÉTAT »,
# SANS AUCUNE GARANTIE NI CONDITION, explicite ou implicite.
# Voir la Licence pour le langage spécifique régissant les autorisations et
# limitations under the License. -->

# Latte

![latte text-to-video](https://github.com/Vchitect/Latte/blob/52bc0029899babbd6e9250384c83d8ed2670ff7a/visuals/latte.gif?raw=true)

[Latte : Latent Diffusion Transformer pour la génération de vidéos](https://huggingface.co/papers/2401.03048) de l'Université Monash, du Shanghai AI Lab, de l'Université de Nanjing et de la Nanyang Technological University.

L'abstract de l'article est :

*Nous proposons un nouveau Latent Diffusion Transformer, nommé Latte, pour la génération de vidéos. Latte extrait d'abord des jetons spatio-temporels à partir des vidéos d'entrée, puis adopte une série de blocs Transformer pour modéliser la distribution des vidéos dans l'espace latent. Afin de modéliser un nombre important de jetons extraits des vidéos, quatre variantes efficaces sont introduites sous l'angle de la décomposition des dimensions spatiales et temporelles des vidéos d'entrée. Pour améliorer la qualité des vidéos générées, nous déterminons les meilleures pratiques de Latte par une analyse expérimentale rigoureuse, incluant l'incorporation de jetons de patch de clips vidéo, les variantes de modèle, l'injection d'informations de classe de pas de temps, l'incorporation de position temporelle et les stratégies d'apprentissage. Notre évaluation complète démontre que Latte atteint des performances de pointe sur quatre jeux de données standard de génération de vidéos, à savoir FaceForensics, SkyTimelapse, UCF101 et Taichi-HD. En outre, nous étendons Latte à la tâche de génération de vidéos à partir de texte (T2V), où Latte obtient des résultats comparables à ceux des modèles T2V récents. Nous sommes fermement convaincus que Latte offre des perspectives précieuses pour les recherches futures sur l'intégration des Transformers dans les modèles de diffusion pour la génération de vidéos.*

**Points forts** : Latte est un transformeur de diffusion latente proposé comme architecture de base pour modéliser différentes modalités (entraîné ici pour la génération de vidéos à partir de texte). Il atteint des performances de pointe sur quatre benchmarks vidéo standard - [FaceForensics](https://huggingface.co/papers/1803.09179), [SkyTimelapse](https://huggingface.co/papers/1709.07592), [UCF101](https://huggingface.co/papers/1212.0402) et [Taichi-HD](https://huggingface.co/papers/2003.00196). Pour préparer et télécharger les jeux de données pour l'évaluation, veuillez consulter [ce lien](https://github.com/Vchitect/Latte/blob/main/docs/datasets_evaluation.md).

Ce pipeline a été contribué par [maxin-cn](https://github.com/maxin-cn). La base de code originale peut être trouvée [ici](https://github.com/Vchitect/Latte). Les poids originaux sont disponibles sous [hf.co/maxin-cn](https://huggingface.co/maxin-cn).

> [!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.

### Inférence

Utilisez [`torch.compile`](https://huggingface.co/docs/diffusers/main/en/tutorials/fast_diffusion#torchcompile) pour réduire la latence d'inférence.

Tout d'abord, chargez le pipeline :

```python
import torch
from diffusers import LattePipeline

pipeline = LattePipeline.from_pretrained(
	"maxin-cn/Latte-1", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"
```

Puis modifiez la disposition mémoire des composants `transformer` et `vae` des pipelines en `torch.channels-last` :

```python
pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.vae.to(memory_format=torch.channels_last)
```

Enfin, compilez les composants et exécutez l'inférence :

```python
pipeline.transformer = torch.compile(pipeline.transformer)
pipeline.vae.decode = torch.compile(pipeline.vae.decode)

video = pipeline(prompt="A dog wearing sunglasses floating in space, surreal, nebulae in background").frames[0]
```

Les résultats du [benchmark](https://gist.github.com/a-r-r-o-w/4e1694ca46374793c0361d740a99ff19) sur une machine A100 de 80 Go sont :

```
Without torch.compile(): Average inference time: 16.246 seconds.
With torch.compile(): Average inference time: 14.573 seconds.
```

## 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 [LattePipeline](/docs/diffusers/main/fr/api/pipelines/latte#diffusers.LattePipeline) quantifié pour l'inférence avec bitsandbytes.

```py
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, LatteTransformer3DModel, LattePipeline
from diffusers.utils import export_to_gif
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "maxin-cn/Latte-1",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = LatteTransformer3DModel.from_pretrained(
    "maxin-cn/Latte-1",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = LattePipeline.from_pretrained(
    "maxin-cn/Latte-1",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "A small cactus with a happy face in the Sahara desert."
video = pipeline(prompt).frames[0]
export_to_gif(video, "latte.gif")
```

## LattePipeline[[diffusers.LattePipeline]]

#### diffusers.LattePipeline[[diffusers.LattePipeline]]

```python
diffusers.LattePipeline(tokenizer: T5Tokenizer, text_encoder: T5EncoderModel, vae: AutoencoderKL, transformer: LatteTransformer3DModel, scheduler: KarrasDiffusionSchedulers)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/latte/pipeline_latte.py#L145)

**Paramètres :**

vae ([AutoencoderKL](/docs/diffusers/main/fr/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modèle de Variational Auto-Encoder (VAE) pour encoder et décoder des vidéos vers et depuis des représentations latentes.

text_encoder (`T5EncoderModel`) : encodeur de texte figé. Latte 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 ([LatteTransformer3DModel](/docs/diffusers/main/fr/api/models/latte_transformer3d#diffusers.LatteTransformer3DModel)) : un `LatteTransformer3DModel` conditionné par le texte pour débruyer les latents vidéo encodés.

scheduler ([SchedulerMixin](/docs/diffusers/main/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 Latte.

Ce modèle hérite de [DiffusionPipeline](/docs/diffusers/main/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.LattePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 50, timesteps: list[int] | None = None, guidance_scale: float = 7.5, num_images_per_prompt: int = 1, video_length: int = 16, height: int = 512, width: int = 512, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str = '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, mask_feature: bool = True, enable_temporal_attentions: bool = True, decode_chunk_size: int = 14)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/latte/pipeline_latte.py#L613)

**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.0) : É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.

video_length (`int`, *facultatif*, par défaut 16) : Le nombre de frames vidéo générées. La valeur par défaut est de 16 frames, soit 8 images par seconde

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

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/main/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.FloatTensor`, *facultatif*) : Latents bruités pré-générés, échantillonnés à partir d'une distribution gaussienne, à utiliser comme entrées pour la génération de vidéos. Peut être utilisé pour ajuster la même génération avec des prompts différents. S'il n'est pas fourni, un tenseur de latents sera généré par échantillonnage à l'aide du `generator` aléatoire fourni.

prompt_embeds (`torch.FloatTensor`, *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.FloatTensor`, *facultatif*) : Incrustations de texte négatif pré-générées. Pour Latte, 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`.

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[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *facultatif*) : une fonction de rappel ou une liste de fonctions de rappel à appeler à la fin de chaque étape de débruitage.

callback_on_step_end_tensor_inputs (`list[str]`, *facultatif*) : Une liste d'entrées tensorielles qui doivent être transmises à la fonction de rappel. Si non définie, toutes les entrées tensorielles seront transmises.

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.

mask_feature (`bool` par défaut `True`) : Si défini sur `True`, les embeddings de texte seront masqués.

enable_temporal_attentions (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut activer les attentions temporelles

decode_chunk_size (`int`, *facultatif*) : Le nombre de frames à décoder à la fois. Une taille de chunk plus élevée améliore la cohérence temporelle au détriment d'une consommation mémoire accrue. Par défaut, le décodeur décode toutes les frames d'un coup pour une qualité maximale. Pour réduire la consommation mémoire, diminuez `decode_chunk_size`.

**Retourne :** `LattePipelineOutput` ou `tuple`

Si `return_dict` est `True`, `LattePipelineOutput` est retourné, sinon un `tuple` est retourné dont le premier élément est une liste contenant les images 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 LattePipeline
>>> from diffusers.utils import export_to_gif

>>> # You can replace the checkpoint id with "maxin-cn/Latte-1" too.
>>> pipe = LattePipeline.from_pretrained("maxin-cn/Latte-1", torch_dtype=torch.float16)
>>> # Enable memory optimizations.
>>> pipe.enable_model_cpu_offload()

>>> prompt = "A small cactus with a happy face in the Sahara desert."
>>> videos = pipe(prompt).frames[0]
>>> export_to_gif(videos, "latte.gif")
```

#### encode_prompt[[diffusers.LattePipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, device: typing.Optional[torch.device] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, clean_caption: bool = False, mask_feature: bool = True, dtype = None)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/latte/pipeline_latte.py#L206)

**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 de la vidéo. 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 Latte, 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_images_per_prompt (`int`, *facultatif*, par défaut 1) : nombre de vidéos à générer par invite

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

prompt_embeds (`torch.FloatTensor`, *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.FloatTensor`, *facultatif*) : Embeddings de texte négatif pré-générés. Pour Latte, 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.

mask_feature : (bool, par défaut `True`) : si `True`, la fonction masque les embeddings de texte.

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