Diffusers documentation
QwenImage21Transformer2DModel
QwenImage21Transformer2DModel
Qwen-Image 2.1에서 사용하는 단일 스트림 transformer입니다. 텍스트와 이미지 latents가 하나의 시퀀스를 공유하며, 단일 공유 modulation 투영이 모든 블록에 공급됩니다.
2.1은 이전 QwenImage 트랜스포머와 구별되는 두 가지 동작을 가지고 있습니다:
- 블록 인과적 어텐션 — 어텐션은
(q_idx >= kv_idx) or same_image_block을 따르므로, 결합된 시퀀스는 인과적이되 각 이미지 블록은 내부적으로 양방향으로 유지됩니다.QwenImage21AttnProcessor는 각 접두사 세그먼트마다 하나의 어텐션 호출로 이를 구현하며 기본값입니다.QwenImage21FlexAttnProcessor는BlockMask에 의해 구동되는 단일flex_attention호출로 이를 구현하며, 모델이 컴파일된 후에는 더 빠릅니다. 두 방식 모두 동일한 결과를 생성합니다. causal_condition— 텍스트와 조건 이미지 토큰은 샘플링된 타임스텝이 아닌t = 0에서 변조됩니다. 이들의 활성화 값은 디노이징 단계와 무관하므로, 해당 프리픽스의 키와 값은kv_cache인수를 통해 단계 간에 캐시할 수 있습니다.
다음으로 로드합니다:
import torch
from diffusers import QwenImage21Transformer2DModel
transformer = QwenImage21Transformer2DModel.from_pretrained(
"Qwen/Qwen-Image-2.1", subfolder="transformer", dtype=torch.bfloat16
)QwenImage21Transformer2DModel
클래스 diffusers.QwenImage21Transformer2DModel
< source >( patch_size: int = 1in_channels: int = 64out_channels: int | None = 64num_layers: int = 32attention_head_dim: int = 128num_attention_heads: int = 32context_in_dim: int = 4096mlp_ratio: int = 3axes_dims_rope: tuple = (16, 56, 56)eps: float = 1e-06causal_condition: bool = True )
매개변수
- patch_size (
int, 기본값1) — 채널 차원으로 접히는 latent patch의 한 변 길이입니다. 2.1은 patch를 적용하지 않은 latents를 사용합니다. - in_channels (
int, 기본값64) — 입력의 Latent 채널 수입니다. - out_channels (
int, 선택 사항, 기본값64) — 출력의 Latent 채널 수입니다.in_channels로 대체됩니다. - num_layers (
int, 기본값32) — 단일 스트림 블록의 수입니다. - attention_head_dim (
int, 기본값128) — Attention head당 채널 수. - num_attention_heads (
int, 기본값32) — Attention head의 수입니다. - context_in_dim (
int, 기본값4096) —encoder_hidden_states의 채널 차원입니다. - mlp_ratio (
int, 기본값3) — Feed-forward 확장 계수. - axes_dims_rope (
tuple[int], 기본값(16, 56, 56)) — 프레임, 높이, 너비 축에 대한 Rotary 차원입니다. - eps (
float, 기본값1e-6) — Norm 레이어에 사용되는 Epsilon 값입니다. - causal_condition (
bool, 기본값True) —t = 0부터 텍스트 및 조건 이미지 토큰을 변조합니다. KV 캐싱에 필요합니다.
Qwen-Image 2.1에서 사용하는 단일 스트림 Transformer입니다.
텍스트와 이미지 latents는 하나의 시퀀스를 공유합니다. 조건 이미지 토큰은 비전-언어 인코더가 해당 토큰을 위해 예약한 위치에 텍스트 스트림에 대입되고, 대상 이미지의 토큰은 뒤에 추가됩니다. 단일 공유 modulation 투영이 모든 블록에 공급되므로, 각 블록은 자체 modulation 매개변수를 보유하지 않습니다.
2.1을 구별하는 두 가지 동작:
- 블록 인과적 어텐션 — 어텐션은
(q_idx >= kv_idx) or same_image_block을 따르므로 시퀀스는 인과적이되 각 이미지 블록은 내부적으로 양방향으로 유지됩니다.flex어텐션 백엔드를 사용하면 효율적인 단일 패스 어텐션을 제공하며, 이 백엔드가 없으면 모델은 각 블록을 개별적으로 처리하는 정확한 다중 패스 SDPA 프리필을 사용합니다. causal_condition— 텍스트와 조건 이미지 토큰은 샘플링된 timestep 대신t = 0에서 modulation되며, 이로 인해 활성화 값이 timestep에 독립적이 되어 denoising 단계 간에 캐싱할 수 있습니다.
build_token_metadata
< source >( image_pad_mask: Tensorimg_shapes: list ) → tuple[torch.Tensor, torch.Tensor]
매개변수
- image_pad_mask (
torch.Tensor) —(seq_len,)bool, 이미지 토큰 위치에서True. - img_shapes (
list[tuple[int, int, int]]) — 각 이미지의(frame, height, width)latent 토큰 수. 조건 이미지가 먼저, 대상 이미지가 마지막에 위치합니다.
반환값
tuple[torch.Tensor, torch.Tensor]
image_ids (seq_len,)은 텍스트 위치에서 -1을, 각 이미지 블록마다 고유한 id를 가지며, target_token_mask (seq_len,)는 대상 이미지의 토큰을 표시합니다.
이미지 블록에 속하는 합성 시퀀스의 모든 토큰을 라벨링합니다.
img_shapes의 토큰 개수에서 블록 경계가 결정되며, image_pad_mask의 True 연속 구간에서 결정되지 않습니다. 텍스트 없이 나란히 배치된 두 개의 조건 이미지는 하나의 연속 구간을 형성하지만, 서로 양방향으로 attend하지 않도록 반드시 별도의 블록으로 유지되어야 합니다.
forward
< source >( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorimg_shapes: listimg_mask: Tensorencoder_hidden_states_mask: typing.Optional[torch.Tensor] = Noneattention_kwargs: dict[str, typing.Any] | None = Nonekv_cache: diffusers.models.transformers.transformer_qwenimage21.QwenImage21KVCache | None = Nonekv_cache_mode: str | None = Nonereturn_dict: bool = True ) → Transformer2DModelOutput or tuple
매개변수
- hidden_states (
torch.Tensor, shape(batch_size, image_sequence_length, in_channels)) — 패킹된 latents입니다. 조건 이미지가 먼저, 대상 이미지가 마지막에 배치됩니다. - encoder_hidden_states (
torch.Tensor, shape(batch_size, text_sequence_length, context_in_dim)) — 비전-언어 인코더에서 생성된 텍스트 임베딩입니다. - timestep (
torch.Tensor) — 현재 디노이징 단계,[0, 1]으로 스케일링됩니다. - img_shapes (
list[list[tuple[int, int, int]]]) — 샘플별(frame, height, width)latent 토큰 목록입니다. 조건 이미지가 먼저, 대상 이미지가 마지막에 위치합니다. 모든 샘플은 동일한 레이아웃을 공유해야 합니다. - img_mask (
torch.Tensor, shape(batch_size, vlm_sequence_length)) — 비전-언어 인코더의 이미지 슬롯 위치에서True이며, 각 슬롯은2x2크기의 잠재 토큰 그룹을 나타냅니다. - encoder_hidden_states_mask (
torch.Tensor, 선택 사항) —(batch_size, text_sequence_length)bool 형식으로 유효한 텍스트 토큰을 표시합니다. 패딩된 위치는 어텐션에서 제외됩니다. - kv_cache (
QwenImage21KVCache, 선택 사항) — 캐시 컨테이너입니다.kv_cache_mode와 함께 전달하여 prefix KV 캐싱을 활성화합니다. - kv_cache_mode (
str, 선택 사항) —"extract"는 캐시를 사전 채우기(첫 번째 디노이징 단계)에,"cached"는 캐시에서 디코딩(이후 단계)에 사용합니다.causal_condition=True가 필요합니다. - attention_kwargs (
dict, 선택 사항) — attention processor로 전달되며, LoRA 레이어의scale을 포함합니다. - return_dict (
bool, 선택 사항, 기본값True) — 단순 tuple 대신 Transformer2DModelOutput를 반환할지 여부.
반환값
Transformer2DModelOutput 또는 tuple
return_dict가 True인 경우 Transformer2DModelOutput, 그렇지 않으면 첫 번째 요소가 노이즈 제거된 latents인 일반 tuple
Transformer2DModelOutput
클래스 diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
매개변수
- sample (
torch.Tensor, shape(batch_size, num_channels, height, width)또는 Transformer2DModel이 discrete인 경우(batch size, num_vector_embeds - 1, num_latent_pixels)) —encoder_hidden_states입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.
Transformer2DModel의 출력입니다.