diffusers/main/vi/api/pipelines/ideogram4.md

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

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

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

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

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

Tham số:

scheduler (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) : Transformer khớp dòng có điều kiện.

unconditional_transformer (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]]

__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

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() 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 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 hoặc tuple.

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

Ví dụ:

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

encode_prompt(prompt: str | list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)

Nguồn

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

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

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

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

Nguồn

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

diffusers.pipelines.ideogram4.Ideogram4PipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)

Nguồn

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.