# P-H3-Image

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

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

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

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, generator=torch.Generator().manual_seed(3), output="images")[0]
edited = pipe(prompt="let it snow on the street", image=image, output="images")[0]
```

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

## المكوّنات

| مكوّن | فئة |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/main/ar/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/main/ar/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/main/ar/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | مُقسِّم النص الخاصّ بمُشفِّر النص، ومعالج `Qwen3VLProcessor` مع مُعالج الصور الخاصّ بـ MiniMax-H3 |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/ar/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (المبني على Qwen3.5-9B) ومعالجه |

## سير العمل

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

- يولّد **`text2image`** من `prompt`. القيم الافتراضية لـ`height` و`width` هي 2912، وتُقرَّب إلى مضاعفات 32. يعمل النموذج بشكل أفضل عند 8 ميغابكسل، على سبيل المثال 2912x2912 أو 3872x2176 أو 2176x3872.
- يُعدّل **`image_conditioned`** صورة `image` بناءً على التعليمات الواردة في `prompt`، ويعمل بشكل أفضل عند دقة 4 أو 8 ميغابكسل. يتم ترميز الصورة بحجم يقارب `vision_pixels` (ميغابكسل واحد) لمُرمّز النص، وبحجمها الفعلي لمُرمّز VAE، مع تكبيرها إلى `reference_min_pixels` (ميغابكسل واحد) أو تصغيرها إلى `reference_max_pixels` (ثمانية ميغابكسل) إذا كانت خارج هذا النطاق. في حال عدم تحديد `height` و`width`، يتم توليد التعديل بحجم الصورة الأولى، مع تكبيرها إلى `canvas_min_pixels` (أربعة ميغابكسل) إذا كانت أصغر من ذلك. أما عند تمرير قيم `height` و`width`، فتُقرَّب إلى مضاعفات العدد 32، مما يغيّر حجم اللوحة دون تغيير حجم الصور. يمكن أن يكون `image` أيضاً قائمة تضم حتى 8 صور: تُعدَّل الصورة الأولى بينما تُستخدم البقية كمرجع، على سبيل المثال `<Picture 2>`، `<Picture 3>` وهكذا.

## توسيع عينات المحفّز

يُصمَّم P-H3-Image لعرض الأوامر الكاملة بدلاً من الطلبات المختصرة، لذا يشغّل خط الأنابيب مُوسِّع الأوامر أولاً على كل طلب. يفكّر في الطلب ثم يكتب الأمر: أمر نص إلى صورة مفصّل يناسب نسبة الأبعاد لـ`height` و`width`، أو، عند التحرير، ملخص لما يجب الحفاظ عليه وما يجب تغييره في الصور. يعود الأمر الذي كتبه كإخراج `prompt`.

```py
out = pipe(prompt=prompt, height=3360, width=2496, output=["images", "prompt"])
print(out["prompt"])
```

`max_new_tokens` يحدد الحد الأقصى لعدد الرموز الخاصة بالاستدلال والموجّه معًا، حيث يكون الافتراضي 1024 رمزًا لتحويل النص إلى صورة و1536 رمزًا للتعديلات. إذا لم يُرجِع مُوسّع الصورة موجّهًا قابلًا للاستخدام، ترفع خط أنابيب المعالجة خطأً بدلاً من عرض الصورة.

لإخراج `prompt` كما هو معطى، أزل الخطوة من الكتل. الكتلة المُزالة تعمل أيضاً بشكل مستقل، على سبيل المثال لعرض الأمر للمستخدم قبل إخراجها:

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

blocks = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image").blocks
upsampler_block = blocks.sub_blocks.pop("prompt_upsampler")

upsampler = upsampler_block.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
upsampler.load_components(dtype=torch.bfloat16)
upsampled = upsampler(prompt=prompt, height=3360, width=2496, output="prompt")

pipe = blocks.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
image = pipe(prompt=upsampled, height=3360, width=2496, output="images")[0]
```

بدون هذه الخطوة، يُرمَّز موجه التحرير بصيغته التي يكتبها المُوسِّع، سواء كان موجزًا من ستة أقسام أو فقرة تبدأ بـ `Edit <Picture 1>.`، كما هو؛ أما أي تعليمات أخرى فتُضاف إليها تلك البادئة.

## العينة

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

## PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

#### diffusers.PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

```python
diffusers.PH3ImageModularPipeline(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/p_h3_image/modular_pipeline.py#L22)

خط أنابيب ModularPipeline لنموذج الصور P-H3-Image، وهو نموذج صور مبني على MiniMax-H3، لتوليد الصور من النص (`text2image`) والتحرير القائم على التعليمات (`image_conditioned`).

الصورة إطار كامن واحد، تم تخليصه من الضوضاء في تسلسل واحد مدمج يحتوي على كامنين صوتيين يتم تجاهلهما.

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

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

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, output="images")[0]
```

## PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

#### diffusers.PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

```python
diffusers.PH3ImageBlocks()
```

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

كتل خط أنابيب معيارية لـ P-H3-Image: `text2image`، والتحرير القائم على التعليمات (`image_conditioned`) عند تمرير `image`. يمر `prompt` أولاً عبر مُوسّع المُوجِّه؛ احذف خطوة `prompt_upsampler` لعرضه كما هو.

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

المكوّنات: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): مُوسّع المُوجّه. prompt_upsampler_processor (`AutoProcessor`): مُعالِجه. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

