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

QwenImage21Transformer2DModel

المحوّل أحادي التدفق المستخدم في Qwen-Image 2.1. تتشارك كامنات النص والصورة تسلسلاً واحداً، وتُغذّي إسقاط modulation مشترك واحد كل كتلة.

يتميز حوّل QwenImage الإصدار 2.1 عن الإصدارات السابقة بسلوكين:

• انتباه سببي على مستوى الكتل — يتبع الانتباه (q_idx >= kv_idx) or same_image_block، لذا تكون التسلسل المشترك سببيًا بينما تبقى كل كتلة صورة ثنائية الاتجاه داخليًا. ينفذ QwenImage21AttnProcessor ذلك كنداء انتباه واحد لكل مقطع بادئة، وهو الإعداد الافتراضي. ينفذ QwenImage21FlexAttnProcessor ذلك كنداء واحد لـ flex_attention يقوده BlockMask، وهو أسرع بعد تجميع النموذج. ينتج كلاهما نفس النتائج.
• 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[int, int, int] = (16, 56, 56), eps: float = 1e-06, causal_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)) : أبعاد الدوران لمحاور الإطار والارتفاع والعرض.

eps (float، القيمة الافتراضية 1e-6) : قيمة إبسيلون لطبقات التطبيع.

causal_condition (bool، القيمة الافتراضية True) : تعديل رموز النص ورموز صورة الشرط بدءًا من t = 0. مطلوب لتخزين KV.

نموذج Transformer ذو تدفق واحد تستخدمه Qwen-Image 2.1.

تشارك كامنات النص والصورة تسلسلاً واحداً: تُستبدل رموز صورة الشرط في تدفق النص عند المواضع التي خصصها مُشفِّر اللغة البصرية لها، وتُضاف رموز الصورة المستهدفة في النهاية. يغذي إسقاط 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[tuple[int, int, int]])

المصدر

المعاملات:

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 في مواضع النص، مع معرّف فريد لكل كتلة صورة، وtarget_token_mask (seq_len,) لتحديد رموز الصورة المستهدفة.

وسِّم كل رمز في التسلسل المشترك بالكتلة الصورية التي ينتمي إليها.

تأتي حدود الكتل من أعداد الرموز في img_shapes، وليس من التتابعات المتتالية لقيمة True في image_pad_mask: فصورتا شرط متجاورتان بالصدفة دون وجود نص بينهما تشكّلان تتابعاً واحداً، لكن يجب أن تظل كتلتين منفصلتين، وإلا فإنهما ستتعاملان مع بعضهما البعض بشكل ثنائي الاتجاه.

forward[[diffusers.QwenImage21Transformer2DModel.forward]]

forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_shapes: list[list[tuple[int, int, int]]], 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 من الشكل (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) تُحدد الرموز النصية الصالحة. تُستبعد المواضع المعبّأة (padded) من الانتباه (attention).

kv_cache (QwenImage21KVCache، اختياري) : حاوية التخزين المؤقت. مرّرها مع kv_cache_mode لتفعيل تخزين بادئة KV المؤقت.

kv_cache_mode (str, اختياري) : "extract" لملء ذاكرة التخزين المؤقت مسبقًا (خطوة إزالة الضوضاء الأولى)، و"cached" لفك الترميز منها (الخطوات اللاحقة). يتطلب causal_condition=True.

attention_kwargs (dict، اختياري) : يُمرَّر إلى معالجات الانتباه، ويحمل scale لطبقات LoRA.

return_dict (bool، اختياري، القيمة الافتراضية True) : ما إذا كان يجب إرجاع Transformer2DModelOutput بدلاً من tuple عادي.

يعيد: Transformer2DModelOutput أو tuple

Transformer2DModelOutput إذا كان return_dict هو True، وإلا فسيكون 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 من الشكل (batch_size, num_channels, height, width) أو (batch size, num_vector_embeds - 1, num_latent_pixels) إذا كان Transformer2DModel منفصلاً): مخرجات الحالات المخفية المشروطة على مدخل encoder_hidden_states. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.

مخرجات Transformer2DModel.