Diffusers documentation
WanAnimate2Transformer3DModel
WanAnimate2Transformer3DModel
نموذج Wan-Animate-2 من فريق Wan في Alibaba، وهو نموذج Diffusion Transformer مخصص لبيانات الفيديو ثلاثية الأبعاد. يقوم هذا النموذج بتحريك صورة شخصية عبر حركة فيديو إرشادي باستخدام آلية مرجعية ضمن السياق: حيث يُنفَّذ لكل مقطع أولاً مسار مرجعي (kv_cache_mode="extract") يخزّن فيه مفاتيح K/V المرجعية لكل طبقة، ثم تُنفَّذ مسارات إزالة الضوضاء (kv_cache_mode="cached") التي تتعامل مع رموز التوليد ورموز المرجع المخزنة معاً عبر BlockMask مرن.
يمكن تحميل النموذج باستخدام مقتطف الشيفرة التالي.
from diffusers import WanAnimate2Transformer3DModel
transformer = WanAnimate2Transformer3DModel.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)WanAnimate2Transformer3DModel
فئة diffusers.WanAnimate2Transformer3DModel
< source >( patch_size: tuple = (1, 2, 2)text_len: int = 512in_dim: int = 36dim: int = 5120ffn_dim: int = 13824freq_dim: int = 256text_dim: int = 4096out_dim: int = 16num_heads: int = 40num_layers: int = 40cross_attn_norm: bool = Trueeps: float = 1e-06use_img_emb: bool = Truerefer_offset_t: int = 1refer_offset_h: int = 0refer_offset_w: int = -1refer_stride: int = 1 )
المعاملات
- patch_size (tuple[int])، القيمة الافتراضية (1, 2, 2)) — أبعاد الباتش ثلاثية الأبعاد لتضمين الفيديو (t_patch, h_patch, w_patch).
- text_len (int، القيمة الافتراضية 512) — الطول الثابت لتضمينات النص.
- in_dim (int، القيمة الافتراضية 36) — عدد القنوات في المدخلات (2 * latent_channels + 4 لقناة القناع).
- dim (int، القيمة الافتراضية 5120) — عدد القنوات في المحوّل.
- ffn_dim (int، القيمة الافتراضية 13824) — البُعد الوسيط في الشبكة الأمامية.
- freq_dim (int، القيمة الافتراضية 256) — البُعد الخاص بالتضمينات الزمنية الجيبية.
- text_dim (int، القيمة الافتراضية 4096) — البُعد المدخل لتضمينات النص.
- out_dim (int، القيمة الافتراضية 16) — عدد القنوات في المخرجات.
- num_heads (int، القيمة الافتراضية 40) — عدد رؤوس الانتباه.
- num_layers (int، القيمة الافتراضية 40) — عدد طبقات كتل التحويل (transformer blocks) المستخدمة.
- cross_attn_norm (bool، القيمة الافتراضية True) — تفعيل تطبيع الانتباه المتقاطع.
- eps (float، القيمة الافتراضية 1e-6) — قيمة إبسيلون لطبقات التطبيع.
- use_img_emb (bool، القيمة الافتراضية True) — ما إذا كان سيتم استخدام تضمين صورة CLIP.
- refer_offset_t (int، القيمة الافتراضية 1) — إزاحة RoPE للبعد الزمني للمرجع.
- refer_offset_h (int، القيمة الافتراضية 0) — إزاحة RoPE لبُعد الارتفاع في المرجع.
- refer_offset_w (int، القيمة الافتراضية -1) — إزاحة RoPE لبُعد العرض في المرجع. القيمة -1 تعني استخدام حجم شبكة التوليد.
- refer_stride (int، القيمة الافتراضية 1) — خطوة تطبيق RoPE على المرجع.
نموذج Transformer لبيانات تشبه الفيديو يُستخدم في نموذج Wan-Animate-2.
يستخدم Wan-Animate-2 آلية انتباه سياقية مع ذاكرة تخزين مؤقت KV: يتم أولاً ترميز فيديو مرجعي (kv_cache_mode="extract") لملء [WanAnimate2KVCache]، ثم ينتبه كل خطوة إزالة ضوضاء (kv_cache_mode="cached") بشكل مشترك على رموز التوليد و K/V المرجعية المخزنة مؤقتًا عبر BlockMask مرن. لذلك، يعمل انتباه التوليد الذاتي حصريًا على واجهة انتباه flex؛ بينما يعمل أي انتباه آخر في النموذج على أي واجهة.
forward
< source >( hidden_states: list[torch.Tensor]timestep: Tensorencoder_hidden_states: list[torch.Tensor]condition_latents: list[torch.Tensor]kv_cache: WanAnimate2KVCachekv_cache_mode: strseq_len: intencoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneoffset_grid_sizes: typing.Optional[torch.Tensor] = Nonereference_grid_sizes: typing.Optional[torch.Tensor] = Noneorigin_len: int | None = Noneorigin_area: list[int] | None = Noneis_uncondtion: bool = Falsereturn_dict: bool = True ) → Transformer2DModelOutput or tuple(list[torch.Tensor])
المعاملات
- hidden_states (
list[torch.Tensor]) — القيم الكامنة لهذا المرور — القيم الكامنة المرجعية عندما يكونkv_cache_mode="extract"، والقيم الكامنة المولّدة مع الضوضاء عندما يكونkv_cache_mode="cached". - timestep (
torch.Tensor) — خطوة إزالة الضوضاء. يتم تجاهلها عند استخدامkv_cache_mode="extract"، حيث تُستخدم خطوة ثابتة بقيمة 1. - encoder_hidden_states (
list[torch.Tensor]) — تمثيلات النص لهذا المرور. - condition_latents (
list[torch.Tensor]) — كعوب الشرط (Conditioning latents) المُدمجة معhidden_statesقبل تضمين البقع (patch embedding). - kv_cache (
WanAnimate2KVCache) — يُكتب عندkv_cache_mode="extract"، ويُقرأ عند"cached". - kv_cache_mode (
str) —"extract"ينفّذ المرور المرجعي ويملأkv_cache؛"cached"ينفّذ خطوة إزالة الضوضاء مقابل الرموز المرجعية المخزّنة مؤقتًا. - seq_len (
int) — عدد الرموز التي يجب أن يحتويها كل عينة بعد تضمين الباتش. - encoder_hidden_states_image (
torch.Tensor، اختياري) — تضمينات صور CLIP، تُستخدم عندما يتم تكوين النموذج باستخدامuse_img_emb. - offset_grid_sizes (
torch.Tensor، اختياري) — شبكة البقع (Patch grid) للكامنات المرجعية، تُستخدم لحل أيrefer_offset_*مُعيّن على -1. مطلوب عندkv_cache_mode="extract"؛ أما عند"cached"، فتصفreference_grid_sizesالشبكة نفسها وتُستخدم بدلاً منها. - reference_grid_sizes (
torch.Tensor، اختياري) — شبكة البقع (Patch grid) للكامنات المرجعية (reference latents)، وتُستخدم للتضمينات الدورانية المرجعية (reference rotary embeddings). مطلوب عندkv_cache_mode="cached". - origin_len (
int، اختياري) — عدد الإطارات في الفيديو الكامل، الذي يُبنى عليه قناع الكتلة داخل السياق. مطلوب عندkv_cache_mode="cached". - origin_area (
list[int]، اختياري) — الحجم المكاني[height, width]للفيديو الكامل، الذي يُبنى عليه قناع كتلة السياق. مطلوب عندkv_cache_mode="cached". - is_uncondtion (
bool، اختياري) — ما إذا كان هذا هو الفرع غير الشرطي لـ classifier-free guidance. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع~models.transformer_2d.Transformer2DModelOutputبدلاً من tuple عادي.
يعيد
Transformer2DModelOutput أو tuple(list[torch.Tensor])
العينة المتنبأ بها لكل مدخل كامن، غير مُقسّمة إلى بقع؛ وهي مجموعة (tuple) عادية إذا كان return_dict هو False.
Transformer2DModelOutput
فئة diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
المعاملات
- sample (
torch.Tensorمن الشكل(batch_size, num_channels, height, width)أو(batch size, num_vector_embeds - 1, num_latent_pixels)إذا كان Transformer2DModel منفصلاً) — مخرجات الحالات المخفية المشروطة على مدخلencoder_hidden_states. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.
مخرجات Transformer2DModel.