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

# EasyAnimate
[EasyAnimate](https://github.com/aigc-apps/EasyAnimate) от Alibaba PAI.

Описание с его страницы на GitHub: *EasyAnimate — это конвейер, основанный на архитектуре трансформера, предназначенный для генерации изображений и видео с помощью ИИ, а также для обучения базовых моделей и моделей Lora для Diffusion Transformer. Мы поддерживаем прямое предсказание с использованием предварительно обученных моделей EasyAnimate, что позволяет генерировать видео с различными разрешениями, продолжительностью около 6 секунд, при частоте 8 кадров в секунду (EasyAnimateV5.1, от 1 до 49 кадров). Кроме того, пользователи могут обучать собственные базовые и Lora-модели для конкретных стилевых трансформаций.*

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

Существуют две официальные контрольные точки EasyAnimate для генерации видео по тексту и преобразования видео в видео.

| чекпоинты | рекомендуемый тип данных для вывода |
|:---:|:---:|
| [`alibaba-pai/EasyAnimateV5.1-12b-zh`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh) | torch.float16 |
| [`alibaba-pai/EasyAnimateV5.1-12b-zh-InP`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh-InP) | torch.float16 |

Доступна одна официальная контрольная точка EasyAnimate для задач изображения в видео и видео в видео.

| чекпоинты | рекомендуемый тип данных для вывода |
|:---:|:---:|
| [`alibaba-pai/EasyAnimateV5.1-12b-zh-InP`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh-InP) | torch.float16 |

Доступны две официальные контрольные точки EasyAnimate для управления генерацией видео.

| чекпоинты | рекомендуемый тип данных для вывода |
|:---:|:---:|
| [`alibaba-pai/EasyAnimateV5.1-12b-zh-Control`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh-Control) | torch.float16 |
| [`alibaba-pai/EasyAnimateV5.1-12b-zh-Control-Camera`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh-Control-Camera) | torch.float16 |

Для серии EasyAnimateV5.1:
- Text-to-video (T2V) and Image-to-video (I2V) works for multiple resolutions. The width and height can vary from 256 to 1024.
- Модели T2V и I2V поддерживают генерацию с 1~49 кадрами и работают лучше всего при этом значении. Рекомендуется экспортировать видео со скоростью 8 FPS.

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

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

См. обзор [Quantization](../../quantization/overview), чтобы узнать больше о поддерживаемых бэкендах квантования и о том, как выбрать бэкенд, подходящий для вашей задачи. Пример ниже показывает, как загрузить квантованный [EasyAnimatePipeline](/docs/diffusers/main/ru/api/pipelines/easyanimate#diffusers.EasyAnimatePipeline) для инференса с помощью bitsandbytes.

```py
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, EasyAnimateTransformer3DModel, EasyAnimatePipeline
from diffusers.utils import export_to_video

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = EasyAnimateTransformer3DModel.from_pretrained(
    "alibaba-pai/EasyAnimateV5.1-12b-zh",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = EasyAnimatePipeline.from_pretrained(
    "alibaba-pai/EasyAnimateV5.1-12b-zh",
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "A cat walks on the grass, realistic style."
negative_prompt = "bad detailed"
video = pipeline(prompt=prompt, negative_prompt=negative_prompt, num_frames=49, num_inference_steps=30).frames[0]
export_to_video(video, "cat.mp4", fps=8)
```

## EasyAnimatePipeline[[diffusers.EasyAnimatePipeline]]

#### diffusers.EasyAnimatePipeline[[diffusers.EasyAnimatePipeline]]

```python
diffusers.EasyAnimatePipeline(vae: AutoencoderKLMagvit, text_encoder: transformers.models.qwen2_vl.modeling_qwen2_vl.Qwen2VLForConditionalGeneration | transformers.models.bert.modeling_bert.BertModel, tokenizer: transformers.models.qwen2.tokenization_qwen2.Qwen2Tokenizer | transformers.models.bert.tokenization_bert.BertTokenizer, transformer: EasyAnimateTransformer3DModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/easyanimate/pipeline_easyanimate.py#L186)

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

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

text_encoder (`~transformers.Qwen2VLForConditionalGeneration`, `~transformers.BertModel` | None) : EasyAnimate использует [qwen2 vl](https://huggingface.co/Qwen/Qwen2-VL-7B-Instruct) в V5.1.

tokenizer (`~transformers.Qwen2Tokenizer`, `~transformers.BertTokenizer` | None) : `Qwen2Tokenizer` или `BertTokenizer` для токенизации текста.

transformer ([EasyAnimateTransformer3DModel](/docs/diffusers/main/ru/api/models/easyanimate_transformer3d#diffusers.EasyAnimateTransformer3DModel)) : модель EasyAnimate, разработанная командой EasyAnimate.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик, используемый в связке с EasyAnimate для удаления шума из закодированных латентов изображения.

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

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

EasyAnimate использует один текстовый энкодер [qwen2 vl](https://huggingface.co/Qwen/Qwen2-VL-7B-Instruct) в V5.1.

#### __call__[[diffusers.EasyAnimatePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, num_frames: int | None = 49, height: int | None = 512, width: int | None = 512, num_inference_steps: int | None = 50, guidance_scale: float | None = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float | None = 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, timesteps: list[int] | None = 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, 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 = ['latents'], guidance_rescale: float = 0.0)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/easyanimate/pipeline_easyanimate.py#L524)

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

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

num_frames (`int`, *optional*) : Длина сгенерированного видео (в кадрах).

height (`int`, *optional*) : Высота генерируемого изображения в пикселях.

width (`int`, *необязательный*) : Ширина сгенерированного изображения в пикселях.

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

guidance_scale (`float`, *optional*, по умолчанию 5.0) : Поощряет модель согласовывать выходные данные с подсказками. Более высокое значение может снизить качество изображения.

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

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

eta (`float`, *optional*, по умолчанию 0.0) : Применяется к расписанию DDIM. Управляется параметром eta из соответствующей литературы.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Генератор для обеспечения воспроизводимости при генерации изображений.

latents (`torch.Tensor`, *необязательный*) : Предопределённые тензоры латентных переменных для обусловливания генерации.

prompt_embeds (`torch.Tensor`, *необязательный*) : Векторные представления текста для промптов. Переопределяет строковые входные данные промптов для большей гибкости.

negative_prompt_embeds (`torch.Tensor`, *необязательный*) : Векторы вложений для отрицательных промптов. Если задано, переопределяет строковые входные данные.

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

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

output_type (`str`, *необязательный*, по умолчанию "latent") : Формат генерируемого вывода, в виде изображения PIL или массива NumPy.

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

callback_on_step_end (`Callable`, *необязательный*) : Функции, вызываемые в конце каждого шага денойзинга.

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

guidance_rescale (`float`, *необязательный*, по умолчанию 0.0) : Настройка уровней шума на основе масштаба руководства.

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

**Возвращает:** [StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) или `tuple`

Если `return_dict` равно `True`, возвращается [StableDiffusionPipelineOutput](/docs/diffusers/main/ru/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список сгенерированных изображений, а второй — список значений `bool`, указывающих, содержит ли соответствующее сгенерированное изображение контент, нежелательный для просмотра на рабочем месте (nsfw).

Генерирует изображения или видео с использованием конвейера EasyAnimate на основе предоставленных промптов.

Примеры:
```python
>>> import torch
>>> from diffusers import EasyAnimatePipeline
>>> from diffusers.utils import export_to_video

>>> # Models: "alibaba-pai/EasyAnimateV5.1-12b-zh"
>>> pipe = EasyAnimatePipeline.from_pretrained(
...     "alibaba-pai/EasyAnimateV5.1-7b-zh-diffusers", torch_dtype=torch.float16
... ).to("cuda")
>>> prompt = (
...     "A panda, dressed in a small, red jacket and a tiny hat, sits on a wooden stool in a serene bamboo forest. "
...     "The panda's fluffy paws strum a miniature acoustic guitar, producing soft, melodic tunes. Nearby, a few other "
...     "pandas gather, watching curiously and some clapping in rhythm. Sunlight filters through the tall bamboo, "
...     "casting a gentle glow on the scene. The panda's face is expressive, showing concentration and joy as it plays. "
...     "The background includes a small, flowing stream and vibrant green foliage, enhancing the peaceful and magical "
...     "atmosphere of this unique musical performance."
... )
>>> sample_size = (512, 512)
>>> video = pipe(
...     prompt=prompt,
...     guidance_scale=6,
...     negative_prompt="bad detailed",
...     height=sample_size[0],
...     width=sample_size[1],
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=8)
```

#### encode_prompt[[diffusers.EasyAnimatePipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | list[str] | None = 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, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, max_sequence_length: int = 256)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/easyanimate/pipeline_easyanimate.py#L241)

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

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

device : (`torch.device`): устройство torch

dtype (`torch.dtype`) : тип данных torch

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

do_classifier_free_guidance (`bool`) : использовать ли классификаторное свободное наведение (classifier free guidance)

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

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

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

prompt_attention_mask (`torch.Tensor`, *необязательный*) : Маска внимания для промпта. Обязательна, если `prompt_embeds` передается напрямую.

negative_prompt_attention_mask (`torch.Tensor`, *необязательный*) : Маска внимания для негативного промпта. Обязательна, если `negative_prompt_embeds` передается напрямую.

max_sequence_length (`int`, *необязательный*) : максимальная длина последовательности, используемая для промпта.

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

## EasyAnimatePipelineOutput[[diffusers.pipelines.easyanimate.pipeline_output.EasyAnimatePipelineOutput]]

#### diffusers.pipelines.easyanimate.pipeline_output.EasyAnimatePipelineOutput[[diffusers.pipelines.easyanimate.pipeline_output.EasyAnimatePipelineOutput]]

```python
diffusers.pipelines.easyanimate.pipeline_output.EasyAnimatePipelineOutput(frames: Tensor)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/easyanimate/pipeline_output.py#L9)

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

frames (`torch.Tensor`, `np.ndarray` или list[list[PIL.Image.Image]]) : список видеовыходов — может представлять собой вложенный список длины `batch_size,` где каждый подсписок содержит последовательности денойзированных изображений PIL длины `num_frames.` Также может быть массивом NumPy или тензором Torch формы `(batch_size, num_frames, channels, height, width)`.

Класс вывода для конвейеров EasyAnimate.