Diffusers documentation
Flux2
Flux2
Flux.2は、Black Forest Labsが最近発表した画像生成モデルのシリーズで、Flux.1シリーズに先立つものです。これは、新しいアーキテクチャを備え、ゼロから事前学習が行われた、まったく新しいモデルです。
Fluxの元のモデルチェックポイントはこちらで確認できます。元の推論コードはこちらで確認できます。
Flux2 は、コンシューマー向けハードウェアで実行するとコストが高くなることがあります。ただし、一連の最適化を行うことで、より高速かつメモリ効率の良い実行が可能です。詳細については、このセクションを参照してください。また、Flux は量子化によってメモリ効率を向上させることができますが、推論レイテンシとのトレードオフが発生します。詳細については、このブログ記事を参照してください。
Caching は、中間出力を保存して再利用することで、推論の高速化にも貢献します。
キャプションのアップサンプリング
Flux.2 は、より良いプロンプトを使用することで、より良い出力を生成する可能性があります。パイプライン呼び出しの引数で caption_upsample_temperature 引数を設定することにより、入力プロンプトを「アップサンプリング」できます。公式実装では、この値を 0.15 とすることを推奨しています。
Flux2Pipeline
クラス diffusers.Flux2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Mistral3ForConditionalGenerationtokenizer: AutoProcessortransformer: Flux2Transformer2DModel )
パラメータ
- transformer (Flux2Transformer2DModel) — エンコードされた画像潜在変数からノイズを除去するための、条件付き Transformer (MMDiT) アーキテクチャ。
- scheduler (FlowMatchEulerDiscreteScheduler) —
transformerと組み合わせて、エンコードされた画像の潜在変数からノイズを除去するために使用するスケジューラ。 - vae (
AutoencoderKLFlux2) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。 - text_encoder (
Mistral3ForConditionalGeneration) — Mistral3ForConditionalGeneration - tokenizer (
AutoProcessor) — PixtralProcessor クラスのトークナイザー。
テキストから画像を生成するためのFlux2パイプライン。
参考: https://bfl.ai/blog/flux-2
__call__
< source >( image: PIL.Image.Image | list[PIL.Image.Image] | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: 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], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (10, 20, 30)caption_upsample_temperature: float = None ) → ~pipelines.flux2.Flux2PipelineOutput or tuple
パラメータ
- 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として受け取れますが、潜在変数を直接渡す場合は、再度エンコードされません。 - prompt (
strまたはlist[str]、省略可) — 画像生成をガイドするためのプロンプトです。未定義の場合、代わりにprompt_embedsを渡す必要があります。 - guidance_scale (
float, 省略可能, 、デフォルト値は 1.0) — 埋め込み型ガイダンススケールはguidance_scale> 1. を高くすることで、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
class diffusers.Flux2KleinPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = False )
パラメータ
- transformer (Flux2Transformer2DModel) — エンコードされた画像潜在変数からノイズを除去するための、条件付き Transformer (MMDiT) アーキテクチャ。
- scheduler (FlowMatchEulerDiscreteScheduler) —
transformerと組み合わせて、エンコードされた画像の潜在変数からノイズを除去するために使用するスケジューラ。 - vae (
AutoencoderKLFlux2) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。 - text_encoder (
Qwen3ForCausalLM) — Qwen3ForCausalLM - tokenizer (
Qwen2TokenizerFast) — クラス Qwen2TokenizerFast のトークナイザー。
テキストから画像を生成するためのFlux2 Kleinパイプライン。
参考: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence
__call__
< source >( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: str | list[str] | None = Noneoutput_type: str = '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']max_sequence_length: int = 512text_encoder_out_layers: tuple[int] = (9, 18, 27) ) → ~pipelines.flux2.Flux2PipelineOutput or tuple
パラメータ
- 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)です。画像の潜在変数（latents）をimageとして受け取ることもできますが、潜在変数を直接渡す場合は、再度エンコードされません。 - 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], 任意) —sigmas引数を受け付けるset_timestepsメソッドを持つスケジューラーで、デノイジングプロセスに使用するカスタムのシグマ。未定義の場合、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
class diffusers.Flux2KleinKVPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = True )
パラメータ
- transformer (Flux2Transformer2DModel) — エンコードされた画像潜在変数からノイズを除去するための、条件付き Transformer (MMDiT) アーキテクチャ。
- scheduler (FlowMatchEulerDiscreteScheduler) —
transformerと組み合わせて、エンコードされた画像の潜在変数からノイズを除去するために使用するスケジューラ。 - vae (
AutoencoderKLFlux2) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。 - text_encoder (
Qwen3ForCausalLM) — Qwen3ForCausalLM - tokenizer (
Qwen2TokenizerFast) — クラス Qwen2TokenizerFast のトークナイザー。
KVキャッシュ付きの参照画像条件付けによるテキストから画像への生成を行うFlux2 Klein KVパイプライン。
最初のノイズ除去ステップでは、参照画像のトークンがフォワードパスに含まれ、そのアテンションのK/V射影がキャッシュされます。その後のステップでは、再計算せずにキャッシュされたK/Vが再利用されるため、参照画像を使用する場合に推論が高速化されます。
参考: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence
__call__
< source >( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: 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] = Noneoutput_type: str = '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']max_sequence_length: int = 512text_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, 省略可) — 生成される画像の幅（ピクセル単位）。 - num_inference_steps (
int、任意、デフォルト値は 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、省略可) — コールバック関数へのテンソル入力。 - max_sequence_length (
int、デフォルト値は 512) — プロンプトの最大シーケンス長。 - text_encoder_out_layers (
tuple[int]) — テキストエンコーダーの隠れ状態を抽出するためのレイヤーのインデックス。
生成用のパイプラインを呼び出したときに実行される関数。
例:
>>> 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")