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는 멀티모달 텍스트 인코더와 비대칭 classifier-free guidance 방식을 사용하는 flow-matching 텍스트-이미지 생성 모델입니다. 전용 unconditional_transformer가 텍스트 특징을 0으로 설정하여 negative branch를 생성하고, 메인 transformer는 전체 packed text + image 시퀀스를 처리합니다.

pipeline 기본값은 최고 품질을 위한 권장 설정이므로, 단순한 pipe(prompt) 호출만으로도开箱 최고 품질의 결과를 얻을 수 있습니다: logit-normal 스케줄(mu=0.0, std=1.5)에서 48개의 flow-matching 스텝을 수행하며, 주요 스텝에서는 classifier-free guidance를 7.0으로 유지하고 마지막 3개의 “polish” 스텝에서는 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를 사용하여 프롬프트를 확장하고, 반환된 캡션을 파이프라인에 그대로 전달하세요(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를 설치하세요(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 스케줄러입니다. 파이프라인은 기본 sigma 스케줄을 해상도 인식 logit-normal 스케줄로 오버라이드합니다.
  • vae (AutoencoderKLFlux2) — Latents를 이미지로 복원하는 데 사용되는 변분 오토인코더(Variational auto-encoder)입니다.
  • text_encoder (PreTrainedModel) — 멀티모달 텍스트 인코더입니다. 파이프라인은 고정된 중간 디코더 레이어 세트에서 숨겨진 상태를 소비합니다(자세한 내용은 QWEN3_VL_ACTIVATION_LAYERS를 참조하세요).
  • tokenizer (AutoTokenizer) — text_encoder와 짝을 이루는 토크나이저.
  • transformer (Ideogram4Transformer2DModel) — 조건부 flow-matching transformer.
  • unconditional_transformer (Ideogram4Transformer2DModel) — 무조건적(비대칭 CFG) flow-matching transformer.

Ideogram4용 텍스트-이미지 파이프라인.

Ideogram4는 비대칭 classifier-free guidance로 학습된 flow-matching 모델입니다. transformer는 이미지 latents와 함께 텍스트 조건 기능이 입력되며, 별도의 unconditional_transformer는 텍스트 기능이 제로로 설정된 상태로 denoise를 수행합니다. 두 velocity 예측값은 각 단계에서 선형으로 혼합됩니다.

__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, 선택 사항) — 모든 단계에서 적용되는 상수 classifier-free guidance scale입니다. 조건부 및 무조건부 velocity 예측은 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개의 “polish” 단계는 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일 때 프롬프트 업샘플링에 사용되는 샘플링 온도입니다.
  • max_sequence_length (int, 선택 사항, 기본값 2048) — 프롬프트당 최대 텍스트 토큰 수.
  • num_images_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성할 이미지의 수.
  • generator (torch.Generator 또는 list[torch.Generator], 선택 사항) — 샘플링을 결정적으로 만들기 위해 사용되는 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 )

패킹된 텍스트+이미지 시퀀스의 조건을 준비합니다(프롬프트당 1개 항목).

(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→