الإعدادات: reference_min_pixels (الافتراضي: 1048576) reference_max_pixels (الافتراضي: 8388608) canvas_min_pixels (الافتراضي:
4194304) vision_pixels (الافتراضي: 1000000) sample_sigmas (الافتراضي: [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]): شبكة أخذ العينات الخاصة بالنقطة المحفوظة، تُستخدم عند عدم تمرير `sigmas`.

المدخلات: image (`Image | list`, *اختياري*): الصورة التي سيتم تحريرها، أو قائمة تحتوي على 8 صور كحد أقصى: تُحرَّر الصورة الأولى، بينما تكون البقية مراجع. height (`int`, *اختياري*): ارتفاع الصورة المولَّدة بالبكسل، ويُقرَّب إلى مضاعف لـ 32. القيمة الافتراضية هي 2912 لـ `text2image`، والتي تعمل بشكل أفضل عند 8 ميغابكسل. أما التحرير فيعتمد افتراضيًا على حجم الصورة الأولى، بحد أدنى `canvas_min_pixels`، ويعمل بشكل أفضل عند 4 أو 8 ميغابكسل. width (`int`, *اختياري*): عرض الصورة المولَّدة بالبكسل، ويُقرَّب إلى مضاعف لـ 32. القيمة الافتراضية هي 2912 لـ `text2image`، والتي تعمل بشكل أفضل عند 8 ميغابكسل. أما التحرير فيعتمد افتراضيًا على حجم الصورة الأولى، بحد أدنى `canvas_min_pixels`، ويعمل بشكل أفضل عند 4 أو 8 ميغابكسل. prompt (`str`): الأمر النصي، أو تعليمات التحرير عند تمرير `image`. نص واحد. max_new_tokens (`int`, *اختياري*, القيمة الافتراضية 1536 أو 1024، حسب سير العمل): الحد الأقصى لعدد الرموز التي قد يولِّدها مُوسِّع الصورة، بما في ذلك رموز الاستدلال. vision_images (`list`, *اختياري*): صور التحرير المُعاد ضبط حجمها لمُشفِّر النص، مع وضع الصورة المراد تحريرها في المقدمة. reference_images (`list`, *اختياري*): صور التحرير المُعاد ضبط حجمها لـ VAE، مع وضع الصورة المراد تحريرها في المقدمة. condition_latents (`list`, *اختياري*): الكمونيات الشرطية لصور التحرير. تُحدِّد أشكالها هندسة كتل المراجع. generator (`Generator`, *اختياري*): مولِّد الطلب. يُستخرج الضوضاء الشرطية منه أولًا، بسحب واحد لكل شرط، قبل ضوضاء الصفوف المولَّدة. latents (`Tensor`): ضوضاء صورة مُولَّدة مسبقًا بشكل `(1, latent_channels, 1, latent_height, latent_width)`، تُستخدم بدلًا من السحب. sigmas (`list`, *اختياري*): شبكة أخذ عينات مخصصة، متناقصة بشكل صارم وتنتهي عند 0. القيمة الافتراضية هي `sample_sigmas` من نقطة التفتيش. **denoiser_input_fields (`None`, *اختياري*): الوصف الهيكلي للتسلسل المُجمَّع الذي يقرأه المحوِّل بالاسم: `token_tags` و`position_ids` ومصفوفات فهارس الصفوف الثلاث. attention_kwargs (`dict`, *اختياري*): معاملات إضافية لمعالجات الانتباه. output_type (`str`, *اختياري*, القيمة الافتراضية pil): صيغة الإخراج: 'pil' أو 'np' أو 'pt'.

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

## PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

#### diffusers.PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

```python
diffusers.PH3ImageTextConnector(hidden_state_indices: tuple[int, ...] = (13, 19, 25, 31, 36), text_hidden_size: int = 2560, out_channels: int = 5120)
```

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

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

hidden_state_indices (`tuple[int, ...]`، القيمة الافتراضية هي `(13, 19, 25, 31, 36)`) : أي إدخالات من `hidden_states` في مُشفِّر النص تُقرأ، وفق ترقيم `output_hidden_states` (حيث `0` هو مخرج التضمين، و`i` هو مخرج طبقة المُفكِّك `i`، والأخير هو حالة المخفي النهائية بعد التطبيع).

text_hidden_size (`int`، القيمة الافتراضية `2560`) : حجم المخفي (hidden size) لمشفّر النص.

out_channels (`int`، القيمة الافتراضية `5120`) : عدد القنوات التي يقرأها محول MiniMax-H3 الشرطي.

تُحوّل الحالات المخفية لمُشفّر النص Qwen3-VL الخاص بـ P-H3-Image إلى شروط النص التي يقرأها محوّله.

تُدمج حالات الإخفاء المدرجة في `hidden_state_indices` ثم تُعيار وتُستخلص خطياً وتُعاد إلى قيمتها الأصلية. الرمز الأول هو مصدّ انتباه يحمل نفس شروط التهيئة لكل موجه، لذا يُستبدل بـ`sink_embedding`.

#### forward[[diffusers.PH3ImageTextConnector.forward]]

```python
forward(hidden_states: tuple[torch.Tensor, ...])
```

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

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

hidden_states (`tuple[torch.Tensor, ...]`) : حالات التشفير النصي المخفية، كما تُرجعها `output_hidden_states=True`: متجه واحد لكل عنصر من الشكل `(batch_size, num_tokens, text_hidden_size)`.

**يعيد:** `torch.Tensor`

الشرط، ذو الشكل `(batch_size, num_tokens, out_channels)`، في نوع البيانات dtype الخاص بمعاملات الوصلة.