# MiniMax-H3

  
    
  

يولّد MiniMax-H3 الفيديو وموسيقاه الخلفية معًا. يقوم محوّل واحد بإزالة الضوضاء من تسلسل واحد مُجمّع يحتوي على شروط النص، ووسائط الشروط، والقيم الكامنة المستهدفة للفيديو والصوت. لا يوجد مُصوِّت منفصل ولا مسار معالجة لاحقة للصوت: فالفيديو والصوت ينبثقان من حلقة إزالة الضوضاء نفسها.

يمكنك العثور على نقاط التفتيش الأصلية لنموذج MiniMax-H3 تحت منظمة [MiniMaxAI](https://huggingface.co/MiniMaxAI).

MiniMax-H3 is integrated as [Modular Diffusers](../../modular_diffusers/overview) blocks only, the way [Anima](./anima) is: the blocks and their [MiniMaxH3ModularPipeline](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline) are the whole integration, and there is no `DiffusionPipeline` half.

## تخطيط نقطة التفتيش

تم إصدار MiniMax-H3 على شكل قسمَي نقطة تفتيش يتشاركان كل المكوّنات باستثناء محوّل التحويل (transformer)، لذا يضع تحويل diffusers كلاهما في **مستودع واحد**:

| مجلد فرعي | سير العمل |
|---|---|
| `transformer/` | `t2va` (نص فقط)، `fl2va` (الإطار المفتاحي الأول و/أو الأخير) |
| `transformer_ref/` | `ref2va` (مزيج مرتب من مراجع الصور والفيديو والصوت) |

كل شيء عدا محوّل التحويل (transformer)، أي نموذج VAE للفيديو، ونموذج VAE للصوت، ومُشكِّل Qwen3-VL، ومُرمّز ومعالج هذا المُشكِّل، والمُجدوِلين، هو مشترك ويُخزَّن مرة واحدة.

المُشكِّل هو `Qwen3VLForConditionalGeneration`، وتقرأ MiniMax-H3 الحالة المخفية *غير المُعايَرة* بعد طبقة المُفكِّك الخمسين بدلاً من الطبقة الأخيرة، لذا يُستخدم نقطة الفحص الكاملة المُطلَقة مع عدم استخدام رأس نموذج اللغة الخاص بها.

جميع المهام الثلاث هي مسارات عمل ضمن [MiniMaxH3Blocks](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) الواحد، ويحمل المستودع ملف `modular_model_index.json` واحدًا يسمّي كل مكوّن مع مواصفات تحميله الخاصة. لخدمة مهمة واحدة، مرّر مسار العمل إلى `from_pretrained`: فهو يحتفظ فقط بمكوّنات ذلك المسار، لذا فإن توقيع خط الأنابيب (`pipe.doc`) يوثّق مدخلات تلك المهمة تحديدًا، ولا تُعلن إلا مكوّنات تلك المهمة، ويجلب `load_components` مجلداتها الفرعية تحديدًا — فخط أنابيب `t2va` / `fl2va` لا يلمس `transformer_ref/` أبدًا، وخط أنابيب `ref2va` لا يلمس `transformer/` أبدًا.

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
pipe.load_components(dtype=torch.bfloat16)
```

> [!TIP]
> `pipe.doc` يطبع ما تستقبله خط المعالجة أمامك وما تعيده — كل مدخل مع قيمته الافتراضية، والمكونات التي تتوقعها والمخرجات التي تنتجها. عند تقليصها إلى مسار عمل واحد، تصف تلك المهمة بدقة، وهو أسرع طريقة لمعرفة ما يحتاجه طلب قبل إرساله.

لإبقاء كل سير عمل متاح على خط أنابيب واحد بدلاً من ذلك، اترك حجة `workflow` فارغة: فسيقوم خط الأنابيب بعد ذلك باختيار سير العمل لكل استدعاء من المدخلات التي يُمرَّر بها.

```py
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
```

يمكن أن يستمر *التحميل* على شكل دورة عمل واحدة في كل مرة. تستدعي هذه الدعوة `transformer/` وكل المكوّنات المشتركة، والتي تخدم كلًا من `t2va` و`fl2va`:

```py
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
```

استدعاء `load_components()` عادي دون تحديد `workflow=` يجلب **كلا** قسمي التحويلي بحجم 61.7 جيجابايت، وهو ما يتيح لخط أنابيب واحد تقديم جميع سير العمل الثلاثة دون الحاجة إلى استدعاء تحميل آخر. اقرنه مع [ComponentsManager](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) والتفريغ التلقائي: تبقى الأوزان في ذاكرة الوصول العشوائي للمضيف، وينقل المدير إلى المعالج التسريعي فقط ما يحتاجه كل خطوة، لذا عندما يطلب مُزيل الضوضاء `ref2va` الجهاز، تقوم الاستراتيجية بتفريغ ما يكفي من العناصر لتحرير مساحة كافية. راجع [الذاكرة](#memory) للوصفات.

## جدولان زمنيان

تتدرّج كامنات الفيديو والصوت على جدولين مختلفين داخل استدعاء واحد لتحوّل (transformer) في كل خطوة، ولهذا تتوقع الكتل وجود مثيلين من [MiniMaxH3Scheduler](/docs/diffusers/main/ar/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler): `scheduler` لكامنات الفيديو (`shift=12.0` في نقاط التفتيش المنشورة) و`audio_scheduler` لكامنات الصوت (`shift=3.0`).

تخضع كلتا تقسيمات الترانسفورمر للتقطير الموجّه، لذا ينطبق هذا على كل سير عمل: فالتوجيه مدمج في الأوزان، ولا يوجد موجّه، ولا `negative_prompt` ولا `guidance_scale`، وتُنفَّذ كل خطوة بتمريرة أمامية واحدة بالضبط.

## قيود التوليد

- **24 إطارًا في الثانية، من 5 إلى 15 ثانية.** يتم تقريب `num_frames` إلى أقرب قيمة من الشكل `17 * n + 5` يمكن لنموذج VAE الخاص بالفيديو فك ترميزها، ويجب أن تبقى المدة الناتجة ضمن هذه النطاق.
- **حافة قصيرة بطول 768 بكسل.** القيم الافتراضية لـ `height` و`width` هي أبعاد MiniMax-H3 الخاصة بالنسبة لأبعاد الإطار المفتاحي الأول (أو 16:9 في حال عدم وجوده)، ويجب أن تكون مضاعفات للرقم 32.
- **مولّد واحد، ثلاث عمليات سحب.** يقوم الطلب بسحب ضوضاء إطار المفتاح أو شرط المرجع أولاً، ثم ضوضاء الفيديو، ثم ضوضاء الصوت، جميعها من `generator` المُمرَّر إليه، لذا فإن تشغيلين من نفس حالة المولّد يعيدان نفس الفيديو والموسيقى التصويرية. تمرير `latents` أو `audio_latents` يستبدل عملية السحب المقابلة.
- **يُحسب `num_inference_steps` نقاط شبكة سيجما**، بما في ذلك `0` النهائي، لذا فإنه يقلل من تقييم النموذج مرة واحدة.

## الذاكرة

يبلغ حجم المحوّل وحده 61.7 غيغابايت في bfloat16، بينما يضيف مشروط Qwen3-VL 62.1 غيغابايت إضافية، لذا تعتمد وصفة التحميل على العتاد. تُعدّ اللوحات الأصغر حجماً أكبر رافعة سرعة في جميع الإعدادات: لا يتعين أن تكون `height` و`width` مضاعفات لـ 32 فحسب، بل إن 960x544 يعمل أسرع بنحو 2.3 مرة لكل خطوة مقارنةً بحجم التدريب 1344x768.

على بطاقة واحدة بسعة 80 جيجابايت، سجّل المكونات في [ComponentsManager](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) ودعه ينقلها إلى المعالج التسريعي وخارجه:

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB")  # or "mps", "xpu", "cpu"
pipe.transformer.set_attention_backend("_flash_3_hub")  # Hopper, roughly 3x faster; kernels fetched from the Hub
```

على بطاقة استهلاكية (24 إلى 32 جيجابايت)، قم بتكميم المكوّنين الكبيرين إلى int8 أثناء تحميلهما، وانقل كتل المحوّل من ذاكرة المعالج المركزية. كل ما يلي يستخدم محمّلات مدعومة فقط، دون أي تعديلات، ويعمل مباشرةً من نقطة التفتيش bfloat16:

```py
import torch
from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline, TorchAoConfig
from diffusers.hooks import apply_group_offloading
from transformers import Qwen3VLForConditionalGeneration
from transformers import TorchAoConfig as TransformersTorchAoConfig
from torchao.quantization import Int8WeightOnlyConfig

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.update_components(
    transformer=MiniMaxH3Transformer3DModel.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16,
        quantization_config=TorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=[
                "proj_in", "audio_proj_in", "context_embedder", "time_embedder", "time_proj",
                "token_refiner", "norm_out", "proj_out", "audio_proj_out",
            ],
        ),
        low_cpu_mem_usage=False,
    ),
    text_encoder=Qwen3VLForConditionalGeneration.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16,
        quantization_config=TransformersTorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=["model.visual", "model.language_model.embed_tokens", "model.language_model.norm", "lm_head"],
        ),
    ),
)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

# version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd
# path the quantized tensors cannot serve.
pipe.transformer.requires_grad_(False)
pipe.text_encoder.requires_grad_(False)

offload = dict(onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), use_stream=True)
pipe.transformer.enable_group_offload(offload_type="block_level", num_blocks_per_group=1, **offload)
apply_group_offloading(pipe.text_encoder.model, offload_type="leaf_level", **offload)
pipe.vae.to("cuda")  # or "mps", "xpu", "cpu"
pipe.audio_vae.to("cuda")
```

على ذاكرة 12 إلى 16 جيجابايت، تعمل الوصفة نفسها مع تفريغ مجموعة VAE الخاصة بالفيديو أيضًا (`offload_type="leaf_level"`، بدون تدفق) ولوحة صغيرة مثل 960x544. توقع أن تقيم الأوزان في ذاكرة RAM على المضيف: حوالي 75 جيجابايت منها عند int8.

مع بطاقتين لا حاجة إلى تفريغ أي شيء: قسّم خط الأنابيب إلى نصفين وضع كل نصف على جهازه الخاص.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

workflow = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3").blocks.get_workflow("t2va")

text_manager = ComponentsManager()
text_manager.enable_auto_cpu_offload(device="cuda:1")
conditioner = workflow.sub_blocks.pop("text_encoder").init_pipeline(
    "MiniMaxAI/MiniMax-H3", components_manager=text_manager
)
conditioner.load_components(dtype=torch.bfloat16)

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda:0")
rest = workflow.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager)
rest.load_components(dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
state = conditioner(prompt=prompt)
results = rest(
    state=state,
    num_frames=124,
    generator=torch.Generator().manual_seed(42),
    output=["videos", "audio", "sampling_rate"],
)
```

يعمل بطاقان بسعة 80 جيجابايت على كامل bfloat16 بهذه الطريقة: حيث يتسع كل نصف على بطاقته الخاصة، فلا يُعاد أي شيء إلى ذاكرة المضيف بعد أن يصبح مقيمًا. وتقوم بطاقتان بسعة 48 جيجابايت بالشيء نفسه باستخدام تحميل int8 المذكور أعلاه على كلا المكوّنين.

## النص والإطارات المفتاحية

يتناول [MiniMaxH3Blocks](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) توليد الفيديو والصوت من النص، والشروط بناءً على الإطارات الرئيسية. يمكن أن يكون الإطار الرئيسي هو الإطار الذي يبدأ منه الفيديو (`image`)، أو الإطار الذي ينتهي عليه (`last_image`)، أو كلاهما معًا.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import load_image
from diffusers.utils.export_utils import encode_video

# 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are
# registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory).
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
# `output=` returns exactly the named outputs instead of the whole pipeline state.
outputs = ["videos", "audio", "sampling_rate"]

# Text to video + audio.
results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

# First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_fl2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)
```

يتم توليد الفيديو والصوت معًا ويخرجان من الاستدعاء كمخرجات منفصلة، `videos` و`audio`، إلى جانب `sampling_rate` الذي يحمله المسار الصوتي؛ ويُترك دمجهما في ملف واحد على المستدعي، مثلًا باستخدام [encode_video()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.encode_video).

## مرجع شامل

يعتمد سير عمل `ref2va` على قائمة مرتبة من المراجع: ما يصل إلى 9 صور، و3 مقاطع فيديو، و3 مقاطع صوتية، أي 12 مرجعًا إجمالًا. الترتيب هنا دلالي؛ فهو يحدد المراجع في عرض الموجّه (`"<Picture 1>"`، `"<Audio 1>"`، `"<Video 1>"`)، كما أنه يُقدّم الساعة الدوّارة المشتركة للصوت/الفيديو، لذا فإن إعادة ترتيب المراجع نفسها تُشكّل طلبًا مختلفًا.

على عكس الإطارات المفتاحية أعلاه، لا تربط المراجع الهندسة المولّدة: فهي تُرمَّز عند دقتها الخاصة، بينما يكون الإطار المستهدف افتراضيًا بنسبة 16:9 الخاصة بـ MiniMax-H3.

توجد فئة مرجعية واحدة لكل نمط، حيث تحتفظ كل فئة بوسائط في الذاكرة والمعدل الذي تنقل به الوسائط:

| مرجع | وسائط | السرعة التي يعلن عنها |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames`، و`audio` لموسيقاه | `fps`، بقيمة افتراضية تبلغ 24.0 الخاصة بـ MiniMax-H3، و`sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/main/ar/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`، حيث يكون الافتراضي هو |

المعدلات هي الأساس الذي يُعاد أخذ عينات كل شيء منه: تُعاد أخذ عينات الإطارات إلى معدل 24 إطارًا في الثانية الخاص بـ MiniMax-H3 نفسه عن طريق حذف إطارات كاملة وتكرارها، وتُعاد أخذ عينات الموجة الصوتية إلى معدل أخذ العينات الخاص بوحدة VAE الصوتية. يمرّ المحتوى الإعلامي بمعدلات MiniMax-H3 الخاصة به دون أي تعديل، لذا لا يتعين على البيانات المنتَجة بمعدل آخر سوى الإشارة إلى ذلك.

يُبنى المرجع بأحد طريقتين: إما عبر فك الترميز من ملف وسائط باستخدام طريقة الفئة `from_file`، أو عبر بنائه مباشرةً من وسائط يحتفظ بها الطلب بالفعل في الذاكرة — وهو الأسلوب الذي تُغذّى به جولة سابقة في العملية (انظر [الجولة كمرجع](#a-generation-as-a-reference)).

لا تفتح الكتل ملف وسائط أبدًا — فك ترميز المسار هو مسؤولية المستدعي، كما هو الحال في كل مكان آخر في المكتبة. يقوم كل فئة مرجعية بذلك من خلال طريقة الفئة `from_file`، التي تقبل مسارًا أو عنوان URL (فيديو وصوت عبر [PyAV](https://github.com/PyAV-Org/PyAV)) وتعيد مرجعًا يحمل المعدلات التي يبلغ عنها الحاوية — يجلب الفيديو معدل إطاراته وموسيقاه المصاحبة معه. يُفضَّل استخدام `from_file` على [load_video()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.load_video)، الذي يتخلّى عن معدل الإطارات: المرجع المُنشأ من إطارات فُقد معدلها الحقيقي يُشترط على سرعة خاطئة، ولا يثير أي شيء خطأً.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import (
    MiniMaxH3AudioReference,
    MiniMaxH3ImageReference,
    MiniMaxH3VideoReference,
)
from diffusers.utils import load_video
from diffusers.utils.export_utils import encode_video

# `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
# checkpoint partition, and the manager moves each component on and off the accelerator in turn.
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

subject = MiniMaxH3ImageReference.from_file(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)

# Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
results = pipe(
    prompt="The character speaks in time with the reference recording, natural lip movement",
    references=[
        subject,
        MiniMaxH3VideoReference.from_file(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
        ),
        MiniMaxH3AudioReference.from_file("voice.wav"),
    ],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

# Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
motion = load_video("motion_ref.mp4")
results = pipe(
    prompt="The subject walks toward camera, matching the reference video's shot rhythm",
    references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_ref2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)
```

`num_frames` مطلوب لـ `ref2va`. ولتوليد فيديو بطول يطابق بالضبط مقطع الصوت المرجعي، احسبه من المقطع — `round(samples / sample_rate * 24)` — وسيُقرَّب إلى أقرب قيمة من الشكل `17 * n + 5` التي يمكن لـ VAE الخاص بالفيديو فك ترميزها؛ ويجب أن يبقى المدة الناتجة ضمن النطاق من 5 إلى 15 ثانية الذي تولده MiniMax-H3.

### الجيل كمرجع

بما أن سير العمل يتشارك خط أنابيب واحدًا، يمكن تمرير توليد `t2va` مباشرةً كمرجع `ref2va` — وقد صُمم منشئ الذاكرة لهذا التسليم تحديدًا. الوسائط المولّدة تكون بالفعل بمعدلات MiniMax-H3 الخاصة (الإطارات بمعدل 24 إطارًا في الثانية، والموسيقى التصويرية بمعدل عينة VAE الصوتي)، لذا لا يحتاج المرجع إلى أي معاملات معدل، ولا يتم إعادة الترميز عبر حاوية خاسرة في الطريق:

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

# The full pipeline holds every workflow and picks one per call from the inputs. Loading without a
# `workflow=` brings both transformer partitions in one call, so the `ref2va` request that follows the
# `t2va` generation needs no further loading.
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

results = pipe(
    prompt="An astronaut hiking through the mountains, humming a tune",
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

reference = MiniMaxH3VideoReference(
    frames=results["videos"][0],
    audio=results["audio"][0],
    sample_rate=results["sampling_rate"],
)
results = pipe(
    prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
    references=[reference],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)
```

## MiniMaxH3ModularPipeline[[diffusers.MiniMaxH3ModularPipeline]]

#### diffusers.MiniMaxH3ModularPipeline[[diffusers.MiniMaxH3ModularPipeline]]

```python
diffusers.MiniMaxH3ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py#L150)

خط أنابيب ModularPipeline لتوليد الفيديو والصوت معًا باستخدام MiniMax-H3: مسارات العمل `t2va` (نص فقط) و`fl2va` (الإطار المفتاحي الأول و/أو الأخير) مقابل تقسيم نقطة التفتيش `transformer/`، ومسار العمل `ref2va` (مرجع شامل) مقابل `transformer_ref/`. يحتوي مستودع واحد على كلا التقسيمين، وعند اختيار مسار عمل يتم تحميل

خاص:

```py
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
```

يقوم MiniMax-H3 بإزالة الضوضاء من **تسلسل واحد مُجمَّع** يحتوي في آنٍ واحد على شروط النص، ومتغيرات شروط الإطارات الرئيسية، ومتغيرات الصوت، ومتغيرات الفيديو، ولهذا السبب تمرر الكتل تخطيط صف بدلاً من متجهات لكل نمط، ولهذا السبب أيضاً يحمل خط الأنابيب مجدولين اثنين (`shift = 12.0` للفيديو، `shift = 3.0` للصوت) يتم تشغيلهما داخل استدعاء واحد لتحويلة.

النقطة المحفوظة مُقطّرة بتوجيه: التوجيه مُدمج في الأوزان، لذا لا يوجد موجّه، ولا `negative_prompt` ولا `guidance_scale`، وكل خطوة تُنفّذ تمريرة أمامية واحدة بالضبط.

MiniMax-H3 هو معياري فقط: هذا المسار ومكوناته يمثلان التكامل الكامل، ولا يوجد جزء من `DiffusionPipeline`. يحمل هذا الوحدة حقائق النموذج التي تعتمد عليها كل المكونات — الهندسة المشتقة من الإعدادات كخصائص، وحسابات اللوحة وعدد الإطارات كدوال — بينما تقيم عقود التكييف والتشفيش والضوضاء على المكونات نفسها.

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components(dtype=torch.bfloat16)
```

## MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

#### diffusers.MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

```python
diffusers.MiniMaxH3Blocks()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py#L659)

كتل خط أنابيب Auto Modular لتوليد الفيديو والصوت معًا باستخدام MiniMax-H3: مسارات العمل `t2va` (نص فقط)، و`fl2va` (إطار رئيسي أولي و/أو أخير)، و`ref2va` (مرجع شامل)، يتم اختيارها بناءً على مدخلات `references` والإطارات الرئيسية. في حال عدم تحديد `workflow=`، فإن تحميل المكونات يجلب **كلا** قسمي التحويلي بحجم 61.7 جيجابايت — مرّر أحد القسمين لتحميل ما يحتاجه المهمة فقط.

سير العمل المدعومة:
- `t2va`: يتطلب `prompt`
- `fl2va`: يتطلب `prompt` أو `image` أو `prompt` و`last_image`
- `ref2va`: يتطلب `prompt`، `references`

المكوّنات: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3`) audio_vae (`AutoencoderKLMiniMaxH3Audio`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer_ref (`MiniMaxH3Transformer3DModel`) transformer (`MiniMaxH3Transformer3DModel`) video_processor (`VideoProcessor`)

الإعدادات: canvas_short_edge (الافتراضي: 768) canvas_max_pixels (الافتراضي: 1032192) reference_image_short_edge (الافتراضي: 2048)

المُدخلات: references (`list`، *اختياري*): المراجع التي يُشترط عليها، **بترتيب القراءة الذي يجب أن يتبعه النموذج**: فترتيبها هو ما يسمّيها في عرض المُوجِّه ويضعها على الساعة الدوّارة المشتركة، وبالتالي فإنّ ترتيبًا مختلفًا يعني طلبًا مختلفًا. فئة بيانات واحدة لكل نمط، جميعها تحتفظ بوسائط في الذاكرة — `MiniMaxH3ImageReference` (بحدٍّ أقصى 9)، أو `MiniMaxH3VideoReference` بمعدل `fps` خاص بها (بحدٍّ أقصى 3، حيث يُشترط أيضًا على المسار الصوتي `audio` الخاص بها)، أو `MiniMaxH3AudioReference` بمعدل `sample_rate` خاص بها (بحدٍّ أقصى 3) — بحدٍّ أقصى 12 مرجعًا إجمالًا، ولا يمكن أن تكون مراجع الصوت هي الوحيدة. لا تفتح هذه الكتل ملف وسائط أبدًا: فكّ الترميز يتم عبر طريقة الفئة `from_file` لكل فئة، والتي تجلب المعدلات معها. height (`int`، *اختياري*): ارتفاع الفيديو المولَّد بالبكسل، ويجب أن يكون مضاعفًا للعدد 32. width (`int`، *اختياري*): عرض الفيديو المولَّد بالبكسل، ويجب أن يكون مضاعفًا للعدد 32. num_frames (`int`، *اختياري*): عدد الإطارات التي سيتم توليدها، بمعدل ثابت 24 fps. يُقرَّب إلى أقرب قيمة أعلى من الشكل `17 * n + 5` التي يمكن لـ VAE الخاص بالفيديو فكّ ترميزها؛ ويجب أن يبقى المدة الناتجة بين 5 و15 ثانية. لتوليد فيديو بطول المسار الصوتي المرجعي، مرّر `round(samples / sample_rate * 24)`. image (`Image`، *اختياري*): الإطار الرئيسي الذي يبدأ منه الفيديو. يتم *تمديده* على اللوحة المستهدفة، والتي تُشتق افتراضيًا من نسبة أبعاده الخاصة. last_image (`Image`، *اختياري*): الإطار الرئيسي الذي ينتهي عليه الفيديو. يمكن تمريره بمفرده لتوليد *حتى* إطار. عند دمجه مع `image`، يكون هو المتبوع من الاثنين ويُقصّ بطريقة الغطاء (cover-crop) على اللوحة. prompt (`str`): المُوجِّه الذي يوجّه عملية التوليد، وهو نص واحد. normalized_references (`list`، *اختياري*): المراجع المُطبَّعة بواسطة خطوة الإعداد، بترتيب مُجمَّع. keyframes (`list`، *اختياري*): الإطارات الرئيسية الموضوعة على اللوحة المستهدفة، بترتيب مُجمَّع. condition_latents (`list`، *اختياري*): متغيرات الحالة (latents) المشفَّرة للشروط الخاصة بالفيديو، واحدة لكل مرجع صورة وفيديو بترتيب مُجمَّع. شكلها هو مصدر هندسة كل كتلة مراجع. audio_condition_latents (`list`، *اختياري*): صفوف الشروط الصوتية المشفَّرة، واحدة لكل مرجع يحمل صوتًا بترتيب مُجمَّع. generator (`Generator`، *اختياري*): المولّد الخاص بالطلب. يُسحب ضجيج الشروط منه أولًا، سحب واحد لكل شرط، قبل ضجيج الصفوف المولَّدة. latents (`Tensor`): ضجيج فيديو مُولَّد مسبقًا بشكل `(1, 24, num_latent_frames, latent_height, latent_width)`، يُستخدم بدلًا من السحب. audio_latents (`Tensor`): ضجيج صوت مُولَّد مسبقًا بشكل `(2, 32, num_audio_latents)`. num_inference_steps (`int`، *اختياري*، الافتراضي 50): عدد خطوات إزالة الضجيج. **denoiser_input_fields (`None`، *اختياري*): الوصف الهيكلي للتسلسل المُجمَّع الذي يقرأه المحوّل (transformer) بالاسم: `token_tags`، `position_ids` ومصفوفات فهارس الصفوف الثلاث. attention_kwargs (`dict`، *اختياري*): معاملات إضافية لمعالجات الانتباه. keyframe_anchors (`tuple`، *اختياري*، الافتراضي ()): أي طرف من الفيديو يُثبَّت عليه كل إطار رئيسي، بترتيب مُجمَّع. output_type (`str`، *اختياري*، الافتراضي pil): صيغة الإخراج: 'pil' أو 'np' أو 'pt'.

المخرجات: مقاطع فيديو (`list`): الفيديو المولّد. الصوت (`Tensor`): المسار الصوتي المولّد، ذو الشكل `(1, 2, num_samples)`. معدل العينة (`int`): معدل عينة المسار الصوتي المولّد بالهرتز.

## MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor])
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L82)

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

image (`PIL.Image.Image` أو `np.ndarray` أو `torch.Tensor`) : الصورة المرجعية: صورة، مصفوفة بأبعاد `(height, width, 3)` أو متجه بأبعاد `(3, height, width)`، من نوع `uint8` أو أرقام عشرية ضمن المدى `[0, 1]`. لا ترتبط هذه الصورة أبدًا بالهندسة المولّدة — إذ يتم ترميزها على حافة قصيرة خاصة بها، تبلغ 2048 للنقطة المرجعية المُصدَرة، بغض النظر عن حجم اللوحة الذي تولّده الطلبات.

مرجع للموضوع أو الأسلوب أو المشهد: بحد أقصى 9 لكل طلب.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference.from_file]]

