Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /zh /api /models /autoencoder_same.md

mishig

2 days ago

preview code

download

raw

9.36 kB

# 自编码器SAME

**SAME**（Semantically-Aligned Music Encoder，语义对齐音乐编码器）自编码器被 [Stable Audio 3](https://stability.ai/news-updates/meet-stable-audio-3-the-model-family-built-for-artistic-experimentation-with-open-weight-models) 用于将立体声音频波形压缩为紧凑的潜在序列并进行重建。

编码器堆叠了 `SAMETransformerResamplingBlock` 模块，每个模块将固定数量的音频 patch 帧分组，并通过差分 Transformer 生成一个可学习的输出 token。解码器则反转此过程，将每个潜在 token 扩展回一组音频帧 patch。

软归一化瓶颈（`SoftNormBottleneck`）在扩散模型之前和之后对潜在变量进行归一化，从而提供稳定的训练动态。

## 自编码器SAME[[diffusers.AutoencoderSAME]]

#### diffusers.AutoencoderSAME[[diffusers.AutoencoderSAME]]

```python
diffusers.AutoencoderSAME(audio_channels: int = 2, patch_size: int = 256, encoder_channels: int = 128, encoder_c_mults: typing.List[int] = (6,), encoder_strides: typing.List[int] = (16,), encoder_transformer_depths: typing.List[int] = (6,), latent_dim: int = 256, use_differential_attention: bool = True, dim_heads: int = 64, ff_mult: int = 3, sliding_window: int = 1, encoder_sinusoidal_blocks: typing.List[int] = (0,), decoder_sinusoidal_blocks: typing.List[int] = (0,), sampling_rate: int = 44100)
```

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

**参数：**

audio_channels : 音频通道数（立体声为 2）。
patch_size : 在 TRB 编码器之前应用的互不重叠的 patch 大小（并在 TRB 解码器之后进行反转）。对总下采样率的贡献为 `patch_size ×`。生产环境中的取值：256。

encoder_channels : TRB 的基础通道数。SAME-S 为 128，SAME-L 为 256。
encoder_c_mults : 每个 TRB 层级的通道乘数（每个 TRB 一个条目）。SAME-S 和 SAME-L 均使用 `(6,)` —— 单个 TRB，其隐藏维度为 `encoder_channels × 6`。

encoder_strides : 每个 TRB 层级的下采样/上采样步长。SAME-S 和 SAME-L 均使用 `(16,)` — 一个步长为 16 的 TRB。
encoder_transformer_depths : 每个 TRB 层级的 Transformer 层数。SAME-S 为 6，SAME-L 为 12。
latent_dim : 潜在空间的维度。两种变体均为 256。

use_differential_attention : 如果 `True`，则在每个 TRB transformer 块内部使用 differential attention（SAME-S/L 默认开启）。

dim_heads : 注意力头维度。生产环境 SAME-S/L 为 64。
ff_mult : SwiGLU 前馈扩展因子。

sliding_window : 用于带状掩码注意力的滑动窗口半宽（以潜在变量计）。生产环境中的 SAME-S/L 使用 1。
encoder_sinusoidal_blocks : 编码器中使用 `sin` FFN 门控的尾部 Transformer 层数（SAME-L: `(0,)`）。
decoder_sinusoidal_blocks : 解码器中使用 `sin` FFN 门控的尾部 Transformer 层数（SAME-L: `(8,)`）。
sampling_rate : 音频采样率，单位为 Hz（例如 44100）。

来自 *Stable Audio 3*（[arXiv 2605.17991](https://arxiv.org/abs/2605.17991)）的语义对齐音乐编码器（SAME）自编码器。

该模型由以下部分组成：

- **补丁嵌入** — 将立体声音频重塑为不重叠的补丁，以时间换取通道数（`patch_size ×` 下采样，无可学习参数）。
- **编码器 TRB 堆栈** — 由 `SAMETransformerResamplingBlock` 块组成，进一步以 `∏(encoder_strides)` 为因子进行下采样。
- **Soft-norm 瓶颈** — 带有运行标准差的可学习仿射归一化。
- **解码器 TRB 堆栈** — 与编码器呈镜像反转结构。
- **Unpatch** — 将通道维度重新整形回时间维度。

总下采样比率：`patch_size × ∏(encoder_strides)`。

默认超参数与 **SAME-S** 检查点（`stabilityai/SAME-S`）相匹配。若要加载 **SAME-L**（`stabilityai/SAME-L`，由 SA3 Medium 使用），请传入 `encoder_channels=256, encoder_transformer_depths=(12,)`。

```python
# SAME-S (108 M params, used by SA3 small models) model = AutoencoderSAME() # default values
# SAME-L (852 M params, used by SA3 Medium) model = AutoencoderSAME(encoder_channels=256,
encoder_transformer_depths=(12,))
```

#### encode[[diffusers.AutoencoderSAME.encode]]

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

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

**参数：**

sample : `(B, audio_channels, T)` 波形张量。

return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEOutput`。
**返回值：**
形状为 `(B, latent_dim, T // downsampling_ratio)` 的潜在张量（当 *return_dict* 为 `True` 时，包裹在 `AutoencoderSAMEOutput` 中）。

将立体声音频编码为潜在表示。

#### decode[[diffusers.AutoencoderSAME.decode]]

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

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

**参数：**

latents : `(B, latent_dim, T_latent)` 潜在张量。

return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEDecoderOutput`。
**返回值：**
形状为 `(B, audio_channels, T_latent × downsampling_ratio)` 的波形张量（当 *return_dict* 为 `True` 时，包裹在 `AutoencoderSAMEDecoderOutput` 中）。

将潜在变量解码回立体声音频。

#### forward[[diffusers.AutoencoderSAME.forward]]

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

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

**参数：**

sample : `(B, audio_channels, T)` 波形张量。

return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEDecoderOutput`。
**返回值：**
重构后的波形（形状与 *sample* 相同，可能因填充而更长），当 *return_dict* 为 `True` 时，会包裹在 `AutoencoderSAMEDecoderOutput` 中。

对 *sample* 进行编码并立即解码（重建）。

## SAMETransformerResamplingBlock[[diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock]]
#### diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock[[diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock]]
```python
diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock(in_channels: int, out_channels: int, stride: int, mode: str = 'encoder', transformer_depth: int = 3, dim_heads: int = 128, use_differential: bool = True, ff_mult: int = 3, sliding_window: int = 1, sinusoidal_blocks: int = 0)
```
[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_same.py#L294)
**参数：**
in_channels : 输入通道数。
out_channels : 输出通道数。
stride : 下采样/上采样因子。
mode : `"encoder"` 或 `"decoder"`。
transformer_depth : `TransformerBlock` 层的数量。
dim_heads : 注意力头维度。
use_differential : 是否使用差分注意力。
ff_mult : 前馈扩展因子。
sliding_window : 潜在表示中的滑动窗口半宽（频带半宽为 `sliding_window * (stride + 1)`）。
sinusoidal_blocks : 使用 `sin` FFN 门控而非 SiLU 的末尾 Transformer 层数。
SAME 的核心构建模块。
**编码器模式**（步长 S）：将 S 个连续输入帧分组为一个片段，追加一个可学习的输出嵌入，然后在展平后的完整片段序列上运行 D 层 Transformer，仅保留输出嵌入 → 实现 S 倍下采样。
**解码器模式**（步幅 S）：将 1 个输入帧与 S 个可学习输出嵌入分组，在展平后的完整序列上运行 D 层 Transformer，然后保留 S 个输出嵌入 → 实现 S 倍上采样。
Attention 在展平的分段序列上使用重叠的 *滑动窗口* 带状掩码：每个 token 关注其左右两侧各 `sliding_window * (stride + 1)` 个邻居。RoPE 基于完整序列长度计算。这与参考实现完全一致（单个不重叠的块仅在一个分段上匹配）。
## AutoencoderSAMEOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput]]
#### diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput]]
```python
diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput(latents: Tensor)
```
[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/autoencoder_same.py#L52)
[AutoencoderSAME.encode()](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_same#diffusers.AutoencoderSAME.encode) 的输出。
## AutoencoderSAMEDecoderOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput]]

#### diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput]]

```python
diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput(sample: Tensor)
```

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

[AutoencoderSAME.decode()](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode) 的输出。

Xet Storage Details

Size:: 9.36 kB
Xet hash:: 99f7780d064e5647c58cdd9e73aef014c992daa2e4029fa26941217628a63b4c

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 自编码器SAME

	SAME（Semantically-Aligned Music Encoder，语义对齐音乐编码器）自编码器被 [Stable Audio 3](https://stability.ai/news-updates/meet-stable-audio-3-the-model-family-built-for-artistic-experimentation-with-open-weight-models) 用于将立体声音频波形压缩为紧凑的潜在序列并进行重建。

	编码器堆叠了 `SAMETransformerResamplingBlock` 模块，每个模块将固定数量的音频 patch 帧分组，并通过差分 Transformer 生成一个可学习的输出 token。解码器则反转此过程，将每个潜在 token 扩展回一组音频帧 patch。

	软归一化瓶颈（`SoftNormBottleneck`）在扩散模型之前和之后对潜在变量进行归一化，从而提供稳定的训练动态。

	## 自编码器SAME[[diffusers.AutoencoderSAME]]

	#### diffusers.AutoencoderSAME[[diffusers.AutoencoderSAME]]

	```python
	diffusers.AutoencoderSAME(audio_channels: int = 2, patch_size: int = 256, encoder_channels: int = 128, encoder_c_mults: typing.List[int] = (6,), encoder_strides: typing.List[int] = (16,), encoder_transformer_depths: typing.List[int] = (6,), latent_dim: int = 256, use_differential_attention: bool = True, dim_heads: int = 64, ff_mult: int = 3, sliding_window: int = 1, encoder_sinusoidal_blocks: typing.List[int] = (0,), decoder_sinusoidal_blocks: typing.List[int] = (0,), sampling_rate: int = 44100)
	```

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

	参数：

	audio_channels : 音频通道数（立体声为 2）。

	patch_size : 在 TRB 编码器之前应用的互不重叠的 patch 大小（并在 TRB 解码器之后进行反转）。对总下采样率的贡献为 `patch_size ×`。生产环境中的取值：256。

	encoder_channels : TRB 的基础通道数。SAME-S 为 128，SAME-L 为 256。

	encoder_c_mults : 每个 TRB 层级的通道乘数（每个 TRB 一个条目）。SAME-S 和 SAME-L 均使用 `(6,)` —— 单个 TRB，其隐藏维度为 `encoder_channels × 6`。

	encoder_strides : 每个 TRB 层级的下采样/上采样步长。SAME-S 和 SAME-L 均使用 `(16,)` — 一个步长为 16 的 TRB。

	encoder_transformer_depths : 每个 TRB 层级的 Transformer 层数。SAME-S 为 6，SAME-L 为 12。

	latent_dim : 潜在空间的维度。两种变体均为 256。

	use_differential_attention : 如果 `True`，则在每个 TRB transformer 块内部使用 differential attention（SAME-S/L 默认开启）。

	dim_heads : 注意力头维度。生产环境 SAME-S/L 为 64。

	ff_mult : SwiGLU 前馈扩展因子。

	sliding_window : 用于带状掩码注意力的滑动窗口半宽（以潜在变量计）。生产环境中的 SAME-S/L 使用 1。

	encoder_sinusoidal_blocks : 编码器中使用 `sin` FFN 门控的尾部 Transformer 层数（SAME-L: `(0,)`）。

	decoder_sinusoidal_blocks : 解码器中使用 `sin` FFN 门控的尾部 Transformer 层数（SAME-L: `(8,)`）。

	sampling_rate : 音频采样率，单位为 Hz（例如 44100）。

	来自 Stable Audio 3（[arXiv 2605.17991](https://arxiv.org/abs/2605.17991)）的语义对齐音乐编码器（SAME）自编码器。

	该模型由以下部分组成：

	- 补丁嵌入 — 将立体声音频重塑为不重叠的补丁，以时间换取通道数（`patch_size ×` 下采样，无可学习参数）。
	- 编码器 TRB 堆栈 — 由 `SAMETransformerResamplingBlock` 块组成，进一步以 `∏(encoder_strides)` 为因子进行下采样。
	- Soft-norm 瓶颈 — 带有运行标准差的可学习仿射归一化。
	- 解码器 TRB 堆栈 — 与编码器呈镜像反转结构。
	- Unpatch — 将通道维度重新整形回时间维度。

	总下采样比率：`patch_size × ∏(encoder_strides)`。

	默认超参数与 SAME-S 检查点（`stabilityai/SAME-S`）相匹配。若要加载 SAME-L（`stabilityai/SAME-L`，由 SA3 Medium 使用），请传入 `encoder_channels=256, encoder_transformer_depths=(12,)`。

	```python
	# SAME-S (108 M params, used by SA3 small models) model = AutoencoderSAME() # default values

	# SAME-L (852 M params, used by SA3 Medium) model = AutoencoderSAME(encoder_channels=256,
	encoder_transformer_depths=(12,))
	```

	#### encode[[diffusers.AutoencoderSAME.encode]]

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

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

	参数：

	sample : `(B, audio_channels, T)` 波形张量。

	return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEOutput`。

	返回值：

	形状为 `(B, latent_dim, T // downsampling_ratio)` 的潜在张量（当 return_dict 为 `True` 时，包裹在 `AutoencoderSAMEOutput` 中）。

	将立体声音频编码为潜在表示。

	#### decode[[diffusers.AutoencoderSAME.decode]]

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

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

	参数：

	latents : `(B, latent_dim, T_latent)` 潜在张量。

	return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEDecoderOutput`。

	返回值：

	形状为 `(B, audio_channels, T_latent × downsampling_ratio)` 的波形张量（当 return_dict 为 `True` 时，包裹在 `AutoencoderSAMEDecoderOutput` 中）。

	将潜在变量解码回立体声音频。

	#### forward[[diffusers.AutoencoderSAME.forward]]

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

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

	参数：

	sample : `(B, audio_channels, T)` 波形张量。

	return_dict : 如果 `True`，则返回一个 `AutoencoderSAMEDecoderOutput`。

	返回值：

	重构后的波形（形状与 sample 相同，可能因填充而更长），当 return_dict 为 `True` 时，会包裹在 `AutoencoderSAMEDecoderOutput` 中。

	对 sample 进行编码并立即解码（重建）。

	## SAMETransformerResamplingBlock[[diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock]]

	#### diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock[[diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock]]

	```python
	diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock(in_channels: int, out_channels: int, stride: int, mode: str = 'encoder', transformer_depth: int = 3, dim_heads: int = 128, use_differential: bool = True, ff_mult: int = 3, sliding_window: int = 1, sinusoidal_blocks: int = 0)
	```

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

	参数：

	in_channels : 输入通道数。

	out_channels : 输出通道数。

	stride : 下采样/上采样因子。

	mode : `"encoder"` 或 `"decoder"`。

	transformer_depth : `TransformerBlock` 层的数量。

	dim_heads : 注意力头维度。

	use_differential : 是否使用差分注意力。

	ff_mult : 前馈扩展因子。

	sliding_window : 潜在表示中的滑动窗口半宽（频带半宽为 `sliding_window * (stride + 1)`）。

	sinusoidal_blocks : 使用 `sin` FFN 门控而非 SiLU 的末尾 Transformer 层数。

	SAME 的核心构建模块。

	编码器模式（步长 S）：将 S 个连续输入帧分组为一个片段，追加一个可学习的输出嵌入，然后在展平后的完整片段序列上运行 D 层 Transformer，仅保留输出嵌入 → 实现 S 倍下采样。

	解码器模式（步幅 S）：将 1 个输入帧与 S 个可学习输出嵌入分组，在展平后的完整序列上运行 D 层 Transformer，然后保留 S 个输出嵌入 → 实现 S 倍上采样。

	Attention 在展平的分段序列上使用重叠的滑动窗口带状掩码：每个 token 关注其左右两侧各 `sliding_window * (stride + 1)` 个邻居。RoPE 基于完整序列长度计算。这与参考实现完全一致（单个不重叠的块仅在一个分段上匹配）。

	## AutoencoderSAMEOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput]]

	#### diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput]]

	```python
	diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput(latents: Tensor)
	```

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

	[AutoencoderSAME.encode()](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_same#diffusers.AutoencoderSAME.encode) 的输出。

	## AutoencoderSAMEDecoderOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput]]

	#### diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput[[diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput]]

	```python
	diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput(sample: Tensor)
	```

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

	[AutoencoderSAME.decode()](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode) 的输出。