# AutoencoderKLMiniMaxH3

MiniMax 的 [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) 中使用的带 KL 散度损失的视频变分自编码器（VAE）模型。该模型将因果 3D CNN 编码器与非因果 ViT 解码器相结合，在空间维度上压缩 16 倍，在时间维度上压缩 4 倍。

它与该库中大多数自编码器有三点不同：

- **潜变量按通道进行归一化。** 不存在 `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/main/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L505)

一种采用因果 3D CNN 编码器和非因果 ViT 解码器的 VAE 模型，用于 [MiniMax-H3](https://huggingface.co/MiniMaxAI)。

该模型继承自 [ModelMixin](/docs/diffusers/main/zh/api/models/overview#diffusers.ModelMixin)。请查阅其父类文档，了解为所有模型实现的通用方法（例如下载或保存）。

Latents 使用逐通道的 `latents_mean` / `latents_std` 进行归一化，而不是使用 `scaling_factor`；pipeline 通过 `(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.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/main/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/main/zh/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/main/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/main/zh/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) 而不是普通元组。

**返回：** [DecoderOutput](/docs/diffusers/main/zh/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/main/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3.py#L628)

**参数：**

tile_sample_min_height (`int`, *可选*) : 像素空间中的瓦片高度。高度超过此值的帧将沿高度维度进行分割。

tile_sample_min_width (`int`，*可选*)：像素空间中的瓦片宽度。宽度超过此值的帧将沿宽度维度进行分割。

tile_sample_min_overlap_height (`int`，*可选*)：两个连续垂直瓦片之间的最小重叠量，以像素为单位。

tile_sample_min_overlap_width (`int`, *可选*)：两个相邻水平切片之间的最小重叠像素数。

启用分块 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/main/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` 时使用的生成器。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [DecoderOutput](/docs/diffusers/main/zh/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) 而不是普通元组。

**返回：** [DecoderOutput](/docs/diffusers/main/zh/api/models/autoencoderkl_qwenimage#diffusers.models.autoencoders.vae.DecoderOutput) 或 `tuple`

往返处理后的视频，形状为 `(batch_size, out_channels, num_frames, height, width)`。

对一批视频进行编码，然后解码。