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

AnyFlowFARTransformer3DModel

المحوّل ثلاثي الأبعاد السببي (FAR) المستخدم في AnyFlowFARPipeline — وهو متغير FAR من AnyFlow. راجع صفحة AnyFlowFARPipeline للاطلاع على الورقة البحثية والمؤلفين والنقاط الفاحصة (checkpoints) المُطلقة. يمتد هذا النموذج فوق الهيكل الأساسي Wan2.1 الإصدار v0.35.1 بإضافات ثلاث:

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

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

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

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

المصدر

المعاملات:

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() (وكذلك إلى forward).

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

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

• قناع كتلة سببية FAR عبر torch.nn.attention.flex_attention، مع دعم التوليد الذاتي التتابعي على مستوى المقاطع (FAR).
• تضمين البقع للإطارات المضغوطة far_patch_embedding للإطارات السياقية (المولّدة مسبقًا)، مُهيّأ من patch_embedding عبر الاستيفاء ثلاثي الخطية بحيث يكون النموذج المُنشأ حديثًا عند نقطة بداية معقولة حتى قبل ضبط LoRA.
• تضمين خريطة التدفق بخطوة زمنية مزدوجة لعينة أي خطوة (نفس AnyFlowTransformer3DModel).

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

build_attention_mask[[diffusers.AnyFlowFARTransformer3DModel.build_attention_mask]]

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')

المصدر

المعاملات:

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

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)

المصدر

المعاملات:

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

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)

المصدر

المعاملات:

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

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

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