# MiniMax-H3-Image

MiniMax-H3-Image هو نموذج صور من MiniMax مبني على [MiniMax-H3](./minimax_h3)، مخصص لتوليد الصور من النص وتحرير الصور المرجعية. يمكنك العثور على نقطة التفتيش في [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).

على غرار MiniMax-H3، يتم دمجه على شكل كتل [Modular Diffusers](../../modular_diffusers/overview) فقط: فـ [MiniMaxH3ImageBlocks](/docs/diffusers/main/ar/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) وخط أنابيبها [MiniMaxH3ImageModularPipeline](/docs/diffusers/main/ar/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) هما كل ما يتألف منه الدمج.

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

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

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

يبلغ حجم المحوّل ومشفّر النص حوالي 62 غيغابايت لكل منهما عند استخدام bfloat16، ولا يتسعان معًا على وحدة معالجة رسومية بسعة 80 غيغابايت، لذا تستخدم الأمثلة التفريغ التلقائي: حيث ينقل [ComponentsManager](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) كل مكوّن إلى المعجّل عندما يحتاج إليه كتل. ثم يبلغ ذروة استهلاك ذاكرة صورة بأبعاد 4736x3552 حوالي 65 غيغابايت.

من النص إلى الصورة:

```py
prompt = (
    "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
    "on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
    prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]
```

تعديل صورة مرجعية:

```py
from diffusers.utils import load_image

reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
    prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
    image=reference,
    height=4096,
    width=4096,
    generator=torch.Generator().manual_seed(1234),
    output="images",
)[0]
```

## المكوّنات

| مكوّن | فئة |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/main/ar/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/main/ar/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | مُقسِّم النص الخاصّ بمُشفِّر النص ومعالج `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/ar/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

المُشفِّر النصي هو نفسه الذي يستخدمه [MiniMax-H3](./minimax_h3). يحتفظ نقطة الفحص بنسخة خاصة بها حتى تكون المستودع مكتفياً ذاتياً؛ حيث يقوم Hub بإزالة التكرار للملفات المتطابقة عبر المستودعات، لذا لا تستهلك النسخة مساحة تخزين إضافية هناك.

## سير العمل

يتم تحديد سير العمل على مدخل `image`:

- يولّد **`text2image`** من `prompt`.
- يولّد **`image_conditioned`** من `prompt` وواحدة أو أكثر من الصور المرجعية المُمررة كـ`image`. تشير الأوامر النصية إليها بالترتيب على أنها `<Picture 1>`، `<Picture 2>`، وهكذا. تحافظ الصور المرجعية على أحجامها الخاصة: يُعاد ضبط حجم كل صورة فقط عندما يكون طول حافتها القصيرة خارج نطاق 1024 إلى 2048 بكسل، ولا يُعاد ضبط حجمها أبدًا إلى حجم الصورة المولّدة.

يُستخدم الأمر النصي كما هو دون أي قالب محادثة، وتعمل الأوصاف الطويلة والكاملة بشكل أفضل. عادةً ما يحدد أمر التعديل ما يجب الحفاظ عليه، ثم ما يجب تغييره، ثم يصف الصورة المستهدفة بشكل كامل.

## تحسين الأوامر

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) هو نموذج توسيع الأوامر من MiniMax: فهو يعيد صياغة الطلب القصير إلى نوع الوصف التفصيلي الذي يعمل معه نموذج الصور بأفضل أداء، ويوصي بنسبة أبعاد. تعمل كتل `diffusers/minimax-h3-image-pe-blocks` المخصصة عليه كخط أنابيب مستقل. تتطلب هذه الكتل `xgrammar`، وحوالي 18 غيغابايت من ذاكرة وحدة معالجة الرسوميات.

```py
import torch
from diffusers import ModularPipeline

enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")

