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

|

36 kB

Z-Image

Z-Image là một mô hình tạo ảnh mạnh mẽ và cực kỳ hiệu quả với 6B tham số. Hiện tại chỉ có một mô hình, với hai mô hình khác sắp được phát hành:

Mô hình	Hugging Face
Z-Image-Turbo	https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

Z-Image-Turbo

Z-Image-Turbo là phiên bản đã được chưng cất (distilled) của Z-Image, đạt hoặc vượt trội so với các đối thủ hàng đầu chỉ với 8 NFEs (số lần đánh giá hàm). Nó cung cấp độ trễ suy luận dưới một giây trên các GPU H800 cấp doanh nghiệp và chạy thoải mái trên các thiết bị tiêu dùng có 16G VRAM. Mô hình này nổi bật trong việc tạo ảnh chân thực, hiển thị văn bản song ngữ (tiếng Anh & tiếng Trung) và tuân thủ chỉ dẫn một cách vững chắc.

Ảnh sang ảnh

Sử dụng ZImageImg2ImgPipeline để biến đổi một hình ảnh hiện có dựa trên một câu lệnh văn bản.

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

Sử dụng ZImageInpaintPipeline để vẽ lại các vùng cụ thể của một hình ảnh dựa trên mô tả văn bản và mặt nạ.

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)

Nguồn

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)

Nguồn

Tham số:

prompt (str hoặc list[str], tùy chọn) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền prompt_embeds thay thế.

height (int, tuỳ chọn, mặc định là 1024) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel.

width (int, tuỳ chọn, mặc định là 1024) : Độ rộng của hình ảnh được tạo ra, tính bằng pixel.

num_inference_steps (int, optional, mặc định là 50) : Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn, với cái giá là suy luận chậm hơn.

sigmas (list[float], optional) : Các sigma tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch hỗ trợ tham số sigmas trong phương thức set_timesteps của chúng. Nếu không được định nghĩa, hành vi mặc định khi num_inference_steps được truyền vào sẽ được sử dụng.

guidance_scale (float, optional, mặc định là 5.0) : Thang độ dẫn hướng như được định nghĩa trong Classifier-Free Diffusion Guidance. guidance_scale được định nghĩa là w của phương trình 2. trong Imagen Paper. Thang độ dẫn hướng được kích hoạt bằng cách đặt guidance_scale > 1. Thang độ dẫn hướng cao hơn khuyến khích tạo ra các hình ảnh gắn kết chặt chẽ với prompt văn bản, thường phải đánh đổi bằng chất lượng hình ảnh thấp hơn.

cfg_normalization (bool, tùy chọn, mặc định là False) : Có áp dụng chuẩn hóa cấu hình hay không.

cfg_truncation (float, tuỳ chọn, mặc định là 1.0) : Giá trị cắt cụt cho cấu hình.

negative_prompt (str hoặc list[str], tùy chọn) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền negative_prompt_embeds thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu guidance_scale nhỏ hơn 1).

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) : Một hoặc một danh sách torch generator để đảm bảo quá trình sinh là tất định.

latents (torch.FloatTensor, tùy chọn) : Các latents nhiễu đã được tạo trước, được lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo ra bằng cách lấy mẫu sử dụng generator ngẫu nhiên được cung cấp.

prompt_embeds (list[torch.FloatTensor], tùy chọn) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, vd. trọng số của prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào prompt.

negative_prompt_embeds (list[torch.FloatTensor], tùy chọn) : Các vector nhúng văn bản âm đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, vd. trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào negative_prompt.

output_type (str, tùy chọn, mặc định là "pil") : Định dạng đầu ra của hình ảnh được tạo. Chọn giữa PIL: PIL.Image.Image hoặc np.array.

return_dict (bool, tùy chọn, mặc định là True) : Có nên trả về một ~pipelines.stable_diffusion.ZImagePipelineOutput thay vì một tuple thông thường hay không.

joint_attention_kwargs (dict, tùy chọn) : Một từ điển kwargs mà nếu được chỉ định sẽ được truyền đến AttentionProcessor như đã định nghĩa dưới self.processor trong diffusers.models.attention_processor.

callback_on_step_end (Callable, tùy chọn) : Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs sẽ bao gồm một danh sách tất cả các tensor như được chỉ định bởi callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List, tùy chọn) : Danh sách các đầu vào tensor cho hàm callback_on_step_end. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham số callback_kwargs. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính ._callback_tensor_inputs của lớp pipeline của bạn.

max_sequence_length (int, tuỳ chọn, mặc định là 512) : Độ dài tối đa của chuỗi để sử dụng với prompt.

Trả về: ZImagePipelineOutput hoặc tuple

ZImagePipelineOutput nếu return_dict là True, ngược lại là một tuple. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:

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

Nguồn

Tham số:

scheduler (FlowMatchEulerDiscreteScheduler) : Một trình lập lịch được sử dụng kết hợp với transformer để khử nhiễu các latent ảnh đã mã hóa.

vae (AutoencoderKL) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn.

text_encoder (PreTrainedModel) : Một mô hình mã hóa văn bản để mã hóa các prompt văn bản.

tokenizer (AutoTokenizer) : Bộ phân từ để phân từ các prompt văn bản.

transformer (ZImageTransformer2DModel) : Một mô hình transformer ZImage để khử nhiễu các latents ảnh đã mã hóa.

Pipeline ZImage cho việc tạo ảnh từ ảnh.

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)

Nguồn

Tham số:

prompt (str hoặc list[str], tùy chọn) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền prompt_embeds thay thế.

image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], hoặc list[np.ndarray]) : Image, mảng numpy hoặc tensor đại diện cho một lô ảnh (image batch) được sử dụng làm điểm khởi đầu. Đối với cả mảng numpy và tensor pytorch, khoảng giá trị mong đợi nằm trong [0, 1]. Nếu là tensor hoặc danh sách các tensor, hình dạng mong đợi phải là (B, C, H, W) hoặc (C, H, W). Nếu là mảng numpy hoặc danh sách các mảng, hình dạng mong đợi phải là (B, H, W, C) hoặc (H, W, C).

strength (float, optional, mặc định là 0.6) : Chỉ định mức độ biến đổi ảnh tham chiếu image. Giá trị phải nằm trong khoảng từ 0 đến 1. image được dùng làm điểm khởi đầu và càng thêm nhiều nhiễu khi strength càng cao. Số bước khử nhiễu phụ thuộc vào lượng nhiễu ban đầu được thêm vào. Khi strength là 1, nhiễu được thêm vào là tối đa và quá trình khử nhiễu chạy đủ số lần lặp được chỉ định trong num_inference_steps. Giá trị 1 về cơ bản sẽ bỏ qua image.

height (int, tuỳ chọn, mặc định là 1024) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel. Nếu không được cung cấp, sẽ sử dụng chiều cao của hình ảnh đầu vào.

width (int, tuỳ chọn, mặc định là 1024) : Độ rộng của hình ảnh được tạo ra, tính bằng pixel. Nếu không được cung cấp, sẽ sử dụng độ rộng của hình ảnh đầu vào.