#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença. -->

# Latte

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

[Latte: Latent Diffusion Transformer for Video Generation](https://huggingface.co/papers/2401.03048) da Monash University, Shanghai AI Lab, Nanjing University e Nanyang Technological University.

O resumo do artigo é:

*Propomos um novo Latent Diffusion Transformer, o Latte, para geração de vídeo. O Latte primeiro extrai tokens espaço-temporais dos vídeos de entrada e, em seguida, adota uma série de blocos Transformer para modelar a distribuição de vídeo no espaço latente. A fim de modelar um número substancial de tokens extraídos de vídeos, são introduzidas quatro variantes eficientes a partir da perspectiva de decompor as dimensões espacial e temporal dos vídeos de entrada. Para melhorar a qualidade dos vídeos gerados, determinamos as melhores práticas do Latte por meio de uma análise experimental rigorosa, incluindo incorporação de patches de clipes de vídeo, variantes de modelo, injeção de informação de classe de passo de tempo, incorporação posicional temporal e estratégias de aprendizado. Nossa avaliação abrangente demonstra que o Latte atinge desempenho de estado da arte em quatro conjuntos de dados padrão de geração de vídeo, a saber, FaceForensics, SkyTimelapse, UCF101 e Taichi-HD. Além disso, estendemos o Latte para a tarefa de geração de vídeo a partir de texto (T2V), na qual o Latte atinge resultados comparáveis aos de modelos T2V recentes. Acreditamos fortemente que o Latte fornece insights valiosos para pesquisas futuras sobre a incorporação de Transformers em modelos de difusão para geração de vídeo.*

**Destaques**: Latte é um transformer de difusão latente proposto como espinha dorsal para modelar diferentes modalidades (treinado aqui para geração de vídeo a partir de texto). Ele atinge desempenho de estado da arte em quatro benchmarks padrão de vídeo - [FaceForensics](https://huggingface.co/papers/1803.09179), [SkyTimelapse](https://huggingface.co/papers/1709.07592), [UCF101](https://huggingface.co/papers/1212.0402) e [Taichi-HD](https://huggingface.co/papers/2003.00196). Para preparar e baixar os conjuntos de dados para avaliação, consulte [este URL](https://github.com/Vchitect/Latte/blob/main/docs/datasets_evaluation.md).

Este pipeline foi contribuído por [maxin-cn](https://github.com/maxin-cn). A base de código original pode ser encontrada [aqui](https://github.com/Vchitect/Latte). Os pesos originais podem ser encontrados em [hf.co/maxin-cn](https://huggingface.co/maxin-cn).

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

### Inferência

Use [`torch.compile`](https://huggingface.co/docs/diffusers/main/en/tutorials/fast_diffusion#torchcompile) para reduzir a latência de inferência.

Primeiro, carregue o 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"
```

Em seguida, altere o layout de memória dos componentes `transformer` e `vae` dos pipelines para `torch.channels-last`:

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

Por fim, compile os componentes e execute a inferência:

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

Os resultados do [benchmark](https://gist.github.com/a-r-r-o-w/4e1694ca46374793c0361d740a99ff19) em uma máquina A100 de 80GB são:

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

## Quantização

A quantização ajuda a reduzir os requisitos de memória de modelos muito grandes armazenando os pesos do modelo em um tipo de dados de menor precisão. No entanto, a quantização pode ter um impacto variável na qualidade do vídeo, dependendo do modelo de vídeo.

Consulte a visão geral de [Quantization](../../quantization/overview) para saber mais sobre os backends de quantização suportados e sobre como selecionar um backend de quantização que atenda ao seu caso de uso. O exemplo abaixo demonstra como carregar um [LattePipeline](/docs/diffusers/main/pt/api/pipelines/latte#diffusers.LattePipeline) quantizado para inferência com 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)
```

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

**Parâmetros:**

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar vídeos para e a partir de representações latentes.

text_encoder (`T5EncoderModel`) : Codificador de texto congelado. O Latte usa [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), especificamente a variante [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

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

transformer ([LatteTransformer3DModel](/docs/diffusers/main/pt/api/models/latte_transformer3d#diffusers.LatteTransformer3DModel)) : Um `LatteTransformer3DModel` condicionado por texto para desruidar os latentes de vídeo codificados.

scheduler ([SchedulerMixin](/docs/diffusers/main/pt/api/schedulers/overview#diffusers.SchedulerMixin)) : Um scheduler para ser usado em combinação com `transformer` para desruidar os latentes de vídeo codificados.

Pipeline para geração de texto para vídeo usando Latte.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

#### __call__[[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 = ['latents'], clean_caption: bool = True, mask_feature: bool = True, enable_temporal_attentions: bool = True, decode_chunk_size: int = 14)
```

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração do vídeo. Se não definido, é necessário passar `prompt_embeds` em vez disso.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração do vídeo. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

num_inference_steps (`int`, *opcional*, padrão 100) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, em detrimento de uma inferência mais lenta.

timesteps (`list[int]`, *opcional*) : Passos de tempo personalizados para usar no processo de remoção de ruído. Se não definido, são usados passos de tempo igualmente espaçados de `num_inference_steps`. Devem estar em ordem decrescente.

guidance_scale (`float`, *opcional*, padrão 7.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de vídeos que estão intimamente ligados ao `prompt` de texto, geralmente em detrimento de uma menor qualidade do vídeo.

video_length (`int`, *opcional*, padrão 16) : O número de quadros de vídeo que são gerados. O padrão é 16 quadros, que a 8 quadros por segundo

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de vídeos a serem gerados por prompt.

height (`int`, *opcional*, padrão é self.unet.config.sample_size) : A altura em pixels do vídeo gerado.

width (`int`, *opcional*, padrão é self.unet.config.sample_size) : A largura em pixels do vídeo gerado.

eta (`float`, *opcional*, padrão 0.0) : Corresponde ao parâmetro eta (η) no paper DDIM: https://huggingface.co/papers/2010.02502. Aplica-se apenas a [schedulers.DDIMScheduler](/docs/diffusers/main/pt/api/schedulers/ddim#diffusers.DDIMScheduler), será ignorado para os demais.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.FloatTensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto negativos pré-gerados. Para o Latte, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída do vídeo gerado. Escolha entre [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `~pipelines.stable_diffusion.IFPipelineOutput` em vez de uma tupla simples.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *opcional*) : Uma função de callback ou uma lista de funções de callback a serem chamadas no final de cada etapa de remoção de ruído.

callback_on_step_end_tensor_inputs (`list[str]`, *opcional*) : Uma lista de entradas de tensor que devem ser passadas para a função de callback. Se não for definida, todas as entradas de tensor serão passadas.

clean_caption (`bool`, *opcional*, padrão `True`) : Se deve ou não limpar a legenda antes de criar os embeddings. Exige que `beautifulsoup4` e `ftfy` estejam instalados. Se as dependências não estiverem instaladas, os embeddings serão criados a partir do prompt bruto.

mask_feature (`bool` padrão é `True`) : Se definido como `True`, as incorporações de texto serão mascaradas.

enable_temporal_attentions (`bool`, *opcional*, padrão `True`) : Se as atenções temporais devem ser habilitadas

decode_chunk_size (`int`, *opcional*) : O número de quadros a decodificar por vez. Um tamanho de bloco maior leva a uma melhor consistência temporal às custas de mais uso de memória. Por padrão, o decodificador decodifica todos os quadros de uma vez para qualidade máxima. Para um menor uso de memória, reduza `decode_chunk_size`.

**Retorna:** `LattePipelineOutput` ou `tuple`

Se `return_dict` for `True`, `LattePipelineOutput` é retornado; caso contrário, uma `tuple` é retornada, onde o primeiro elemento é uma lista com as imagens geradas

Função invocada ao chamar o pipeline para geração.

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

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : prompt a ser codificado

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt negativo para orientar a geração do vídeo. Se não for definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`). Para o Latte, isso deve ser "".

do_classifier_free_guidance (`bool`, *opcional*, padrão `True`) : se deve ou não usar classifier free guidance

num_images_per_prompt (`int`, *opcional*, padrão 1) : número de vídeos que devem ser gerados por prompt

device : (`torch.device`, *opcional*): dispositivo torch onde os embeddings resultantes serão colocados

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embebidings de texto negativo pré-gerados. Para o Latte, deve ser os embebidings da string "".

clean_caption (bool, padrão `False`) : Se `True`, a função pré-processará e limpará a legenda fornecida antes da codificação.

mask_feature : (bool, padrão `True`): Se `True`, a função aplicará uma máscara aos embeddings de texto.

Codifica o prompt em estados ocultos do codificador de texto.