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

|

raw

120 kB

Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。

このファイルは、ライセンスに準拠した場合にのみ使用できます。

ライセンスのコピーは以下から入手できます

http://www.apache.org/licenses/LICENSE-2.0

適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア

ライセンスに基づき配布される本ソフトウェアは、「現状のまま」

明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。

権限を管理する特定の言語については、ライセンスを参照してください。

ライセンスの下での制限。-->

QwenImage

QwenチームによるQwen-Imageは、Qwenシリーズの画像生成基盤モデルであり、複雑なテキストレンダリングと精密な画像編集において大きな進歩を遂げています。実験により、画像生成および編集の両方で優れた汎用性が示されており、特に中国語におけるテキストレンダリングで卓越したパフォーマンスを発揮しています。

Qwen-Imageには、以下のバリエーションがあります。

モデルタイプ	モデルID
Qwen-Image	`Qwen/Qwen-Image`
Qwen-Image-Edit	`Qwen/Qwen-Image-Edit`
Qwen-Image-Edit Plus	Qwen/Qwen-Image-Edit-2509

Cachingガイドを参照し、中間出力を保存して再利用することで推論を高速化できます。

より高速な推論のためのLoRA

lightx2v/Qwen-Image-Lightning の LoRA を使用して、ステップ数を減らし、推論を高速化します。以下のコードスニペットを参照してください。

コード

from diffusers import DiffusionPipeline, FlowMatchEulerDiscreteScheduler
import torch 
import math

ckpt_id = "Qwen/Qwen-Image"

# From
# https://github.com/ModelTC/Qwen-Image-Lightning/blob/342260e8f5468d2f24d084ce04f55e101007118b/generate_with_diffusers.py#L82C9-L97C10
scheduler_config = {
    "base_image_seq_len": 256,
    "base_shift": math.log(3),  # We use shift=3 in distillation
    "invert_sigmas": False,
    "max_image_seq_len": 8192,
    "max_shift": math.log(3),  # We use shift=3 in distillation
    "num_train_timesteps": 1000,
    "shift": 1.0,
    "shift_terminal": None,  # set shift_terminal to None
    "stochastic_sampling": False,
    "time_shift_type": "exponential",
    "use_beta_sigmas": False,
    "use_dynamic_shifting": True,
    "use_exponential_sigmas": False,
    "use_karras_sigmas": False,
}
scheduler = FlowMatchEulerDiscreteScheduler.from_config(scheduler_config)
pipe = DiffusionPipeline.from_pretrained(
    ckpt_id, scheduler=scheduler, dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
pipe.load_lora_weights(
    "lightx2v/Qwen-Image-Lightning", weight_name="Qwen-Image-Lightning-8steps-V1.0.safetensors"
)

prompt = "a tiny astronaut hatching from an egg on the moon, Ultra HD, 4K, cinematic composition."
negative_prompt = " "
image = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1024,
    height=1024,
    num_inference_steps=8,
    true_cfg_scale=1.0,
    generator=torch.manual_seed(0),
).images[0]
image.save("qwen_fewsteps.png")

パイプラインの guidance_scale パラメータは、将来リリースされるガイダンス蒸留モデルをサポートするために用意されています。なお、パイプラインに guidance_scale を渡しても効果はありません。Classifier-free guidance を有効にするには、true_cfg_scale と negative_prompt を渡してください（" " のような空の negative prompt でも、classifier-free guidance の計算は有効になります）。

QwenImageEditPlusPipelineによる複数画像参照

QwenImageEditPlusPipelineでは、複数の画像を入力リファレンスとして指定できます。

import torch
from PIL import Image
from diffusers import QwenImageEditPlusPipeline
from diffusers.utils import load_image

pipe = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2509", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

image_1 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/grumpy.jpg")
image_2 = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/peng.png")
image = pipe(
    image=[image_1, image_2],
    prompt='''put the penguin and the cat at a game show called "Qwen Edit Plus Games"''',
    num_inference_steps=50
).images[0]

パフォーマンス

torch.compile

transformer に torch.compile を適用すると、約 2.4 倍の高速化が得られます（A100 80GB: 4.70s → 1.93s）：

import torch
from diffusers import QwenImagePipeline

pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
pipe.transformer = torch.compile(pipe.transformer)

# First call triggers compilation (~7s overhead)
# Subsequent calls run at ~2.4x faster
image = pipe("a cat", num_inference_steps=50).images[0]

可変長のプロンプトを用いたバッチ推論

