# Ideogram 4

Ideogram 4 هو نموذج لتوليد الصور من النص يعتمد على مطابقة التدفق (flow-matching)، ويستخدم مشفّرًا نصيًا متعدد الوسائط ومخطط إرشاد بدون تصنيف غير متماثل: حيث ينتج `unconditional_transformer` المخصص الفرع السلبي مع ميزات نصية معدومة، بينما يستهلك `transformer` الرئيسي تسلسل النص والصورة المعبأ بالكامل.

الإعدادات الافتراضية للخط الأنابيب هي الإعدادات الموصى بها للحصول على أفضل جودة، لذا فإن استدعاء `pipe(prompt)` العادي ينتج نتائج بأفضل جودة دون أي إعدادات مسبقة: 48 خطوة مطابقة تدفق على جدول لوغاريتمي طبيعي (`mu=0.0`، `std=1.5`) مع إبقاء التوجيه الحر من التصنيف عند 7.0 للخطوات الرئيسية وتخفيضه إلى 3.0 للخطوات الثلاث الأخيرة "للتلميع".

تُعرَض الإعدادات الرئيسية أثناء الاستدلال عبر استدعاء خط الأنابيب:

- `num_inference_steps` و`mu` و`std` تتحكم في جدول flow-matching الطبيعي اللوغاريتمي الذي يأخذ الدقة في الاعتبار.
- `guidance_scale` (أو جدول كامل لكل خطوة `guidance_schedule`) يمزج بين السرعات الشرطية وغير الشرطية.

## النص إلى صورة

```python
import torch
from diffusers import Ideogram4Pipeline

pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A photo of a cat holding a sign that says hello world"
# The defaults are the recommended settings for best quality.
image = pipe(prompt, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
image.save("ideogram4.png")
```

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

يُدرَّب Ideogram 4 على وصف JSON مُنظَّم بدلاً من موجه حر، لذا يُفضَّل توسيع الموجه القصير إلى ذلك المخطط الأصلي قبل التوليد. هناك طريقتان لإنتاج الوصف.

### Remote (واجهة برمجة تطبيقات Ideogram)

