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

Flux.1 と ControlNet

FluxControlNetPipeline は、Flux.1 向けの ControlNet の実装です。

ControlNetは、Lvmin Zhang、Anyi Rao、Maneesh Agrawalaによる論文Adding Conditional Control to Text-to-Image Diffusion Modelsで提案されました。

ControlNetモデルを使用すると、Stable Diffusionの生成を条件付け・制御するための追加の制御画像を指定できます。例えば、深度マップを指定した場合、ControlNetモデルは深度マップの空間情報を保持した画像を生成します。これは、画像生成プロセスをより柔軟かつ正確に制御する方法です。

論文の抄録は以下の通りです：

本稿では、大規模な事前学習済みテキストから画像への拡散モデルに空間的条件付け制御を追加するためのニューラルネットワークアーキテクチャであるControlNetを提案します。ControlNetは、実運用可能な大規模拡散モデルを固定し、数十億枚の画像で事前学習された深く頑健なエンコーディング層を強力なバックボーンとして再利用することで、多様な条件付け制御のセットを学習します。このニューラルアーキテクチャは、「ゼロ畳み込み」（ゼロ初期化された畳み込み層）によって接続されており、パラメータをゼロから段階的に増加させ、有害なノイズがファインチューニングに影響を与えないことを保証します。Stable Diffusionを用いて、エッジ、深度、セグメンテーション、人間のポーズなどの様々な条件付け制御を、プロンプトの有無にかかわらず、単一または複数の条件を用いてテストしました。ControlNetの学習は、小規模（<50k）および大規模（>1m）のデータセットのいずれにおいても頑健であることが示されています。広範な結果から、ControlNetは画像拡散モデルの制御に関するより幅広いアプリケーションを促進し得ることが示されました。

This controlnet code is implemented by The InstantX Team. You can find pre-trained checkpoints for Flux-ControlNet in the table below:

ControlNetのタイプ	開発者	リンク
Canny	InstantX チーム	リンク
深さ	InstantX チーム	リンク
Union	InstantX チーム	リンク

XLabs ControlNetもサポートされており、これはXLabsチームによって提供されました。

ControlNetのタイプ	開発者	リンク
Canny	XLabs チーム	リンク
深さ	XLabs チーム	リンク
HED	XLabs チーム	リンク

スケジューラーのトレードオフ、すなわち速度と品質のバランスをどのように探求するかを学ぶには、ガイドを必ずご確認ください。また、同じコンポーネントを複数のパイプラインに効率的に読み込む方法については、パイプライン間でコンポーネントを再利用するセクションを参照してください。

FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]]

diffusers.FluxControlNetPipeline[[diffusers.FluxControlNetPipeline]]

diffusers.FluxControlNetPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel, controlnet: diffusers.models.controlnets.controlnet_flux.FluxControlNetModel | list[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel] | diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModel, image_encoder: CLIPVisionModelWithProjection = None, feature_extractor: CLIPImageProcessorPil = None)

ソース

パラメータ:

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

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

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

text_encoder (CLIPTextModel) : CLIP、具体的には clip-vit-large-patch14 バリアントです。

text_encoder_2 (T5EncoderModel) : T5、具体的には google/t5-v1_1-xxl バリアントです。

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

tokenizer_2 (T5TokenizerFast) : クラス T5TokenizerFast の2番目の Tokenizer。

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

参考: https://blackforestlabs.ai/announcing-black-forest-labs/

