#
# Лицензия Apache License, Version 2.0 («Лицензия»);
# вы можете использовать этот файл только в соответствии с Лицензией.
# Вы можете получить копию Лицензии по адресу
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Если это не требуется применимым законодательством или не оговорено письменно, программное
# распространяется по Лицензии на условиях «КАК ЕСТЬ»,
# БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.
# См. Лицензию для получения конкретных условий, регулирующих разрешения и
# ограничениями Лицензии. -->

# 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) от Университета Монаш, Шанхайской лаборатории искусственного интеллекта, Нанкинского университета и Наньянского технологического университета.

Аннотация из статьи:

*Мы предлагаем новый Latent Diffusion Transformer, а именно Latte, для генерации видео. Latte сначала извлекает пространственно-временные токены из входных видео, а затем использует серию блоков Transformer для моделирования распределения видео в латентном пространстве. Чтобы смоделировать значительное количество токенов, извлечённых из видео, с точки зрения разложения пространственных и временных измерений входных видео введены четыре эффективных варианта. Для повышения качества генерируемых видео мы определяем лучшие практики для Latte с помощью тщательного экспериментального анализа, включая встраивание патчей видеоклипов, варианты моделей, инъекцию информации о временных шагах и классах, временное позиционное встраивание и стратегии обучения. Наша комплексная оценка демонстрирует, что Latte достигает передовых результатов на четырёх стандартных наборах данных для генерации видео, а именно FaceForensics, SkyTimelapse, UCF101 и Taichi-HD. Кроме того, мы расширяем Latte для задачи генерации видео по тексту (T2V), где Latte показывает результаты, сопоставимые с результатами последних T2V-моделей. Мы твёрдо верим, что Latte предоставляет ценные идеи для будущих исследований по интеграции Transformer в диффузионные модели для генерации видео.*

