Hugging Face's logo

Diffusers documentation

Ideogram 4

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).
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 = ['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→