# AutoencoderKLMiniMaxH3

MiniMax による [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) で使用される、KL 損失付きの動画変分オートエンコーダ (VAE) モデルです。因果的な 3D CNN エンコーダと非因果的な ViT デコーダを組み合わせ、空間方向に 16 倍、時間方向に 4 倍に圧縮します。

このモデルをライブラリ内の他の大多数のオートエンコーダーと区別する3つの点があります。

- **Latents はチャンネルごとに正規化されます。** `scaling_factor` は存在せず、パイプラインは `(latent - latents_mean) / latents_std` でエンコードし、`latent * latents_std + latents_mean` でデコードします。
- **ピクセルの規約は、`[0, 1]`を基準範囲とするImageNet正規化済みRGBです**。通常の`[-1, 1]`ではありません。`encode`は`(pixel - imagenet_mean) / imagenet_std`を期待し、`decode`は同じ空間の値を返します。そのため、パイプラインは`sample * imagenet_std + imagenet_mean`を適用し、後処理の前に`[0, 1]`にクランプします。
- **空間タイルリングはデフォルトで有効です。**MiniMax-H3はエンコードとデコードの両方でタイルリングを有効にしてリリースされており、公開されているフレームはブレンド済みタイルのものです。そのため、無効にすると出力が変わります。タイルのジオメトリを変更するには`enable_tiling`を、無効にするには`disable_tiling`を使用してください。

時間方向の幾何構造は、`clip_length`（エンコーダチャンクあたり17ピクセルフレーム）と`token_drop`（エンコードごとに末尾の潜在フレームを3フレーム破棄）によって固定されており、`17 * n + 5`ピクセルフレームが`5 * n + 2`潜在フレームに対応します。

```python
import torch
from diffusers import AutoencoderKLMiniMaxH3

vae = AutoencoderKLMiniMaxH3.from_pretrained(
    "MiniMaxAI/MiniMax-H3", subfolder="vae", dtype=torch.float32
).to("cuda")  # or "mps", "xpu", "cpu"
```

## AutoencoderKLMiniMaxH3[[diffusers.AutoencoderKLMiniMaxH3]]

#### diffusers.AutoencoderKLMiniMaxH3[[diffusers.AutoencoderKLMiniMaxH3]]

```python
diffusers.AutoencoderKLMiniMaxH3(in_channels: int = 3, out_channels: int = 3, latent_channels: int = 24, block_out_channels: tuple[int, ...] = (128, 256, 256, 512, 512, 1024), layers_per_block: int = 2, spatial_downsample_factors: tuple[int, ...] = (2, 2, 2, 2, 1, 1), temporal_downsample_factors: tuple[int, ...] = (1, 2, 2, 1, 1, 1), norm_num_groups: int = 32, norm_eps: float = 1e-06, spatial_padding_mode: str = 'reflect', decoder_num_layers: int = 36, decoder_num_attention_heads: int = 32, decoder_attention_head_dim: int = 64, decoder_num_register_tokens: int = 4, decoder_ffn_mult: int = 4, decoder_rope_theta: float = 100.0, decoder_rope_dim_ratio: float = 0.75, decoder_norm_eps: float = 1e-05, clip_length: int = 17, token_drop: int = 3, latents_mean: tuple[float, ...] = (0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), latents_std: tuple[float, ...] = (1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0))
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L505)

[MiniMax-H3](https://huggingface.co/MiniMaxAI)で使用される、因果的な3D CNNエンコーダーと非因果的なViTデコーダーを備えたVAEモデル。

このモデルは [ModelMixin](/docs/diffusers/v0.43.0/ja/api/models/overview#diffusers.ModelMixin) を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存など）については、スーパークラスのドキュメントを参照してください。

Latents は `scaling_factor` ではなく、チャンネルごとの `latents_mean` / `latents_std` で正規化されます。パイプラインは `(latent - latents_mean) / latents_std` でエンコードし、`latent * latents_std + latents_mean` でデコードします。

ピクセルの規約は、通常の`[-1, 1]`ではなく、`[0, 1]`を基準範囲とするImageNet正規化済みRGBです。`encode`は`(pixel - imagenet_mean) / imagenet_std`を期待し、`decode`は同じ空間の値を返すため、パイプラインは`sample * imagenet_std + imagenet_mean`（平均`(0.485, 0.456, 0.406)`、標準偏差`(0.229, 0.224, 0.225)`）を適用し、後処理の前に`[0, 1]`にクランプする必要があります。

時間方向の幾何構造は、`clip_length`(エンコーダチャンクあたり17ピクセルフレーム)と`token_drop`(エンコードごとに末尾の潜在フレーム3フレームを破棄)によって固定されます:`17 * n + 5`ピクセルフレームが`5 * n + 2`潜在フレームに対応します。

ライブラリ内のほとんどのオートエンコーダーとは異なり、空間タイル分割は**デフォルトで有効**です。MiniMax-H3はエンコードとデコードの両方でタイル分割を有効にしてリリースされており、公開されているフレームはブレンドされたタイルのものです。そのため、タイル分割を無効にすると出力が変わります。`enable_tiling`でタイルのジオメトリを変更し、`disable_tiling`で無効にしてください。

#### encode[[diffusers.AutoencoderKLMiniMaxH3.encode]]

```python
encode(x: Tensor, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L855)

