hf-doc-build/doc / diffusers /main /id /api /pipelines /z_image.md

|

32.2 kB

Z-Image

Z-Image adalah model generasi gambar yang kuat dan sangat efisien dengan 6B parameter. Saat ini hanya ada satu model, dengan dua model lagi yang akan dirilis:

Model	Hugging Face
Z-Image-Turbo	https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

Z-Image-Turbo

Z-Image-Turbo adalah versi terdistil dari Z-Image yang menyamai atau melampaui pesaing utama dengan hanya 8 NFEs (Number of Function Evaluations). Model ini menawarkan latensi inferensi di bawah satu detik pada GPU H800 kelas enterprise dan muat dengan nyaman dalam perangkat konsumen dengan VRAM 16G. Z-Image-Turbo unggul dalam generasi gambar fotorealistis, render teks dwibahasa (Inggris & Mandarin), serta kepatuhan instruksi yang kuat.

Gambar-ke-gambar

Gunakan ZImageImg2ImgPipeline untuk mengubah gambar yang sudah ada berdasarkan prompt teks.

import torch
from diffusers import ZImageImg2ImgPipeline
from diffusers.utils import load_image

pipe = ZImageImg2ImgPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
image = pipe(
    prompt,
    image=init_image,
    strength=0.6,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_img2img.png")

Inpainting

Gunakan ZImageInpaintPipeline untuk inpaint area tertentu pada gambar berdasarkan prompt teks dan mask.

import torch
import numpy as np
from PIL import Image
from diffusers import ZImageInpaintPipeline
from diffusers.utils import load_image

pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

# Create a mask (white = inpaint, black = preserve)
mask = np.zeros((1024, 1024), dtype=np.uint8)
mask[256:768, 256:768] = 255  # Inpaint center region
mask_image = Image.fromarray(mask)

prompt = "A beautiful lake with mountains in the background"
image = pipe(
    prompt,
    image=init_image,
    mask_image=mask_image,
    strength=1.0,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_inpaint.png")

ZImagePipeline[[diffusers.ZImagePipeline]]

diffusers.ZImagePipeline[[diffusers.ZImagePipeline]]

diffusers.ZImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)

Sumber

call[[diffusers.ZImagePipeline.call]]

__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus melewatkan prompt_embeds sebagai gantinya.

height (int, opsional, default 1024) : Tinggi gambar yang dihasilkan dalam piksel.

width (int, opsional, default 1024) : Lebar gambar yang dihasilkan dalam piksel.

num_inference_steps (int, opsional, defaultnya 50) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.

sigmas (list[float], opsional) : Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas di metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.

guidance_scale (float, opsional, default 5.0) : Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. pada Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.

cfg_normalization (bool, opsional, defaultnya False) : Apakah akan menerapkan normalisasi konfigurasi.

cfg_truncation (float, opsional, default 1.0) : Nilai pemotongan untuk konfigurasi.

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).

num_images_per_prompt (int, opsional, default 1) : Jumlah gambar yang akan dihasilkan per prompt.

generator (torch.Generator atau list[torch.Generator], opsional) : Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.

latents (torch.FloatTensor, opsional) : Laten berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor laten akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.

prompt_embeds (list[torch.FloatTensor], opsional) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

negative_prompt_embeds (list[torch.FloatTensor], opsional) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.

output_type (str, opsional, defaultnya "pil") : Format output dari gambar yang dihasilkan. Pilih antara PIL: PIL.Image.Image atau np.array.

return_dict (bool, opsional, defaultnya True) : Apakah akan mengembalikan ~pipelines.stable_diffusion.ZImagePipelineOutput alih-alih tuple biasa.

joint_attention_kwargs (dict, opsional) : Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.

callback_on_step_end (Callable, opsional) : Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List, opsional) : Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.

max_sequence_length (int, opsional, default 512) : Panjang maksimum urutan yang digunakan dengan prompt.

Mengembalikan: ZImagePipelineOutput atau tuple

ZImagePipelineOutput jika return_dict bernilai True, selain itu berupa tuple. Saat mengembalikan tuple, elemen pertama adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> import torch
>>> from diffusers import ZImagePipeline

>>> pipe = ZImagePipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> # Optionally, set the attention backend to flash-attn 2 or 3, default is SDPA in PyTorch.
>>> # (1) Use flash attention 2
>>> # pipe.transformer.set_attention_backend("flash")
>>> # (2) Use flash attention 3
>>> # pipe.transformer.set_attention_backend("_flash_3")

>>> prompt = "一幅为名为“造相「Z-IMAGE-TURBO」”的项目设计的创意海报。画面巧妙地将文字概念视觉化：一辆复古蒸汽小火车化身为巨大的拉链头，正拉开厚厚的冬日积雪，展露出一个生机盎然的春天。"
>>> image = pipe(
...     prompt,
...     height=1024,
...     width=1024,
...     num_inference_steps=8,
...     guidance_scale=0.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage.png")

ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

diffusers.ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

diffusers.ZImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)

Sumber

Parameter:

scheduler (FlowMatchEulerDiscreteScheduler) : Penjadwal yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.

vae (AutoencoderKL) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.

text_encoder (PreTrainedModel) : Model pengkode teks untuk mengkodekan prompt teks.

tokenizer (AutoTokenizer) : Tokenizer untuk melakukan tokenisasi prompt teks.

transformer (ZImageTransformer2DModel) : Model transformer ZImage untuk menghilangkan noise pada latens gambar yang telah dikodekan.

Pipeline ZImage untuk generasi gambar-ke-gambar.

call[[diffusers.ZImageImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.6, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus melewatkan prompt_embeds sebagai gantinya.

image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], atau list[np.ndarray]) : Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk digunakan sebagai titik awal. Untuk array numpy dan tensor pytorch, rentang nilai yang diharapkan adalah antara [0, 1]. Jika berupa tensor atau daftar tensor, bentuk yang diharapkan adalah (B, C, H, W) atau (C, H, W). Jika berupa array numpy atau daftar array, bentuk yang diharapkan adalah (B, H, W, C) atau (H, W, C).

strength (float, opsional, default 0.6) : Menunjukkan sejauh mana image referensi akan ditransformasi. Nilai harus berada di antara 0 dan 1. image digunakan sebagai titik awal, dan semakin tinggi nilai strength, semakin banyak noise yang ditambahkan. Jumlah langkah denoising bergantung pada jumlah noise yang ditambahkan di awal. Ketika strength bernilai 1, noise yang ditambahkan maksimal dan proses denoising berjalan untuk jumlah iterasi penuh yang ditentukan dalam num_inference_steps. Nilai 1 pada dasarnya mengabaikan image.

height (int, opsional, default 1024) : Tinggi gambar yang dihasilkan dalam piksel. Jika tidak diberikan, menggunakan tinggi gambar input.

width (int, opsional, default 1024) : Lebar gambar yang dihasilkan dalam piksel. Jika tidak disediakan, menggunakan lebar gambar input.