# MiniMaxH3Transformer3DModel

نموذج Diffusion Transformer لتوليد الفيديو والصوت معًا، تم تقديمه في [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) بواسطة MiniMax.

يعمل MiniMax-H3 على مكدس واحد من الكتل فوق **تسلسل أحادي البُعد مُجمَّع واحد** يحتفظ في آنٍ واحد بشروط النص، وصفوف صورة الشرط والفيديو، وصفوف الصوت، وصفوف الفيديو المستهدفة. يكون الانتباه انتباه ذاتي كاملًا على ذلك التسلسل، لذا لا يوجد انتباه متقاطع ولا أوزان كتل لكل نمط. تأتي السلوكيات الخاصة بكل نمط فقط من إسقاطي الباتش المدخلين، ووسم النمط لكل صف الذي يختار معاملات تعديل AdaLN، والرأسين المخرجين.

إنشاء التخطيط المُجمَّع هو مسؤولية المُستدعي، ولهذا السبب يستقبل توقيع الدالة الأمامية التخطيط منفصلاً عن الكمونيات: شبكة المواضع `(t, h, w)`، ووسوم الوسائط لكل صف، ومؤشرات خطوات الزمن لكل صف، والمصفوفات الفهرسية الثلاث التي تشير إلى صفوف الفيديو والصوت والنص. يبني [MiniMaxH3Blocks](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) و`MiniMaxH3Ref2VABlocks` كل ذلك.

يتطلب التخطيط الذي يحمل صفوف حشو (الوسم `-1`) واجهة خلفية للانتباه المقنّع، لأن تلك الصفوف تُحفظ في وثيقة انتباه خاصة بها بواسطة قناع منطقي؛ أما التسلسل الخالي من الحشو فلا يحتاج إلى قناع ويبقي جميع الواجهات الخلفية متاحة.

يحتوي المستودع الواحد على كلا قسمَي نقطة التفتيش المُصدَّرة، لذا فإن المجلد الفرعي هو ما يختار المهمة: `transformer/` لمهام النص والإطارات المفتاحية، و`transformer_ref/` لمهمة المرجع الشامل.

```python
import torch
from diffusers import MiniMaxH3Transformer3DModel

transformer = MiniMaxH3Transformer3DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
```

النقطة المحفوظة بدقة مختلطة: إسقاطا الباتش المدخلين، وشبكة MLP الخاصة بخطوة الزمن، ورأسا المخرج هما من نوع float32 بينما مجموعة الكتل من نوع bfloat16. يحافظ `from_pretrained` على هذا التوزيع عبر `_keep_in_fp32_modules`، لذا مرّر `dtype=torch.bfloat16` ودعه يضع وحدات float32 بدلاً من تحويل النموذج باستخدام `.to(torch.bfloat16)` لاحقاً.

## MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

#### diffusers.MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

```python
diffusers.MiniMaxH3Transformer3DModel(num_attention_heads: int = 56, attention_head_dim: int = 128, hidden_size: int = 5376, num_layers: int = 50, num_refiner_layers: int = 2, ffn_dim: int = 14336, in_channels: int = 24, audio_in_channels: int = 32, patch_size: tuple[int, int, int] = (1, 2, 2), text_dim: int = 5120, freq_dim: int = 256, time_embed_hidden_dim: int = 5376, time_embed_dim: int = 2688, rope_freq_dim: int = 16, rope_theta: float = 10000.0, norm_eps: float = 1e-05, qk_norm_eps: float = 1e-05, final_norm_eps: float = 1e-05)
```

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

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

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

attention_head_dim (`int`، القيمة الافتراضية `128`) : عدد القنوات في كل رأس انتباه. لاحظ أن `num_attention_heads * attention_head_dim` يكون *أكبر* من `hidden_size` في MiniMax-H3.

hidden_size (`int`، القيمة الافتراضية `5376`) : عدد قنوات التسلسل المُجمَّع (تدفق المتبقي).

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

num_refiner_layers (`int`، القيمة الافتراضية `2`) : عدد كتل تحسين الرموز المطبقة على تدفق النص المُسقط.

