Diffusers documentation
Qwen-Image 2.1
Qwen-Image 2.1
Qwen-Image 2.1 は、プロンプトと条件画像を Qwen3-VL モデルで一緒にエンコードし、その後、単一ストリームのブロック因果型 Transformer を用いてターゲット画像のノイズ除去を行います。ブロック因果型アテンション、アテンションプロセッサ、および causal_condition については、QwenImage21Transformer2DModel を参照してください。
デフォルト値は Qwen が推奨する値です: 40 ステップ、guidance なし。negative_prompt と true_cfg_scale > 1 を一緒に渡すことで classifier-free guidance を有効にできますが、これによりステップごとの計算量が2倍になります。
import torch
from diffusers import QwenImage21Pipeline
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16).to("cuda")
# Text-to-image
image = pipe("A capybara wearing a wizard hat, oil painting").images[0]
image.save("t2i.png")
# Image-conditioned editing
edited = pipe("Move it to a snowy mountain top", image=image).images[0]
edited.save("edit.png")複数の条件画像
image にリストを渡すと、各エントリが結合シーケンス内の独立したブロックになります。Qwen3-VL エンコーダーはこれらをビジョンコンテキストとして認識し、VAE はそれらの潜在トークンを提供します。ブロック因果的アテンションにより、各ブロック内部では双方向のアテンションが適用され、後続のブロックやターゲット画像が先行するブロックにアテンションを向けることが可能になります。したがって、リストを渡す順序が、モデルがそれらを解釈する順序となります。
edited = pipe("Put the flowers from the first image into the second scene", image=[flowers, scene]).images[0]flex_attentionによる高速なattention
デフォルトのQwenImage21AttnProcessorは、ブロック因果プリフィルをプレフィックスセグメントごとに1回のアテンション呼び出しとして実行します。コンパイルは不要で、どのPyTorchビルドでも動作します。QwenImage21FlexAttnProcessorは、同じマスクを単一のflex_attention呼び出しとして表現し、モデルがコンパイルされた後は高速になります。
flex プロセッサーに切り替える際は、モデルをコンパイルしてください。コンパイルされていない
flex_attentionは、fp32 で完全なアテンションスコア行列を生成するため、高速解像度でははるかに遅く、メモリ不足に陥ります。
from diffusers.models.transformers.transformer_qwenimage21 import QwenImage21FlexAttnProcessor
pipe.transformer.set_attn_processor(QwenImage21FlexAttnProcessor())
pipe.transformer.compile()単一ファイルのチェックポイントの読み込み
import torch
from diffusers import QwenImage21Pipeline, QwenImage21Transformer2DModel
transformer = QwenImage21Transformer2DModel.from_single_file(
"https://huggingface.co/Comfy-Org/Qwen-Image-2.1/blob/main/diffusion_models/qwen_image_2.1_bf16.safetensors",
dtype=torch.bfloat16,
)
pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", transformer=transformer, dtype=torch.bfloat16).to(
"cuda"
)サンプリングシグマ
モデルの作成者は、パイプライン設定内のsample_sigmasでデフォルトのサンプリンググリッドを設定できます。リリースされたチェックポイントを読み込むと、そのデフォルトのグリッドとスケジューラーの設定が自動的に復元されます。
実行時に別のグリッドをテストするには、パイプラインの呼び出しにsigmasを渡します:
# Use the checkpoint's default sampling grid.
image = pipe(prompt).images[0]
# Override the default grid for this call.
image = pipe(prompt, sigmas=[1.0, 0.8, 0.5, 0.2]).images[0]上記のカスタムグリッドはAPIの仕組みを示しています。生成品質はチェックポイントとグリッドに依存します。Sigmaのリストには、スケジューラが末尾に追加するターミナルsigmaは含まれません。明示的に指定したsigmasは、設定済みのsample_sigmasを上書きし、どちらかのリストがnum_inference_stepsの代わりにステップ数を決定します。どちらも指定されない場合、パイプラインはnum_inference_stepsを使用してスケジュールを生成します。スケジューラは、どちらのグリッドに対しても設定済みの処理を適用します。
モジュール化
Qwen-Image 2.1 は モジュール型パイプライン としても利用できます。同じブロックがテキストから画像への生成と、画像条件付き生成を実行します。1 つ以上の画像を条件として指定するには、image を渡します。Classifier-free guidance は true_cfg_scale の呼び出し引数ではなく、guider コンポーネントを通じて設定します。また、プレフィックス KV キャッシュはデフォルトで有効になっており、use_kv_cache=False を指定すると無効になります。
import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline
pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")
image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]
# Turn classifier-free guidance on for an edit.
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=4.0))
edited = pipe(prompt="Move it to a snowy mountain top", negative_prompt="blurry", image=image).images[0]Turbo チェックポイントは独自のブロック (QwenImage21TurboAutoBlocks) にマッピングされます。guider なしで動作し、negative_prompt を受け取らず、チェックポイントに同梱されているシグマグリッドをサンプリングします。ModularPipeline.from_pretrained は、チェックポイントの config 内の sample_sigmas エントリから Turbo ブロックを選択するため、設定は不要です:
import torch
from diffusers import ModularPipeline
pipe = ModularPipeline.from_pretrained("Qwen/Qwen-Image-2.1-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")
image = pipe(prompt="A capybara wearing a wizard hat, oil painting").images[0]QwenImage21Pipeline
class diffusers.QwenImage21Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImage21text_encoder: Qwen3VLForConditionalGenerationprocessor: Qwen3VLProcessortransformer: QwenImage21Transformer2DModelsample_sigmas: list[float] | None = None )
パラメータ
- scheduler (FlowMatchEulerDiscreteScheduler) — エンコードされた画像の潜在変数からノイズを除去するために使用されるスケジューラ。
- vae (AutoencoderKLQwenImage21) — 画像を64チャネルの潜在空間へ、およびその逆方向へマッピングする変分オートエンコーダー。
- text_encoder (
Qwen3VLForConditionalGeneration) — テキストと画像の埋め込みを同時に生成する Qwen3-VL モデルです。 - processor (
Qwen3VLProcessor) — チャットテンプレートを構築し、プロンプトと条件画像をトークン化するプロセッサ。 - transformer (QwenImage21Transformer2DModel) — 潜変数（latents）のノイズ除去を行う、単一ストリームのブロック因果型 Transformer です。
- sample_sigmas (
list[float]、省略可) — モデル作成者が設定したデフォルトのサンプリングシグマ（ターミナルシグマを除く）です。その長さがデノイジングステップ数を決定します。実行時に別のグリッドで実験する場合は、sigmasを__call__に渡してください。
Qwen-Image 2.1 によるテキストから画像への生成および画像条件付き生成。
Promptと条件画像はQwen3-VLモデルによって一緒にエンコードされるため、条件画像はエンコーダーがそのために確保したビジョンスロットを占有し、transformerはテキストと画像が交互に並んだ単一のシーケンスを参照します。
__call__
< source >( prompt: str | list[str] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_prompt: str | list[str] = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']output_resolution: int = 1024use_kv_cache: bool = True ) → ~pipelines.qwenimage.QwenImagePipelineOutput or tuple
パラメータ
- prompt (
strまたはlist[str]、省略可) — 画像生成を導くプロンプトです。埋め込みを直接指定する場合は、代わりにprompt_embedsを渡してください。 - image (
PipelineImageInput、任意) — 1 つ以上の条件画像。PIL 画像または numpy 配列として指定します。テキストエンコーダーによってビジョンコンテキストとしてエンコードされ、VAE によってノイズの前に付加される潜在トークンに変換されます。リストは、バッチ内のすべてのプロンプトで共有される 1 組の画像を意味し、プロンプトごとに 1 項目を指定するものではありません。 - negative_prompt (
strまたはlist[str]、省略可) — 画像生成を導かないプロンプトです。true_cfg_scaleが 1 より大きくない場合は無視されます。 - true_cfg_scale (
float、任意、デフォルト値は 1.0) — Classifier-free guidance のスケールです。true_cfg_scale > 1とネガティブプロンプトを併用することで有効になります。 Qwen-Image 2.1 はガイダンスなしでサンプリングすることを前提としているため、デフォルト値は 1.0 です。 - height (
int, 省略可) — 生成される画像のピクセル単位の縦幅。省略した場合、条件画像のアスペクト比から導出されます。 - width (
int, 省略可) — 生成される画像の幅（ピクセル単位）。省略した場合、条件画像のアスペクト比から導出されます。 - num_inference_steps (
int、任意、デフォルト値は 40)— デノイジングのステップ数です。sigmasまたはパイプラインで設定されたsample_sigmasが使用される場合は無視されます。ステップ数はそのスケジュールの長さによって決定されます。 - sigmas (
list[float]、省略可) — この呼び出しで試行するサンプリングのシグマのリストです。終端シグマは除外されます。パイプラインで設定されたsample_sigmasを上書きし、デノイジングのステップ数を決定します。スケジューラは、これらの値に対して設定された処理を適用します。 - num_images_per_prompt (
int、任意、デフォルトは 1) — 1 つのプロンプトごとに生成される画像の数。 - generator (
torch.Generatorまたはlist[torch.Generator]、省略可) — 生成を決定論的にするために使用するジェネレーター。 - latents (
torch.Tensor, 任意) — 事前生成されたノイズ付き潜在変数。 - prompt_embeds (
torch.Tensor, 任意) — プロンプトエンコーディングをスキップするための、事前生成されたテキスト埋め込み。これと同時にprompt_embeds_maskを渡してください。 - prompt_embeds_mask (
torch.Tensor, 任意) —prompt_embedsの有効な位置を示す Bool マスクです。 - negative_prompt_embeds (
torch.Tensor, 任意) —negative_promptの代わりに使用する、事前生成されたネガティブテキストの埋め込み。これらを使用する場合は、negative_prompt_embeds_maskも一緒に渡してください。 - negative_prompt_embeds_mask (
torch.Tensor, 任意) —negative_prompt_embedsの有効な位置を示す Bool マスクです。 - output_type (
str、任意、デフォルトは"pil") — 出力形式。"pil"、"np"、"pt"、または"latent"。 - return_dict (
bool、任意、デフォルトはTrue) —~pipelines.qwenimage.QwenImagePipelineOutputを返すか、プレーンなタプルを返すかを指定します。 - attention_kwargs (
dict, 任意) — attention processor に渡されます。 - callback_on_step_end (
Callable, 省略可) — 各デノイジングステップの終了時に呼び出されます。 - callback_on_step_end_tensor_inputs (
list[str]、任意、デフォルトは["latents"]) — デノイジングループからcallback_on_step_endに渡すテンソルです。パイプラインの_callback_tensor_inputsに列挙されている必要があります。 - output_resolution (
int、任意、デフォルト値は 1024) —height/widthを導出し、条件画像をリサイズするために使用するターゲットの辺の長さです。 - use_kv_cache (
bool, 省略可能, デフォルトはTrue) — 最初のステップ以降、テキストおよび条件画像のキーとバリューをキャッシュします。causal_conditionがこれらのトークンをt = 0, から変調するため、それらの活性化はステップに依存しなくなります。この設定を切り替えても、低精度ではビット単位で同じ画像を再現しません。キャッシュにより、デコードステップはプリフィルステップとは異なるシーケンスレイアウトでアテンションを行うため、タイルの分割方法が異なり、丸め処理の結果も異なります。ただし、両者は fp32 の参照値に対して同じ許容誤差の範囲で一致します。最初のブロックでの 1 ULP の差は、32 個のブロックとすべてのサンプラーステップによって増幅されるため、両方の設定は同等に有効ですが、視覚的に異なるサンプルを生成します。サンプルを固定するには、このフラグを固定してください。この設定を切り替えても、低精度ではビット単位で同一の画像を再現しません。キャッシュにより、デコードステップではプリフィルステップとは異なるシーケンスレイアウトでアテンションが行われるため、タイルの分割方法が異なり、丸め処理の結果も異なります。ただし、両者は fp32 の参照値に対して同じ許容誤差の範囲で一致しています。最初のブロックにおける 1 ULP の差は、32 ブロックおよびすべてのサンプラーステップによって増幅されるため、両方の設定は同等に有効ですが、視覚的に明確に異なるサンプルを生成します。サンプルを固定するには、このフラグを固定してください。
戻り値
~pipelines.qwenimage.QwenImagePipelineOutput または tuple
return_dict が True の場合は ~pipelines.qwenimage.QwenImagePipelineOutput、それ以外の場合は、最初の要素が生成された画像のリストである tuple を返します。
生成用のパイプラインを呼び出したときに実行される関数。
例:
>>> import torch
>>> from diffusers import QwenImage21Pipeline
>>> pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A capybara wearing a wizard hat, reading a book by candlelight, oil painting"
>>> image = pipe(prompt).images[0]
>>> image.save("qwenimage21.png")encode_prompt
< source >( prompt: str | list[str]image: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneimage_pad_mask: typing.Optional[torch.Tensor] = None )
QwenImagePipelineOutput
class diffusers.pipelines.qwenimage.pipeline_output.QwenImagePipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
Stable Diffusion パイプライン用の出力クラスです。
QwenImage21ModularPipeline
class diffusers.QwenImage21ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Qwen-Image 2.1 用の ModularPipeline。
QwenImage21AutoBlocks
Qwen-Image 2.1 を用いたテキストから画像への生成および画像条件付き生成のための Auto Modular パイプライン。
- テキストから画像を生成するには、
promptを指定するだけで十分です。 - 画像条件付き生成を行うには、
promptとimage（1枚の画像またはリスト）を指定する必要があります。
サポートされているワークフロー:
text2image:promptが必要ですimage_conditioned:promptとimageが必要です
コンポーネント:
image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor
(Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler) guider
(ClassifierFreeGuidance) transformer (QwenImage21Transformer2DModel)
入力:
image (Image | list, 任意):
デノイジング用の参照画像。単一の画像または画像のリストを指定できます。
output_resolution (int, 任意, デフォルト値: 1024):
出力サイズを導出するために使用される、および条件画像をリサイズするために使用される、ターゲットの辺の長さ。
prompt (str):
画像生成をガイドするためのプロンプト。
negative_prompt (str, 任意):
画像生成をガイドしないためのプロンプト。
generator (Generator, 任意):
決定論的な生成のための Torch ジェネレーター。
num_images_per_prompt (int, 任意, デフォルト値: 1):
プロンプトごとに生成する画像の数。
height (int, 任意):
生成される画像の高さ（ピクセル単位）。
width (int, 任意):
生成される画像の幅（ピクセル単位）。
image_latents (list, 任意):
各条件画像の正規化された潜在変数。vae_encoder ステップから生成できます。
latents (Tensor):
画像生成用の事前生成されたノイズ付き潜在変数。
num_inference_steps (int):
デノイジングのステップ数。
sigmas (list, 任意):
デノイジングプロセス用のカスタムシグマ。
use_kv_cache (bool, 任意, デフォルト値: True):
最初のステップ以降、テキストおよび条件画像のキーとバリューをキャッシュします。causal_condition が t = 0 からそれらのトークンを調整するため、それらのアクティベーションはステップに依存せず、有効です。これを切り替えても、低精度ではビット単位で同じ画像を再現しません。
attention_kwargs (dict, 任意):
アテンションプロセッサー用の追加の kwargs。
*denoiser_input_fields (None,任意):
デノイザー用の条件付きモデルの入力: 例: prompt_embeds, negative_prompt_embeds など。
output_type (str,任意*, デフォルト値: pil):
出力形式: ‘pil’, ‘np’, ‘pt’。
出力:
images (list):
生成された画像。
QwenImage21TurboModularPipeline
class diffusers.QwenImage21TurboModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Qwen-Image 2.1 Turbo は、ガイダンスなしで数ステップのサンプリングにより高速化されたチェックポイントです。
QwenImage21TurboAutoBlocks
Qwen-Image 2.1 Turbo を使用したテキストから画像への生成および画像条件付き生成のための Auto Modular パイプラインです。Qwen-Image 2.1 Turbo は、ガイダンスなしで数ステップのサンプリングにより、同梱のシグマグリッドをサンプリングする高速化されたチェックポイントです。
- テキストから画像を生成するには、
promptを指定するだけで十分です。 - 画像条件付き生成を行うには、
promptとimage（1枚の画像またはリスト）を指定する必要があります。
サポートされているワークフロー:
text2image:promptが必要ですimage_conditioned:promptとimageが必要です
コンポーネント:
image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) processor
(Qwen3VLProcessor) vae (AutoencoderKLQwenImage21) scheduler (FlowMatchEulerDiscreteScheduler)
transformer (QwenImage21Transformer2DModel)
Configs:
sample_sigmas (デフォルト: None): チェックポイントに同梱されているサンプリンググリッド。sigmas が渡されない場合に使用されます。
入力:
image (Image | list, 省略可):
デノイジング用の参照画像。単一の画像または画像のリストを指定できます。
output_resolution (int, 省略可, デフォルト値: 1024):
出力サイズを導出するために使用される、および条件画像をリサイズするために使用される、ターゲットの辺の長さ。
prompt (str):
画像生成をガイドするためのプロンプト。
generator (Generator, 省略可):
決定論的な生成のための Torch ジェネレーター。
num_images_per_prompt (int, 省略可, デフォルト値: 1):
プロンプトごとに生成する画像の数。
height (int, 省略可):
生成される画像の高さ（ピクセル単位）。
width (int, 省略可):
生成される画像の幅（ピクセル単位）。
image_latents (list, 省略可):
各条件画像の正規化された潜在変数。vae_encoder ステップから生成できます。
latents (Tensor):
画像生成用の事前生成されたノイズ付き潜在変数。
num_inference_steps (int):
デノイジングのステップ数。
sigmas (list, 省略可):
デノイジングプロセス用のカスタムシグマ。
use_kv_cache (bool, 省略可, デフォルト値: True):
最初のステップ以降、テキストおよび条件画像のキーとバリューをキャッシュします。causal_condition が t = 0 からこれらのトークンを調整するため、それらの活性化はステップに依存せず、有効です。これを切り替えても、低精度ではビット単位で同じ画像を再現しません。
attention_kwargs (dict, 省略可):
アテンションプロセッサー用の追加の kwargs。
*denoiser_input_fields (None,省略可):
デノイザー用の条件付きモデルの入力: 例: prompt_embeds, negative_prompt_embeds など。
output_type (str,省略可*, デフォルト値: pil):
出力形式: ‘pil’, ‘np’, ‘pt’。
出力:
images (list):
生成された画像。