# 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`.

حمّله باستخدام:

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

```python
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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L716)

**المعاملات:**

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

```python
build_token_metadata(image_pad_mask: Tensor, img_shapes: list[tuple[int, int, int]])
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L822)

**المعاملات:**

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

```python
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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_qwenimage21.py#L862)

**المعاملات:**

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](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) بدلاً من tuple عادي.

**يعيد:** [Transformer2DModelOutput](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) أو `tuple`

[Transformer2DModelOutput](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) إذا كان `return_dict` هو True، وإلا فسيكون `tuple` بسيطاً يكون عنصره الأول هو الكمونيات المُزالة الضوضاء.

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

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

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**المعاملات:**

sample (`torch.Tensor` من الشكل `(batch_size, num_channels, height, width)` أو `(batch size, num_vector_embeds - 1, num_latent_pixels)` إذا كان [Transformer2DModel](/docs/diffusers/main/ar/api/models/transformer2d#diffusers.Transformer2DModel) منفصلاً): مخرجات الحالات المخفية المشروطة على مدخل `encoder_hidden_states`. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.

مخرجات [Transformer2DModel](/docs/diffusers/main/ar/api/models/transformer2d#diffusers.Transformer2DModel).