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

QwenImage21Transformer2DModel

Qwen-Image 2.1에서 사용하는 단일 스트림 transformer입니다. 텍스트와 이미지 latents가 하나의 시퀀스를 공유하며, 단일 공유 modulation 투영이 모든 블록에 공급됩니다.

2.1은 이전 QwenImage 트랜스포머와 구별되는 두 가지 동작을 가지고 있습니다:

• 블록 인과적 어텐션 — 어텐션은 (q_idx >= kv_idx) or same_image_block을 따르므로, 결합된 시퀀스는 인과적(casual)인 반면 각 이미지 블록은 내부적으로 양방향(bidirectional)으로 유지됩니다. 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]]

diffusers.QwenImage21Transformer2DModel[[diffusers.QwenImage21Transformer2DModel]]

diffusers.QwenImage21Transformer2DModel(patch_size: int = 1, in_channels: int = 64, out_channels: int | None = 64, num_layers: int = 32, attention_head_dim: int = 128, num_attention_heads: int = 32, context_in_dim: int = 4096, mlp_ratio: int = 3, axes_dims_rope: tuple = (16, 56, 56), eps: float = 1e-06, causal_condition: bool = True)

소스

매개변수:

patch_size (int, 기본값 1) : 채널 차원으로 접히는 잠재 변수 패치의 한 변 길이. 2.1은 패치되지 않은 잠재 변수를 사용합니다.

in_channels (int, 기본값 64) : 입력의 Latent channels.

out_channels (int, 선택 사항, 기본값 64) : 출력의 Latent 채널 수. in_channels로 대체됩니다.

num_layers (int, 기본값 32) : 단일 스트림 블록의 수.

attention_head_dim (int, 기본값 128) : 각 attention head의 채널 수.

num_attention_heads (int, 기본값 32) : 어텐션 헤드 수.

context_in_dim (int, 기본값 4096) : encoder_hidden_states의 채널 차원.

mlp_ratio (int, 기본값 3) : Feed-forward 확장 계수.

axes_dims_rope (tuple[int], 기본값 (16, 56, 56)) : 프레임, 높이, 너비 축에 대한 Rotary dims입니다.

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 — 텍스트와 조건 이미지 토큰은 샘플링된 시간 단계 대신 t = 0에서 변조되며, 이로 인해 활성화 값이 시간 단계에 독립적이 되어 디노이징 단계 간에 캐싱할 수 있습니다.

build_token_metadata[[diffusers.QwenImage21Transformer2DModel.build_token_metadata]]

build_token_metadata(image_pad_mask: Tensor, img_shapes: list)

소스

매개변수:

image_pad_mask (torch.Tensor) : (seq_len,) bool, 이미지 토큰 위치에서 True.

img_shapes (list[tuple[int, int, int]]) : 잠재 토큰으로 표현된 이미지별 (frame, height, width) 값입니다. 조건 이미지가 먼저, 대상 이미지가 마지막에 위치합니다.

반환값: tuple[torch.Tensor, torch.Tensor]

image_ids (seq_len,)은 텍스트 위치에서 -1을, 각 이미지 블록마다 고유한 id를 가지며, target_token_mask (seq_len,)는 대상 이미지의 토큰을 표시합니다.

이미지 블록에 속하는 합성 시퀀스의 모든 토큰을 라벨링합니다.

img_shapes의 토큰 개수에서 블록 경계가 결정되며, image_pad_mask의 True 연속 구간에서 결정되지 않습니다. 텍스트 없이 인접해 있는 두 개의 조건 이미지는 하나의 연속 구간을 형성하지만 반드시 별도의 블록으로 유지되어야 하며, 그렇지 않으면 양방향으로 서로에 대한 주의를 기울이게 됩니다.

forward[[diffusers.QwenImage21Transformer2DModel.forward]]

forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_shapes: list, img_mask: Tensor, encoder_hidden_states_mask: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, kv_cache: diffusers.models.transformers.transformer_qwenimage21.QwenImage21KVCache | None = None, kv_cache_mode: str | None = None, return_dict: bool = True)

소스

매개변수:

hidden_states (torch.Tensor, shape (batch_size, image_sequence_length, in_channels)) : Packed 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)의 샘플별 목록입니다. 조건 이미지가 먼저, 대상 이미지가 마지막에 위치합니다. 모든 샘플은 동일한 레이아웃을 공유해야 합니다.

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) : 일반 튜플 대신 Transformer2DModelOutput을 반환할지 여부.

반환값: Transformer2DModelOutput 또는 tuple

return_dict가 True인 경우 Transformer2DModelOutput, 그렇지 않으면 첫 번째 요소가 노이즈 제거된 latents인 일반 tuple

Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

diffusers.models.modeling_outputs.Transformer2DModelOutput(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의 출력입니다.