# StableAudio3DiTModel

음성 생성에 사용되는, [Stable Audio 3](https://stability.ai/news-updates/meet-stable-audio-3-the-model-family-built-for-artistic-experimentation-with-open-weight-models)에서 활용되는 rectified-flow 속도 예측 Diffusion Transformer(DiT)입니다.

각 `StableAudio3DiTBlock`은 다음을 수행합니다:

1. **Self-attention** — 회전 위치 임베딩(RoPE)을 사용한 차등 멀티헤드 어텐션.
2. **Cross-attention** — T5Gemma 텍스트 인코더의 토큰 시퀀스에 주의를 기울입니다.
3. **Feed-forward** — SwiGLU 투영.

모델은 **timestep**(지수 푸리에 특징 → 선형 투영)과 **전역 조건 벡터**([StableAudio3DurationEmbedder](/docs/diffusers/main/ko/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder)에서 생성된 길이 임베딩)에 조건화됩니다.

## StableAudio3DiTModel[[diffusers.StableAudio3DiTModel]]

#### diffusers.StableAudio3DiTModel[[diffusers.StableAudio3DiTModel]]

```python
diffusers.StableAudio3DiTModel(io_channels: int = 256, patch_size: int = 1, embed_dim: int = 1536, depth: int = 24, num_heads: int = 24, cond_token_dim: int = 768, global_cond_dim: int = 768, local_add_cond_dim: int = 257, timestep_features_dim: int = 256, ff_mult: float = 4.0, num_memory_tokens: int = 64, use_differential_attention: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_stable_audio3.py#L403)

**매개변수:**

io_channels (`int`, 기본값 256) : 잠재 채널의 수.

patch_size (`int`, 기본값 1) : Transformer에 적용하기 전에 사용되는 시간 패치 크기입니다.

embed_dim (`int`, 기본값 1536) : Transformer 은닉 차원.

depth (`int`, 기본값 24) : `StableAudio3DiTBlock` 레이어의 수.

num_heads (`int`, 기본값 24) : 어텐션 헤드 수.

cond_token_dim (`int`, 기본값 768) : cross-attention context 토큰의 차원.

global_cond_dim (`int`, 기본값 768) : 전역 지속 시간 임베딩의 차원.

local_add_cond_dim (`int`, 기본값 257) : 로컬-가산(inpaint) 텐서의 채널 수.

timestep_features_dim (`int`, 기본값 256) : Fourier timestep features의 출력 차원입니다.

ff_mult (`float`, 기본값 4.0) : SwiGLU 피드포워드 확장 계수.

num_memory_tokens (`int`, 기본값 64) : 학습 가능한 메모리 토큰의 수.

use_differential_attention (`bool`, 기본값 `True`) : 차등 self/cross attention을 활성화합니다.

[Stable Audio 3](https://stability.ai/news/stable-audio-3)의 Diffusion Transformer(DiT) 백본입니다.

모델은 노이즈 오디오 레이턴트 배치, 스칼라 타임스텝, 크로스 어텐션 컨텍스트(투영된 텍스트 및 길이 토큰), 전역 길이 임베딩을 입력으로 받아 속도 필드(rectified-flow 목적함수)를 예측합니다.

조건부 생성:
- Cross-attention 컨텍스트(`encoder_hidden_states`)는 `to_cond_embed`에 의해 투사됩니다.
- 전역 지속 시간 임베딩(`global_hidden_states`)은 `to_global_embed`에 의해 투영된 후, 타임스텝 임베딩과 합산되고, `global_cond_embedder`에 의해 블록별 AdaLN 변조로 확장됩니다.
- `local_add_cond`(inpainting)은 `to_local_embed`에 의해 블록별로 투사됩니다.

`num_memory_tokens`개의 학습 가능한 토큰은 transformer 내부에서 오디오 시퀀스 앞에 추가되고, 출력 투영 전에 제거됩니다.

#### forward[[diffusers.StableAudio3DiTModel.forward]]

```python
forward(hidden_states: Tensor, timestep: Tensor, encoder_hidden_states: Tensor, global_hidden_states: Tensor, encoder_attention_mask: typing.Optional[torch.Tensor] = None, local_add_cond: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_stable_audio3.py#L521)

**매개변수:**

hidden_states (`torch.Tensor`) : 노이즈가 포함된 잠재 오디오 `(batch, io_channels, T)`.

timestep (`torch.Tensor`) : `[0, 1]` 범위의 `(batch,)` Diffusion timestep

encoder_hidden_states (`torch.Tensor`) : Cross-attention 컨텍스트 `(batch, T_ctx, cond_token_dim)`.

global_hidden_states (`torch.Tensor`) : 전역 기간 임베딩 `(batch, global_cond_dim)`.

encoder_attention_mask (`torch.Tensor`, *선택 사항*) : Bool 마스크 `(batch, T_ctx)`, `True` = 유효.

local_add_cond (`torch.Tensor`, *선택 사항*) : 로컬 가산(인페인팅) 조건 `(batch, local_add_cond_dim, T)`.

return_dict (`bool`, 기본값 `True`) : `StableAudio3DiTModelOutput`를 반환할지 여부.

**반환값:** `StableAudio3DiTModelOutput` 또는 `tuple`

`hidden_states`와 동일한 형태의 예측 속도 필드

## StableAudio3DiTBlock[[diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTBlock]]

#### diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTBlock[[diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTBlock]]

```python
diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTBlock(dim: int, context_dim: int, dim_heads: int = 64, use_differential: bool = True, ff_mult: float = 4.0, local_add_cond_dim: int = 257)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_stable_audio3.py#L316)

단일 SA3 DiT transformer 블록.

작업 순서:
1. AdaLN 변조 자기 주의(부분 RoPE, RMS QK-norm)
2. 텍스트/길이 컨텍스트에 대한 크로스 어텐션(일반 RMS pre-norm)
3. AdaLN 변조 SwiGLU 피드포워드

AdaLN 변조는 `to_scale_shift_gate + global_modulation`이며, `(scale_attn, shift_attn, gate_attn, scale_ff, shift_ff, gate_ff)`로 여섯 개의 청크로 나뉩니다. 각 게이트된 분기는 `sigmoid(1 - gate)`로 스케일링됩니다. 크로스 어텐션은 *AdaLN 변조가 적용되지 않으며*, 이는 레퍼런스와 일치합니다(`cross_attend_norm`는 단순한 RMS norm입니다).

`local_seq`가 제공된 경우(인페인팅), `to_local_embed`에 의해 블록별로 투영된 후 크로스 어텐션 이후(피드포워드 이전) 잔차 스트림의 오디오 위치에 추가되며, 이는 레퍼런스와 일치합니다.

## StableAudio3DiTModelOutput[[diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTModelOutput]]

#### diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTModelOutput[[diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTModelOutput]]

```python
diffusers.models.transformers.transformer_stable_audio3.StableAudio3DiTModelOutput(sample: Tensor)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_stable_audio3.py#L34)

**매개변수:**

sample (`torch.Tensor`) : 입력 `hidden_states`와 동일한 형상을 가진 예측 속도 필드.

[StableAudio3DiTModel](/docs/diffusers/main/ko/api/models/stable_audio_3_transformer#diffusers.StableAudio3DiTModel)의 출력입니다.