call[[diffusers.FluxControlNetPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, negative_prompt: str | list[str] = None, negative_prompt_2: str | list[str] | None = None, true_cfg_scale: float = 1.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 28, sigmas: list[float] | None = None, guidance_scale: float = 7.0, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_mode: int | list[int] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, 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: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, negative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, negative_ip_adapter_image_embeds: list[torch.Tensor] | None = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = 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 を渡す必要があります。

prompt_2 (str または list[str]、省略可能) : tokenizer_2 および text_encoder_2 に送信するプロンプトです。定義されていない場合、代わりに prompt が使用されます。

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

negative_prompt_2 (str または list[str]、任意) : 画像生成を誘導しないプロンプト、またはプロンプトのリストです。tokenizer_2 および text_encoder_2 に送信されます。定義されていない場合、すべてのテキストエンコーダーで negative_prompt が使用されます。

true_cfg_scale (float、任意、デフォルト値は 1.0) : true_cfg_scale > 1 かつ negative_prompt が指定されている場合、True classifier-free guidance（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 が渡された場合のデフォルトの動作が使用されます。

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

control_guidance_start (float または list[float]、任意、デフォルト値は 0.0) : ControlNet が適用を開始するステップの割合（全体のステップ数に対するパーセンテージ）。

control_guidance_end (float または list[float]、任意、デフォルト値は 1.0) : ControlNet が適用を停止するステップの割合（全体のステップ数に対するパーセンテージ）。

control_image (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image]、list[np.ndarray]、: list[list[torch.Tensor]]、list[list[np.ndarray]] または list[list[PIL.Image.Image]]): 生成において unet にガイダンスを与えるための ControlNet の入力条件です。型が torch.Tensor として指定されている場合、ControlNet にそのまま渡されます。画像として PIL.Image.Image も受け付けられます。出力画像の寸法は、デフォルトで image の寸法になります。高さおよび/または幅が渡された場合、image はそれに応じてリサイズされます。init で複数の ControlNet が指定されている場合、各 ControlNet への入力が正しくバッチ処理できるよう、リストとして画像を渡す必要があります。

controlnet_conditioning_scale (float または list[float]、任意、デフォルト値は 1.0) : ControlNet の出力は、元の unet の残差に加算される前に controlnet_conditioning_scale 倍されます。init で複数の ControlNet を指定する場合は、対応するスケールをリストとして設定できます。

control_mode (int または list[int]、任意、デフォルトは None) : ControlNet-Union を適用する際の制御モードです。

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

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

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

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

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

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

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

ip_adapter_image : (PipelineImageInput、任意): IP Adapter で使用する任意の画像入力。

ip_adapter_image_embeds (list[torch.Tensor]、省略可) : IP-Adapter用の事前生成された画像埋め込み。IP-Adapterの数と同じ長さのリストである必要があります。各要素は、(batch_size, num_images, emb_dim) の形状を持つテンソルである必要があります。指定されない場合、ip_adapter_image 入力引数から埋め込みが計算されます。

negative_ip_adapter_image : (PipelineImageInput、任意): IP Adapter で使用する任意の画像入力。

negative_ip_adapter_image_embeds (list[torch.Tensor]、省略可) : IP-Adapter用の事前生成された画像埋め込み。IP-Adapterの数と同じ長さのリストである必要があります。各要素は、(batch_size, num_images, emb_dim) の形状を持つテンソルである必要があります。指定されない場合、ip_adapter_image 入力引数から埋め込みが計算されます。

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

return_dict (bool、任意、デフォルトはTrue) : 通常のタプルではなく~pipelines.flux.FluxPipelineOutputを返すかどうか。

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

戻り値: ~pipelines.flux.FluxPipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers.utils import load_image
>>> from diffusers import FluxControlNetPipeline
>>> from diffusers import FluxControlNetModel

>>> base_model = "black-forest-labs/FLUX.1-dev"
>>> controlnet_model = "InstantX/FLUX.1-dev-controlnet-canny"
>>> controlnet = FluxControlNetModel.from_pretrained(controlnet_model, torch_dtype=torch.bfloat16)
>>> pipe = FluxControlNetPipeline.from_pretrained(
...     base_model, controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg")
>>> prompt = "A girl in city, 25 years old, cool, futuristic"
>>> image = pipe(
...     prompt,
...     control_image=control_image,
...     control_guidance_start=0.2,
...     control_guidance_end=0.8,
...     controlnet_conditioning_scale=1.0,
...     num_inference_steps=28,
...     guidance_scale=3.5,
... ).images[0]
>>> image.save("flux.png")

encode_prompt[[diffusers.FluxControlNetPipeline.encode_prompt]]

encode_prompt(prompt: str | list[str], prompt_2: str | list[str] | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, max_sequence_length: int = 512, lora_scale: float | None = None)

ソース

パラメータ:

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

prompt_2 (str または list[str]、省略可) : tokenizer_2 および text_encoder_2 に送信するプロンプトです。未定義の場合、すべての text-encoder で prompt が使用されます。

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

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

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

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

lora_scale (float、任意) : LoRAレイヤーが読み込まれている場合、テキストエンコーダーのすべてのLoRAレイヤーに適用されるLoRAスケールです。

FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]]

diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput[[diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput]]

diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)

ソース

パラメータ:

images (list[PIL.Image.Image] または torch.Tensor または np.ndarray) : 長さ batch_size のノイズ除去済み PIL イメージのリスト、または形状 (batch_size, height, width, num_channels) の numpy 配列または torch テンソル。PIL イメージまたは numpy 配列は、拡散パイプラインのノイズ除去済みイメージを表します。Torch テンソルは、ノイズ除去済みイメージ、またはデコーダーに渡す準備が整った中間潜在変数のいずれかを表すことができます。

Flux画像生成パイプライン用の出力クラス。