state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")
```

مرّر الصور المرجعية كـ`image` لتوسيع تعليمات التحرير بدلاً من ذلك. ثم مرّر `prompt` إلى خط أنابيب الصور، مع `height` و`width` تتطابق مع `aspect_ratio`.

## حجم الصورة

`height` و`width` هما حجم الصورة المُعادَة، وقيمتاهما الافتراضية 2048. يولّد النموذج بدقة 4 ميغابكسل أو أكثر: فأي طلب أصغر يُنشأ على لوحة أكبر بنفس نسبة الأبعاد ثم يُعاد تحجيمه، لذا فإن طلبًا بمقاس 1024x1024 يكلف نفس تكلفة طلب بمقاس 2048x2028. يحدد `min_generation_area` ذلك الحد الأدنى بالبكسل؛ مرّر `1024` لتوليد الصورة دائمًا بالحجم المطلوب. وفي كلتا الحالتين، تُقرَّب أضلاع اللوحة إلى مضاعفات العدد 32.

توصي MiniMax بأبعاد 4096x4096 لنسبة 1:1، و4736x3552 لنسبة 4:3، و5024x3360 لنسبة 3:2، و5472x3072 لنسبة 16:9، و6272x2688 لنسبة 21:9، أو نفس الأبعاد مع تبديل الارتفاع والعرض لتنسيقات البورتريه.

## العينة

- تأخذ نقاط التفتيش عينات في 6 خطوات عبر `sample_sigmas` الخاصة بها، ولدى المحوّل رأس إخراج واحد لكل خطوة، لذا لا يوجد `num_inference_steps`.
- النموذج مُقطّر بالإرشاد، لذا لا يوجد مُوجِّه، أو `negative_prompt` أو `guidance_scale`.

## MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

#### diffusers.MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

```python
diffusers.MiniMaxH3ImageModularPipeline(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_image/modular_pipeline.py#L27)

خط أنابيب ModularPipeline لـ MiniMax-H3-Image: من النص إلى الصورة (`text2image`) وتعديل الصورة المرجعية (`image_conditioned`).

يعمل MiniMax-H3-Image على محوّل MiniMax-H3 دون صوت عبر تسلسل واحد مُجمَّع من صفوف النص وصفوف الصور المرجعية وصفوف الصورة المولَّدة، وهي إطار كامن واحد. وقد خُصِّصت نقطة التفتيش مرتين: فالتوجيه مُدمَج في الأوزان، لذا لا يوجد موجِّه، ولا `negative_prompt`، ولا `guidance_scale`، كما أنه يُعَيِّن على شبكة ثابتة من ست خطوات مع رأس مخرجات واحد من المحوّل لكل خطوة، لذا لا يوجد `num_inference_steps` أيضًا.

```py
import torch
from diffusers import ModularPipeline

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

## MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

#### diffusers.MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

```python
diffusers.MiniMaxH3ImageBlocks()
```

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

كتل خط أنابيب معيارية لنموذج MiniMax-H3-Image: `text2image`، وتعديل الصور المرجعية (`image_conditioned`) عند تمرير `image`.

سير العمل المدعومة:
- `text2image`: يتطلب `prompt`
- `image_conditioned`: يتطلب `prompt`، `image`

المكوّنات: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3Image`) scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3ImageTransformer2DModel`)

Configs: reference_min_short_edge (الافتراضي: 1024) reference_max_short_edge (الافتراضي: 2048) vision_min_short_edge (الافتراضي: 1024) vision_max_short_edge (الافتراضي: 1024) sample_sigmas (الافتراضي: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): شبكة العينة التي تم تقطير رؤوس المخرجات لكل خطوة في نقطة الحفظ عليها.

المدخلات: image (`Image | list`, *اختياري*): الصورة المرجعية للتحرير، أو قائمة بها. تشير الأوامر النصية إليها بالترتيب على أنها `<Picture 1>`، `<Picture 2>`، ... prompt (`str`): الأمر النصي الموجّه للتوليد، وهو نص واحد. vision_images (`list`, *اختياري*): الصور المرجعية المُعاد تحجيمها لمُشفّر النص. reference_images (`list`, *اختياري*): الصور المرجعية المُعاد تحجيمها لـ VAE. generator (`Generator`, *اختياري*): مولّد الطلب. يُسحب منه عيّنة لاحقة واحدة لكل مرجع. height (`int`): ارتفاع الصورة المُعاد إياها بالبكسل. width (`int`): عرض الصورة المُعاد إياها بالبكسل. min_generation_area (`int`, *اختياري*, القيمة الافتراضية 4194304): أصغر مساحة، بالبكسل، يتم توليد الصورة عليها. يتم توليد `height x width` أصغر على لوحة مُوسّعة إلى هذه المساحة ثم يُعاد تحجيمها إلى `height x width` بعد فك الترميز. مرّر 1024 لتوليد الصورة دائمًا بالحجم المطلوب. reference_latents (`list`, *اختياري*): الكمونيات الشرطية للصور المرجعية. شكلها هو المكان الذي تأتي منه هندسة كل مرجع. latents (`Tensor`): ضوضاء مُولّدة مسبقًا بشكل `(1, latent_channels, latent_height, latent_width)`، تُستخدم بدلاً من السحب. reference_noise (`list`, *اختياري*): ضوضاء مُولّدة مسبقًا للصور المرجعية، متجه واحد من شكل كل عنصر في `reference_latents`، تُستخدم بدلاً من السحوبات. **denoiser_input_fields (`None`, *اختياري*): الوصف الهيكلي للتسلسل المُجمّع الذي يقرأه المحوّل بالاسم: `token_tags`، `position_ids` ومتجهَا فهارس الصفوف. output_type (`str`, *اختياري*, القيمة الافتراضية pil): صيغة الإخراج: 'pil'، 'np'، 'pt'.

المخرجات: صور (`list`): الصور المولّدة.