# Ideogram 4

Ideogram 4 là một mô hình text-to-image dựa trên flow-matching, sử dụng bộ mã hóa văn bản đa phương thức và một lược đồ classifier-free guidance bất đối xứng: một `unconditional_transformer` riêng biệt tạo ra nhánh âm với các đặc trưng văn bản được đặt về không, trong khi `transformer` chính xử lý chuỗi văn bản + hình ảnh đã đóng gói đầy đủ.

Các cài đặt mặc định của pipeline là các thiết lập được khuyến nghị để đạt chất lượng tốt nhất, do đó một lời gọi `pipe(prompt)` đơn giản sẽ tạo ra kết quả chất lượng cao nhất ngay khi sử dụng: 48 bước flow-matching trên lịch trình logit-normal (`mu=0.0`, `std=1.5`) với classifier-free guidance được giữ ở mức 7.0 cho các bước chính và giảm xuống 3.0 cho 3 bước "hoàn thiện" cuối cùng.

Các tùy chọn quan trọng khi suy luận được cung cấp qua lệnh gọi pipeline:

- `num_inference_steps`, `mu` và `std` kiểm soát lịch trình flow-matching logit-normal nhận thức độ phân giải.
- `guidance_scale` (hoặc một `guidance_schedule` đầy đủ cho từng bước) trộn lẫn các vận tốc có điều kiện và không điều kiện.

## Văn bản sang hình ảnh

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

## Mẫu hóa lại prompt

Ideogram 4 được huấn luyện trên mô tả dạng JSON có cấu trúc thay vì prompt tự do, do đó prompt ngắn nên được mở rộng thành schema gốc đó trước khi tạo ảnh. Có hai cách để tạo mô tả.

### Remote (Ideogram API)

