#
# مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص")
# لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص.
# يمكنك الحصول على نسخة من الترخيص في
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات
# تُوزَّع بموجب الرخصة على أساس "كما هي"،
# بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية.
# راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و
# قيود بموجب الترخيص. -->

# Flux3Transformer2DModel

نموذج Transformer لبيانات تشبه الصور من [FLUX.3](https://bfl.ai/)، لتوليد الصور من النص وتوليد الصور من الصور. تتشارك ثلاثة أوضاع رموز تسلسلًا مشتركًا واحدًا: رموز الصورة الضجيجية، ورموز الصورة المرجعية المُرمّزة بواسطة VAE، وسياق النص. يمرّ كل وضع أولًا عبر كتل transformer الخاصة به لكل وضع، ثم تُدمج الأوضاع معًا لتمريرها عبر الكتل المفردة المشتركة، وتُمرَّر رموز الصورة عبر طبقات الإخراج. تكون الخطوات الزمنية لكل رمز: تحمل رموز الصورة خطوة تدفق زمنية، بينما تبقى رموز المرجع وسياق النص عند `0`.

```python
import torch
from diffusers import Flux3Transformer2DModel

transformer = Flux3Transformer2DModel.from_pretrained(
    "black-forest-labs/flux-3-image-klein-base", subfolder="transformer", dtype=torch.bfloat16
)
```

## Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

#### diffusers.Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

```python
diffusers.Flux3Transformer2DModel(in_channels: int = 128, cond_in_channels: int = 128, num_layers: int = 5, num_single_layers: int = 28, attention_head_dim: int = 128, num_attention_heads: int = 24, joint_attention_dim: int = 20480, timestep_channels: int = 256, mlp_ratio: float = 3.0, axes_dims_rope: tuple = (32, 32, 32, 32), rope_theta: int = 10000, eps: float = 1e-06, flow_map: bool = False)
```

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

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

in_channels (`int`، القيمة الافتراضية `128`) : عرض قناة رموز الصورة (المتغيرات الكامنة المعبأة لـ VAE، `latent_channels * 4`).

cond_in_channels (`int`، القيمة الافتراضية `128`) : عرض قناة رموز الصورة المرجعية.

num_layers (`int`، القيمة الافتراضية `5`) : عدد كتل التحويل (transformer blocks) لكل وضع.

num_single_layers (`int`، القيمة الافتراضية `28`) : عدد كتل الترانسفورمر المفردة المشتركة.

attention_head_dim (`int`، القيمة الافتراضية `128`) : عدد الأبعاد المستخدمة لكل رأس انتباه.

num_attention_heads (`int`، القيمة الافتراضية `24`) : عدد رؤوس الانتباه (attention heads) المستخدمة.

joint_attention_dim (`int`، القيمة الافتراضية `20480`) : بُعد التضمين/القناة الخاص بـ `encoder_hidden_states` (حالات Qwen3-VL المخفية المكدسة).

timestep_channels (`int`، القيمة الافتراضية `256`) : عدد قنوات تضمين خطوة الزمن الجيبية.

mlp_ratio (`float`، القيمة الافتراضية `3.0`) : نسبة التوسّع في كتل التغذية الأمامية الفرعية.

axes_dims_rope (`tuple[int]`، القيمة الافتراضية هي `(32, 32, 32, 32)`) : الأبعاد المستخدمة للتضمينات الموضعية الدوارة، لكل محور من محاور الموضع `(t, h, w, l)`.

rope_theta (`int`، القيمة الافتراضية `10000`) : التردد الأساسي للتضمينات الموضعية الدوارة.

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

flow_map (`bool`، القيمة الافتراضية `False`) : ما إذا كان النموذج خريطة تدفق (مُقطَّرة خطوة بخطوة): يضيف `target_timestep_embedder` ويتطلب `target_timestep` في مسار الأمامي.

نموذج Transformer الذي تم تقديمه في FLUX.3 لتوليد الصور من النص وتحويل الصور إلى صور.

تشارك ثلاثة أوضاع للرموز تسلسلًا مشتركًا واحدًا: رموز الصورة الضجيجية (`hidden_states`)، ورموز صورة المرجع الاختيارية المُرمَّزة بواسطة VAE (`image_cond_hidden_states`)، وسياق النص (`encoder_hidden_states`). يمرّ كل وضع أولًا عبر كتل التحوّل الخاصة بالوضع (`mode_blocks` لأوضاع الصورة، و`txt_mode_blocks` لسياق النص)، ثم يُدمج سياق النص مع أوضاع الصورة النشطة للكتل المفردة المشتركة، ولا تمرّ رموز الصورة فقط عبر طبقات الإخراج. التعديل (Modulation) يتم لكل وضع على حدة: تُعدَّل رموز الصورة بخطوة الزمن (timestep) للتدفق، بينما تُعدَّل رموز صورة المرجع وسياق النص بخطوة الزمن `0`. يُضمّن نقطة التفتيش الخاصة بخريطة التدفق (`flow_map=True`، وهي النماذج المُقطَّرة على مستوى الخطوة) خطوة الزمن التي يقفز إليها كل خطوة إزالة ضجيج، ويضيفها إلى تعديل كل وضع.

#### forward[[diffusers.Flux3Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_ids: Tensor, txt_ids: Tensor, image_cond_hidden_states: typing.Optional[torch.Tensor] = None, image_cond_ids: typing.Optional[torch.Tensor] = None, target_timestep: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

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

hidden_states (`torch.Tensor` من الشكل `(batch_size, image_seq_len, in_channels)`) : رموز الكامنة للصورة الضوضائية.

encoder_hidden_states (`torch.Tensor` من الشكل `(batch_size, text_seq_len, joint_attention_dim)`) : تمثيلات سياق النص (حالات خفية مكدسة من Qwen3-VL).

timestep (`torch.Tensor` من الشكل `(batch_size,)`) : خطوة الزمن للتدفق في `[0, 1]` لرموز الصورة. رموز الصورة المرجعية وسياق النص يقعان عند خطوة الزمن `0`.

img_ids (`torch.Tensor` من الشكل `(image_seq_len, 4)`) : معرّفات المواقع `(t, h, w, l)` لرموز الصورة، تُستخدم للتضمينات الموضعية الدوّارية ومُشارَكة بين جميع العينات في الدفعة.

txt_ids (`torch.Tensor` من الشكل `(text_seq_len, 4)`) : معرّفات مواضع رموز سياق النص.

image_cond_hidden_states (`torch.Tensor` من الشكل `(batch_size, cond_seq_len, cond_in_channels)`، *اختياري*) : رموز صورة مرجعية مُرمّزة بواسطة VAE (محتوى تكييف نظيف، لتوليد الصور من الصور).

image_cond_ids (`torch.Tensor` من الشكل `(cond_seq_len, 4)`، *اختياري*) : معرّفات المواضع لرموز الصورة المرجعية. مطلوب عند استخدام `image_cond_hidden_states`.

target_timestep (`torch.Tensor` من الشكل `(batch_size,)`، *اختياري*) : خطوة الزمن التدفقي في `[0, 1]` التي يقفز إليها خطو إزالة الضوضاء الحالي. مطلوب من قبل نموذج خريطة التدفق (`flow_map=True`) فقط، ولا يُطلب من غيره.

attention_kwargs (`dict`، *اختياري*) : قاموس kwargs حيث يُقيّم إدخال `scale`، إن وُجد، طبقات LoRA لهذا المرور الأمامي.

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

**يعيد:**

إذا كان `return_dict` صحيحًا، يُعاد `~models.transformer_2d.Transformer2DModelOutput`، وإلا يُعاد `tuple` يكون عنصره الأول هو السرعة المتوقعة لرموز الصورة، بنفس شكل `hidden_states`.

طريقة [Flux3Transformer2DModel](/docs/diffusers/main/ar/api/models/flux3_transformer#diffusers.Flux3Transformer2DModel) الأمامية.

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