# AutoencoderKLMiniMaxH3Audio

MiniMax 在 [MiniMax-H3](https://huggingface.co/MiniMaxAI) 中使用的音频自编码器。它直接以波形作为输入和输出，没有 mel 前端，也没有独立的声码器：其结构包括一个源自 DAC 的步幅卷积编码器、一个将特征投影到扩散潜变量宽度的因果注意力层，以及一个 BigVGAN 解码器。

编码器在 32 kHz 采样率下每次跳跃 800 个采样点，即每秒生成 40 个潜在向量，因此长度为 `800 * n` 个采样点的波形将编码为 `n` 个潜在向量。对于长度不是跳跃长度整数倍的波形，将在右侧进行填充。

因果注意力投影会经过注意力调度器，因此 `set_attention_backend` 对其生效；其掩码为 `is_causal=True`，除 `_native_npu` 外，所有后端均支持该掩码，因为 `_native_npu` 的内核不接受因果标志。

自编码器是 **mono** 的，并且使用 `latents_mean` / `latents_std` 按通道对潜变量进行归一化，而不是使用标量 `scaling_factor`。MiniMax-H3 将立体声作为两个 *batch* 项处理，并且始终使用后验均值（`latent_dist.mode()`），从不使用采样值。

```python
import torch
from diffusers import AutoencoderKLMiniMaxH3Audio

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

## AutoencoderKLMiniMaxH3Audio[[diffusers.AutoencoderKLMiniMaxH3Audio]]

#### diffusers.AutoencoderKLMiniMaxH3Audio[[diffusers.AutoencoderKLMiniMaxH3Audio]]

```python
diffusers.AutoencoderKLMiniMaxH3Audio(encoder_dim: int = 64, encoder_rates: tuple[int, ...] = (2, 4, 4, 5, 5), latent_dim: int = 2048, latent_channels: int = 32, num_attention_heads: int = 8, decoder_dim: int = 1024, decoder_rates: tuple[int, ...] = (5, 5, 2, 2, 2, 2, 2), decoder_kernel_sizes: tuple[int, ...] = (9, 9, 4, 4, 4, 4, 4), resblock_kernel_sizes: tuple[int, ...] = (3, 7, 11), resblock_dilation_sizes: tuple[tuple[int, ...], ...] = ((1, 3, 5), (1, 3, 5), (1, 3, 5)), sampling_rate: int = 32000, latents_mean: list[float] | None = None, latents_std: list[float] | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py#L489)

**参数：**

encoder_dim (`int`，默认为 `64`)：编码器第一个卷积的通道宽度；在每个下采样阶段翻倍。

encoder_rates (`tuple[int]`，默认为 `(2, 4, 4, 5, 5)`)：编码器步幅。它们的乘积（`800`）即为跳长，即在 32 kHz 下为每秒 40 个潜在变量。

latent_dim (`int`，默认值为 `2048`)：在潜在投影之前/之后，编码器主干和解码器输入的宽度。

latent_channels (`int`，默认为 `32`)：扩散潜变量的宽度，即 `mean_proj` / `logs_proj` 的输出通道数。

num_attention_heads (`int`，默认为 `8`)：因果注意力投影 `pre_block` 中的注意力头数量。

decoder_dim (`int`，默认为 `1024`)：BigVGAN 的初始通道数；在每个上采样阶段减半。

decoder_rates (`tuple[int]`，默认为 `(5, 5, 2, 2, 2, 2, 2)`)：BigVGAN 的上采样率。它们的乘积必须等于 `prod(encoder_rates)`。

decoder_kernel_sizes (`tuple[int]`，默认为 `(9, 9, 4, 4, 4, 4, 4)`)：每个上采样阶段的转置卷积核大小。

resblock_kernel_sizes (`tuple[int]`，默认为 `(3, 7, 11)`)：每个上采样阶段中并行 AMP 残差块的核大小。

resblock_dilation_sizes (`tuple[tuple[int]]`，默认为 `((1, 3, 5), (1, 3, 5), (1, 3, 5))`)：每个 AMP 块的膨胀率。

sampling_rate (`int`，默认为 `32000`)：波形采样率。

latents_mean (`list[float]`, *可选*) : 流水线用于对潜变量进行归一化/反归一化的逐通道潜变量均值。

latents_std (`list[float]`, *可选*) : 流水线用于对潜变量进行归一化/反归一化的逐通道潜变量标准差。

[MiniMax-H3](https://huggingface.co/MiniMaxAI) 所使用的音频自编码器：一个 DAC 谱系的卷积编码器和一个 BigVGAN 解码器，直接处理单声道 32 kHz 波形。

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

#### encode[[diffusers.AutoencoderKLMiniMaxH3Audio.encode]]

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py#L583)

**参数：**

sample (`torch.Tensor`) : 形状为 `[batch_size, 1, samples]` 的单声道波形。MiniMax-H3 将参考片段的两个立体声通道作为 `batch_size = 2` 传入。

return_dict (`bool`，默认为 `True`)：是否返回 `MiniMaxH3AudioEncoderOutput` 而不是普通元组。

**返回：** `MiniMaxH3AudioEncoderOutput` 或 `tuple`

`[batch_size, latent_channels, samples / 800]` 上的潜在后验分布。

将波形编码为音频潜在后验分布。

波形首先会进行右侧填充，使其长度成为 `hop_length`（800 个采样点）的整数倍。MiniMax-H3 始终使用后验 **均值**（`latent_dist.mode()`）——参考流水线从不评估 `logs_proj` 头。

#### decode[[diffusers.AutoencoderKLMiniMaxH3Audio.decode]]

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py#L623)

**参数：**

latents (`torch.Tensor`) : 形状为 `[batch_size, latent_channels, num_frames]` 的非归一化潜在变量。MiniMax-H3 将两个立体声通道作为 `batch_size = 2` 传入。

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

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

形状为 `[batch_size, 1, num_frames * 800]` 的波形，其值被限制在 `[-1, 1]` 范围内。

将音频潜在变量解码为波形。

#### forward[[diffusers.AutoencoderKLMiniMaxH3Audio.forward]]

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_kl_minimax_h3_audio.py#L653)

**参数：**

sample (`torch.Tensor`) : 形状为 `[batch_size, 1, samples]` 的单声道波形。

sample_posterior (`bool`，默认为 `False`)：是否对后验分布进行采样，而不是取其众数。MiniMax-H3 使用众数。

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

generator (`torch.Generator`，*可选*)：当 `sample_posterior=True` 时使用的生成器。

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

形状为 `[batch_size, 1, num_frames * 800]` 的往返波形，已截断至 `[-1, 1]`。

对波形进行编码，然后解码。