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 是一个基于流匹配的文本生成图像模型，它采用多模态文本编码器和非对称的无分类器引导方案：专用的 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 描述而非自由形式的提示词进行训练的，因此在生成之前，最好将简短的提示词扩展为该原生模式。生成描述有两种方式。

远程（Ideogram API）

为获得最佳效果，请使用 Ideogram 托管的 magic-prompt API 扩展提示词，并将返回的 caption 直接传入 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")

本地（设备端）

对于完全本地化的流水线，请加载一个小型的 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

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: Ideogram4Transformer2DModelunconditional_transformer: Ideogram4Transformer2DModelprompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None )

参数

  • scheduler (FlowMatchEulerDiscreteScheduler) — Flow-matching 调度器。该流水线使用分辨率感知的 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 则在文本特征置零的情况下执行去噪。每一步中，两个速度预测值会进行线性混合。

__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，可选) — 在每一步中应用的恒定无分类器引导尺度。条件速度预测和无条件速度预测按 v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg 进行混合。 与 guidance_schedule 互斥（同时设置两者会引发错误）。默认值为 None。
  • guidance_schedule (list[float] 或 torch.Tensor，可选) — 逐步 guidance scale 调度；长度必须为 num_inference_steps。第一个元素对应第一步（噪声水平最高）。与 guidance_scale 互斥；必须且只能设置其中一个。默认使用推荐调度（主步骤为 7.0，最后 3 个“抛光”步骤降至 3.0）。若要使用恒定 scale，请传入 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 时，用于 prompt upsampling 的采样温度。
  • 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 暴露给回调的张量名称。

运行文本到图像生成。

示例：

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

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

需要可选的 prompt_enhancer_head 组件，该组件会嫁接到共享的 text_encoder 主体上，使其具备生成能力。如果已安装 outlines，则生成过程受模式约束；否则，生成过程不受约束。传入 generator（与 __call__ 接受的相同）可使采样过程可复现。

Ideogram4PromptEnhancerHead

class diffusers.Ideogram4PromptEnhancerHead

< >

( hidden_size: int = 4096vocab_size: int = 151936 )

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

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

Ideogram 4 管道的输出类。

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→