ffn_dim (`int`، القيمة الافتراضية `14336`) : البُعد الداخلي لطبقات التغذية الأمامية SwiGLU.

in_channels (`int`، القيمة الافتراضية `24`) : عدد قنوات الكامنات (latents) للفيديو.

audio_in_channels (`int`، القيمة الافتراضية `32`) : عدد قنوات الكامن الصوتي.

patch_size (`tuple[int, int, int]`، القيمة الافتراضية `(1, 2, 2)`) : البقعة `(t, h, w)` المستخدمة لتعبئة كامنات الفيديو في صفوف.

text_dim (`int`، القيمة الافتراضية `5120`) : عدد قنوات الشرط النصي الناتجة عن مُشفِّر النص.

freq_dim (`int`، القيمة الافتراضية `256`) : بُعد تضمين خطوة الزمن الجيبية. تُستهلك خطوات الزمن دون تحجيم ضمن `[0, 1]`.

time_embed_hidden_dim (`int`، القيمة الافتراضية `5376`) : البُعد الداخلي لشبكة MLP الخاصة بخطوة الزمن.

time_embed_dim (`int`، القيمة الافتراضية `2688`) : بُعد المخرجات لشبكة MLP الخاصة بخطوة الزمن، أي مدخل كل إسقاط AdaLN.

rope_freq_dim (`int`، القيمة الافتراضية `16`) : عدد الترددات الدوارة لكل محور. تتشارك محاور `(t, h, w)` مخزنًا واحدًا باسم `inv_freq` بطول هذا العدد، وتُدار `2 * 3 * rope_freq_dim` من قنوات `attention_head_dim`.

rope_theta (`float`، القيمة الافتراضية `10000.0`) : الأساس الذي تُحسب منه جدول الترددات الدوارة المخزن في `rope.inv_freq`.

norm_eps (`float`، القيمة الافتراضية `1e-5`) : قيمة إيبسلون (Epsilon) لمعايير ما قبل الانتباه (pre-attention) وما قبل الشبكة العصبية الأمامية (pre-feed-forward).

qk_norm_eps (`float`، القيمة الافتراضية `1e-5`) : قيمة إيبسلون (Epsilon) لمعايير الاستعلام/المفتاح لكل رأس.

final_norm_eps (`float`، القيمة الافتراضية `1e-5`) : قيمة إبسيلون لمعايرة مخرجات مُحسّن الرموز ولمعايرة `norm_out`.

نموذج Transformer لتوليد الفيديو والصوت معًا، تم تقديمه في MiniMax-H3.

يعمل MiniMax-H3 على مكدس واحد من الكتل فوق **تسلسل أحادي البُعد واحد مُجمَّع** يحتوي على شرط النص، وصفوف صورة/فيديو الشرط، وصفوف الصوت، وصفوف الفيديو المستهدف. يكون الانتباه انتباه ذاتي كاملًا على ذلك التسلسل؛ فلا يوجد انتباه متقاطع ولا أوزان كتل لكل نمط. يأتي السلوك الخاص بكل نمط فقط من إسقاطي الباتش المدخلين، ووسم النمط الخاص بـ AdaLN لكل صف، والرأسين المخرجين.

يتحمّل المُستدعي مسؤولية بناء التخطيط المُجمَّع: تحويل كامنات الفيديو إلى رقعات، وترتيب الصفوف، وإنتاج شبكة المواضع `(t, h, w)` ووسوم النمط لكل صف والفهارس الزمنية لكل صف. لا يحمل التسلسل أي حشو — حيث يقوم التنفيذ المرجعي بحشوه إلى مضاعف من 64 من أجل FlashAttention وفصل الذيل باستخدام `cu_seqlens = [0, used, S]`، وهو ما لا يحتاجه هذا النقل — لذا يعمل الانتباه دون أقنعة على مستند واحد وتبقى جميع واجهات الانتباه متاحة.

