diffusers/main/ko/api/models/stable_audio_3_transformer.md

StableAudio3DiTModel

음성 생성에 사용되는, Stable Audio 3에서 활용되는 rectified-flow 속도 예측 Diffusion Transformer(DiT)입니다.

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

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

모델은 timestep(지수 푸리에 특징 → 선형 투영)과 전역 조건 벡터(StableAudio3DurationEmbedder에서 생성된 길이 임베딩)에 조건화됩니다.

StableAudio3DiTModel[[diffusers.StableAudio3DiTModel]]

diffusers.StableAudio3DiTModel[[diffusers.StableAudio3DiTModel]]

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)

소스

매개변수:

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의 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]]

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)

소스

매개변수:

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]]

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)

소스

단일 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]]

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

소스

매개변수:

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

StableAudio3DiTModel의 출력입니다.