Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

2 days ago

preview code

download

raw

11.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`モジュールをスタックし、各モジュールは固定数のオーディオパッチフレームをグループ化し、差分トランスフォーマーを通じて1つの学習可能な出力トークンを生成します。デコーダーはこの過程を逆転させ、各潜在トークンをオーディオフレームのパッチに再展開します。

ソフトノームボトルネック（`SoftNormBottleneck`）は、拡散モデルの前後で潜在変数を正規化し、安定した学習ダイナミクスを実現します。

## 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/v0.43.0/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 ごとに 1 項目）。SAME-S と SAME-L はどちらも `(6,)` を使用します。これは、隠れ次元が `encoder_channels × 6` である単一の TRB です。

encoder_strides : 各 TRB レベルにおけるダウン/アップサンプリングのストライド。SAME-S と SAME-L の両方で `(16,)` が使用されます — ストライド 16 の TRB が 1 つです。
encoder_transformer_depths : TRBレベルあたりのTransformerレイヤー数。SAME-Sでは6、SAME-Lでは12です。
latent_dim : 潜在空間の次元数。両方のバリアントで256です。

use_differential_attention : `True`の場合、各TRB Transformerブロック内で微分注意機構を使用します（SAME-S/Lではデフォルトで有効）。

dim_heads : Attention head の次元。本番環境の SAME-S/L では 64 です。
ff_mult : SwiGLUフィードフォワードの拡張係数。

sliding_window : バンドマスク注意機構におけるスライディングウィンドウの半幅（潜在変数単位）。本番環境の SAME-S/L では 1 を使用します。
encoder_sinusoidal_blocks : エンコーダー内で`sin` FFNゲーティングを使用する末尾のTransformer層のTRBごとの数（SAME-L: `(0,)`）。
decoder_sinusoidal_blocks : デコーダー内で`sin` FFNゲーティングを使用する末尾のTransformer層の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 ×` のダウンサンプリング、学習可能なパラメータなし）。
- **エンコーダーTRBスタック** — `∏(encoder_strides)`倍の係数でさらにダウンサンプリングを行う`SAMETransformerResamplingBlock`ブロック。
- **Soft-norm bottleneck** — 実行標準偏差を持つ学習可能なアフィン正規化。
- **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/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` にラップされます)。

潜在変数（latents）をステレオ音声にデコードします。

#### 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 : Attentionヘッドの次元。
use_differential : 微分注意機構を使用するかどうか。
ff_mult : Feed-forward 拡張係数。
sliding_window : 潜在変数におけるスライディングウィンドウの半幅（バンドの半幅は `sliding_window * (stride + 1)` です）。
sinusoidal_blocks `sin` FFN ゲーティングを SiLU の代わりに使用する、末尾の Transformer レイヤーの数。
SAMEの基本的な構成要素です。
**エンコーダーモード**（ストライド S）: 連続する S 個の入力フレームを 1 セグメントにグループ化し、学習可能な出力埋め込みを 1 つ付加します。その後、フラット化されたセグメントシーケンス全体に対して D 層の Transformer を実行し、出力埋め込みのみを保持します → S 倍ダウンサンプリング。
**デコーダーモード**（ストライド S）：1つの入力フレームを S 個の学習可能な出力埋め込みとグループ化し、フラット化された完全なシーケンス全体に対して D 層の Transformer を実行した上で、S 個の出力埋め込みを保持します → S 倍のアップサンプリング。
Attention は、フラット化されたセグメントシーケンスに対して、重複する*スライディングウィンドウ*のバンドマスクを使用します。各トークンは、左右それぞれ`sliding_window * (stride + 1)`個の近傍トークンにアテンションを向けます。RoPE はシーケンス全体の長さに対して計算されます。これにより、参照実装と完全に一致します（重複しない単一のチャンクでは、1つのセグメントでのみ一致します）。
## 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/ja/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/ja/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode)の出力。

Xet Storage Details

Size:: 11.4 kB
Xet hash:: a814e05df68c6e8c27d13c3f1345d5ed5d60fa630f07c8ebd571d89f9e1cffec

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`モジュールをスタックし、各モジュールは固定数のオーディオパッチフレームをグループ化し、差分トランスフォーマーを通じて1つの学習可能な出力トークンを生成します。デコーダーはこの過程を逆転させ、各潜在トークンをオーディオフレームのパッチに再展開します。

	ソフトノームボトルネック（`SoftNormBottleneck`）は、拡散モデルの前後で潜在変数を正規化し、安定した学習ダイナミクスを実現します。

	## 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/v0.43.0/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 ごとに 1 項目）。SAME-S と SAME-L はどちらも `(6,)` を使用します。これは、隠れ次元が `encoder_channels × 6` である単一の TRB です。

	encoder_strides : 各 TRB レベルにおけるダウン/アップサンプリングのストライド。SAME-S と SAME-L の両方で `(16,)` が使用されます — ストライド 16 の TRB が 1 つです。

	encoder_transformer_depths : TRBレベルあたりのTransformerレイヤー数。SAME-Sでは6、SAME-Lでは12です。

	latent_dim : 潜在空間の次元数。両方のバリアントで256です。

	use_differential_attention : `True`の場合、各TRB Transformerブロック内で微分注意機構を使用します（SAME-S/Lではデフォルトで有効）。

	dim_heads : Attention head の次元。本番環境の SAME-S/L では 64 です。

	ff_mult : SwiGLUフィードフォワードの拡張係数。

	sliding_window : バンドマスク注意機構におけるスライディングウィンドウの半幅（潜在変数単位）。本番環境の SAME-S/L では 1 を使用します。

	encoder_sinusoidal_blocks : エンコーダー内で`sin` FFNゲーティングを使用する末尾のTransformer層のTRBごとの数（SAME-L: `(0,)`）。

	decoder_sinusoidal_blocks : デコーダー内で`sin` FFNゲーティングを使用する末尾のTransformer層の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 ×` のダウンサンプリング、学習可能なパラメータなし）。
	- エンコーダーTRBスタック — `∏(encoder_strides)`倍の係数でさらにダウンサンプリングを行う`SAMETransformerResamplingBlock`ブロック。
	- Soft-norm bottleneck — 実行標準偏差を持つ学習可能なアフィン正規化。
	- 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/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` にラップされます)。

	潜在変数（latents）をステレオ音声にデコードします。

	#### 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 : Attentionヘッドの次元。

	use_differential : 微分注意機構を使用するかどうか。

	ff_mult : Feed-forward 拡張係数。

	sliding_window : 潜在変数におけるスライディングウィンドウの半幅（バンドの半幅は `sliding_window * (stride + 1)` です）。

	sinusoidal_blocks `sin` FFN ゲーティングを SiLU の代わりに使用する、末尾の Transformer レイヤーの数。

	SAMEの基本的な構成要素です。

	エンコーダーモード（ストライド S）: 連続する S 個の入力フレームを 1 セグメントにグループ化し、学習可能な出力埋め込みを 1 つ付加します。その後、フラット化されたセグメントシーケンス全体に対して D 層の Transformer を実行し、出力埋め込みのみを保持します → S 倍ダウンサンプリング。

	デコーダーモード（ストライド S）：1つの入力フレームを S 個の学習可能な出力埋め込みとグループ化し、フラット化された完全なシーケンス全体に対して D 層の Transformer を実行した上で、S 個の出力埋め込みを保持します → S 倍のアップサンプリング。

	Attention は、フラット化されたセグメントシーケンスに対して、重複するスライディングウィンドウのバンドマスクを使用します。各トークンは、左右それぞれ`sliding_window * (stride + 1)`個の近傍トークンにアテンションを向けます。RoPE はシーケンス全体の長さに対して計算されます。これにより、参照実装と完全に一致します（重複しない単一のチャンクでは、1つのセグメントでのみ一致します）。

	## 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/ja/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/ja/api/models/autoencoder_same#diffusers.AutoencoderSAME.decode)の出力。