#
# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
# このファイルは、ライセンスに準拠した場合にのみ使用できます。
# ライセンスのコピーは以下から入手できます
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
# 権限を管理する特定の言語については、ライセンスを参照してください。
# ライセンスの下での制限事項。
-->

# EasyAnimate
Alibaba PAI による [EasyAnimate](https://github.com/aigc-apps/EasyAnimate)。

GitHubページの説明: *EasyAnimateは、Diffusion TransformerのベースラインモデルおよびLoraモデルの学習、ならびにAI画像と動画の生成を目的として設計された、transformerアーキテクチャに基づくパイプラインです。事前学習済みのEasyAnimateモデルからの直接予測に対応しており、さまざまな解像度で、長さ約6秒、8fpsの動画を生成できます（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チェックポイントが2つあります。

| チェックポイント | 推奨される推論用データ型 |
|:---:|:---:|
| [`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チェックポイントが1つ利用可能です。

| チェックポイント | 推奨される推論用データ型 |
|:---:|:---:|
| [`alibaba-pai/EasyAnimateV5.1-12b-zh-InP`](https://huggingface.co/alibaba-pai/EasyAnimateV5.1-12b-zh-InP) | torch.float16 |

control-to-video用の公式EasyAnimateチェックポイントは2つ利用可能です。

| チェックポイント | 推奨される推論用データ型 |
|:---:|:---:|
| [`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 シリーズについて:
- テキストトゥビデオ（T2V）とイメージトゥビデオ（I2V）は、複数の解像度に対応しています。幅と高さは 256 から 1024 まで変更できます。
- T2VモデルとI2Vモデルの両方は、1〜49フレームでの生成に対応しており、この範囲のフレーム数で最も良好な結果が得られます。動画の書き出しには8 FPSでの出力を推奨します。

## 量子化

Quantizationは、モデルの重みを低精度のデータ型で保存することで、非常に大規模なモデルのメモリ要件を軽減するのに役立ちます。ただし、動画モデルによって、Quantizationが動画の品質に与える影響は異なります。

サポートされている量子化バックエンドと、ユースケースに対応する量子化バックエンドの選択について詳しくは、[Quantization](../../quantization/overview)の概要を参照してください。以下の例では、bitsandbytesを使用して量子化された[EasyAnimatePipeline](/docs/diffusers/main/ja/api/pipelines/easyanimate#diffusers.EasyAnimatePipeline)を読み込んで推論を実行する方法を示しています。

```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/ja/api/models/autoencoderkl_magvit#diffusers.AutoencoderKLMagvit)) : 動画を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (`~transformers.Qwen2VLForConditionalGeneration`, `~transformers.BertModel` | None) : EasyAnimate は V5.1 で [qwen2 vl](https://huggingface.co/Qwen/Qwen2-VL-7B-Instruct) を使用しています。

tokenizer (`~transformers.Qwen2Tokenizer`、`~transformers.BertTokenizer` | None) : テキストをトークン化するための`Qwen2Tokenizer`または`BertTokenizer`。

transformer ([EasyAnimateTransformer3DModel](/docs/diffusers/main/ja/api/models/easyanimate_transformer3d#diffusers.EasyAnimateTransformer3DModel)) : EasyAnimate Team によって設計された EasyAnimate モデル。

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : EasyAnimate と組み合わせて使用し、エンコードされた画像の潜在変数からノイズを除去するためのスケジューラ。

EasyAnimate を使用したテキストから動画への生成を行う Pipeline です。

このモデルは [DiffusionPipeline](/docs/diffusers/main/ja/api/pipelines/overview#diffusers.DiffusionPipeline) を継承しています。ライブラリがすべてのパイプラインに対して実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

EasyAnimateはV5.1で1つのテキストエンコーダー[qwen2 vl](https://huggingface.co/Qwen/Qwen2-VL-7B-Instruct)を使用しています。

#### __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[str] = ['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`, *任意*) : 生成される動画の長さ（フレーム数）。

height (`int`, *任意*) : 生成される画像の高さ（ピクセル単位）。

width (`int`, *任意*) : 生成される画像の幅（ピクセル単位）。

num_inference_steps (`int`、*optional*、デフォルト値は 50) : 生成時のデノイジングステップ数。ステップ数が多いほど画像の品質は向上する傾向がありますが、推論速度は低下します。

guidance_scale (`float`、*任意*、デフォルト値は 5.0) : モデルがプロンプトと出力を整合させることを促します。値を高くすると、画像の品質が低下する可能性があります。

negative_prompt (`str` または `list[str]`、*省略可能*) : 生成時に除外する内容を指定するプロンプトです。指定しない場合、`negative_prompt_embeds` が使用されます。

num_images_per_prompt (`int`、*optional*、デフォルトは 1) : 各プロンプトに対して生成する画像の数。

eta (`float`、*任意*、デフォルト値は 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]`、*任意*) : デノイジングプロセスに使用するカスタムタイムステップ。定義されていない場合、`num_inference_steps` に対するスケジューラのデフォルトスケジュールが使用されます。

**戻り値:** [StableDiffusionPipelineOutput](/docs/diffusers/main/ja/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) または `tuple`

If `return_dict` is `True`, [StableDiffusionPipelineOutput](/docs/diffusers/main/ja/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) is returned, otherwise a `tuple` is returned where the first element is a list with the generated images and the second element is a list of `bool`s indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content.

提供されたプロンプトに基づいて、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 dtype

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` 入力引数から negative_prompt_embeds が生成されます。

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,` 長のネストされたリストであり、各サブリストには `num_frames.` 長のデノイズ済み PIL 画像シーケンスが含まれる場合があります。また、`(batch_size, num_frames, channels, height, width)` の形状を持つ NumPy 配列や Torch テンソルである場合もあります。

EasyAnimate パイプライン用の出力クラスです。