Diffusers documentation

Ideogram 4

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Ideogram 4

Ideogram 4, çok modlu bir metin kodlayıcı ve asimetrik bir sınıflayıcı-ücretsiz yönlendirme şeması kullanan, akış eşleştirme tabanlı 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ı-özgürlü 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 en iyi şekilde üretimden önce bu yerel şemaya genişletilir. Açıklamayı üretmenin iki yolu vardır.

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

Yerel (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

sınıf diffusers.Ideogram4Pipeline

< source >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: Ideogram4Transformer2DModelunconditional_transformer: Ideogram4Transformer2DModelprompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None )

Parametreler

scheduler (FlowMatchEulerDiscreteScheduler) — Flow-matching zamanlayıcısı. Pipeline, 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ı. Pipeline, sabit bir ara decoder katmanı kümesinden gizli durumları tüketir (bkz. QWEN3_VL_ACTIVATION_LAYERS).
tokenizer (AutoTokenizer) — text_encoder ile eşleştirilen 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) 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

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

Parametreler

prompt (str veya list[str]) — Görsel üretimi için yönlendirici 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'in katı olmalıdır.
num_inference_steps (int, isteğe bağlı, varsayılan 48) — Flow-matching 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 sınıflandırıcı-özgürlüğü yönlendirme ö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 rehberlik ö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, isteğe bağlı, varsayılan 0.0) — Logit-normal akış eşleştirme zaman çizelgesinin taban ortalaması. Zaman çizelgesi 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, prompt kodlamadan önce upsample_prompt() aracılığıyla Ideogram4'ün yerel yapılandırılmış JSON başlığına dönüştürülür. İsteğe bağlı prompt_enhancer_head bileşenini gerektirir; şema kısıtlamalı başlıklar 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 alma sıcaklığı.
max_sequence_length (int, isteğe bağlı, varsayılan 2048) — İstek başına en fazla metin belirteç sayısı.
num_images_per_prompt (int, isteğe bağlı, varsayılan 1) — Her istem için oluşturulacak 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ülmediğini belirtir.
attention_kwargs (dict, isteğe bağlı) — Her transformer'ın dikkat işlemcisine iletilen bir kwargs sözlüğü. PEFT arka ucu 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ı.

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

< source >

( prompt: str | list[str]grid_h: intgrid_w: intmax_sequence_length: intdevice: device )

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

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

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ıtlamasız çalışır. Örnekleme tekrarlanabilir olsun diye generator ( __call__ tarafından kabul edilen aynı nesne) parametresini iletin.

Ideogram4PromptEnhancerHead

sınıf diffusers.Ideogram4PromptEnhancerHead

< source >

( hidden_size: int = 4096vocab_size: int = 151936 )

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 ortak text_encoder gövdesiyle birleştirerek üretken modeli oluşturur.

Ideogram4PipelineOutput

sınıf diffusers.pipelines.ideogram4.Ideogram4PipelineOutput

< source >

( images: list[PIL.Image.Image] | numpy.ndarray )

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ı.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→