#
# 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)

Monash University、Shanghai AI Lab、Nanjing University、Nanyang Technological University による [Latte: Latent Diffusion Transformer for Video Generation](https://huggingface.co/papers/2401.03048)。

論文の抄録は以下の通りです：

*私たちは、動画生成のための新しい Latent Diffusion Transformer、すなわち Latte を提案します。Latte はまず入力動画から時空間トークンを抽出し、その後、一連の Transformer ブロックを用いて潜在空間における動画の分布をモデル化します。動画から抽出される大量のトークンをモデル化するために、入力動画の空間次元と時間次元を分解する観点から、4 つの効率的なバリアントを導入します。生成動画の品質を向上させるため、動画クリップのパッチ埋め込み、モデルのバリアント、タイムステップとクラス情報の注入、時間的位置埋め込み、学習戦略を含む厳密な実験分析を通じて、Latte のベストプラクティスを決定しました。包括的な評価により、Latte は FaceForensics、SkyTimelapse、UCF101、Taichi-HD という 4 つの標準的な動画生成データセットにおいて、最先端の性能を達成することが示されました。さらに、Latte をテキストから動画生成（T2V）タスクに拡張し、最近の T2V モデルと比較して同等の結果を達成しました。私たちは、Latte が動画生成のための拡散モデルへの Transformer の統合に関する今後の研究に貴重な洞察を提供すると強く信じています。*

**ハイライト**: Latte は、異なるモダリティのモデリングのバックボーンとして提案された潜在拡散トランスフォーマーです（ここではテキストから動画への生成のために学習されています）。4 つの標準的な動画ベンチマーク、[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) で、最先端の性能を達成しています。評価用のデータセットの準備とダウンロードについては、[この https 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]
```

80GB A100マシンでの[ベンチマーク](https://gist.github.com/a-r-r-o-w/4e1694ca46374793c0361d740a99ff19)結果は以下の通りです:

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

## 量子化

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

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

```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/ja/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) の Tokenizer。

transformer ([LatteTransformer3DModel](/docs/diffusers/v0.43.0/ja/api/models/latte_transformer3d#diffusers.LatteTransformer3DModel)) : 入力テキストの条件付き`LatteTransformer3DModel`。エンコードされた動画の潜在変数（latents）のノイズ除去を行います。

scheduler ([SchedulerMixin](/docs/diffusers/v0.43.0/ja/api/schedulers/overview#diffusers.SchedulerMixin)) : `transformer` と組み合わせて、エンコードされた動画の潜在変数（latents）のノイズ除去に使用するスケジューラ。

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

このモデルは [DiffusionPipeline](/docs/diffusers/v0.43.0/ja/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`、*任意*、デフォルトは 100) : デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常、より高品質な動画が生成されます。

timesteps (`list[int]`、*任意*) : デノイジングプロセスに使用するカスタムタイムステップ。未定義の場合、等間隔の`num_inference_steps`個のタイムステップが使用されます。降順で指定する必要があります。

guidance_scale (`float`、*任意*、デフォルト値は 7.0) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)で定義されているガイダンススケールです。`guidance_scale` は、[Imagen Paper](https://huggingface.co/papers/2205.11487)の式 2 の `w` として定義されています。`guidance_scale > 1` を設定することで、ガイダンススケールが有効になります。ガイダンススケールを高くすると、`prompt` のテキストと密接に関連する動画の生成が促されますが、通常は動画の品質が低下する傾向があります。

video_length (`int`、*optional*、デフォルトは 16) : 生成される動画フレームの数です。デフォルトは 16 フレームで、8 フレーム/秒

num_images_per_prompt (`int`、*optional*、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。

height (`int`、*optional*、デフォルトは self.unet.config.sample_size) : 生成される動画のピクセル単位の縦幅。

width (`int`、*任意*、デフォルトは self.unet.config.sample_size) : 生成される動画のピクセル単位の幅。

eta (`float`、*任意*、デフォルト値は 0.0) : DDIM 論文におけるパラメータ eta (η) に相当します: https://huggingface.co/papers/2010.02502。[schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/ddim#diffusers.DDIMScheduler) にのみ適用され、それ以外のスケジューラーでは無視されます。

generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。

latents (`torch.FloatTensor`, *任意*) : 動画生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。

prompt_embeds (`torch.FloatTensor`、*任意*) : 事前に生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを簡単に実行できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。

negative_prompt_embeds (`torch.FloatTensor`, *任意*) : 事前に生成されたネガティブテキスト埋め込み。Latte の場合、このネガティブプロンプトは "" である必要があります。指定されない場合、`negative_prompt` 入力引数から negative_prompt_embeds が生成されます。

output_type (`str`、*任意*、デフォルトは `"pil"`) : generate video の出力形式。[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`、*任意*) : 各デノイジングステップの終了時に呼び出されるコールバック関数、またはコールバック関数のリストです。

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`、*optional*、デフォルトは 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` の場合、この関数はテキスト埋め込みをマスクします。

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。