# Ideogram 4

Ideogram 4는 멀티모달 텍스트 인코더와 비대칭 classifier-free guidance 방식을 사용하는 flow-matching 텍스트-이미지 생성 모델입니다. 전용 `unconditional_transformer`가 텍스트 특징을 제로로 설정하여 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` 전체)은 조건부 및 무조건부 속도를 혼합합니다.

## 텍스트-이미지

```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를 사용하여 프롬프트를 확장하고, 반환된 캡션을 파이프라인에 그대로 전달하세요 ([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/ko/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead)(Qwen3-VL LM head)를 선택적 `prompt_enhancer_head` 구성 요소로 로드하고 `prompt_upsampling=True`를 전달하세요. 이 head는 공유된 `text_encoder`에 이식되므로 두 번째 텍스트 인코더는 로드되지 않습니다. 스키마 제약이 있는 캡션을 생성하려면 `outlines`를 설치하세요(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/ko/api/schedulers/flow_match_euler_discrete#diffusers.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](/docs/diffusers/main/ko/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : 조건부 flow-matching transformer.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/ko/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : 무조건적(비대칭 CFG) flow-matching transformer.

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

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

#### __호출__[[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 scale입니다. 조건부 및 무조건부 속도 예측은 `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()](/docs/diffusers/main/ko/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) : 프롬프트당 최대 텍스트 토큰 수.

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](/docs/diffusers/main/ko/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/ko/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)

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

`(prompt_embeds, position_ids, segment_ids, indicator)`의 평탄한 튜플을 반환합니다. 무조건 분기는 텍스트를 포함하지 않으므로, 파이프라인은 negative prompt를 인코딩하는 대신 (제로로 초기화된) 입력을 직접 구성합니다.

#### 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 파이프라인의 출력 클래스입니다.