# AnyFlowFARTransformer3DModel

المحوّل ثلاثي الأبعاد السببي (FAR) المستخدم في [`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) — وهو متغير FAR من [AnyFlow](https://huggingface.co/papers/2605.13724). راجع صفحة [`AnyFlowFARPipeline`](../pipelines/anyflow) للاطلاع على الورقة البحثية والمؤلفين والنقاط الفاحصة (checkpoints) المُطلقة. يمتد هذا النموذج فوق الهيكل الأساسي Wan2.1 الإصدار v0.35.1 بإضافات ثلاث:

1. **قناع كتلة سببية FAR** عبر `torch.nn.attention.flex_attention`، مع دعم التوليد الذاتي التتابعي على مستوى المقاطع كما تم تقديمه في [FAR](https://huggingface.co/papers/2503.19325).
2. **تضمين البقع للإطارات المضغوطة** (`far_patch_embedding`) للإطارات السياقية (المولّدة مسبقًا)، مع بدء التشغيل الدافئ من `patch_embedding` عالي الدقة عند الإنشاء عبر الاستيفاء ثلاثي الخطية.
3. **تضمين خريطة التدفق بخطوة زمنية مزدوجة** (نفس [`AnyFlowTransformer3DModel`](anyflow_transformer3d)) — كل استدعاء للأمام يشترط على كل من الخطوة الزمنية المصدر ``t`` والخطوة الزمنية الهدف ``r``.

يُخزَّن جدول التقطيع الافتراضي (`chunk_partition`) في إعدادات النموذج؛ وتستخدم نقاط التفتيش المُطلقة من NVIDIA AnyFlow-FAR `[1, 3, 3, 3, 3, 3, 3, 2]` للإعداد القياسي المكوّن من 81 إطارًا. ويقبل `forward` تجاوزًا لـ`chunk_partition` لكل استدعاء، مما يتيح لنفس نقطة التفتيش التعامل مع إعدادات أخرى لـ`num_frames` دون إعادة تدريب.

```python
from diffusers import AnyFlowFARTransformer3DModel

# Causal AnyFlow checkpoint (FAR):
transformer = AnyFlowFARTransformer3DModel.from_pretrained(
    "nvidia/AnyFlow-FAR-Wan2.1-1.3B-Diffusers", subfolder="transformer"
)
```

## AnyFlowFARTransformer3DModel[[diffusers.AnyFlowFARTransformer3DModel]]

#### diffusers.AnyFlowFARTransformer3DModel[[diffusers.AnyFlowFARTransformer3DModel]]

```python
diffusers.AnyFlowFARTransformer3DModel(patch_size: typing.Tuple[int] = (1, 2, 2), compressed_patch_size: typing.Tuple[int] = (1, 4, 4), full_chunk_limit: int = 3, num_attention_heads: int = 40, attention_head_dim: int = 128, in_channels: int = 16, out_channels: int = 16, text_dim: int = 4096, freq_dim: int = 256, ffn_dim: int = 13824, num_layers: int = 40, cross_attn_norm: bool = True, eps: float = 1e-06, image_dim: typing.Optional[int] = None, rope_max_seq_len: int = 1024, gate_value: float = 0.25, deltatime_type: str = 'r', chunk_partition: typing.Tuple[int, ...] = (1, 3, 3, 3, 3, 3, 3, 2))
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L961)

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

patch_size (*Tuple[int]*، القيمة الافتراضية *(1, 2, 2)*) : أبعاد الباتش ثلاثية الأبعاد لمقاطع الدقة الكاملة.

compressed_patch_size (*Tuple[int]*، القيمة الافتراضية *(1, 4, 4)*) : أبعاد رقعة أكبر للقطع المضغوطة بواسطة FAR (سياق).

full_chunk_limit (*int*، القيمة الافتراضية *3*) : الحد الأقصى لعدد مقاطع الدقة الكاملة قبل أن تُخفَّض المقاطع السابقة إلى سياق FAR المضغوط. تستخدم نقاط التفتيش المُصدَّرة `3`.

num_attention_heads (*int*، القيمة الافتراضية *40*) : عدد رؤوس الانتباه.

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

in_channels (*int*، القيمة الافتراضية *16*) : عدد القنوات في الكامن المُدخل.

out_channels (*int*، القيمة الافتراضية *16*) : عدد القنوات في الكامن الناتج.

text_dim (*int*، القيمة الافتراضية *4096*) : بُعد الإدخال لتضمينات النص (UMT5).

freq_dim (*int*، القيمة الافتراضية *256*) : البُعد الخاص بالتضمينات الزمنية الجيبية.

ffn_dim (*int*، القيمة الافتراضية *13824*) : البُعد الوسيط في الشبكة الأمامية (feed-forward).

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

cross_attn_norm (*bool*، القيمة الافتراضية *True*) : تفعيل تطبيع الانتباه المتقاطع.

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

