diffusers/main/tr/api/pipelines/ideogram4.md

Ideogram 4

Ideogram 4, çok modlu bir metin kodlayıcı ve asimetrik bir sınıflandırıcı-ücretsiz yönlendirme şeması kullanan, akış eşleştirmeli metinden görüntüye bir modeldir: özel bir unconditional_transformer, sıfırlanmış metin özellikleriyle negatif dalı üretirken, ana transformer tam paketli metin + görüntü dizisini işler.

Pipeline varsayılanları, en iyi kalite için önerilen ayarlardır; bu nedenle düz bir pipe(prompt) çağrısı, kutudan çıktığı gibi en yüksek kalitede sonuçlar üretir: logit-normal zaman çizelgesinde (mu=0.0, std=1.5) 48 akış eşleştirme adımı, ana adımlarda sınıflandırıcı-ücretsiz yönlendirme 7.0'da tutulurken son 3 "parlatma" adımında 3.0'a düşürülür.

Temel çıkarım zamanı ayarları, pipeline çağrısı üzerinden sunulur:

• num_inference_steps, mu ve std, çözünürlük duyarlı logit-normal akış eşleştirme zamanlamasını kontrol eder.
• guidance_scale (veya tam adım başına guidance_schedule) koşullu ve koşulsuz hızları birleştirir.

Metinden görüntüye

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

Prompt örnekleme

Ideogram 4, serbest biçimli bir istem yerine yapılandırılmış bir JSON açıklaması üzerinde eğitildiğinden, kısa bir istem üretimden önce bu yerel şemaya genişletilmelidir. Açıklamayı üretmenin iki yolu vardır.

Remote (Ideogram API)

En iyi sonuçlar için, istemi Ideogram'ın barındırdığı magic-prompt API'siyle genişletin ve döndürülen başlığı doğrudan pipeline'a iletin (anahtar için 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 (cihaz üzerinde)

Tamamen yerel bir iş akışı için, küçük bir Ideogram4PromptEnhancerHead (Qwen3-VL LM başlığı) bileşenini isteğe bağlı prompt_enhancer_head olarak yükleyin ve prompt_upsampling=True parametresini iletin. Bu başlık, paylaşılan text_encoder üzerine eklenir, bu nedenle ikinci bir metin kodlayıcı yüklenmez. Şema kısıtlamalı açıklamalar için outlines paketini kurun (nf4 kontrol noktası ayrıca bitsandbytes gerektirir):

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)

Kaynak

Parametreler:

scheduler (FlowMatchEulerDiscreteScheduler) : Akış eşleştirme zamanlayıcısı. Boru hattı, varsayılan sigma zamanlamasını çözünürlük duyarlı logit-normal zamanlama ile değiştirir.

vae (AutoencoderKLFlux2) : Gizli değişkenleri (latents) tekrar görüntülere dönüştürmek için kullanılan varyasyonel oto-kodlayıcı.

text_encoder (PreTrainedModel) : Çok modlu metin kodlayıcı. Boru hattı, sabit bir ara decoder katmanı kümesinden gizli durumları tüketir (bkz. QWEN3_VL_ACTIVATION_LAYERS).

tokenizer (AutoTokenizer) : text_encoder ile eşleştirilmiş tokenizer.

transformer (Ideogram4Transformer2DModel) : Koşullu akış eşleştirme dönüştürücüsü.

unconditional_transformer (Ideogram4Transformer2DModel) : Koşulsuz (asimetrik-CFG) akış eşleştirme (flow-matching) dönüştürücüsü (transformer).

Ideogram4 için metinden görüntüye pipeline.

Ideogram4, asimetrik sınıflandırıcı-ücretsiz yönlendirme ile eğitilmiş bir akış-eşleştirme modelidir: bir transformer, metin koşullu özelliklerin yanı sıra görüntü latentlerini tüketirken, ayrı bir unconditional_transformer sıfırlanmış metin özellikleriyle gürültü giderme yapar. İki hız tahmini her adımda doğrusal olarak birleştirilir.

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 = ['latents'])

Kaynak

Parametreler:

prompt (str veya list[str]) : Görsel üretimi yönlendirmek için istem(ler).

height (int, isteğe bağlı, varsayılan 2048) : Piksel cinsinden çıktı görüntü yüksekliği; vae_scale_factor * patch_size'in katı olmalıdır.

width (int, isteğe bağlı, varsayılan 2048) : Piksel cinsinden çıktı görüntü genişliği; vae_scale_factor * patch_size'nin katı olmalıdır.

num_inference_steps (int, isteğe bağlı, varsayılan 48) : Akış eşleştirme adım sayısı. Varsayılan değer, en iyi kalite için önerilen ayaradır.

guidance_scale (float, isteğe bağlı) : Her adımda uygulanan sabit classifier-free guidance ölçeği. Koşullu ve koşulsuz hız tahminleri v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg olarak birleştirilir. guidance_schedule ile birbirini dışlar (her ikisi de ayarlanırsa hata verir). Varsayılan değeri None'dir.

