Diffusers documentation
Ideogram 4
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 مُنظّم بدلاً من موجه حر، لذا يُفضّل توسيع الموجه القصير إلى ذلك المخطط الأصلي قبل التوليد. هناك طريقتان لإنتاج الوصف.
بعيد (واجهة برمجة تطبيقات Ideogram)
للحصول على أفضل النتائج، قم بتوسيع الأمر باستخدام واجهة برمجة التطبيقات السحرية (magic-prompt) التي تستضيفها 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")محلي (على الجهاز)
لخط أنابيب محلي بالكامل، حمّل رأس 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
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: Ideogram4Transformer2DModelunconditional_transformer: Ideogram4Transformer2DModelprompt_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) — محوّل تطابق تدفقي مشروط.
- unconditional_transformer (Ideogram4Transformer2DModel) — محوّل تطابق تدفّق غير مشروط (غير متماثل-CFG).
خط أنابيب من النص إلى الصورة لـ Ideogram4.
يعتمد نموذج Ideogram4 على مطابقة التدفق (flow-matching) مع تدريبه باستخدام إرشاد بدون مُصنِّف غير متماثل: يستهلك transformer الميزات المشروطة بالنص إلى جانب كامنات الصورة، بينما يقوم unconditional_transformer منفصل بإزالة الضوضاء باستخدام ميزات نصية معدومة. يتم دمج تنبؤات السرعة الخطيتين خطياً في كل خطوة.
__call__
< source >( prompt: str | list[str] | None = Noneheight: int = 2048width: int = 2048num_inference_steps: int = 48guidance_scale: float | None = Noneguidance_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.0std: float = 1.5prompt_upsampling: bool = Falseprompt_upsampling_temperature: float = 1.0max_sequence_length: int = 2048num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[ForwardRef('Ideogram4Pipeline'), int, int, dict[str, typing.Any]], dict[str, typing.Any]]] = Nonecallback_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، اختياري) — مقياس التوجيه الحر من التصنيف (classifier-free guidance) الثابت المطبَّق في كل خطوة. يتم دمج تنبؤات السرعة الشرطية وغير الشرطية على النحو التالي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إلى الاستدعاء العكسي.
شغّل توليد الصور من النص.
أمثلة:
>>> 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
< source >( prompt: str | list[str]grid_h: intgrid_w: intmax_sequence_length: intdevice: device )
جهّز الشرط (conditioning) لسلسلة النص والصورة المعبأة (بند واحد لكل موجه).
يعيد مجموعة مسطحة (prompt_embeds, position_ids, segment_ids, indicator). لا يحمل الفرع غير الشرطي أي نص، لذا يبني خط المعالجة مدخلاته (المصفّرة) مباشرة بدلاً من ترميز موجه سلبي.
upsample_prompt
< source >( prompt: str | list[str]height: int = 2048width: int = 2048temperature: float = 1.0max_new_tokens: int = 1024generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonedevice: typing.Optional[torch.device] = None )
أعد كتابة كل موجه إلى وصف JSON منظم أصلي لـ Ideogram4.
يتطلب المكوّن الاختياري prompt_enhancer_head، والذي يُدمج في جسم text_encoder المشترك لجعله توليديًا. يكون التوليد مقيدًا بالمخطط عند تثبيت outlines، وإلا فإنه يعمل دون قيود. مرّر generator (نفس المقبولة بواسطة __call__) لجعل أخذ العينات قابلًا للتكرار.
Ideogram4PromptEnhancerHead
فئة diffusers.Ideogram4PromptEnhancerHead
< source >( hidden_size: int = 4096vocab_size: int = 151936 )
رأس نموذج اللغة الذي يجعل text_encoder الخاص بـ Qwen3-VL بدون رأس توليديًا لأغراض تحسين الاستعلامات.
مكوّن خط أنابيب اختياري (prompt_enhancer_head): يتم تحميل أوزانه عبر استدعاء from_pretrained عادي (سواء من مستودع صغير خاص به، أو مندمجًا في مستودع النموذج) بدلاً من التحميل ضمن خط الأنابيب. عند وقت التوسيع، يجمع خط الأنابيب هذا المكوّن مع جسم text_encoder المشترك لتشكيل النموذج التوليدي.
Ideogram4PipelineOutput
فئة diffusers.pipelines.ideogram4.Ideogram4PipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
فئة الإخراج لخط أنابيب Ideogram 4.