```python
from_file(media)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L98)

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

media (`str` أو `os.PathLike`) : مسار الصورة أو عنوانها.

حمّل ملف صورة إلى `MiniMaxH3ImageReference` من خلال [load_image()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.load_image).

## MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference(frames: typing.Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor], fps: float | None = None, audio: typing.Optional[torch.Tensor] = None, sample_rate: int | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L110)

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

frames (`list[PIL.Image.Image]` أو `np.ndarray` أو `torch.Tensor`) : الإطارات المرجعية: قائمة من الصور، مصفوفة `(num_frames, height, width, 3)` أو متجه `(num_frames, 3, height, width)`، `uint8` أو أرقام عشرية ضمن `[0, 1]`.

fps (`float`, *اختياري*, القيمة الافتراضية 24.0) : معدل الإطارات الذي تحمله `frames`، وهو ما يحدد موضع كتل الرؤية الخاصة بالمرجع على شبكة 2 إطار/ثانية الخاصة بمشروط التوليد. الساعة الداخلية الخاصة بـ MiniMax-H3 هي 24 إطار/ثانية، لذا يتم إعادة أخذ عينات أي معدل آخر عليها عن طريق حذف إطارات كاملة وتكرارها — مما يجعل هذا الحقل هو ما يجب ضبطه بشكل صحيح عندما تكون الإطارات مستخرجة من ملف.

audio (`torch.Tensor` من الشكل `(channels, num_samples)`، *اختياري*) : موسيقى هذا الفيديو، أحادية أو ستيريو، مشروطة كمرجع خاص بها وليس كمرجع لمرجع آخر. عند إهماله، يُشترط المرجع على الحركة فقط.

sample_rate (`int`, *اختياري*) : المعدل الذي تنقل به `audio` عيناتها. إذا حُذف، فهو معدل VAE الصوتي نفسه، مما يترك العينات دون تغيير؛ أما أي معدل آخر فيُعاد أخذ عينات الصوت عليه.

مرجع للحركة والكاميرا: بحد أقصى 3 لكل طلب، مشروطًا معًا مع موسيقاه الخاصة.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference.from_file]]

```python
from_file(media)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L146)

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