Để đạt kết quả tốt nhất, hãy mở rộng prompt bằng API magic-prompt do Ideogram cung cấp và truyền caption trả về trực tiếp vào pipeline (lấy key tại [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 (trên thiết bị)

Để có một pipeline hoàn toàn cục bộ, hãy nạp một [Ideogram4PromptEnhancerHead](/docs/diffusers/v0.43.0/vi/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) nhỏ (đầu LM của Qwen3-VL) làm thành phần tùy chọn `prompt_enhancer_head` và truyền `prompt_upsampling=True`. Đầu này được ghép vào `text_encoder` dùng chung, nên không cần nạp thêm text encoder thứ hai. Cài đặt `outlines` cho các chú thích bị ràng buộc theo schema (checkpoint nf4 cũng cần `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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L141)

**Tham số:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Trình lập lịch flow-matching. Pipeline ghi đè lên lịch sigma mặc định bằng lịch logit-normal nhận thức độ phân giải.

vae (`AutoencoderKLFlux2`) : Auto-encoder biến phân được sử dụng để giải mã các ẩn (latents) trở lại thành hình ảnh.

text_encoder (`PreTrainedModel`) : Bộ mã hóa văn bản đa phương thức. Pipeline tiêu thụ các trạng thái ẩn từ một tập hợp cố định các lớp giải mã trung gian (xem `QWEN3_VL_ACTIVATION_LAYERS`).

tokenizer (`AutoTokenizer`) : Tokenizer đi kèm với `text_encoder`.

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer khớp dòng có điều kiện.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer flow-matching không điều kiện (asymmetric-CFG).

Pipeline tạo ảnh từ văn bản cho Ideogram4.

Ideogram4 là một mô hình flow-matching được huấn luyện với asymmetric classifier-free guidance: một `transformer` tiêu thụ các đặc trưng có điều kiện văn bản cùng với các latent của hình ảnh, trong khi một `unconditional_transformer` riêng biệt khử nhiễu với các đặc trưng văn bản được đặt về zero. Hai dự đoán velocity được trộn tuyến tính ở mỗi bước.

#### __call__[[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[str] = ['latents'])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

**Tham số:**

prompt (`str` hoặc `list[str]`) : Prompt để hướng dẫn tạo ảnh.

height (`int`, *tuỳ chọn*, mặc định là 2048) : Chiều cao ảnh đầu ra tính bằng pixel; phải là bội số của `vae_scale_factor * patch_size`.

width (`int`, *tuỳ chọn*, mặc định là 2048) : Độ rộng của ảnh đầu ra tính bằng pixel; phải là bội số của `vae_scale_factor * patch_size`.

num_inference_steps (`int`, *optional*, mặc định là 48) : Số bước flow-matching. Giá trị mặc định là cài đặt được khuyến nghị để đạt chất lượng tốt nhất.

guidance_scale (`float`, *optional*) : Thang độ dẫn hướng không điều kiện (classifier-free guidance) cố định được áp dụng ở mỗi bước. Dự đoán vận tốc có điều kiện và không điều kiện được trộn lẫn theo công thức `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. Loại trừ lẫn nhau với `guidance_schedule` (việc đặt cả hai sẽ gây lỗi). Mặc định là `None`.

guidance_schedule (`list[float]` hoặc `torch.Tensor`, *tuỳ chọn*) : Lịch trình thang độ dẫn hướng cho từng bước; phải có độ dài `num_inference_steps`. Mục đầu tiên tương ứng với bước đầu tiên (mức nhiễu lớn nhất). Loại trừ lẫn nhau với `guidance_scale`; chỉ được đặt đúng một trong hai. Mặc định là lịch trình được khuyến nghị (7.0 cho các bước chính, giảm xuống 3.0 cho 3 bước "hoàn thiện" cuối cùng). Để sử dụng thang độ không đổi, hãy truyền `guidance_scale` và `guidance_schedule=None`.

mu (`float`, *optional*, mặc định là 0.0) : Trung bình cơ bản của lịch trình khớp dòng logit-normal. Trung bình của lịch trình được dịch đi một nửa log của tỷ lệ độ phân giải so với 512x512.

std (`float`, *optional*, mặc định là 1.5) : Độ lệch chuẩn của lịch trình flow-matching logit-normal.

prompt_upsampling (`bool`, *tuỳ chọn*, mặc định là `False`) : Nếu `True`, viết lại `prompt` thành chú thích JSON có cấu trúc bản địa của Ideogram4 thông qua [upsample_prompt()](/docs/diffusers/v0.43.0/vi/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) trước khi mã hóa. Yêu cầu thành phần tuỳ chọn `prompt_enhancer_head`; cài đặt `outlines` để có chú thích bị ràng buộc theo schema. `generator` được tái sử dụng để đảm bảo quá trình upsampling có thể tái lập được.

prompt_upsampling_temperature (`float`, *tuỳ chọn*, mặc định là 1.0) : Nhiệt độ lấy mẫu cho việc tăng mẫu prompt khi `prompt_upsampling=True`.

max_sequence_length (`int`, *tuỳ chọn*, mặc định là 2048) : Số lượng token văn bản tối đa cho mỗi prompt.

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Bộ tạo (Generator) được sử dụng để làm cho việc lấy mẫu (sampling) trở nên tất định (deterministic).

latents (`torch.Tensor`, *tùy chọn*) : Nhiễu đã tạo trước có hình dạng `(batch_size, num_image_tokens, latent_dim)`.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Một trong số `"pil"`, `"np"`, `"pt"` hoặc `"latent"`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một [Ideogram4PipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) hay không.

attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs được truyền đến bộ xử lý chú ý của mỗi transformer. Một mục `"scale"` sẽ điều chỉnh các trọng số LoRA đã tải (ví dụ `{"scale": 0.7}`) khi backend PEFT đang hoạt động.

callback_on_step_end (`Callable`, *tùy chọn*) : Callback được gọi vào cuối mỗi bước khử nhiễu.

callback_on_step_end_tensor_inputs (`list[str]`, *tùy chọn*) : Tên của các tensor để phơi bày cho callback thông qua `callback_kwargs`.

**Trả về:**

[Ideogram4PipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) hoặc `tuple`.

Chạy tạo ảnh từ văn bản.

Ví dụ:
```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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

Chuẩn bị điều kiện cho chuỗi văn bản + hình ảnh đã đóng gói (một mục cho mỗi prompt).

Trả về một tuple phẳng `(prompt_embeds, position_ids, segment_ids, indicator)`. Nhánh không điều kiện không chứa văn bản, do đó pipeline xây dựng trực tiếp các đầu vào (đã đặt về không) của nó thay vì mã hóa một prompt tiêu cực.

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

Viết lại từng prompt thành chú thích JSON có cấu trúc theo định dạng gốc của Ideogram4.

Yêu cầu thành phần tùy chọn `prompt_enhancer_head`, được ghép vào thân `text_encoder` dùng chung để biến nó thành mô hình sinh. Việc sinh sẽ bị ràng buộc theo schema nếu `outlines` được cài đặt, ngược lại sẽ chạy không ràng buộc. Truyền `generator` (cùng một đối tượng được chấp nhận bởi `__call__`) để đảm bảo quá trình lấy mẫu có thể tái lập.

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

```python
diffusers.Ideogram4PromptEnhancerHead(hidden_size: int = 4096, vocab_size: int = 151936)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

LM head giúp `text_encoder` không có head của Qwen3-VL trở nên sinh tạo cho việc lấy mẫu lại prompt.

Một thành phần pipeline tùy chọn (`prompt_enhancer_head`): trọng số của nó được nạp thông qua `from_pretrained` thông thường (từ kho nhỏ riêng của nó, hoặc được đóng gói trong kho mô hình) thay vì tải xuống trong pipeline. Khi thực hiện upsample, pipeline kết hợp nó với phần thân `text_encoder` dùng chung để tạo thành mô hình sinh.

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ideogram4/pipeline_output.py#L24)

**Tham số:**

images (`list[PIL.Image.Image]` hoặc `np.ndarray`) : Danh sách các hình ảnh PIL đã khử nhiễu có độ dài `batch_size`, hoặc mảng numpy có hình dạng `(batch_size, height, width, num_channels)`.

Lớp đầu ra cho pipeline Ideogram 4.