محور الدفعة هو محور تكرار خالص: فالحجج الهيكلية (`timestep`، `timestep_indices`، `token_tags`، `position_ids` ومصفوفات الفهارس الثلاث) تصف تخطيطًا واحدًا مضغوطًا تشاركه جميع عناصر الدفعة، وكل عنصر هو مستند انتباه واحد.

#### forward[[diffusers.MiniMaxH3Transformer3DModel.forward]]

```python
forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, video_indices: Tensor, audio_indices: Tensor, text_indices: Tensor, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

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

hidden_states (`torch.Tensor` من الشكل `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : صفوف الكامنة المُقطَّعة للفيديو — صفوف الشروط وصفوف الأهداف — مرتبة كما تظهر في التسلسل المُجمَّع، أي مطابقة لـ`video_indices`.

audio_hidden_states (`torch.Tensor` من الشكل `(batch_size, num_audio_tokens, audio_in_channels)`) : صفوف الكامنة للصوت، مرتبة لتتوافق مع `audio_indices`.

encoder_hidden_states (`torch.Tensor` من الشكل `(batch_size, num_text_tokens, text_dim)`) : شروط النص، مرتبة لتتوافق مع `text_indices`.

timestep (`torch.Tensor` من الشكل `(num_timesteps,)`) : قيم *خطوة الزمن* المميزة الموجودة في التسلسل المُجمَّع، ضمن `[0, 1]` وغير المُقيَّسة. تخدم تمريرة واحدة الصفوف عند مستويات ضوضاء مختلفة (الفيديو المستهدف، الصوت المستهدف، صفوف الشروط).

timestep_indices (`torch.Tensor` من الشكل `(seq_len,)`) : لكل صف من التسلسل المُجمَّع، فهرس خطوته الزمنية في `timestep`.

token_tags (`torch.Tensor` من الشكل `(seq_len,)`) : لكل صف من التسلسل المُجمَّع، نمطه: `0` فيديو، `1` نص، `2` صوت.

position_ids (`torch.Tensor` من الشكل `(seq_len, 3)`) : إحداثيات الدوران `(t, h, w)` لكل صف من التسلسل المُجمَّع.

video_indices (`torch.Tensor` من الشكل `(num_video_tokens,)`) : مواضع صفوف الفيديو في التسلسل المُجمَّع.

audio_indices (`torch.Tensor` من الشكل `(num_audio_tokens,)`) : مواضع صفوف الصوت في التسلسل المُجمَّع.

text_indices (`torch.Tensor` من الشكل `(num_text_tokens,)`) : مواضع صفوف النص في التسلسل المُجمَّع.

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

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

**يعيد:** `MiniMaxH3TransformerOutput` أو `tuple`

سرعة الفيديو ذات الشكل `(batch_size, num_video_tokens, in_channels * prod(patch_size))` وسرعة الصوت ذات الشكل `(batch_size, num_audio_tokens, audio_in_channels)`، بترتيب الصفوف في `video_indices` و`audio_indices`.

## MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

#### diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

```python
diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput(sample: Tensor, audio_sample: typing.Optional[torch.Tensor] = None)
```

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

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

sample (`torch.Tensor` من الشكل `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : تنبؤ سرعة الفيديو للصفوف المشار إليها بواسطة `video_indices`، وبالترتيب نفسه. تُعاد صفوف الشروط دون إخفاء — إخفاؤها قبل خطوة المجدول هي مسؤولية المستدعي.

audio_sample (`torch.Tensor` من الشكل `(batch_size, num_audio_tokens, audio_in_channels)`، القيمة الافتراضية `None`) : تنبؤ سرعة الصوت للصفوف المشار إليها بواسطة `audio_indices`، بنفس الترتيب. يملأ `forward` هذا الحقل دائمًا؛ ولا تكون قيمته الافتراضية `None` إلا حتى يمكن إعادة بناء المخرجات من قاموس بسيط لحقولها، وهو الطريقة التي تنتقل بها خطافات offload في accelerate كائن `BaseOutput` إلى جهاز الإدخال.

مخرجات [MiniMaxH3Transformer3DModel](/docs/diffusers/main/ar/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel).