diffusers/main/ja/api/pipelines/flux2.md

Flux2

Flux.2は、Black Forest Labsが最近発表した画像生成モデルのシリーズで、Flux.1シリーズに先立つものです。これは、新しいアーキテクチャを備え、ゼロから事前学習が行われた、まったく新しいモデルです。

Fluxの元のモデルチェックポイントはこちらで確認できます。元の推論コードはこちらで確認できます。

Flux2 は、コンシューマー向けハードウェアで実行するとコストが高くなることがあります。ただし、一連の最適化を行うことで、より高速かつメモリ効率の良い実行が可能です。詳細については、このセクションを参照してください。また、Flux は量子化によってメモリ効率を向上させることができますが、推論レイテンシとのトレードオフが発生します。詳細については、このブログ記事を参照してください。

Caching は、中間出力を保存して再利用することで、推論の高速化にも貢献します。

キャプションのアップサンプリング

Flux.2 は、より良いプロンプトを使用することで、より良い出力を生成する可能性があります。パイプライン呼び出しの引数で caption_upsample_temperature 引数を設定することにより、入力プロンプトを「アップサンプリング」できます。公式実装では、この値を 0.15 とすることを推奨しています。

Flux2Pipeline[[diffusers.Flux2Pipeline]]

diffusers.Flux2Pipeline[[diffusers.Flux2Pipeline]]

diffusers.Flux2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Mistral3ForConditionalGeneration, tokenizer: AutoProcessor, transformer: Flux2Transformer2DModel)

ソース

パラメータ:

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

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

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

text_encoder (Mistral3ForConditionalGeneration) : Mistral3ForConditionalGeneration

tokenizer (AutoProcessor) : クラス PixtralProcessor の Tokenizer。

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

参考: https://bfl.ai/blog/flux-2

call[[diffusers.Flux2Pipeline.call]]

__call__(image: PIL.Image.Image | list[PIL.Image.Image] | None = None, 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 | None = 4.0, 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, 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, text_encoder_out_layers: tuple[int] = (10, 20, 30), caption_upsample_temperature: float = None)

ソース

パラメータ:

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

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

guidance_scale (float、任意、デフォルト値は 1.0) : guidance_scale > 1 に設定することで、埋め込み型 guidance scale が有効になります。guidance_scale を高くすると、prompt により一貫性のある画像を生成するようモデルを促しますが、画像の品質が低下する可能性があります。Guidance-distilled モデルは、guidance_scale > 1 の場合に、真の classifer-free guidance を近似します。詳細については、論文を参照してください。

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 が渡された場合のデフォルトの動作が使用されます。

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

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

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

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

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

text_encoder_out_layers (tuple[int]) : text_encoder内で最終的なプロンプト埋め込みを導出するために使用するレイヤーのインデックス。

caption_upsample_temperature (float) : 指定した場合、出力の向上を目的としてキャプションのアップサンプリングを試みます。キャプションのアップサンプリングを行う場合は、0.15に設定することを推奨します。

戻り値: ~pipelines.flux2.Flux2PipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers import Flux2Pipeline

>>> pipe = Flux2Pipeline.from_pretrained("black-forest-labs/FLUX.2-dev", 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, guidance_scale=2.5).images[0]
>>> image.save("flux.png")

Flux2KleinPipeline[[diffusers.Flux2KleinPipeline]]

diffusers.Flux2KleinPipeline[[diffusers.Flux2KleinPipeline]]

diffusers.Flux2KleinPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Qwen3ForCausalLM, tokenizer: Qwen2Tokenizer, transformer: Flux2Transformer2DModel, is_distilled: bool = False)

ソース

パラメータ:

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

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

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

text_encoder (Qwen3ForCausalLM) : Qwen3ForCausalLM

tokenizer (Qwen2TokenizerFast) : クラス Qwen2TokenizerFast の Tokenizer。

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

参考: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

call[[diffusers.Flux2KleinPipeline.call]]

__call__(image: list[PIL.Image.Image] | PIL.Image.Image | None = None, 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 = 4.0, 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, negative_prompt_embeds: str | list[str] | None = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512, text_encoder_out_layers: tuple[int] = (9, 18, 27))

ソース

