Hugging Face's logo

Diffusers documentation

Ideogram 4

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ideogram 4

Ideogram 4 — это модель text-to-image на основе flow-matching, использующая мультимодальный текстовый энкодер и асимметричную схему classifier-free guidance: выделенный unconditional_transformer формирует отрицательную ветвь с обнулёнными текстовыми признаками, тогда как основной transformer обрабатывает полную упакованную последовательность текста и изображения.

Значения по умолчанию для конвейера представляют собой рекомендуемые настройки для достижения наилучшего качества, поэтому обычный вызов pipe(prompt) сразу даёт результаты высшего качества: 48 шагов flow-matching по логит-нормальному расписанию (mu=0.0, std=1.5) с коэффициентом classifier-free guidance, равным 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-описаниях, а не на свободных промптах, поэтому короткий промпт лучше всего расширить до этого нативного формата перед генерацией. Существует два способа создания описания.

Удалённый (API Ideogram)

Для наилучших результатов расширьте промпт с помощью хостингуемого API 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 (LM-голову 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

< >

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

Параметры

  • scheduler (FlowMatchEulerDiscreteScheduler) — планировщик flow-matching. Конвейер переопределяет расписание сигм по умолчанию на логит-нормальное расписание, учитывающее разрешение.
  • vae (AutoencoderKLFlux2) — Вариационный автоэнкодер, используемый для декодирования латентов обратно в изображения.
  • text_encoder (PreTrainedModel) — Мультимодальный текстовый энкодер. Пайплайн использует скрытые состояния из фиксированного набора промежуточных слоев декодера (см. QWEN3_VL_ACTIVATION_LAYERS).
  • tokenizer (AutoTokenizer) — токенизатор, используемый вместе с text_encoder.
  • transformer (Ideogram4Transformer2DModel) — Условный трансформер flow-matching.
  • unconditional_transformer (Ideogram4Transformer2DModel) — Безусловный (asymmetric-CFG) flow-matching трансформер.

Пайплайн «текст в изображение» для Ideogram4.

Ideogram4 — это модель flow-matching, обученная с асимметричным classifier-free guidance: transformer обрабатывает текстовые признаки вместе с латентами изображения, а отдельный unconditional_transformer выполняет денойзинг с обнулёнными текстовыми признаками. На каждом шаге два предсказания скорости линейно смешиваются.

__call__

< >

( 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]) — Промпт(ы) для управления генерацией изображения.
  • height (int, необязательный, по умолчанию 2048) — Высота выходного изображения в пикселях; должна быть кратна vae_scale_factor * patch_size.
  • width (int, необязательный, по умолчанию 2048) — Ширина выходного изображения в пикселях; должна быть кратна vae_scale_factor * patch_size.
  • num_inference_steps (int, необязательный, по умолчанию 48) — Количество шагов flow-matching. По умолчанию установлено рекомендуемое значение для наилучшего качества.
  • 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 для последних 3 «полирующих» шагов). Чтобы использовать постоянный масштаб, передайте guidance_scale и guidance_schedule=None.
  • mu (float, необязательный, по умолчанию 0.0) — Базовое среднее значение расписания flow-matching для logit-normal. Среднее значение расписания сдвигается на половину логарифма коэффициента разрешения относительно 512x512.
  • std (float, необязательный, по умолчанию 1.5) — Стандартное отклонение логит-нормального расписания flow-matching.
  • prompt_upsampling (bool, необязательный, по умолчанию False) — Если True, переписывает prompt в нативный структурированный JSON-описание Ideogram4 с помощью upsample_prompt() перед кодированием. Требуется необязательный компонент prompt_enhancer_head; установите outlines для описаний с ограничением схемы. generator переиспользуется, чтобы сделать процесс апсемплинга воспроизводимым.
  • prompt_upsampling_temperature (float, необязательный, по умолчанию 1.0) — Температура выборки при апсемплинге промпта, если 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-процессор каждого трансформера. Запись "scale" масштабирует загруженные веса LoRA (например, {"scale": 0.7}), если активен бэкенд PEFT.
  • callback_on_step_end (Callable, необязательный) — Обработчик, вызываемый в конце каждого шага удаления шума.
  • callback_on_step_end_tensor_inputs (list[str], необязательный) — Имена тензоров, которые передаются в callback через 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

< >

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

Подготовьте условия для упакованной последовательности «текст+изображение» (одна запись на каждый запрос).

Возвращает плоский кортеж (prompt_embeds, position_ids, segment_ids, indicator). Безусловная ветка не содержит текста, поэтому конвейер формирует свои (обнулённые) входные данные напрямую, а не кодирует отрицательный промпт.

upsample_prompt

< >

( 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

< >

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

LM head, делающий head-less Qwen3-VL text_encoder генеративным для апсемплинга промптов.

Необязательный компонент конвейера (prompt_enhancer_head): его веса загружаются через обычный from_pretrained (из собственного небольшого репозитория или из репозитория модели), а не скачиваются внутри конвейера. При апсемплинге конвейер объединяет его с общим корпусом text_encoder, чтобы сформировать генеративную модель.

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.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→