Diffusers documentation
自编码器SAME
自编码器SAME
SAME（Semantically-Aligned Music Encoder，语义对齐音乐编码器）自编码器被 Stable Audio 3 用于将立体声音频波形压缩为紧凑的潜在序列并进行重建。
编码器堆叠了 SAMETransformerResamplingBlock 模块，每个模块将固定数量的音频 patch 帧分组，并通过差分 Transformer 生成一个可学习的输出 token。解码器则反转此过程，将每个潜在 token 扩展回一组音频帧 patch。
软归一化瓶颈（SoftNormBottleneck）在扩散模型之前和之后对潜在变量进行归一化，从而提供稳定的训练动态。
AutoencoderSAME
class diffusers.AutoencoderSAME
< source >( audio_channels: int = 2patch_size: int = 256encoder_channels: int = 128encoder_c_mults: typing.List[int] = (6,)encoder_strides: typing.List[int] = (16,)encoder_transformer_depths: typing.List[int] = (6,)latent_dim: int = 256use_differential_attention: bool = Truedim_heads: int = 64ff_mult: int = 3sliding_window: int = 1encoder_sinusoidal_blocks: typing.List[int] = (0,)decoder_sinusoidal_blocks: typing.List[int] = (0,)sampling_rate: int = 44100 )
参数
- audio_channels — 音频通道数（立体声为 2）。
- patch_size — 在 TRB 编码器之前应用（并在 TRB 解码器之后反转）的非重叠 patch 大小。对总下采样率的贡献为
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 — 编码器中每个 TRB 末尾使用
sinFFN 门控的 Transformer 层数（SAME-L:(0,)）。 - decoder_sinusoidal_blocks — 解码器中每个 TRB 末尾使用
sinFFN 门控的 Transformer 层数（SAME-L：(8,)）。 - sampling_rate — 音频采样率，单位为 Hz（例如 44100）。
来自 Stable Audio 3（arXiv 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,)。
# 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
< source >( sample: Tensorreturn_dict: bool = True )
将立体声音频编码为潜在表示。
decode
< source >( latents: Tensorreturn_dict: bool = True )
将潜在变量解码回立体声音频。
forward
< source >( sample: Tensorreturn_dict: bool = True )
对 sample 进行编码并立即解码（重建）。
SAMETransformerResamplingBlock
class diffusers.models.autoencoders.autoencoder_same.SAMETransformerResamplingBlock
< source >( in_channels: intout_channels: intstride: intmode: str = 'encoder'transformer_depth: int = 3dim_heads: int = 128use_differential: bool = Trueff_mult: int = 3sliding_window: int = 1sinusoidal_blocks: int = 0 )
参数
- 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 — 末尾使用
sinFFN 门控而非 SiLU 的 Transformer 层数。
SAME 的核心构建模块。
编码器模式（步长 S）： 将 S 个连续的输入帧分组为一个片段，追加一个可学习的输出嵌入，然后在展平后的完整片段序列上运行 D 层 transformer，仅保留输出嵌入 → 实现 S 倍下采样。
解码器模式（步幅 S）： 将 1 个输入帧与 S 个可学习输出嵌入分组，在展平后的完整序列上运行 D 层 Transformer，然后保留 S 个输出嵌入 → 实现 S 倍上采样。
Attention 在展平的片段序列上使用重叠的 滑动窗口 带状掩码：每个 token 关注其左右两侧各 sliding_window * (stride + 1) 个相邻 token。RoPE 基于完整序列长度计算。这与参考实现完全一致（单个不重叠的块仅在一个片段上匹配）。
AutoencoderSAMEOutput
class diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEOutput
< source >( latents: Tensor )
AutoencoderSAMEDecoderOutput
class diffusers.models.autoencoders.autoencoder_same.AutoencoderSAMEDecoderOutput
< source >( sample: Tensor )