パラメータ:

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

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

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

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 が渡された場合のデフォルトの動作が使用されます。

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

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

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

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

negative_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたネガティブなテキスト埋め込み。このパイプラインでは、"" がネガティブプロンプトとして使用されます。指定されない場合、"" から生成されます。

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

text_encoder_out_layers (tuple[int]) : text_encoder内で最終的なプロンプト埋め込みを導出するために使用するレイヤーのインデックス。

戻り値: ~pipelines.flux2.Flux2PipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers import Flux2KleinPipeline

>>> pipe = Flux2KleinPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-base-9B", 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, guidance_scale=4.0).images[0]
>>> image.save("flux2_output.png")

Flux2KleinKVPipeline[[diffusers.Flux2KleinKVPipeline]]

diffusers.Flux2KleinKVPipeline[[diffusers.Flux2KleinKVPipeline]]

diffusers.Flux2KleinKVPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: Qwen3ForCausalLM, tokenizer: Qwen2Tokenizer, transformer: Flux2Transformer2DModel, is_distilled: bool = True)

ソース

パラメータ:

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

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

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

text_encoder (Qwen3ForCausalLM) : Qwen3ForCausalLM

tokenizer (Qwen2TokenizerFast) : クラス Qwen2TokenizerFast の Tokenizer。

KVキャッシュ付きの参照画像条件付けによるテキストから画像への生成を行うFlux2 Klein KVパイプライン。

最初のノイズ除去ステップでは、参照画像のトークンがフォワードパスに含められ、そのアテンションのK/Vプロジェクションがキャッシュされます。その後のステップでは、再計算せずにキャッシュされたK/Vが再利用されるため、参照画像を使用する場合に推論が高速になります。

参考: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

call[[diffusers.Flux2KleinKVPipeline.call]]

__call__(image: list[PIL.Image.Image] | PIL.Image.Image | None = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 4, sigmas: list[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, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512, text_encoder_out_layers: tuple[int] = (9, 18, 27))

ソース

パラメータ:

image (PIL.Image.Image または List[PIL.Image.Image]、任意) : 条件付け用の参照画像。最初のデノイジングステップでは、参照トークンがフォワードパスに含められ、そのアテンションの K/V がキャッシュされます。以降のステップでは、再計算せずにキャッシュされた K/V が再利用されます。

prompt (str または List[str]、省略可能) : 画像生成をガイドするためのプロンプトまたはプロンプトのリスト。

height (int, 任意) : 生成される画像のピクセル単位の縦幅。

width (int, optional) : 生成される画像の幅（ピクセル単位）。

num_inference_steps (int、optional、デフォルトは 4) : デノイジングのステップ数です。

sigmas (List[float], 任意) : デノイジングスケジュール用のカスタムシグマ。

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

generator (torch.Generator または List[torch.Generator]、任意) : 決定論的な生成を行うためのジェネレーター。

latents (torch.Tensor, 任意) : 事前生成されたノイズ付き潜在変数。

prompt_embeds (torch.Tensor, 任意) : 事前に生成されたテキスト埋め込み。

output_type (str、任意、デフォルトは"pil") : 出力形式: "pil"または"np"。

return_dict (bool、任意、デフォルトはTrue) : Flux2PipelineOutputを返すか、通常のタプルを返すかを指定します。

attention_kwargs (dict, 任意) : attention プロセッサに渡す追加の kwargs。

callback_on_step_end (Callable, 任意) : 各デノイジングステップの終了時に呼び出されるコールバック関数。

callback_on_step_end_tensor_inputs (List、任意) : コールバック関数へのTensor入力。

max_sequence_length (int、デフォルトは 512) : プロンプトの最大シーケンス長。

text_encoder_out_layers (tuple[int]) : テキストエンコーダーの隠れ状態を抽出するためのレイヤーのインデックス。

戻り値:

~pipelines.flux2.Flux2PipelineOutput または tuple。

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

例:

>>> import torch
>>> from PIL import Image
>>> from diffusers import Flux2KleinKVPipeline

>>> pipe = Flux2KleinKVPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-9b-kv", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> ref_image = Image.open("reference.png")
>>> image = pipe("A cat dressed like a wizard", image=ref_image, num_inference_steps=4).images[0]
>>> image.save("flux2_kv_output.png")