Hugging Face's logo

Diffusers documentation

AnyFlowFARTransformer3DModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

< >

( patch_size: typing.Tuple[int] = (1, 2, 2)compressed_patch_size: typing.Tuple[int] = (1, 4, 4)full_chunk_limit: int = 3num_attention_heads: int = 40attention_head_dim: int = 128in_channels: int = 16out_channels: int = 16text_dim: int = 4096freq_dim: int = 256ffn_dim: int = 13824num_layers: int = 40cross_attn_norm: bool = Trueeps: float = 1e-06image_dim: typing.Optional[int] = Nonerope_max_seq_len: int = 1024gate_value: float = 0.25deltatime_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) — البُعد الوسيط في الشبكة الأمامية.
  • 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).

تحويلة ثلاثية الأبعاد سببية (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

< >

( chunk_partition: typing.List[int]height: intwidth: inthas_clean_context: bool = Falsedevice: typing.Optional[torch.device] = Nonemode: str = 'train' ) → ~torch.nn.attention.flex_attention.BlockMask

المعاملات

  • 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

< >

( hidden_states: Tensortimestep: Tensorr_timestep: Tensorencoder_hidden_states: Tensorchunk_partition: typing.List[int]encoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneclean_hidden_states: typing.Optional[torch.Tensor] = Noneclean_timestep: typing.Optional[torch.Tensor] = Nonekv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = Nonekv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = Noneattention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = Noneattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonereturn_dict: bool = True ) → [~models.transformer_2d.Transformer2DModelOutput], [AnyFlowFARTransformerOutput] or tuple

المعاملات

  • 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

< >

( sample: typing.Optional[torch.Tensor] = Nonekv_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.

Update on GitHub

←AllegroTransformer3DModel AnyFlowTransformer3DModel→