Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /pt /api /models /autoencoder_same.md

mishig

8 days ago

preview code

download

raw

9.96 kB

# AutoencoderSAME

O autoencoder **SAME** (Semantically-Aligned Music Encoder) é usado pelo [Stable Audio 3](https://stability.ai/news-updates/meet-stable-audio-3-the-model-family-built-for-artistic-experimentation-with-open-weight-models) para comprimir formas de onda de áudio estéreo em uma sequência latente compacta e reconstruí-las.

O codificador empilha módulos `SAMETransformerResamplingBlock`, cada um dos quais agrupa um número fixo de quadros de patch de áudio e produz um token de saída aprendível por meio de um transformador diferencial. O decodificador inverte esse processo, expandindo cada token latente de volta para um patch de quadros de áudio.

Um gargalo de normalização suave (`SoftNormBottleneck`) normaliza os latentes antes e depois do modelo de difusão, proporcionando dinâmicas de treinamento estáveis.

## AutoencoderSAME[[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)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L608)

**Parâmetros:**

audio_channels : Número de canais de áudio (2 para estéreo).
patch_size : Tamanho de patch não sobreposto aplicado antes do codificador TRB (e revertido após o decodificador TRB). Contribui com `patch_size ×` para a razão total de downsampling. Valor de produção: 256.

encoder_channels : Número de canais base para o TRB. 128 para SAME-S, 256 para SAME-L.
encoder_c_mults : Multiplicador de canal para cada nível de TRB (uma entrada por TRB). Tanto SAME-S quanto SAME-L usam `(6,)` — um único TRB cuja dimensão oculta é `encoder_channels × 6`.

encoder_strides : Passo de down-/up-sampling para cada nível de TRB. Tanto SAME-S quanto SAME-L usam `(16,)` — um TRB com passo 16.
encoder_transformer_depths : Camadas de Transformer por nível de TRB. 6 para SAME-S, 12 para SAME-L.
latent_dim : Dimensão do espaço latente. 256 para ambas as variantes.

use_differential_attention : Se `True`, use atenção diferencial dentro de cada bloco do transformador TRB (padrão ativado para SAME-S/L).

dim_heads : Dimensão da cabeça de atenção. 64 para produção SAME-S/L.
ff_mult : Fator de expansão do feed-forward SwiGLU.

sliding_window : Meia-largura da janela deslizante (em latentes) para a atenção com máscara de banda. O uso de SAME-S/L em produção é 1.
encoder_sinusoidal_blocks : Contagem por TRB das camadas finais de transformador que usam o gating de FFN `sin` no codificador (SAME-L: `(0,)`).
decoder_sinusoidal_blocks : Contagem por TRB das camadas finais de transformador que usam o gating de FFN `sin` no decodificador (SAME-L: `(8,)`).
sampling_rate : Taxa de amostragem de áudio em Hz (ex.: 44100).

Autoencoder Semantically-Aligned Music Encoder (SAME) do *Stable Audio 3* ([arXiv 2605.17991](https://arxiv.org/abs/2605.17991)).

O modelo consiste em:

- **Embedding de patch** — reorganiza o áudio estéreo em patches não sobrepostos, trocando tempo por canais (`patch_size ×` de redução de amostragem, sem parâmetros aprendidos).
- **Stack de codificador TRB** — blocos `SAMETransformerResamplingBlock` que realizam mais uma etapa de redução de amostragem por um fator de `∏(encoder_strides)`.
- **Gargalo de normalização suave** — normalização afim aprendível com desvio padrão em execução.
- **Pilha TRB do decodificador** — espelha o codificador em ordem inversa.
- **Unpatch** — reorganiza os canais de volta para a dimensão de tempo.

Razão total de subamostragem: `patch_size × ∏(encoder_strides)`.

Os hiperparâmetros padrão correspondem ao checkpoint **SAME-S** (`stabilityai/SAME-S`). Para carregar o **SAME-L** (`stabilityai/SAME-L`, usado pelo SA3 Medium), passe `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)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L733)

**Parâmetros:**

sample : tensor de forma de onda `(B, audio_channels, T)`.

return_dict : Se `True`, retorna um `AutoencoderSAMEOutput`.
**Retorna:**
Tensor latente de forma `(B, latent_dim, T // downsampling_ratio)` (envolvido em `AutoencoderSAMEOutput` quando *return_dict* é `True`).

Codifique áudio estéreo em latentes.

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

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L758)

**Parâmetros:**

latents : tensor latente `(B, latent_dim, T_latent)`.

return_dict : Se `True`, retorna um `AutoencoderSAMEDecoderOutput`.
**Retorna:**
Tensor de forma de onda com forma `(B, audio_channels, T_latent × downsampling_ratio)` (envolvido em `AutoencoderSAMEDecoderOutput` quando *return_dict* é `True`).

Decodifique os latentes de volta para áudio estéreo.

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

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L783)

**Parâmetros:**

sample : tensor de forma de onda `(B, audio_channels, T)`.

return_dict : Se `True`, retorna um `AutoencoderSAMEDecoderOutput`.
**Retorna:**
Forma de onda reconstruída (mesma forma que *sample*, possivelmente mais longa devido ao padding), encapsulada em `AutoencoderSAMEDecoderOutput` quando *return_dict* é `True`.

Codifique e decodifique imediatamente *sample* (reconstrução).

## 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)
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L294)
**Parâmetros:**
in_channels : Número de canais de entrada.
out_channels : Número de canais de saída.
stride : Fator de sub/amostragem.
mode : `"encoder"` ou `"decoder"`.
transformer_depth : Número de camadas `TransformerBlock`.
dim_heads : Dimensão da cabeça de atenção.
use_differential : Se deve usar atenção diferencial.
ff_mult : Fator de expansão feed-forward.
sliding_window : Meia-largura da janela deslizante em latentes (a meia-largura da faixa é `sliding_window * (stride + 1)`).
sinusoidal_blocks : Número de camadas finais de transformer que usam o gating de FFN `sin` em vez de SiLU.
Bloco de construção principal do SAME.
**Modo codificador** (passo S): agrupa S quadros de entrada consecutivos em um único segmento, adiciona uma única incorporação de saída aprendível e, em seguida, executa D camadas de transformador sobre a sequência de segmento achatada completa, mantendo apenas a incorporação de saída → reduz a amostragem por S.
**Modo decodificador** (passo S): Agrupa 1 quadro de entrada com S embeddings de saída aprendíveis, executa D camadas de transformer sobre a sequência achatada completa e, em seguida, mantém os S embeddings de saída → aumenta a amostragem por S.
A atenção usa uma máscara de banda *janela deslizante* sobreposta sobre a sequência de segmentos achatada: cada token presta atenção a `sliding_window * (stride + 1)` vizinhos em cada lado. O RoPE é calculado sobre o comprimento total da sequência. Isso corresponde exatamente à implementação de referência (um único bloco não sobreposto corresponderia apenas para um segmento).
## 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)
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L52)
Saída de [AutoencoderSAME.encode()](/docs/diffusers/main/pt/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)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L59)

