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 es un modelo de texto a imagen basado en flow-matching que utiliza un codificador de texto multimodal y un esquema de guía libre de clasificador asimétrico: un unconditional_transformer dedicado produce la rama negativa con características de texto puestas a cero, mientras que el transformer principal consume la secuencia completa empaquetada de texto + imagen.

Los valores predeterminados del pipeline son la configuración recomendada para obtener la mejor calidad, por lo que una llamada simple a pipe(prompt) produce resultados de la mejor calidad desde el inicio: 48 pasos de flow-matching en una programación logit-normal (mu=0.0, std=1.5) con classifier-free guidance mantenido en 7.0 para los pasos principales y reducido a 3.0 para los 3 pasos finales de “pulido”.

Los parámetros clave de tiempo de inferencia se exponen a través de la llamada de pipeline:

  • num_inference_steps, mu y std controlan el flujo de correspondencia logit-normal con resolución consciente.
  • guidance_scale (o un guidance_schedule completo por paso) combina las velocidades condicionales y no condicionales.

Texto a imagen

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

Ampliación de prompts

Ideogram 4 se entrena con una descripción en JSON estructurada en lugar de un prompt libre, por lo que es mejor expandir un prompt corto a ese esquema nativo antes de la generación. Hay dos formas de generar la descripción.

Remoto (API de Ideogram)