image_dim (*Optional[int]*، *اختياري*، القيمة الافتراضية *None*) : بُعد تضمين الصورة (Image embedding) لتكييف I2V.

rope_max_seq_len (*int*، القيمة الافتراضية *1024*) : الحد الأقصى لطول التسلسل المستخدم لحساب ترددات الموضع الدوّار مسبقًا.

gate_value (*float*، القيمة الافتراضية *0.25*) : بوابة الخلط بين تمثيلات خطوة المصدر وخطوة الدلتا.

deltatime_type (*str*، القيمة الافتراضية *'r'*) : إما `"r"` (حيث يكون الدلتا هو خطوة الزمن المستهدفة) أو `"t-r"` (حيث يكون الدلتا هو الفاصل المطلق).

chunk_partition (*Tuple[int, ...]*، القيمة الافتراضية هي *(1, 3, 3, 3, 3, 3, 3, 2)*) : عدد الإطارات الافتراضي لكل جزء الذي تستخدمه خط المعالجة. تستهدف نقاط التفتيش (checkpoints) المُصدَّرة من NVIDIA AnyFlow-FAR قيمة `num_frames=81` (21 إطارًا كامنًا عند خطوة VAE الزمنية 4) مقسمة على النحو `1 + 3*6 + 2`. يتطلب استخدام قيمة مختلفة لـ `num_frames` تجاوزًا مطابقًا لـ `chunk_partition` يُمرَّر إلى [AnyFlowFARPipeline.__call__()](/docs/diffusers/v0.43.0/ar/api/pipelines/anyflow#diffusers.AnyFlowFARPipeline.__call__) (وكذلك إلى `forward`).

Causal (FAR) محوّل ثلاثي الأبعاد لعينة خرائط التدفق في AnyFlow مع توليد ذاتي مرجعي على مستوى المقاطع.

يمدّد هيكل Wan2.1 الإصدار v0.35.1 بما يلي:

- **قناع كتلة سببية FAR** عبر `torch.nn.attention.flex_attention`، مع دعم التوليد الذاتي التتابعي على مستوى المقاطع ([FAR](https://huggingface.co/papers/2503.19325)).
- **تضمين البقع للإطارات المضغوطة** `far_patch_embedding` للإطارات السياقية (المولّدة مسبقًا)، مُهيّأ من `patch_embedding` عبر الاستيفاء ثلاثي الخطية بحيث يكون النموذج المُنشأ حديثًا عند نقطة بداية معقولة حتى قبل ضبط LoRA.
- **تضمين خريطة التدفق بخطوة زمنية مزدوجة** لعينة أي خطوة (نفس `AnyFlowTransformer3DModel`).

استخدم `AnyFlowTransformer3DModel` بدلاً من ذلك لتوليد الفيديو من النص ثنائي الاتجاه البسيط — إذ يتخطى هذا المتغير قناع السببية الخاص بـ FAR و`far_patch_embedding` ويكون أصغر بحوالي 5–10%.

#### build_attention_mask[[diffusers.AnyFlowFARTransformer3DModel.build_attention_mask]]

```python
build_attention_mask(chunk_partition: typing.List[int], height: int, width: int, has_clean_context: bool = False, device: typing.Optional[torch.device] = None, mode: str = 'train')
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L1237)

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

chunk_partition : عدد الإطارات لكل جزء (يجب أن يكون مجموعها مساوياً لعدد الإطارات الكامنة).

height, width : الأبعاد المكانية الكامنة.

has_clean_context : `True` عندما يُمرَّر `clean_hidden_states` عبر `forward` (تدريب V2V/I2V)؛ لا يؤثر على تخطيط القناع سوى وجود هذا العلم.

device : الجهاز الخاص بـ`BlockMask` الناتج. لا يتم نقل القناع تلقائيًا بواسطة `device_map="auto"`؛ قم ببنائه على نفس الجهاز الذي ستُستضاف عليه مدخلات المحوّل.

mode : `"train"` (يتطابق مع `_forward_train`) أو `"cache"` (يتطابق مع `_forward_cache`). مسار الاستدلال التلقائي `_forward_inference` يستدعي عبر ذاكرة KV ولا يحتوي على وضع هنا.

**يعيد:** `~torch.nn.attention.flex_attention.BlockMask`

قناع سببي يمتد عبر تخطيط FAR، مع ملء الأبعاد حتى أقرب مضاعف لـ 128 على طول بُعد التسلسل (متطلب حجم الكتلة في BlockMask).

**يرفع:** `ValueError`

- `ValueError` -- إذا لم يكن `mode` أيًا من `"train"` أو `"cache"`.

قم ببناء `~torch.nn.attention.flex_attention.BlockMask` السببي مسبقًا خارج `forward`.

مرّر النتيجة عبر معامل `attention_mask` في `forward` لجعل المحوّل بالكامل متوافقًا مع `torch.compile(fullgraph=True)`. في غياب قناع مُعدّ مسبقًا، يعود `forward` إلى بنائه داخليًا — وهذا المسار يستخدم `flex_attention.create_block_mask(_compile=False)` ويكسر رسم التجميع.

#### forward[[diffusers.AnyFlowFARTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: Tensor, r_timestep: Tensor, encoder_hidden_states: Tensor, chunk_partition: typing.List[int], encoder_hidden_states_image: typing.Optional[torch.Tensor] = None, clean_hidden_states: typing.Optional[torch.Tensor] = None, clean_timestep: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None, kv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = None, attention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = None, attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L1098)

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

hidden_states (*torch.Tensor*) : مدخل كامن (Latent) على شكل `(B, F, C, H, W)`.

timestep (*torch.Tensor*) : خطوة الزمن *t* لخريطة التدفق المصدرية (الأكثر ضجيجًا).

r_timestep (*torch.Tensor*) : خطوة الزمن *r* لخريطة التدفق المستهدفة (النظيفة).

encoder_hidden_states (*torch.Tensor*) : تمثيلات نصوص UMT5.

chunk_partition (*List[int]*) : عدد الإطارات لكل شريحة؛ يجب أن يتطابق المجموع مع عدد الإطارات الكامنة في `hidden_states`.

encoder_hidden_states_image (*torch.Tensor*، *اختياري*) : تضمين صورة I2V؛ يُدمج قبل رموز النص عند توفيره.

clean_hidden_states (*torch.Tensor*، *اختياري*) : إطارات شرطية نظيفة (خالية من الضوضاء) تُستخدمها عملية التدريب.

clean_timestep (*torch.Tensor*، *اختياري*) : خطوات زمنية للإطارات الشرطية النظيفة في تمرين التدريب.

kv_cache (*List[Dict[str, torch.Tensor]]*، *اختياري*) : ذاكرة تخزين مؤقتة لمفاتيقات وقيم (KV) لكل كتلة للاستدلال التلقائي التوليد. اختيار *None* يحدد مسار التدريب.

kv_cache_flag (*Dict[str, Any]*، *اختياري*) : بيانات وصفية لـ KV-cache (مثل علم `is_cache_step` وعدد الرموز).

attention_mask (*BlockMask*، *اختياري*) : قناع سببي مُعدّ مسبقًا، يُنشأ عادةً عبر `build_attention_mask`. يُستهلك في مسارات التدريب ومسارات تعبئة ذاكرة KV؛ بينما تعتمد مسار الاستدلال التلقائي على الانتباه عبر ذاكرة KV ولا تستخدم قناعًا كاملًا. عند تعيين `None`، تبني مسارات التدريب / الكاش القناع داخليًا؛ لكن هذا المسار الاحتياطي غير آمن للتجميع (إذ يكسر `flex_attention.create_block_mask` الرسم البياني عند `fullgraph=True`)، لذا مرّر قناعًا مُعدًّا مسبقًا دائمًا عند تغليف `forward` بـ `torch.compile`.

attention_kwargs (*dict*، *اختياري*) : يُمرَّر إلى معالجات الانتباه.

return_dict (*bool*، *اختياري*، القيمة الافتراضية *True*) : إذا كانت *False*، تُرجع مجموعات موضعية (positional tuples) بدلاً من كائن بيانات المخرجات (output dataclass).

**يعيد:** [*~models.transformer_2d.Transformer2DModelOutput*]، [*AnyFlowFARTransformerOutput*] أو *tuple*

عندما يكون *return_dict* بقيمة *False*، يُعاد *tuple* عادي. وإلا، فإن مسار التدريب السببي (*kv_cache is None*) يعيد [*~models.transformer_2d.Transformer2DModelOutput*]، بينما تعيد مسارات تعبئة الكاش والاستدلال التلقائي [*AnyFlowFARTransformerOutput*].

المرور الأمامي السببي في FAR. يُوجَّه إلى أحد المسارات الداخلية الثلاثة:

- `kv_cache is None` → تمرين سببي (يعيد `Transformer2DModelOutput`).
- `kv_cache is not None` و `kv_cache_flag["is_cache_step"]` → تعبئة الكاش (يعيد `AnyFlowFARTransformerOutput` مع `sample=None`).
- في حال العكس → خطوة استنتاج ذاتية التوليد (تعيد `AnyFlowFARTransformerOutput`).

## AnyFlowFARTransformerOutput[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

#### diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

```python
diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput(sample: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L55)

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

sample (*torch.Tensor* أو *None*) : الهدف المتوقع لإزالة الضوضاء للقطعة التوليدية الذاتية. `None` لمسار تعبئة الكاش، الذي يكتب ذاكرة KV فقط ولا ينتج أي عينة قابلة للاستخدام.

kv_cache (*list[dict[str, torch.Tensor]]*، *اختياري*) : حالة ذاكرة KV لكل كتلة تُستخدم في الخطوات التوليدية الذاتية اللاحقة.

فئة بيانات المخرجات لمسارات الأمامية السببية في `AnyFlowFARTransformer3DModel`.