プロンプトの長さが異なる場合にclassifier-free guidance (CFG)を使用すると、パイプラインはアテンションマスキングを通じてパディングを適切に処理します。これにより、パディングトークンが生成された出力に影響を与えないことが保証されます。

# CFG with different prompt lengths works correctly
image = pipe(
    prompt="A cat",
    negative_prompt="blurry, low quality, distorted",
    true_cfg_scale=3.5,
    num_inference_steps=50,
).images[0]

詳細なベンチマークスクリプトと結果については、この gistを参照してください。

QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline[[diffusers.QwenImagePipeline]]

diffusers.QwenImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

ソース

パラメータ:

transformer (QwenImageTransformer2DModel) : エンコードされた画像潜在変数をデノイズするための条件付き Transformer (MMDiT) アーキテクチャ。

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

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

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct、具体的には Qwen2.5-VL-7B-Instruct バリアントです。

tokenizer (Qwen2Tokenizer) : クラス https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer の Tokenizer

テキストから画像を生成するためのQwenImageパイプライン。

call[[diffusers.QwenImagePipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, 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 を渡す必要があります。

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

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

height (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像のピクセル単位の縦幅。最適な結果を得るため、デフォルトでは 1024 に設定されています。

width (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像の幅（ピクセル単位）。最適な結果を得るため、デフォルトでは 1024 に設定されています。

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

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

guidance_scale (float、任意、デフォルトは None) : ガイダンス蒸留モデル用のガイダンススケール値です。従来の classifier-free guidance では、推論時にノイズ予測の再スケーリングを通じてガイダンススケールが適用されますが、ガイダンス蒸留モデルでは、フォワードパス中にガイダンススケールを直接入力パラメータとして受け取ります。guidance_scale > 1 を設定することでガイダンススケールが有効になります。ガイダンススケールを高くすると、prompt のテキストと密接に関連した画像の生成が促されますが、通常は画像品質の低下を伴います。このパラメータは、将来登場するガイダンス蒸留モデルをサポートするためにパイプラインに用意されています。ガイダンス蒸留モデルを使用しない場合は無視されます。従来の classifier-free guidance を有効にするには、true_cfg_scale > 1.0 と negative_prompt（" " のような空の negative prompt でも classifier-free guidance の計算を有効にします）を渡してください。

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

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

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

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

prompt_embeds_mask (torch.Tensor, 任意) : prompt_embeds用のアテンションマスク。

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

negative_prompt_embeds_mask (torch.Tensor, 任意) : negative_prompt_embeds 用のアテンションマスク。

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

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

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 に使用する最大シーケンス長。

戻り値: ~pipelines.qwenimage.QwenImagePipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers import QwenImagePipeline

>>> pipe = QwenImagePipeline.from_pretrained("Qwen/Qwen-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50).images[0]
>>> image.save("qwenimage.png")

encode_prompt[[diffusers.QwenImagePipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024)

ソース

パラメータ:

prompt (str または list[str]、省略可能) : エンコードするプロンプト

device : (torch.device): torch デバイス

num_images_per_prompt (int) : プロンプトごとに生成すべき画像の数

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

QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline[[diffusers.QwenImageImg2ImgPipeline]]

diffusers.QwenImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen2_5_VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: QwenImageTransformer2DModel)

ソース

パラメータ:

transformer (QwenImageTransformer2DModel) : エンコードされた画像潜在変数をデノイズするための条件付き Transformer (MMDiT) アーキテクチャ。

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

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

text_encoder (Qwen2.5-VL-7B-Instruct) : Qwen2.5-VL-7B-Instruct、具体的には Qwen2.5-VL-7B-Instruct バリアントです。

tokenizer (Qwen2Tokenizer) : クラス https://huggingface.co/docs/transformers/en/model_doc/qwen2#transformers.Qwen2Tokenizer の Tokenizer

テキストから画像を生成するためのQwenImageパイプライン。

call[[diffusers.QwenImageImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, true_cfg_scale: float = 4.0, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, height: int | None = None, width: int | None = None, strength: float = 0.6, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float | None = None, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, 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 を渡す必要があります。

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

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) です。image として画像の潜在変数（latents）を受け取ることもできますが、潜在変数を直接渡す場合は、再度エンコードされません。

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

height (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像のピクセル単位の縦幅。最適な結果を得るため、デフォルトでは 1024 に設定されています。

width (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像の幅（ピクセル単位）。最適な結果を得るため、デフォルトでは 1024 に設定されています。

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