Diffusers documentation
Ideogram 4
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 chuyên dụng 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 “polish” 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,muvàstdkiểm soát lịch trình flow-matching logit-normal nhận thức độ phân giải.guidance_scale(hoặc mộtguidance_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 dạng 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 ra mô tả.
Từ xa (API Ideogram)
Để đạt kết quả tốt nhất, hãy mở rộng prompt bằng API magic-prompt do Ideogram lưu trữ 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")Cục bộ (trên thiết bị)
Để có một pipeline hoàn toàn cục bộ, hãy tải 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 tải thêm text encoder thứ hai. Cài đặt outlines cho các chú thích có 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
lớp diffusers.Ideogram4Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: Ideogram4Transformer2DModelunconditional_transformer: Ideogram4Transformer2DModelprompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None )
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) — Biến thể tự mã hóa (variational auto-encoder) được dùng để giải mã các ẩn (latents) trở lại thành ảnh. - text_encoder (
PreTrainedModel) — Bộ mã hóa văn bản đa phương thức. Pipeline sử dụng 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 (xemQWEN3_VL_ACTIVATION_LAYERS). - tokenizer (
AutoTokenizer) — Tokenizer đi kèm vớitext_encoder. - transformer (Ideogram4Transformer2DModel) — Transformer flow-matching 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 nhận 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__
< source >( 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'] )
Tham số
- prompt (
strhoặclist[str]) — Prompt để hướng dẫn tạo ảnh. - height (
int, tùy chọn, mặc định là 2048) — Chiều cao của ảnh đầu ra tính bằng pixel; phải là bội số củavae_scale_factor * patch_size. - width (
int, tùy chọn, mặc định là 2048) — Chiều rộng của ảnh đầu ra tính bằng pixel; phải là bội số củavae_scale_factor * patch_size. - num_inference_steps (
int, tùy chọn, 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, tùy chọn) — Thang độ hướng dẫn phân loại không điều kiện (classifier-free guidance) cố định được áp dụng ở mỗi bước. Cá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ứcv = guidance_scale * v_pos + (1 - guidance_scale) * v_neg. Xung đột vớiguidance_schedule(việc đặt cả hai sẽ gây lỗi). Mặc định làNone. - guidance_schedule (
list[float]hoặctorch.Tensor, tùy chọn) — Lịch trình thang độ dẫn hướng cho từng bước; phải có độ dài bằngnum_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ớiguidance_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 thay thế, hãy truyềnguidance_scalevàguidance_schedule=None. - mu (
float, tuỳ chọn, mặc định là 0.0) — Trung bình cơ bản của lịch trình flow-matching 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, tuỳ chọn, mặc định là 1.5) — Độ lệch chuẩn của lịch trình flow-matching logit-normal. - prompt_upsampling (
bool, tùy chọn, mặc định làFalse) — NếuTrue, viết lạipromptthà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 tùy chọnprompt_enhancer_head; cài đặtoutlinesđể có chú thích bị ràng buộc theo schema.generatorđược tái sử dụng để quá trình mở rộng có thể tái lập được. - prompt_upsampling_temperature (
float, tùy chọn, mặc định là 1.0) — Nhiệt độ lấy mẫu cho việc mở rộng prompt khiprompt_upsampling=True. - max_sequence_length (
int, tùy 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, tùy chọn, mặc định là 1) — Số lượng hình ảnh cần tạo cho mỗi prompt. - generator (
torch.Generatorhoặclist[torch.Generator], tùy chọn) — Bộ sinh được sử dụng để làm cho quá trình lấy mẫu (sampling) trở nên tất định (deterministic). - latents (
torch.Tensor, tùy chọn) — Nhiễu được 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"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ý attention 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 quacallback_kwargs.
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
< source >( prompt: str | list[str]grid_h: intgrid_w: intmax_sequence_length: intdevice: device )
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
< source >( 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 )
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 để
khiến nó có khả năng sinh. Việc sinh bị ràng buộc theo schema khi outlines được cài đặt, nếu không thì 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__) để làm cho việc lấy mẫu có thể tái lập được.
Ideogram4PromptEnhancerHead
lớp diffusers.Ideogram4PromptEnhancerHead
< source >( hidden_size: int = 4096vocab_size: int = 151936 )
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
lớp diffusers.pipelines.ideogram4.Ideogram4PipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
Lớp đầu ra cho pipeline Ideogram 4.