**Ключевые особенности**: Latte — это трансформер латентной диффузии, предложенный в качестве базовой архитектуры для моделирования различных модальностей (здесь обучен для генерации видео по тексту). Он демонстрирует наилучшие результаты на четырёх стандартных видео-бенчмарках — [FaceForensics](https://huggingface.co/papers/1803.09179), [SkyTimelapse](https://huggingface.co/papers/1709.07592), [UCF101](https://huggingface.co/papers/1212.0402) и [Taichi-HD](https://huggingface.co/papers/2003.00196). Для подготовки и загрузки наборов данных для оценки см. [этот URL](https://github.com/Vchitect/Latte/blob/main/docs/datasets_evaluation.md).

Этот конвейер был предложен пользователем [maxin-cn](https://github.com/maxin-cn). Исходная кодовая база доступна [здесь](https://github.com/Vchitect/Latte). Исходные веса можно найти по адресу [hf.co/maxin-cn](https://huggingface.co/maxin-cn).

> [!TIP]
> Обязательно ознакомьтесь с [руководством по планировщикам](../../using-diffusers/schedulers), чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом [повторное использование компонентов в разных конвейерах](../../using-diffusers/loading#reusing-models-in-multiple-pipelines), чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.

### Вывод

Используйте [`torch.compile`](https://huggingface.co/docs/diffusers/main/en/tutorials/fast_diffusion#torchcompile) для снижения задержки при выводе.

Сначала загрузите конвейер:

```python
import torch
from diffusers import LattePipeline

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

Затем измените раскладку памяти компонентов `transformer` и `vae` на `torch.channels-last`:

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

Наконец, скомпилируйте компоненты и запустите инференс:

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

Результаты [бенчмарка](https://gist.github.com/a-r-r-o-w/4e1694ca46374793c0361d740a99ff19) на машине с 80 ГБ A100:

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

## Квантование

Квантование помогает снизить требования к памяти для очень больших моделей, храня веса модели в формате данных с меньшей точностью. Однако влияние квантования на качество видео может различаться в зависимости от используемой модели видео.

См. обзор [Quantization](../../quantization/overview), чтобы узнать больше о поддерживаемых бэкендах квантования и о том, как выбрать бэкенд, подходящий для вашей задачи. Пример ниже показывает, как загрузить квантованный [LattePipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/latte#diffusers.LattePipeline) для инференса с помощью 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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/latte/pipeline_latte.py#L145)

**Параметры:**

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.

text_encoder (`T5EncoderModel`) : Замороженный текстовый энкодер. Latte использует [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel), а именно вариант [t5-v1_1-xxl](https://huggingface.co/PixArt-alpha/PixArt-alpha/tree/main/t5-v1_1-xxl).

tokenizer (`T5Tokenizer`) : Токенизатор класса [T5Tokenizer](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5Tokenizer).

transformer ([LatteTransformer3DModel](/docs/diffusers/v0.43.0/ru/api/models/latte_transformer3d#diffusers.LatteTransformer3DModel)) : модель `LatteTransformer3DModel` с текстовым условием для удаления шума из закодированных латентов видео.

scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ru/api/schedulers/overview#diffusers.SchedulerMixin)) : планировщик, используемый в сочетании с `transformer` для удаления шума из закодированных латентных представлений видео.

Pipeline для генерации видео из текста с использованием Latte.

Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). См. документацию родительского класса для общих методов, которые библиотека реализует для всех пайплайнов (например, загрузка или сохранение, запуск на конкретном устройстве и т. д.)

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/latte/pipeline_latte.py#L613)

**Параметры:**

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией видео. Если не задан, необходимо передать `prompt_embeds` вместо него.

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию видео. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющее влияние (то есть игнорируется, если `guidance_scale` меньше `1`).

num_inference_steps (`int`, *optional*, по умолчанию 100) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к более высокому качеству видео, но за счёт более медленного вывода.

timesteps (`list[int]`, *optional*) : Пользовательские шаги для процесса денойзинга. Если не заданы, используются равномерно распределённые шаги `num_inference_steps`. Должны быть в порядке убывания.

guidance_scale (`float`, *optional*, по умолчанию 7.0) : Масштаб направленного генерирования, определённый в [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` соответствует `w` из уравнения 2 в [Imagen Paper](https://huggingface.co/papers/2205.11487). Направленное генерирование активируется при установке `guidance_scale > 1`. Более высокое значение масштаба направленного генерирования способствует созданию видео, тесно связанных с текстовым `prompt`, как правило, за счёт снижения качества видео.

video_length (`int`, *optional*, по умолчанию 16) : Количество генерируемых кадров видео. По умолчанию 16 кадров, что при 8 кадрах в секунду

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество видео, генерируемых на один промпт.

height (`int`, *optional*, по умолчанию self.unet.config.sample_size) : Высота генерируемого видео в пикселях.

width (`int`, *optional*, по умолчанию self.unet.config.sample_size) : Ширина генерируемого видео в пикселях.

eta (`float`, *optional*, по умолчанию 0.0) : Соответствует параметру eta (η) в статье DDIM: https://huggingface.co/papers/2010.02502. Применяется только к [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/ddim#diffusers.DDIMScheduler), для остальных игнорируется.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не указаны, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные эмбеддинги отрицательного текста. Для Latte этот отрицательный промпт должен быть "". Если не указан, negative_prompt_embeds будет сгенерирован из аргумента `negative_prompt`.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерации видео. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~pipelines.stable_diffusion.IFPipelineOutput` вместо обычного кортежа.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *optional*) : Функция обратного вызова или список функций обратного вызова, которые вызываются в конце каждого шага удаления шума.

callback_on_step_end_tensor_inputs (`list[str]`, *необязательный*) : Список тензорных входных данных, которые должны передаваться в функцию обратного вызова. Если не определено, будут переданы все тензорные входные данные.

clean_caption (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли очищать подпись перед созданием эмбеддингов. Требует установки `beautifulsoup4` и `ftfy`. Если зависимости не установлены, эмбеддинги будут созданы из исходного промпта.

mask_feature (`bool` по умолчанию `True`) : Если установлено в `True`, текстовые эмбеддинги будут замаскированы.

enable_temporal_attentions (`bool`, *необязательный*, по умолчанию `True`) : Включать ли временное внимание

decode_chunk_size (`int`, *optional*) : Количество кадров, декодируемых за один раз. Увеличение размера блока повышает временную согласованность ценой роста потребления памяти. По умолчанию декодер обрабатывает все кадры сразу для достижения максимального качества. Для снижения потребления памяти уменьшите `decode_chunk_size`.

**Возвращает:** `LattePipelineOutput` или `tuple`

Если `return_dict` равно `True`, возвращается `LattePipelineOutput`, иначе возвращается `tuple`, где первый элемент — это список с сгенерированными изображениями

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/latte/pipeline_latte.py#L206)

**Параметры:**

prompt (`str` или `list[str]`, *необязательный*) : промпт для кодирования

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт, который не должен направлять генерацию видео. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющая (то есть игнорируется, если `guidance_scale` меньше `1`). Для Latte это должно быть "".

do_classifier_free_guidance (`bool`, *необязательный*, по умолчанию `True`) : использовать ли classifier free guidance

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : количество видео, которое должно быть сгенерировано на один запрос

device : (`torch.device`, *необязательный*): устройство torch, на котором будут размещены полученные эмбеддинги

prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные эмбеддинги отрицательного текста. Для Latte это должны быть эмбеддинги строки "".

clean_caption (bool, по умолчанию `False`) : Если `True`, функция выполнит предобработку и очистку предоставленной подписи перед кодированием.

mask_feature : (bool, по умолчанию `True`): если `True`, функция маскирует эмбеддинги текста.

Кодирует промпт в скрытые состояния текстового энкодера.