Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ru /api /pipelines /ideogram4.md

mishig

3 days ago

preview code

download

raw

19.9 kB

# 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`) смешивает условные и безусловные скорости.

## Текст в изображение

```python
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](https://developer.ideogram.ai/)):

```python
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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) (LM-голову Qwen3-VL) в качестве необязательного компонента `prompt_enhancer_head` и передайте `prompt_upsampling=True`. Голова присоединяется к общему `text_encoder`, поэтому второй текстовый энкодер не загружается. Установите `outlines` для описаний с ограничением по схеме (для контрольной точки nf4 также потребуется `bitsandbytes`):

```python
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]]

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

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

**Параметры:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик flow-matching. Конвейер переопределяет расписание сигм по умолчанию на логит-нормальное расписание, учитывающее разрешение.

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

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

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

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/ru/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : условный трансформер flow-matching.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/ru/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Трансформер flow-matching для безусловного (asymmetric-CFG) генерирования.
Пайплайн «текст в изображение» для Ideogram4.
Ideogram4 — это модель flow-matching, обученная с асимметричным classifier-free guidance: `transformer` обрабатывает текстовые признаки вместе с латентами изображения, а отдельный `unconditional_transformer` выполняет денойзинг с обнулёнными текстовыми признаками. Два предсказания скорости линейно смешиваются на каждом шаге.

#### __call__[[diffusers.Ideogram4Pipeline.__call__]]

```python
__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'])
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

**Параметры:**

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()](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) или `tuple`.

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

Примеры:
```py
>>> 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]]

```python
encode_prompt(prompt: str | list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

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

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

#### upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

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

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

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

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

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

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

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

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_output.py#L24)

**Параметры:**

images (`list[PIL.Image.Image]` или `np.ndarray`) : список денойзированных изображений PIL длиной `batch_size` или массив numpy с формой `(batch_size, height, width, num_channels)`.

Класс вывода для пайплайна Ideogram 4.

Xet Storage Details

Size:: 19.9 kB
Xet hash:: 5f6c3611b2deb58ee24351f476ee1fb216210e689866bfcf97c505ba3b9a6e7c

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 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`) смешивает условные и безусловные скорости.

	## Текст в изображение

	```python
	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](https://developer.ideogram.ai/)):

	```python
	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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) (LM-голову Qwen3-VL) в качестве необязательного компонента `prompt_enhancer_head` и передайте `prompt_upsampling=True`. Голова присоединяется к общему `text_encoder`, поэтому второй текстовый энкодер не загружается. Установите `outlines` для описаний с ограничением по схеме (для контрольной точки nf4 также потребуется `bitsandbytes`):

	```python
	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]]

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

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

	Параметры:

	scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик flow-matching. Конвейер переопределяет расписание сигм по умолчанию на логит-нормальное расписание, учитывающее разрешение.

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

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

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

	transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/ru/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : условный трансформер flow-matching.

	unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/ru/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Трансформер flow-matching для безусловного (asymmetric-CFG) генерирования.

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

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

	#### __call__[[diffusers.Ideogram4Pipeline.__call__]]

	```python
	__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'])
	```

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

	Параметры:

	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()](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.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](/docs/diffusers/main/ru/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) или `tuple`.

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

	Примеры:
	```py
	>>> 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]]

	```python
	encode_prompt(prompt: str \| list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)
	```

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

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

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

	#### upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

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

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

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

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

	## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

	#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

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

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

	[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_output.py#L24)

	Параметры:

	images (`list[PIL.Image.Image]` или `np.ndarray`) : список денойзированных изображений PIL длиной `batch_size` или массив numpy с формой `(batch_size, height, width, num_channels)`.

	Класс вывода для пайплайна Ideogram 4.