Para obtener los mejores resultados, expanda el prompt con la API magic-prompt alojada de Ideogram y pase la descripción devuelta directamente a la pipeline (obtenga una clave en 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 (en el dispositivo)

Para un pipeline totalmente local, cargue una pequeña Ideogram4PromptEnhancerHead (la cabeza LM de Qwen3-VL) como el componente opcional prompt_enhancer_head y pase prompt_upsampling=True. La cabeza se injerta en el text_encoder compartido, por lo que no se carga un segundo codificador de texto. Instale outlines para descripciones con restricciones de esquema (el punto de control nf4 también requiere 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

clase diffusers.Ideogram4Pipeline

< >

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

Parámetros

  • scheduler (FlowMatchEulerDiscreteScheduler) — Programador de flow-matching. El pipeline reemplaza el programa de sigma predeterminado con un programa logit-normal consciente de la resolución.
  • vae (AutoencoderKLFlux2) — Autoencoder variacional utilizado para decodificar los latentes de vuelta en imágenes.
  • text_encoder (PreTrainedModel) — Codificador de texto multimodal. El pipeline consume estados ocultos de un conjunto fijo de capas intermedias del decodificador (ver QWEN3_VL_ACTIVATION_LAYERS).
  • tokenizer (AutoTokenizer) — Tokenizer asociado a text_encoder.
  • transformer (Ideogram4Transformer2DModel) — Transformador de flujo condicional.
  • unconditional_transformer (Ideogram4Transformer2DModel) — Transformador de flow-matching incondicional (asymmetric-CFG).

Pipeline de texto a imagen para Ideogram4.

Ideogram4 es un modelo de flow-matching entrenado con guía libre de clasificador asimétrica: un transformer consume características condicionadas por texto junto con los latentes de la imagen, mientras que un unconditional_transformer separado realiza el desruido con características de texto puestas a cero. Las dos predicciones de velocidad se combinan linealmente en cada paso.

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

Parámetros

  • prompt (str o list[str]) — Prompt(s) para guiar la generación de imágenes.
  • height (int, opcional, valor predeterminado 2048) — Altura de la imagen de salida en píxeles; debe ser un múltiplo de vae_scale_factor * patch_size.
  • width (int, opcional, valor predeterminado 2048) — Ancho de la imagen de salida en píxeles; debe ser un múltiplo de vae_scale_factor * patch_size.
  • num_inference_steps (int, opcional, valor predeterminado 48) — Número de pasos de flow-matching. El valor predeterminado es la configuración recomendada para obtener la mejor calidad.
  • guidance_scale (float, opcional) — Escala de guía sin clasificador constante aplicada en cada paso. Las predicciones de velocidad condicionales y no condicionales se combinan como v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg. Es mutuamente excluyente con guidance_schedule (establecer ambos provoca un error). El valor predeterminado es None.
  • guidance_schedule (list[float] o torch.Tensor, opcional) — Programa de escala de guía por paso; debe tener longitud num_inference_steps. La primera entrada corresponde al primer paso (nivel de ruido más alto). Es mutuamente excluyente con guidance_scale; se debe establecer exactamente uno. Por defecto, utiliza el programa recomendado (7.0 para los pasos principales, bajando a 3.0 para los últimos 3 pasos de “pulido”). Para usar una escala constante en su lugar, pase guidance_scale y guidance_schedule=None.
  • mu (float, opcional, valor predeterminado 0.0) — Media base del programa de flow-matching logit-normal. La media del programa se desplaza la mitad del logaritmo de la proporción de resolución relativa a 512x512.
  • std (float, opcional, valor predeterminado 1.5) — Desviación estándar del programa de flow-matching logit-normal.
  • prompt_upsampling (bool, opcional, valor predeterminado False) — Si es True, reescribe prompt en la descripción JSON estructurada nativa de Ideogram4 mediante upsample_prompt() antes de codificarlo. Requiere el componente opcional prompt_enhancer_head; instala outlines para descripciones con esquema restringido. Se reutiliza generator para que el muestreo sea reproducible.
  • prompt_upsampling_temperature (float, opcional, valor predeterminado 1.0) — Temperatura de muestreo para el upsampling de prompts cuando prompt_upsampling=True.
  • max_sequence_length (int, opcional, valor predeterminado 2048) — Número máximo de tokens de texto por indicación.
  • num_images_per_prompt (int, opcional, valor predeterminado 1) — Número de imágenes a generar por indicación.
  • generator (torch.Generator o list[torch.Generator], opcional) — Generador(es) utilizados para hacer la muestreo determinista.
  • latents (torch.Tensor, opcional) — Ruido pregenerado de forma (batch_size, num_image_tokens, latent_dim).
  • output_type (str, opcional, valor predeterminado "pil") — Uno de "pil", "np", "pt" o "latent".
  • return_dict (bool, opcional, valor predeterminado True) — Si se debe devolver un Ideogram4PipelineOutput.
  • attention_kwargs (dict, opcional) — Un diccionario de kwargs que se pasa al procesador de atención de cada transformer. Una entrada "scale" escala los pesos de LoRA cargados (p. ej. {"scale": 0.7}) cuando el backend PEFT está activo.
  • callback_on_step_end (Callable, opcional) — Callback que se invoca al final de cada paso de desruido.
  • callback_on_step_end_tensor_inputs (list[str], opcional) — Nombres de los tensores que se expondrán al callback a través de callback_kwargs.

Ejecuta la generación de texto a imagen.

Ejemplos:

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

Prepara el condicionamiento para la secuencia empaquetada de texto+imagen (una entrada por prompt).

Devuelve una tupla plana (prompt_embeds, position_ids, segment_ids, indicator). La rama incondicional no lleva texto, por lo que el pipeline construye sus entradas (a ceros) directamente en lugar de codificar un prompt negativo.

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 )

Reescribe cada indicación en la descripción JSON estructurada nativa de Ideogram4.

Requiere el componente opcional prompt_enhancer_head, que se injerta en el cuerpo compartido text_encoder para hacerlo generativo. La generación está restringida por el esquema cuando outlines está instalado; de lo contrario, se ejecuta sin restricciones. Pasa generator (el mismo aceptado por __call__) para hacer que el muestreo sea reproducible.

Ideogram4PromptEnhancerHead

clase diffusers.Ideogram4PromptEnhancerHead

< >

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

LM head que hace que el text_encoder sin cabeza de Qwen3-VL sea generativo para el muestreo de prompts.

Un componente de pipeline opcional (prompt_enhancer_head): sus pesos se cargan mediante un from_pretrained normal (su propio repositorio pequeño, o incluido en el repositorio del modelo) en lugar de una descarga dentro del pipeline. En el momento del upsample, el pipeline lo combina con el cuerpo compartido text_encoder para formar el modelo generativo.

Ideogram4PipelineOutput

clase diffusers.pipelines.ideogram4.Ideogram4PipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

Parámetros

  • images (list[PIL.Image.Image] o np.ndarray) — Lista de imágenes PIL desruidadas de longitud batch_size, o matriz numpy de forma (batch_size, height, width, num_channels).

Clase de salida para el pipeline de Ideogram 4.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→