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

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）用于混合条件速度和无条件速度。

文本到图像

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 获取密钥）：

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（即 Qwen3-VL LM head）作为可选的 prompt_enhancer_head 组件，并传入 prompt_upsampling=True。该 head 会嫁接到共享的 text_encoder 上，因此无需加载第二个文本编码器。请安装 outlines 以支持基于 schema 约束的说明文本生成（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 调度器。该 pipeline 使用分辨率感知的 logit-normal 调度覆盖了默认的 sigma 调度。

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

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

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

transformer (Ideogram4Transformer2DModel)：条件流匹配 Transformer。

unconditional_transformer (Ideogram4Transformer2DModel)：无条件（非对称 CFG）流匹配 Transformer。

Ideogram4 的文本到图像流水线。

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

调用[[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，可选，默认值为 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() 将 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。

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

源代码

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

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

源代码

用于使无头 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]]

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

源代码

参数：

images (list[PIL.Image.Image] 或 np.ndarray) : 长度为 batch_size 的去噪 PIL 图像列表，或形状为 (batch_size, height, width, num_channels) 的 numpy 数组。

Ideogram 4 管道的输出类。