Diffusers documentation
Flux.1 と ControlNet
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
class diffusers.FluxControlNetPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModeltokenizer: CLIPTokenizertext_encoder_2: T5EncoderModeltokenizer_2: T5Tokenizertransformer: FluxTransformer2DModelcontrolnet: 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.FluxMultiControlNetModelimage_encoder: CLIPVisionModelWithProjection = Nonefeature_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_2 (
T5TokenizerFast) — クラス T5TokenizerFast の2番目の Tokenizer。
テキストから画像を生成するためのFluxパイプライン。
参照: https://blackforestlabs.ai/announcing-black-forest-labs/
__call__
< source >( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Nonenegative_prompt: str | list[str] = Nonenegative_prompt_2: str | list[str] | None = Nonetrue_cfg_scale: float = 1.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 7.0control_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_mode: int | list[int] | None = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0num_images_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.FloatTensor] = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneip_adapter_image_embeds: list[torch.Tensor] | None = Nonenegative_ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Nonenegative_ip_adapter_image_embeds: list[torch.Tensor] | None = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512 ) → ~pipelines.flux.FluxPipelineOutput or tuple
パラメータ
- 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, 任意) — 画像生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジーな潜在変数です。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム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
< source >( prompt: str | list[str]prompt_2: str | list[str] | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonemax_sequence_length: int = 512lora_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) — 1つのプロンプトに対して生成する画像の数 - prompt_embeds (
torch.FloatTensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt入力引数からテキスト埋め込みが生成されます。 - pooled_prompt_embeds (
torch.FloatTensor, 任意) — 事前に生成されたプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に使用できます。 指定されない場合、prompt入力引数からプールのテキスト埋め込みが生成されます。 - lora_scale (
float, 省略可) — LoRA レイヤーが読み込まれている場合、テキストエンコーダーのすべての LoRA レイヤーに適用される LoRA スケールです。
FluxPipelineOutput
class diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
Flux画像生成パイプライン用の出力クラス。