Saída de [AutoencoderSAME.decode()](/docs/diffusers/main/pt/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode).

Xet Storage Details

Size:: 9.96 kB
Xet hash:: 098e7c7f275be2ea627a5aea689bb015983b890d29719104c2a752f6e76fe2a5

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

	# AutoencoderSAME

	O autoencoder SAME (Semantically-Aligned Music Encoder) é usado pelo [Stable Audio 3](https://stability.ai/news-updates/meet-stable-audio-3-the-model-family-built-for-artistic-experimentation-with-open-weight-models) para comprimir formas de onda de áudio estéreo em uma sequência latente compacta e reconstruí-las.

	O codificador empilha módulos `SAMETransformerResamplingBlock`, cada um dos quais agrupa um número fixo de quadros de patch de áudio e produz um token de saída aprendível por meio de um transformador diferencial. O decodificador inverte esse processo, expandindo cada token latente de volta para um patch de quadros de áudio.

	Um gargalo de normalização suave (`SoftNormBottleneck`) normaliza os latentes antes e depois do modelo de difusão, proporcionando dinâmicas de treinamento estáveis.

	## AutoencoderSAME[[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)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L608)

	Parâmetros:

	audio_channels : Número de canais de áudio (2 para estéreo).

	patch_size : Tamanho de patch não sobreposto aplicado antes do codificador TRB (e revertido após o decodificador TRB). Contribui com `patch_size ×` para a razão total de downsampling. Valor de produção: 256.

	encoder_channels : Número de canais base para o TRB. 128 para SAME-S, 256 para SAME-L.

	encoder_c_mults : Multiplicador de canal para cada nível de TRB (uma entrada por TRB). Tanto SAME-S quanto SAME-L usam `(6,)` — um único TRB cuja dimensão oculta é `encoder_channels × 6`.

	encoder_strides : Passo de down-/up-sampling para cada nível de TRB. Tanto SAME-S quanto SAME-L usam `(16,)` — um TRB com passo 16.

	encoder_transformer_depths : Camadas de Transformer por nível de TRB. 6 para SAME-S, 12 para SAME-L.

	latent_dim : Dimensão do espaço latente. 256 para ambas as variantes.

	use_differential_attention : Se `True`, use atenção diferencial dentro de cada bloco do transformador TRB (padrão ativado para SAME-S/L).

	dim_heads : Dimensão da cabeça de atenção. 64 para produção SAME-S/L.

	ff_mult : Fator de expansão do feed-forward SwiGLU.

	sliding_window : Meia-largura da janela deslizante (em latentes) para a atenção com máscara de banda. O uso de SAME-S/L em produção é 1.

	encoder_sinusoidal_blocks : Contagem por TRB das camadas finais de transformador que usam o gating de FFN `sin` no codificador (SAME-L: `(0,)`).

	decoder_sinusoidal_blocks : Contagem por TRB das camadas finais de transformador que usam o gating de FFN `sin` no decodificador (SAME-L: `(8,)`).

	sampling_rate : Taxa de amostragem de áudio em Hz (ex.: 44100).

	Autoencoder Semantically-Aligned Music Encoder (SAME) do Stable Audio 3 ([arXiv 2605.17991](https://arxiv.org/abs/2605.17991)).

	O modelo consiste em:

	- Embedding de patch — reorganiza o áudio estéreo em patches não sobrepostos, trocando tempo por canais (`patch_size ×` de redução de amostragem, sem parâmetros aprendidos).
	- Stack de codificador TRB — blocos `SAMETransformerResamplingBlock` que realizam mais uma etapa de redução de amostragem por um fator de `∏(encoder_strides)`.
	- Gargalo de normalização suave — normalização afim aprendível com desvio padrão em execução.
	- Pilha TRB do decodificador — espelha o codificador em ordem inversa.
	- Unpatch — reorganiza os canais de volta para a dimensão de tempo.

	Razão total de subamostragem: `patch_size × ∏(encoder_strides)`.

	Os hiperparâmetros padrão correspondem ao checkpoint SAME-S (`stabilityai/SAME-S`). Para carregar o SAME-L (`stabilityai/SAME-L`, usado pelo SA3 Medium), passe `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)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L733)

	Parâmetros:

	sample : tensor de forma de onda `(B, audio_channels, T)`.

	return_dict : Se `True`, retorna um `AutoencoderSAMEOutput`.

	Retorna:

	Tensor latente de forma `(B, latent_dim, T // downsampling_ratio)` (envolvido em `AutoencoderSAMEOutput` quando return_dict é `True`).

	Codifique áudio estéreo em latentes.

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

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

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L758)

	Parâmetros:

	latents : tensor latente `(B, latent_dim, T_latent)`.

	return_dict : Se `True`, retorna um `AutoencoderSAMEDecoderOutput`.

	Retorna:

	Tensor de forma de onda com forma `(B, audio_channels, T_latent × downsampling_ratio)` (envolvido em `AutoencoderSAMEDecoderOutput` quando return_dict é `True`).

	Decodifique os latentes de volta para áudio estéreo.

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

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

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L783)

	Parâmetros:

	sample : tensor de forma de onda `(B, audio_channels, T)`.

	return_dict : Se `True`, retorna um `AutoencoderSAMEDecoderOutput`.

	Retorna:

	Forma de onda reconstruída (mesma forma que sample, possivelmente mais longa devido ao padding), encapsulada em `AutoencoderSAMEDecoderOutput` quando return_dict é `True`.

	Codifique e decodifique imediatamente sample (reconstrução).

	## 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)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L294)

	Parâmetros:

	in_channels : Número de canais de entrada.

	out_channels : Número de canais de saída.

	stride : Fator de sub/amostragem.

	mode : `"encoder"` ou `"decoder"`.

	transformer_depth : Número de camadas `TransformerBlock`.

	dim_heads : Dimensão da cabeça de atenção.

	use_differential : Se deve usar atenção diferencial.

	ff_mult : Fator de expansão feed-forward.

	sliding_window : Meia-largura da janela deslizante em latentes (a meia-largura da faixa é `sliding_window * (stride + 1)`).

	sinusoidal_blocks : Número de camadas finais de transformer que usam o gating de FFN `sin` em vez de SiLU.

	Bloco de construção principal do SAME.

	Modo codificador (passo S): agrupa S quadros de entrada consecutivos em um único segmento, adiciona uma única incorporação de saída aprendível e, em seguida, executa D camadas de transformador sobre a sequência de segmento achatada completa, mantendo apenas a incorporação de saída → reduz a amostragem por S.

	Modo decodificador (passo S): Agrupa 1 quadro de entrada com S embeddings de saída aprendíveis, executa D camadas de transformer sobre a sequência achatada completa e, em seguida, mantém os S embeddings de saída → aumenta a amostragem por S.

	A atenção usa uma máscara de banda janela deslizante sobreposta sobre a sequência de segmentos achatada: cada token presta atenção a `sliding_window * (stride + 1)` vizinhos em cada lado. O RoPE é calculado sobre o comprimento total da sequência. Isso corresponde exatamente à implementação de referência (um único bloco não sobreposto corresponderia apenas para um segmento).

	## 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)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L52)

	Saída de [AutoencoderSAME.encode()](/docs/diffusers/main/pt/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)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L59)

	Saída de [AutoencoderSAME.decode()](/docs/diffusers/main/pt/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode).