diffusers/v0.43.0/ar/api/pipelines/ideogram4.md

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) يمزج بين السرعات الشرطية وغير الشرطية.

النص إلى صورة

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):

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 صغير الحجم (رأس نموذج Qwen3-VL اللغوي) كمكوّن اختياري باسم prompt_enhancer_head ومرّر prompt_upsampling=True. يُزرع هذا الرأس على text_encoder المشترك، لذا لا يتم تحميل مُشفّر نصي ثانٍ. ثبّت outlines للحصول على أوصاف مقيدة بالمخطط (يتطلب نقطة التفتيش nf4 أيضًا bitsandbytes):

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]]

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)

المصدر

المعاملات:

scheduler (FlowMatchEulerDiscreteScheduler) : مجدول مطابقة التدفق. يعيد خط الأنابيب جدولة سيجما الافتراضية إلى جدولة لوجيت-طبيعية تراعي الدقة.

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

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

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

transformer (Ideogram4Transformer2DModel) : نموذج تحويل (Transformer) لتطابق التدفق الشرطي.

unconditional_transformer (Ideogram4Transformer2DModel) : نموذج تحويل (transformer) لتطابق التدفق (flow-matching) غير الشرطي (غير متماثل CFG).

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

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

call[[diffusers.Ideogram4Pipeline.call]]

__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'])

المصدر

المعاملات:

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() قبل الترميز. يتطلب المكوّن الاختياري 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.

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 أو tuple.

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

أمثلة:

>>> 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]]

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

المصدر

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

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

upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

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)

المصدر

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

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

Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

المصدر

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

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

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

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

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

المصدر

المعاملات:

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

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