للحصول على أفضل النتائج، قم بتوسيع الأمر باستخدام واجهة برمجة التطبيقات السحرية (magic-prompt API) التي تستضيفها Ideogram، ثم مرّر الوصف المُعاد مباشرةً إلى خط المعالجة (احصل على مفتاح من [developer.ideogram.ai](https://developer.ideogram.ai/)):

```python
import json
import requests
import torch
from diffusers import Ideogram4Pipeline

pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-4-nf4", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Expand the prompt into a structured JSON caption with Ideogram's hosted magic-prompt API.
response = requests.post(
    "https://api.ideogram.ai/v1/ideogram-v4/magic-prompt",
    headers={"Api-Key": "your_ideogram_api_key"},
    json={"text_prompt": "A photo of a cat holding a sign that says hello world", "aspect_ratio": "1x1"},
).json()
caption = json.dumps(response["json_prompt"])

# The caption is already upsampled, so pass it directly (no prompt_upsampling).
image = pipe(caption, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
image.save("ideogram4_upsampled.png")
```

### Local (على الجهاز)

لخط أنابيب محلي بالكامل، حمّل رأس [Ideogram4PromptEnhancerHead](/docs/diffusers/v0.43.0/ar/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) صغير الحجم (رأس نموذج Qwen3-VL اللغوي) كمكوّن اختياري باسم `prompt_enhancer_head` ومرّر `prompt_upsampling=True`. يُزرع هذا الرأس على `text_encoder` المشترك، لذا لا يتم تحميل مُشفّر نصي ثانٍ. ثبّت `outlines` للحصول على أوصاف مقيدة بالمخطط (يتطلب نقطة التفتيش nf4 أيضًا `bitsandbytes`):

```python
import torch
from diffusers import Ideogram4Pipeline, Ideogram4PromptEnhancerHead

prompt_enhancer_head = Ideogram4PromptEnhancerHead.from_pretrained(
    "diffusers/qwen3-vl-8b-instruct-lm-head", dtype=torch.bfloat16
)
pipe = Ideogram4Pipeline.from_pretrained(
    "ideogram-ai/ideogram-4-nf4", prompt_enhancer_head=prompt_enhancer_head, dtype=torch.bfloat16
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A photo of a cat holding a sign that says hello world"
image = pipe(
    prompt,
    height=1024,
    width=1024,
    prompt_upsampling=True,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("ideogram4_upsampled.png")
```

## Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

#### diffusers.Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

```python
diffusers.Ideogram4Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: Ideogram4Transformer2DModel, unconditional_transformer: Ideogram4Transformer2DModel, prompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

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

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مجدول مطابقة التدفق. يعيد خط الأنابيب جدولة سيجما الافتراضية إلى جدولة لوجيت-طبيعية تراعي الدقة.

vae (`AutoencoderKLFlux2`) : ترميز فك ترميز احتمالي يُستخدم لفك الترميز من المتغيرات الكامنة (latents) إلى الصور.

text_encoder (`PreTrainedModel`) : مُشفِّر نص متعدد الوسائط. تستهلك خط المعالجة حالات مخفية من مجموعة ثابتة من طبقات فك الترميز الوسيطة (انظر `QWEN3_VL_ACTIVATION_LAYERS`).

tokenizer (`AutoTokenizer`) : مُجزِّئ مقترن بـ `text_encoder`.

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/v0.43.0/ar/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : نموذج تحويل (Transformer) لتطابق التدفق الشرطي.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/v0.43.0/ar/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : نموذج تحويل (transformer) لتطابق التدفق (flow-matching) غير الشرطي (غير متماثل CFG).

خط أنابيب من النص إلى الصورة لـ Ideogram4.

يعتمد نموذج Ideogram4 على مطابقة التدفق (flow-matching) مع تدريبه باستخدام إرشاد غير مشروط غير متماثل (asymmetric classifier-free guidance): حيث يستهلك `transformer` الميزات المشروطة بالنص إلى جانب كامنات الصورة، بينما يقوم `unconditional_transformer` منفصل بإزالة الضوضاء باستخدام ميزات نصية معدومة. يتم دمج التنبؤين بالسرعة خطياً في كل خطوة.

#### __call__[[diffusers.Ideogram4Pipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, height: int = 2048, width: int = 2048, num_inference_steps: int = 48, guidance_scale: float | None = None, guidance_schedule: typing.Union[list[float], torch.Tensor, NoneType] = (7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 3.0, 3.0, 3.0), mu: float = 0.0, std: float = 1.5, prompt_upsampling: bool = False, prompt_upsampling_temperature: float = 1.0, max_sequence_length: int = 2048, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[ForwardRef('Ideogram4Pipeline'), int, int, dict[str, typing.Any]], dict[str, typing.Any]]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

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

prompt (`str` أو `list[str]`) : الأوامر النصية (Prompt) التي توجّه توليد الصورة.

height (`int`، *اختياري*، القيمة الافتراضية 2048) : ارتفاع الصورة الناتجة بالبكسلات؛ يجب أن يكون مضاعفًا لـ `vae_scale_factor * patch_size`.

width (`int`، *اختياري*، القيمة الافتراضية 2048) : عرض الصورة الناتجة بالبكسلات؛ يجب أن يكون مضاعفًا لـ `vae_scale_factor * patch_size`.

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 48) : عدد خطوات مطابقة التدفق. القيمة الافتراضية هي الإعداد الموصى به للحصول على أفضل جودة.

guidance_scale (`float`, *اختياري*) : مقياس التوجيه الحر من التصنيف الثابت المطبَّق في كل خطوة. يتم دمج تنبؤات السرعة الشرطية وغير الشرطية على النحو التالي `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. يتعارض مع `guidance_schedule` (فإن تعيين كلاهما معًا يثير خطأ). القيمة الافتراضية هي `None`.

guidance_schedule (`list[float]` أو `torch.Tensor`، *اختياري*) : جدول مقياس التوجيه لكل خطوة؛ يجب أن يكون طوله `num_inference_steps`. يتوافق العنصر الأول مع الخطوة الأولى (أعلى مستوى ضوضاء). يتعارض مع `guidance_scale`؛ يجب تعيين أحدهما فقط. الافتراضي هو الجدول الموصى به (7.0 للخطوات الرئيسية، وينخفض إلى 3.0 للخطوات الثلاث الأخيرة "للتشطيب"). لاستخدام مقياس ثابت بدلاً من ذلك، مرّر `guidance_scale` و`guidance_schedule=None`.

mu (`float`، *اختياري*، القيمة الافتراضية 0.0) : متوسط الأساس لجدول مطابقة التدفق اللوغاريتمي الطبيعي. يتم إزاحة متوسط الجدول بمقدار نصف اللوغاريتم لنسبة الدقة مقارنةً بدقة 512x512.

std (`float`، *اختياري*، القيمة الافتراضية 1.5) : الانحراف المعياري لجدول مطابقة التدفق ذي التوزيع الطبيعي اللوغاريتمي.

prompt_upsampling (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا كانت `True`، يُعاد كتابة `prompt` إلى وصف JSON مُهيكّل أصلي لـ Ideogram4 عبر [upsample_prompt()](/docs/diffusers/v0.43.0/ar/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) قبل الترميز. يتطلب المكوّن الاختياري `prompt_enhancer_head`؛ ثبّت `outlines` للأوصاف المقيدة بالمخطط. يُعاد استخدام `generator` لجعل عملية التوسيع قابلة للتكرار.

prompt_upsampling_temperature (`float`، *اختياري*، القيمة الافتراضية 1.0) : درجة حرارة العينة (Sampling temperature) لرفع عينة الموجه (prompt upsampling) عندما يكون `prompt_upsampling=True`.

max_sequence_length (`int`، *اختياري*، القيمة الافتراضية 2048) : الحد الأقصى لعدد رموز النص لكل موجه.

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : المولّدات المستخدمة لجعل عملية أخذ العينات حتمية.

latents (`torch.Tensor`، *اختياري*) : ضوضاء مُولّدة مسبقًا بأبعاد `(batch_size, num_image_tokens, latent_dim)`.

output_type (`str`، *اختياري*، الافتراضي `"pil"`) : أحد `"pil"`، `"np"`، `"pt"`، أو `"latent"`.

return_dict (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان يجب إرجاع [Ideogram4PipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput).

attention_kwargs (`dict`, *اختياري*) : قاموس kwargs يُمرَّر إلى معالج الانتباه (attention processor) الخاص بكل محوّل (transformer). يُقيّم إدخال `"scale"` أوزان LoRA المحمّلة (مثل `{"scale": 0.7}`) عندما يكون نظام PEFT نشطًا.

callback_on_step_end (`Callable`، *اختياري*) : استدعاء يُستدعى في نهاية كل خطوة إزالة ضوضاء.

callback_on_step_end_tensor_inputs (`list[str]`، *اختياري*) : أسماء الموترات التي سيتم كشفها عن طريق `callback_kwargs` إلى الاستدعاء العكسي.

**يعيد:**

[Ideogram4PipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) أو `tuple`.

شغّل توليد الصور من النص.

أمثلة:
```py
>>> import torch
>>> from diffusers import Ideogram4Pipeline

>>> pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A photo of a cat holding a sign that says hello world"
>>> # The defaults are the recommended settings for best quality.
>>> image = pipe(prompt, height=2048, width=2048, generator=torch.Generator("cuda").manual_seed(0)).images[0]
>>> image.save("ideogram4.png")
```

#### encode_prompt[[diffusers.Ideogram4Pipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

جهّز الشرط (conditioning) لسلسلة النص والصورة المعبأة (بند واحد لكل موجه).

يعيد مجموعة مسطحة `(prompt_embeds, position_ids, segment_ids, indicator)`. لا يحمل الفرع غير الشرطي أي نص، لذا يبني خط المعالجة مدخلاته (المصفّرة) مباشرة بدلاً من ترميز موجه سلبي.

#### upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

```python
upsample_prompt(prompt: str | list[str], height: int = 2048, width: int = 2048, temperature: float = 1.0, max_new_tokens: int = 1024, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, device: typing.Optional[torch.device] = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

أعد كتابة كل موجه إلى وصف JSON منظم أصلي لـ Ideogram4.

يتطلب المكوّن الاختياري `prompt_enhancer_head`، والذي يُدمج في جسم `text_encoder` المشترك لجعله توليديًا. يكون التوليد مقيدًا بالمخطط (schema) عند تثبيت `outlines`، وإلا فإنه يعمل دون قيود. مرّر `generator` (نفس المقبولة بواسطة `__call__`) لجعل أخذ العينات قابلًا للتكرار.

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

```python
diffusers.Ideogram4PromptEnhancerHead(hidden_size: int = 4096, vocab_size: int = 151936)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

رأس نموذج اللغة الذي يجعل `text_encoder` الخاص بـ Qwen3-VL بدون رأس توليديًا لأغراض تحسين الاستعلامات.

مكوّن خط أنابيب اختياري (`prompt_enhancer_head`): يتم تحميل أوزانه عبر استدعاء `from_pretrained` عادي (سواء من مستودع صغير خاص به، أو مندمجًا في مستودع النموذج) بدلاً من التحميل ضمن خط الأنابيب. عند وقت التوسيع، يجمع خط الأنابيب هذا المكوّن مع جسم `text_encoder` المشترك لتشكيل النموذج التوليدي.

## Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

#### diffusers.pipelines.ideogram4.Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

```python
diffusers.pipelines.ideogram4.Ideogram4PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_output.py#L24)

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

images (`list[PIL.Image.Image]` أو `np.ndarray`) : قائمة من صور PIL منزوعة الضوضاء بطول `batch_size`، أو مصفوفة numpy بأبعاد `(batch_size, height, width, num_channels)`.

فئة الإخراج لخط أنابيب Ideogram 4.