**パラメータ:**

x (`torch.Tensor`) : 入力バッチの動画。形状は `(batch_size, in_channels, num_frames, height, width)` です。

return_dict (`bool`、*任意*、デフォルトは`True`) : プレーンなタプルではなく[AutoencoderKLOutput](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.models.modeling_outputs.AutoencoderKLOutput)を返すかどうか。

**戻り値:**

エンコードされた動画の潜在分布。MiniMax-H3 は、サンプリングされた潜在変数をその後 `latents_mean` / `latents_std` で正規化します。

バッチの動画を潜在変数にエンコードします。

#### decode[[diffusers.AutoencoderKLMiniMaxH3.decode]]

```python
decode(z: Tensor, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L883)

**パラメータ:**

z (`torch.Tensor`) : 潜在動画の入力バッチ。形状は `(batch_size, latent_channels, num_latent_frames, height, width)` です。

return_dict (`bool`、*任意*、デフォルトは`True`) : プレーンなタプルではなく[DecoderOutput](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput)を返すかどうか。

**戻り値:** [DecoderOutput](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) または `tuple`

デコードされた動画の形状は`(batch_size, out_channels, num_frames, height, width)`です。

バッチの潜在動画をデコードします。

#### enable_tiling[[diffusers.AutoencoderKLMiniMaxH3.enable_tiling]]

```python
enable_tiling(tile_sample_min_height: int | None = None, tile_sample_min_width: int | None = None, tile_sample_min_overlap_height: int | None = None, tile_sample_min_overlap_width: int | None = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L628)

**パラメータ:**

tile_sample_min_height (`int`, *任意*) : ピクセル空間におけるタイルの高さ。この値より高いフレームは、高さの次元に沿って分割されます。

tile_sample_min_width (`int`, *optional*) : ピクセル空間におけるタイルの幅。この幅を超えるフレームは、幅方向に分割されます。

tile_sample_min_overlap_height (`int`, *optional*) : 2つの連続する縦方向のタイル間の最小重複量（ピクセル単位）。

tile_sample_min_overlap_width (`int`, *optional*) : 2つの連続する水平タイル間の最小オーバーラップ量（ピクセル単位）。

タイル化されたVAEエンコード/デコードを有効にします。このオプションを有効にすると、VAEはフレームをタイルに分割し、各タイルを個別にエンコードまたはデコードした上で、重複部分を線形にブレンドして再結合します。これによりメモリ要件が低減され、より大きなフレームの処理が可能になります。

#### forward[[diffusers.AutoencoderKLMiniMaxH3.forward]]

```python
forward(sample: Tensor, sample_posterior: bool = False, generator: typing.Optional[torch.Generator] = None, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L908)

**パラメータ:**

sample (`torch.Tensor`) : 入力バッチの動画。形状は `(batch_size, in_channels, num_frames, height, width)` です。

sample_posterior (`bool`、*任意*、デフォルトは `False`) : モードを取るのではなく、事後分布からサンプリングするかどうか。

generator (`torch.Generator`, *任意*) : `sample_posterior=True` の場合に使用される Generator。

return_dict (`bool`、*任意*、デフォルトは`True`) : プレーンなタプルではなく[DecoderOutput](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput)を返すかどうか。

**戻り値:** [DecoderOutput](/docs/diffusers/v0.43.0/ja/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) または `tuple`

ラウンドトリップされた動画、形状は`(batch_size, out_channels, num_frames, height, width)`です。

バッチの動画をエンコードしてからデコードします。