Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ar /api /pipelines /ideogram4.md

mishig

3 days ago

preview code

download

raw

18 kB

# 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/main/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/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

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

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/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/main/ar/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : نموذج تحويل (Transformer) لتطابق التدفق الشرطي.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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.

Xet Storage Details

Size:: 18 kB
Xet hash:: 51e95c79292a9130ccfcbd2f64329e940fc754bcb08ba71f030b7dd3a4c5aaa7

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 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/main/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/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

	المعاملات:

	scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/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/main/ar/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : نموذج تحويل (Transformer) لتطابق التدفق الشرطي.

	unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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.