media (`str` أو `os.PathLike`) : مسار أو عنوان URL للفيديو.

**يعيد:** `MiniMaxH3VideoReference`

الإطارات من نوع `uint8` بأبعاد `(num_frames, height, width, 3)` بمعدل الإطارات الذي يبلّغ عنه الحاوية، مع حملها لمسار الصوت ومعدل عينات ذلك المسار عندما يحتوي على تدفق صوتي.

فكّ ترميز ملف فيديو إلى `MiniMaxH3VideoReference`، عند الدقة ومعدل الإطارات والموسيقى المصاحبة التي يحملها.

تستقر المعدّلات على المرجع، وهذا هو الهدف من فك الترميز بهذه الطريقة بدلاً من استخدام [load_video()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.load_video): يعيد نموذج MiniMax-H3 أخذ عينات من المرجع بمعدل 24 إطاراً في الثانية، لذا فإن معدل الإطارات المفقود أثناء الإدخال يعني أن الطلب مشروط بسرعة خاطئة، دون وجود أي آلية للتنبيه بذلك. يتم تصحيح الحاوية التي تحتوي على بيانات وصفية خاطئة عن طريق تجاوز قيمة `fps` أو `sample_rate` على المرجع المُعاد.

يتطلب [PyAV](https://github.com/PyAV-Org/PyAV).

## MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference(audio: Tensor, sample_rate: int | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L172)

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

audio (`torch.Tensor` من الشكل `(channels, num_samples)`) : الموجة المرجعية، أحادية أو ستيريو.

sample_rate (`int`, *اختياري*) : المعدل الذي تنقل به `audio` عيناتها. إذا حُذف، فهو معدل VAE الصوتي نفسه، مما يترك العينات دون تغيير؛ أما أي معدل آخر فيُعاد أخذ عينات الصوت عليه.

مرجع صوتي أو موسيقي: بحد أقصى 3 لكل طلب، ولا يُستخدم أبدًا بمفرده — إذ يجب أن يُقرن المرجع الصوتي بمرجع صورة أو فيديو واحد على الأقل. لا يصل هذا المرجع إلى المُشكِّل (conditioner) بل يُرمَّز بواسطة VAE الصوتي وحده.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference.from_file]]

```python
from_file(media)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L191)

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

media (`str` أو `os.PathLike`) : مسار أو عنوان URL للملف الصوتي، أو لفيديو يُستخرج منه المسار الصوتي.

**يعيد:** `MiniMaxH3AudioReference`

موجة الصوت `(channels, num_samples)` من نوع float32 عند معدل العينة الذي يبلّغ عنه الحاوية.

فكّ ترميز ملف صوتي إلى `MiniMaxH3AudioReference`، بمعدل العينة الذي يحمله.

يتطلب [PyAV](https://github.com/PyAV-Org/PyAV).