# Ideogram 4

Ideogram 4 是一个基于流匹配的文本生成图像模型，采用多模态文本编码器和非对称的无分类器引导方案：专用的 `unconditional_transformer` 通过置零的文本特征生成负分支，而主 `transformer` 则处理完整的打包文本 + 图像序列。

Pipeline 的默认值是为获得最佳质量而推荐的设置，因此直接调用 `pipe(prompt)` 即可开箱即用地生成最佳质量的结果：在 logit-normal 调度（`mu=0.0`、`std=1.5`）上执行 48 步 flow-matching，主步骤的 classifier-free guidance 保持为 7.0，最后 3 个“抛光”步骤则降至 3.0。

关键推理参数通过 pipeline 调用暴露：

- `num_inference_steps`、`mu` 和 `std` 控制分辨率感知的 logit-normal 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）

为获得最佳效果，请使用 Ideogram 托管的 magic-prompt API 扩展提示词，并将返回的说明直接传入 pipeline（在 [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/zh/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead)（即 Qwen3-VL LM head）作为可选的 `prompt_enhancer_head` 组件，并传入 `prompt_upsampling=True`。该 head 会嫁接到共享的 `text_encoder` 上，因此无需加载第二个文本编码器。请安装 `outlines` 以支持基于 schema 约束的说明文本生成（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/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：Flow-matching 调度器。该 pipeline 使用分辨率感知的 logit-normal 调度覆盖了默认的 sigma 调度。

vae (`AutoencoderKLFlux2`)：用于将潜在变量解码回图像的变分自编码器。

text_encoder (`PreTrainedModel`)：多模态文本编码器。该流水线使用来自一组固定中间解码器层的隐藏状态（参见 `QWEN3_VL_ACTIVATION_LAYERS`）。

tokenizer (`AutoTokenizer`)：与 `text_encoder` 配对的 Tokenizer。

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/zh/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel))：条件流匹配 Transformer。

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/zh/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel))：无条件（非对称 CFG）流匹配 Transformer。

Ideogram4 的文本到图像流水线。

Ideogram4 是一个采用非对称无分类器引导（asymmetric classifier-free guidance）进行训练的流匹配模型：一个 `transformer` 同时接收文本条件特征和图像潜在表示，而另一个独立的 `unconditional_transformer` 则在文本特征置零的情况下执行去噪。每一步中，两个速度预测值会进行线性混合。

#### __调用__[[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 = ['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`，*可选*，默认值为 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 个“抛光”步骤降至 3.0）。若要使用恒定比例，请传入 `guidance_scale` 并设置 `guidance_schedule=None`。

mu (`float`, *可选*，默认值为 0.0)：logit-normal flow-matching 调度的基础均值。调度均值会根据相对于 512x512 的分辨率比值的对数的一半进行偏移。

std (`float`, *可选*，默认值为 1.5) : logit-normal flow-matching 调度的标准差。

prompt_upsampling (`bool`，*可选*，默认为 `False`)：如果为 `True`，则在编码之前，通过 [upsample_prompt()](/docs/diffusers/main/zh/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) 将 `prompt` 重写为 Ideogram4 原生的结构化 JSON 描述。需要可选的 `prompt_enhancer_head` 组件；请安装 `outlines` 以支持基于模式约束的描述生成。`generator` 会被复用，以确保上采样过程可复现。

prompt_upsampling_temperature (`float`，*可选*，默认值为 1.0)：当 `prompt_upsampling=True` 时，用于提示上采样的采样温度。

max_sequence_length (`int`，*可选*，默认值为 2048)：每个提示词的最大文本 token 数。

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/zh/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput)。

attention_kwargs (`dict`, *可选*) : 传递给每个 transformer 的 attention processor 的 kwargs 字典。当 PEFT 后端处于激活状态时，`"scale"` 条目会对加载的 LoRA 权重进行缩放（例如 `{"scale": 0.7}`）。

callback_on_step_end (`Callable`，*可选*)：在每个去噪步骤结束时调用的回调函数。

callback_on_step_end_tensor_inputs (`list[str]`，*可选*) : 通过 `callback_kwargs` 暴露给回调的张量名称。

**返回值：**

[Ideogram4PipelineOutput](/docs/diffusers/main/zh/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)

将每个提示词重写为 Ideogram4 的原生结构化 JSON 描述。

需要可选的 `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)

用于使无头 Qwen3-VL `text_encoder` 具备提示词上采样生成能力的 LM head。

一个可选的流水线组件（`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`) : 长度为 `batch_size` 的去噪 PIL 图像列表，或形状为 `(batch_size, height, width, num_channels)` 的 numpy 数组。

Ideogram 4 管道的输出类。