guidance_schedule (list[float] veya torch.Tensor, isteğe bağlı) : Adım başına yönlendirme ölçeği zamanlaması; uzunluğu num_inference_steps olmalıdır. İlk giriş, ilk adıma (en yüksek gürültü seviyesine) karşılık gelir. guidance_scale ile birbirini dışlar; bunlardan tam olarak biri ayarlanmalıdır. Varsayılan olarak önerilen zamanlama kullanılır (ana adımlar için 7.0, son 3 "parlatma" adımı için 3.0'a düşer). Bunun yerine sabit bir ölçek kullanmak için guidance_scale ve guidance_schedule=None geçin.

mu (float, opsiyonel, varsayılan 0.0) : Logit-normal akış eşleştirme zamanlamasının taban ortalaması. Zamanlama ortalaması, 512x512'ye göre çözünürlük oranının logaritmasının yarısı kadar kaydırılır.

std (float, isteğe bağlı, varsayılan 1.5) : Logit-normal akış eşleştirme zamanlamasının standart sapması.

prompt_upsampling (bool, isteğe bağlı, varsayılan False) : True ise, kodlamadan önce prompt değeri upsample_prompt() aracılığıyla Ideogram4'ün yerleşik yapılandırılmış JSON açıklamasına dönüştürülür. İsteğe bağlı prompt_enhancer_head bileşenini gerektirir; şema kısıtlamalı açıklamalar için outlines paketini yükleyin. generator, örnekleme işleminin tekrarlanabilir olması için yeniden kullanılır.

prompt_upsampling_temperature (float, isteğe bağlı, varsayılan 1.0) : prompt_upsampling=True olduğunda prompt upsampling için örneklem sıcaklığı.

max_sequence_length (int, isteğe bağlı, varsayılan 2048) : İstek başına maksimum metin jetonu sayısı.

num_images_per_prompt (int, isteğe bağlı, varsayılan 1) : Her istem için üretilecek görsel sayısı.

generator (torch.Generator veya list[torch.Generator], isteğe bağlı) : Örnekleme işlemini deterministik hale getirmek için kullanılan üreteç(ler).

latents (torch.Tensor, isteğe bağlı) : (batch_size, num_image_tokens, latent_dim) biçiminde önceden üretilmiş gürültü.

output_type (str, isteğe bağlı, varsayılan "pil") : "pil", "np", "pt" veya "latent" değerlerinden biri.

return_dict (bool, isteğe bağlı, varsayılan True) : Bir Ideogram4PipelineOutput döndürülüp döndürülmemesi.

attention_kwargs (dict, isteğe bağlı) : Her transformer'ın dikkat işlemcisine (attention processor) iletilen bir kwargs sözlüğü. PEFT arka ucu (backend) etkin olduğunda, "scale" girdisi yüklenen LoRA ağırlıklarını ölçekler (ör. {"scale": 0.7}).

callback_on_step_end (Callable, isteğe bağlı) : Her gürültü azaltma adımının sonunda çağrılan geri çağrı.

callback_on_step_end_tensor_inputs (list[str], isteğe bağlı) : callback_kwargs üzerinden geri çağrıya (callback) açılacak tensörlerin adları.

Dönüş:

Ideogram4PipelineOutput veya tuple.

Metinden görüntüye üretim çalıştırın.

Örnekler:

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

Kaynak

Paketli metin+görsel dizisi için koşullandırmayı hazırlayın (her istem için bir giriş).

Düz bir demet döndürür: (prompt_embeds, position_ids, segment_ids, indicator). Koşulsuz dal metin içermediğinden, boru hattı negatif bir prompt kodlamak yerine (sıfırlanmış) girdilerini doğrudan oluşturur.

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)

Kaynak

Her istemi Ideogram4'ün yerleşik yapılandırılmış JSON başlığına yeniden yazın.

Opsiyonel prompt_enhancer_head bileşenini gerektirir; bu bileşen, onu üretken hale getirmek için paylaşılan text_encoder gövdesine eklenir. outlines yüklüyse üretim şema kısıtlamalıdır, aksi halde kısıtsız çalışır. Örnekleme işlemini tekrarlanabilir kılmak için generator ( __call__ tarafından kabul edilen aynı nesne) parametresini iletin.

Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

Kaynak

Başlıksız Qwen3-VL text_encoder'ini prompt örneklemesi için üretken hale getiren LM başlığı.

İsteğe bağlı bir pipeline bileşeni (prompt_enhancer_head): ağırlıkları, pipeline içi bir indirme yerine normal bir from_pretrained ile yüklenir (kendi küçük deposu veya model deposunda paketlenmiş olarak). Upsample sırasında pipeline, bu bileşeni paylaşılan text_encoder gövdesiyle birleştirerek üretken modeli oluşturur.

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

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

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

Kaynak

Parametreler:

images (list[PIL.Image.Image] veya np.ndarray) : batch_size uzunluğunda gürültüsü azaltılmış PIL görüntülerinin listesi veya (batch_size, height, width, num_channels) biçiminde bir numpy dizisi.

Ideogram 4 hattı için çıktı sınıfı.