diffusers/v0.43.0/ru/api/pipelines/ideogram4.md

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 для последних 3 «полирующих» шагов.

Ключевые параметры, настраиваемые во время инференса, доступны через вызов пайплайна:

• 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-описаниях, а не на свободных промптах, поэтому короткий промпт лучше расширить до этого нативного формата перед генерацией. Существует два способа создания описания.

Remote (Ideogram API)

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

Local (на устройстве)

Для полностью локального конвейера загрузите небольшую 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]]

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)

Источник

Параметры:

scheduler (FlowMatchEulerDiscreteScheduler) : планировщик flow-matching. Конвейер переопределяет расписание сигм по умолчанию на логит-нормальное расписание, учитывающее разрешение.

vae (AutoencoderKLFlux2) : вариационный автоэнкодер, используемый для декодирования латентов обратно в изображения.

text_encoder (PreTrainedModel) : мультимодальный текстовый энкодер. Конвейер использует скрытые состояния из фиксированного набора промежуточных слоев декодера (см. QWEN3_VL_ACTIVATION_LAYERS).

tokenizer (AutoTokenizer) : Токенизатор, связанный с text_encoder.

transformer (Ideogram4Transformer2DModel) : условный трансформер flow-matching.

unconditional_transformer (Ideogram4Transformer2DModel) : Трансформер flow-matching для безусловного (asymmetric-CFG) генерирования.

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

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

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[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, optional, по умолчанию 48) : Количество шагов flow-matching. Значение по умолчанию — рекомендуемая настройка для наилучшего качества.

guidance_scale (float, optional) : Постоянный масштаб 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, optional, по умолчанию 0.0) : Базовое среднее значение расписания flow-matching для логит-нормального распределения. Среднее значение расписания сдвигается на половину логарифма отношения разрешения относительно 512x512.

std (float, optional, по умолчанию 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, передаваемый в процессор внимания каждого трансформера. Запись "scale" масштабирует загруженные веса LoRA (например, {"scale": 0.7}), если активен бэкенд PEFT.

callback_on_step_end (Callable, необязательный) : Колбэк, вызываемый в конце каждого шага денойзинга.

callback_on_step_end_tensor_inputs (list[str], необязательный) : Имена тензоров, которые будут переданы в обратный вызов через callback_kwargs.

Возвращает:

Ideogram4PipelineOutput или tuple.

Запустите генерацию изображений по тексту.

Примеры:

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

Источник

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

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

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)

Источник

Переформулируйте каждый промпт в нативный структурированный JSON-описание Ideogram4.

Требуется необязательный компонент prompt_enhancer_head, который присоединяется к общему корпусу text_encoder, чтобы сделать его генеративным. Генерация ограничена схемой, если установлен пакет outlines, в противном случае выполняется без ограничений. Передайте generator (тот же, что принимается __call__), чтобы сделать выборку воспроизводимой.

Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

Источник

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

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

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

diffusers.pipelines.ideogram4.Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.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.