Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

about 20 hours ago

preview code

download

raw

10.4 kB

# AutoencoderSAME

**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` 모듈을 적층하며, 각 모듈은 고정된 수의 오디오 패치 프레임을 그룹화하여 차등 변환기(differential transformer)를 통해 하나의 학습 가능한 출력 토큰을 생성합니다. 디코더는 이 과정을 역으로 수행하여 각 잠재 토큰을 오디오 프레임 패치로 다시 확장합니다.

소프트 노름 병목(`SoftNormBottleneck`)은 diffusion 모델의 전후로 latents를 정규화하여 안정적인 학습 동역학을 제공합니다.

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

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

**매개변수:**

audio_channels : 오디오 채널 수(스테레오의 경우 2).
patch_size : TRB 인코더 적용 전(그리고 TRB 디코더 적용 후 역순으로) 적용되는 겹치지 않는 패치 크기. 전체 다운샘플링 비율에 `patch_size ×`만큼 기여합니다. 프로덕션 값: 256.

encoder_channels : TRB의 기본 채널 수. SAME-S의 경우 128, SAME-L의 경우 256입니다.
encoder_c_mults : 각 TRB 레벨에 대한 채널 배율(TRB당 하나의 항목). SAME-S와 SAME-L 모두 `(6,)`를 사용합니다. 이는 숨겨진 차원이 `encoder_channels × 6`인 단일 TRB입니다.

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 : Attention head 차원. 프로덕션 SAME-S/L의 경우 64입니다.
ff_mult : SwiGLU 피드포워드 확장 계수.

sliding_window : band-mask attention의 sliding-window 반폭(latents 단위). 프로덕션 SAME-S/L은 1을 사용합니다.
encoder_sinusoidal_blocks : 인코더에서 `sin` FFN 게이팅을 사용하는 후행 트랜스포머 레이어의 TRB별 개수 (SAME-L: `(0,)`).
decoder_sinusoidal_blocks : 디코더에서 `sin` FFN 게이팅을 사용하는 후행 트랜스포머 레이어의 TRB별 개수 (SAME-L: `(8,)`).
sampling_rate : Hz 단위의 오디오 샘플링 주파수 (예: 44100).

*Stable Audio 3*의 Semantically-Aligned Music Encoder(SAME) 오토인코더([arXiv 2605.17991](https://arxiv.org/abs/2605.17991)).

모델은 다음으로 구성됩니다:

- **패치 임베딩** — 스테레오 오디오를 겹치지 않는 패치로 재구성하여 채널을 시간으로 교환합니다(`patch_size ×` 다운샘플링, 학습 가능한 매개변수 없음).
- **Encoder TRB 스택** — `∏(encoder_strides)` 배율로 추가 다운샘플링을 수행하는 `SAMETransformerResamplingBlock` 블록들.
- **Soft-norm bottleneck** — running std를 사용하는 학습 가능한 affine 정규화
- **Decoder 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/main/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`에 래핑됨).
스테레오 오디오를 latents로 인코딩합니다.
#### decode[[diffusers.AutoencoderSAME.decode]]
```python
decode(latents: Tensor, return_dict: bool = True)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_same.py#L758)
**매개변수:**
latents : `(B, latent_dim, T_latent)` latent 텐서.
return_dict : `True`인 경우 `AutoencoderSAMEDecoderOutput`를 반환합니다.
**반환값:**
`(B, audio_channels, T_latent × downsampling_ratio)` 형태의 웨이브폼 텐서(*return_dict*가 `True`인 경우 `AutoencoderSAMEDecoderOutput`에 래핑됨).
latents를 스테레오 오디오로 디코딩합니다.
#### forward[[diffusers.AutoencoderSAME.forward]]
```python
forward(sample: Tensor, return_dict: bool = True)
```
[소스](https://github.com/huggingface/diffusers/blob/main/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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L294)
**매개변수:**
in_channels : 입력 채널 수.

out_channels : 출력 채널 수.
stride : 다운/업 샘플링 계수.
mode : `"encoder"` 또는 `"decoder"`.
transformer_depth : `TransformerBlock` 레이어의 수.

dim_heads : Attention 헤드 차원.
use_differential : 차등 주의(differential attention)를 사용할지 여부.

ff_mult : 피드포워드 확장 계수.
sliding_window : latents의 슬라이딩 윈도우 반폭(밴드 반폭은 `sliding_window * (stride + 1)`입니다).

sinusoidal_blocks : SiLU 대신 `sin` FFN 게이팅을 사용하는 후행 transformer 레이어의 수.
SAME의 핵심 구성 요소
**인코더 모드**(스트라이드 S): S개의 연속된 입력 프레임을 하나의 세그먼트로 묶고, 학습 가능한 출력 임베딩 하나를 추가한 뒤, 전체적으로 평탄화된 세그먼트 시퀀스에 대해 D개의 트랜스포머 레이어를 실행하며 출력 임베딩만 유지합니다 → S배 다운샘플링.
**디코더 모드**(스트라이드 S): 1개의 입력 프레임과 S개의 학습 가능한 출력 임베딩을 그룹화하고, 전체 평탄화 시퀀스에 대해 D개의 트랜스포머 레이어를 실행한 후 S개의 출력 임베딩만 유지하여 S배 업샘플링을 수행합니다.
Attention은 평탄화된 세그먼트 시퀀스에 겹치는 *슬라이딩 윈도우* 밴드 마스크를 사용합니다. 각 토큰은 양쪽에서 `sliding_window * (stride + 1)`개의 이웃 토큰에 대해 attention을 수행합니다. 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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L52)
[AutoencoderSAME.encode()](/docs/diffusers/main/ko/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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L59)
[AutoencoderSAME.decode()](/docs/diffusers/main/ko/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode)의 출력입니다.

Xet Storage Details

Size:: 10.4 kB
Xet hash:: e13f5cd7db33d5fcf0e5a10d936f215008b3109cd930ae4405ab14f612732773

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

	# AutoencoderSAME

	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` 모듈을 적층하며, 각 모듈은 고정된 수의 오디오 패치 프레임을 그룹화하여 차등 변환기(differential transformer)를 통해 하나의 학습 가능한 출력 토큰을 생성합니다. 디코더는 이 과정을 역으로 수행하여 각 잠재 토큰을 오디오 프레임 패치로 다시 확장합니다.

	소프트 노름 병목(`SoftNormBottleneck`)은 diffusion 모델의 전후로 latents를 정규화하여 안정적인 학습 동역학을 제공합니다.

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

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

	매개변수:

	audio_channels : 오디오 채널 수(스테레오의 경우 2).

	patch_size : TRB 인코더 적용 전(그리고 TRB 디코더 적용 후 역순으로) 적용되는 겹치지 않는 패치 크기. 전체 다운샘플링 비율에 `patch_size ×`만큼 기여합니다. 프로덕션 값: 256.

	encoder_channels : TRB의 기본 채널 수. SAME-S의 경우 128, SAME-L의 경우 256입니다.

	encoder_c_mults : 각 TRB 레벨에 대한 채널 배율(TRB당 하나의 항목). SAME-S와 SAME-L 모두 `(6,)`를 사용합니다. 이는 숨겨진 차원이 `encoder_channels × 6`인 단일 TRB입니다.

	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 : Attention head 차원. 프로덕션 SAME-S/L의 경우 64입니다.

	ff_mult : SwiGLU 피드포워드 확장 계수.

	sliding_window : band-mask attention의 sliding-window 반폭(latents 단위). 프로덕션 SAME-S/L은 1을 사용합니다.

	encoder_sinusoidal_blocks : 인코더에서 `sin` FFN 게이팅을 사용하는 후행 트랜스포머 레이어의 TRB별 개수 (SAME-L: `(0,)`).

	decoder_sinusoidal_blocks : 디코더에서 `sin` FFN 게이팅을 사용하는 후행 트랜스포머 레이어의 TRB별 개수 (SAME-L: `(8,)`).

	sampling_rate : Hz 단위의 오디오 샘플링 주파수 (예: 44100).

	Stable Audio 3의 Semantically-Aligned Music Encoder(SAME) 오토인코더([arXiv 2605.17991](https://arxiv.org/abs/2605.17991)).

	모델은 다음으로 구성됩니다:

	- 패치 임베딩 — 스테레오 오디오를 겹치지 않는 패치로 재구성하여 채널을 시간으로 교환합니다(`patch_size ×` 다운샘플링, 학습 가능한 매개변수 없음).
	- Encoder TRB 스택 — `∏(encoder_strides)` 배율로 추가 다운샘플링을 수행하는 `SAMETransformerResamplingBlock` 블록들.
	- Soft-norm bottleneck — running std를 사용하는 학습 가능한 affine 정규화
	- Decoder 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/main/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`에 래핑됨).

	스테레오 오디오를 latents로 인코딩합니다.

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

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

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

	매개변수:

	latents : `(B, latent_dim, T_latent)` latent 텐서.

	return_dict : `True`인 경우 `AutoencoderSAMEDecoderOutput`를 반환합니다.

	반환값:

	`(B, audio_channels, T_latent × downsampling_ratio)` 형태의 웨이브폼 텐서(return_dict가 `True`인 경우 `AutoencoderSAMEDecoderOutput`에 래핑됨).

	latents를 스테레오 오디오로 디코딩합니다.

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

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

	[소스](https://github.com/huggingface/diffusers/blob/main/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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L294)

	매개변수:

	in_channels : 입력 채널 수.

	out_channels : 출력 채널 수.

	stride : 다운/업 샘플링 계수.

	mode : `"encoder"` 또는 `"decoder"`.

	transformer_depth : `TransformerBlock` 레이어의 수.

	dim_heads : Attention 헤드 차원.

	use_differential : 차등 주의(differential attention)를 사용할지 여부.

	ff_mult : 피드포워드 확장 계수.

	sliding_window : latents의 슬라이딩 윈도우 반폭(밴드 반폭은 `sliding_window * (stride + 1)`입니다).

	sinusoidal_blocks : SiLU 대신 `sin` FFN 게이팅을 사용하는 후행 transformer 레이어의 수.

	SAME의 핵심 구성 요소

	인코더 모드(스트라이드 S): S개의 연속된 입력 프레임을 하나의 세그먼트로 묶고, 학습 가능한 출력 임베딩 하나를 추가한 뒤, 전체적으로 평탄화된 세그먼트 시퀀스에 대해 D개의 트랜스포머 레이어를 실행하며 출력 임베딩만 유지합니다 → S배 다운샘플링.

	디코더 모드(스트라이드 S): 1개의 입력 프레임과 S개의 학습 가능한 출력 임베딩을 그룹화하고, 전체 평탄화 시퀀스에 대해 D개의 트랜스포머 레이어를 실행한 후 S개의 출력 임베딩만 유지하여 S배 업샘플링을 수행합니다.

	Attention은 평탄화된 세그먼트 시퀀스에 겹치는 슬라이딩 윈도우 밴드 마스크를 사용합니다. 각 토큰은 양쪽에서 `sliding_window * (stride + 1)`개의 이웃 토큰에 대해 attention을 수행합니다. 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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L52)

	[AutoencoderSAME.encode()](/docs/diffusers/main/ko/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/main/src/diffusers/models/autoencoders/autoencoder_same.py#L59)

	[AutoencoderSAME.decode()](/docs/diffusers/main/ko/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode)의 출력입니다.