Diffusers documentation
QwenImage21Transformer2DModel
QwenImage21Transformer2DModel
Qwen-Image 2.1で使用される単一ストリーム型transformerです。テキストと画像の潜在変数は1つのシーケンスを共有し、単一の共有modulation投影がすべてのブロックに供給されます。
2.1は、以前のQwenImageトランスフォーマーと区別される2つの動作特性を持っています。
- ブロック因果アテンション — アテンションは
(q_idx >= kv_idx) or same_image_blockに従うため、結合シーケンス全体は因果的でありながら、各画像ブロック内部は双方向のままです。QwenImage21AttnProcessorは、プレフィックスセグメントごとに1回のアテンション呼び出しとして実装されており、デフォルトです。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) — チャネル次元に折り畳まれる潜在パッチの辺の長さです。2.1 では、パッチ化されていない潜在変数を消費します。 - in_channels (
int、デフォルトは64) — 入力レイテンシーのチャネル数。 - out_channels (
int、任意、デフォルトは64) — 出力の潜在チャネル数。in_channelsにフォールバックします。 - num_layers (
int、デフォルトは32) — シングルストリームブロックの数。 - attention_head_dim (
int、デフォルトは128) — アテンションヘッドあたりのチャネル数。 - num_attention_heads (
int、デフォルトは32) — アテンションヘッドの数。 - context_in_dim (
int、デフォルトは4096) —encoder_hidden_statesのチャネル次元。 - mlp_ratio (
int、デフォルトは3) — フィードフォワードの拡張係数です。 - axes_dims_rope (
tuple[int]、デフォルトは(16, 56, 56)) — フレーム、高さ、幅の各軸に対する Rotary 次元です。 - eps (
float、デフォルトは1e-6) — Norm レイヤー用のエプシロン値。 - causal_condition (
bool、デフォルトはTrue) —t = 0からテキストおよび条件画像のトークンをモジュレートします。KVキャッシュには必須です。
Qwen-Image 2.1で使用される単一ストリームTransformer。
テキストと画像の潜在変数は1つのシーケンスを共有します。条件画像のトークンは、ビジョン・言語エンコーダーがそれ用に確保した位置にテキストストリームへ代入され、ターゲット画像のトークンは末尾に追加されます。単一の共有modulation射影がすべてのブロックに供給されるため、各ブロックは独自のmodulationパラメータを保持しません。
2.1を特徴づける2つの動作:
- ブロック因果アテンション — アテンションは
(q_idx >= kv_idx) or same_image_blockに従うため、シーケンス全体としては因果的でありながら、各画像ブロック内部では双方向になります。flexアテンションバックエンドを使用すると、効率的な単一パスのアテンションが得られます。使用しない場合、モデルは各ブロックを個別に処理する正確なマルチパスSDPAプリフィルを使用します。 causal_condition— テキストおよび条件画像のトークンは、サンプリングされたタイムステップではなくt = 0からモジュレーションされるため、それらのアクティベーションはタイムステップに依存せず、デノイジングステップ間でキャッシュ可能になります。
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)。条件画像を先頭に、ターゲット画像を末尾に配置します。
戻り値
tuple[torch.Tensor, torch.Tensor]
image_ids (seq_len,) はテキストの位置に -1 を持ち、画像ブロックごとに一意の id を持つ配列です。また、target_token_mask (seq_len,) は対象となる画像のトークンを示すマスクです。
結合シーケンスの各トークンに、それが属する画像ブロックをラベル付けします。
ブロックの境界は、image_pad_mask における True の連続ではなく、img_shapes 内のトークン数から決定されます。テキストを挟まず隣接して配置された 2 つの条件画像は 1 つの連続区間を形成しますが、別々のブロックとして保持されなければなりません。そうしないと、それらが双方向に相互注意を払うことになってしまいます。
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)) — パックされた潜変数。条件画像が先頭、ターゲット画像が末尾に配置されています。 - encoder_hidden_states (
torch.Tensor、形状(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、形状(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と一緒に渡すことで、プレフィックス 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、それ以外の場合は、最初の要素がノイズ除去された潜変数である通常の tuple を返します。
Transformer2DModelOutput
クラス diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
パラメータ
- sample (
torch.Tensor、形状(batch_size, num_channels, height, width)、または Transformer2DModel が離散型の場合(batch size, num_vector_embeds - 1, num_latent_pixels)) —encoder_hidden_states入力を条件とする隠れ状態の出力です。離散型の場合、ノイズ除去されていない潜在ピクセルの確率分布を返します。
Transformer2DModelの出力です。