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

|

35.9 kB

Z-Image

Z-Imageは、6Bパラメータを持つ、強力かつ高効率な画像生成モデルです。現在、1つのモデルが公開されており、さらに2つのモデルがリリース予定です。

モデル	Hugging Face
Z-Image-Turbo	https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

Z-Image-Turbo

Z-Image-Turbo は、Z-Image の蒸留版であり、わずか 8 NFEs（Number of Function Evaluations）で主要な競合製品に匹敵する、あるいはそれを上回る性能を発揮します。エンタープライズグレードの H800 GPU では 1 秒未満の推論レイテンシを実現し、16G VRAM を備えたコンシューマーデバイスにも余裕で収まります。フォトリアリスティックな画像生成、バイリンガルなテキストレンダリング（英語 & 中国語）、そして堅牢な指示追従性に優れています。

画像から画像へ

ZImageImg2ImgPipeline を使用して、テキストプロンプトに基づいて既存の画像を変換します。

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

インペインティング

テキストプロンプトとマスクに基づいて画像の特定の領域をインペイントするには、ZImageInpaintPipelineを使用します。

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)

ソース

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)

ソース

パラメータ:

prompt (str または list[str]、省略可) : 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。

height (int、optional、デフォルト値は 1024) : 生成される画像のピクセル単位の縦幅。

width (int、任意、デフォルトは 1024) : 生成される画像の幅（ピクセル単位）。

num_inference_steps (int、任意、デフォルト値は 50) : デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常はより高品質な画像が得られます。

sigmas (list[float], 任意) : set_timesteps メソッドで sigmas 引数をサポートするスケジューラーにおいて、デノイジングプロセスに使用するカスタムシグマ。num_inference_steps が渡された場合のデフォルトの動作が使用されます。

guidance_scale (float、任意、デフォルト値は 5.0) : Classifier-Free Diffusion Guidanceで定義されているガイダンススケールです。guidance_scale は、Imagen Paperの式 2 の w として定義されています。guidance_scale > 1 を設定することで、ガイダンススケールが有効になります。ガイダンススケールを高くすると、prompt のテキストと密接に関連した画像の生成が促されますが、通常は画像の品質が低下する傾向があります。

cfg_normalization (bool、任意、デフォルトは False) : 設定の正規化を適用するかどうか。

cfg_truncation (float、任意、デフォルトは 1.0) : 設定用の切り捨て値です。

negative_prompt (str または list[str]、省略可能) : 画像生成をガイドしないプロンプトです。定義されていない場合、代わりに negative_prompt_embeds を渡す必要があります。ガイドを使用していない場合は無視されます（guidance_scale が 1 未満の場合は無視されます）。

num_images_per_prompt (int、任意、デフォルトは 1) : プロンプトごとに生成する画像の数。

generator (torch.Generator または list[torch.Generator]、任意) : 生成を決定論的にするための torch ジェネレーター 1 つまたはそのリスト。

latents (torch.FloatTensor, 任意) : 画像生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイズ付き潜在変数（latents）。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。

prompt_embeds (list[torch.FloatTensor]、任意) : 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。

negative_prompt_embeds (list[torch.FloatTensor]、任意) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。

output_type (str、任意、デフォルトは "pil") : 生成画像の出力形式。PIL（PIL.Image.Image）または np.array から選択します。

return_dict (bool、任意、デフォルトはTrue) : プレーンなタプルではなく~pipelines.stable_diffusion.ZImagePipelineOutputを返すかどうか。

joint_attention_kwargs (dict, 任意) : 指定された場合、diffusers.models.attention_processor の self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

callback_on_step_end (Callable、任意) : 推論中の各デノイジングステップの終了時に呼び出される関数です。この関数は、以下の引数とともに呼び出されます: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。 callback_kwargs には、callback_on_step_end_tensor_inputs で指定されたすべてのテンソルのリストが含まれます。

callback_on_step_end_tensor_inputs (List, 任意) : callback_on_step_end 関数へのテンソル入力のリストです。リストで指定されたテンソルは、callback_kwargs 引数として渡されます。パイプラインクラスの ._callback_tensor_inputs 属性にリストされている変数のみを包含できます。

max_sequence_length (int、任意、デフォルト値は 512) : prompt に使用する最大シーケンス長です。

戻り値: ZImagePipelineOutput または tuple

return_dict が True の場合は ZImagePipelineOutput、それ以外の場合は tuple を返します。tuple を返す場合、最初の要素は生成された画像のリストです。

生成用のパイプラインを呼び出したときに実行される関数。

例:

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

ソース

パラメータ:

scheduler (FlowMatchEulerDiscreteScheduler) : transformer と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラー。

vae (AutoencoderKL) : 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (PreTrainedModel) : テキストプロンプトをエンコードするためのテキストエンコーダーモデル。

tokenizer (AutoTokenizer) : テキストプロンプトをトークン化するトークナイザー。

transformer (ZImageTransformer2DModel) : エンコードされた画像潜在変数をデノイズするための ZImage トランスフォーマーモデル。

画像から画像への生成を行うZImageパイプライン。

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)

ソース

パラメータ:

prompt (str または list[str]、省略可) : 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。

image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image]、または list[np.ndarray]) : 開始点として使用する画像バッチを表す Image、numpy 配列、またはテンソル。numpy 配列および PyTorch テンソルの両方について、想定される値の範囲は [0, 1] です。テンソルまたはテンソルのリストの場合、想定される形状は (B, C, H, W) または (C, H, W) です。numpy 配列または配列のリストの場合、想定される形状は (B, H, W, C) または (H, W, C) です。

strength (float、任意、デフォルト値は 0.6) : 参照となる image を変換する度合いを示します。0 から 1 の間の値である必要があります。image が起点として使用され、strength の値が大きいほど、より多くのノイズが追加されます。デノイジングのステップ数は、最初に追加されるノイズの量に依存します。strength が 1 の場合、追加されるノイズは最大となり、num_inference_steps で指定された全イテレーション数にわたってデノイジングプロセスが実行されます。値が 1 である場合、image は実質的に無視されます。

height (int、任意、デフォルトは 1024) : 生成される画像のピクセル単位の縦幅です。指定されない場合、入力画像の縦幅が使用されます。

width (int、任意、デフォルトは 1024) : 生成される画像の幅（ピクセル単位）。指定しない場合、入力画像の幅が使用されます。