hf-doc-build/doc / diffusers /main /ja /api /pipelines /controlnet_union.md

|

92.7 kB

ControlNetUnion

ControlNetUnionModel は、Stable Diffusion XL 向けの ControlNet の実装です。

ControlNetモデルは、xinsir6によってControlNetPlusで導入されました。計算量を増やすことなく、複数の条件付け入力をサポートします。

条件付きテキストから画像への生成において10種類以上の制御タイプをサポートし、Midjourneyと視覚的に比較可能な高解像度画像を生成できる新しいアーキテクチャを設計しました。このネットワークは元のControlNetアーキテクチャをベースとしており、2つの新しいモジュールを提案しています。1. 同じネットワークパラメータを使用して異なる画像条件をサポートするように元のControlNetを拡張する。2. 計算オフロードを増やさずに複数の条件入力をサポートする。これは、画像を詳細に編集したいデザイナーにとって特に重要であり、異なる条件は同じ条件エンコーダを使用するため、追加の計算やパラメータは不要です。

StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

diffusers.StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

diffusers.StableDiffusionXLControlNetUnionPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)

ソース

パラメータ:

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

text_encoder (CLIPTextModel) : 凍結されたテキストエンコーダー (clip-vit-large-patch14)。

text_encoder_2 (CLIPTextModelWithProjection) : 2番目の凍結されたテキストエンコーダー (laion/CLIP-ViT-bigG-14-laion2B-39B-b160k)。

tokenizer (CLIPTokenizer) : テキストをトークン化するためのCLIPTokenizer。

tokenizer_2 (CLIPTokenizer) : テキストをトークン化するためのCLIPTokenizer。

unet (UNet2DConditionModel) : エンコードされた画像の潜在変数をノイズ除去するための UNet2DConditionModel。

controlnet (ControlNetUnionModel) : Provides additional conditioning to the unet` during the denoising process.

scheduler (SchedulerMixin) : unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラ。DDIMScheduler、LMSDiscreteScheduler、または PNDMScheduler のいずれかです。

force_zeros_for_empty_prompt (bool、任意、デフォルトは"True") : 負のプロンプト埋め込みを常に0に設定するかどうか。stabilityai/stable-diffusion-xl-base-1-0の設定も参照してください。

add_watermarker (bool, optional) : 出力画像にウォーターマークを付与するために invisible_watermark ライブラリを使用するかどうか。未定義の場合、パッケージがインストールされている場合は True がデフォルトとなり、それ以外の場合はウォーターマーカは使用されません。

ControlNetによるガイダンスを用いたStable Diffusion XLのテキストから画像への生成を行うPipelineです。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、以下の読み込みメソッドも継承します:

テキストインバージョンの埋め込みを読み込むためのload_textual_inversion()
LoRA重みの読み込みにload_lora_weights()
LoRA重みの保存にはsave_lora_weights()を使用します
.ckptファイルを読み込むためのfrom_single_file()
IP Adapterの読み込みにload_ip_adapter()

call[[diffusers.StableDiffusionXLControlNetUnionPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, 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: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = 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, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])

ソース

パラメータ:

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

prompt_2 (str または list[str]、省略可) : tokenizer_2 および text_encoder_2 に送信するプロンプトです。定義されていない場合、両方のテキストエンコーダーで prompt が使用されます。

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

height (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像のピクセル単位の縦幅です。stabilityai/stable-diffusion-xl-base-1.0 や、低解像度に特化してファインチューニングされていないチェックポイントでは、512 ピクセル未満ではうまく動作しません。

width (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) : 生成される画像の幅（ピクセル単位）です。stabilityai/stable-diffusion-xl-base-1.0 や、低解像度に特化してファインチューニングされていないチェックポイントでは、512 ピクセル未満の値ではうまく動作しない場合があります。

num_inference_steps (int、任意、デフォルト値は 50) : デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常はより高品質な画像が得られます。

timesteps (list[int]、任意) : set_timesteps メソッドで timesteps 引数をサポートするスケジューラーにおいて、デノイジングプロセスに使用するカスタムタイムステップ。num_inference_steps が渡された場合のデフォルトの動作が使用されます。降順で指定する必要があります。

sigmas (list[float], 任意) : set_timesteps メソッドで sigmas 引数をサポートするスケジューラーにおいて、デノイジングプロセスに使用するカスタムシグマ。num_inference_steps が渡された場合のデフォルトの動作が使用されます。

denoising_end (float, 任意) : 指定すると、デノイジング全体のどの割合（0.0 から 1.0 の間）で処理を意図的に早期終了させるかを決定します。その結果、スケジューラによって選択された離散タイムステップによって決定されるように、返されるサンプルには依然としてかなりの量のノイズが残ります。画像出力の洗練 に詳述されているように、このパラメータは、このパイプラインが「Mixture of Denoisers」マルチパイプライン構成の一部を形成する場合に、理想的には利用されるべきです。

guidance_scale (float、任意、デフォルト値は 5.0) : guidance scale の値を高くすると、画像の品質が低下する代わりに、テキストの prompt と密接に関連した画像を生成するようモデルが促されます。guidance_scale > 1 の場合、guidance scale が有効になります。

negative_prompt (str または list[str]、省略可能) : 画像生成に含めるべきでない内容を指示するためのプロンプトまたはプロンプトのリストです。定義されていない場合、代わりに negative_prompt_embeds を渡す必要があります。ガイダンスを使用していない場合（guidance_scale < 1）は無視されます。

negative_prompt_2 (str または list[str]、省略可能) : 画像生成に含めるべきでない内容を指示するためのプロンプトです。tokenizer_2 および text_encoder_2 に送信されます。定義されていない場合、negative_prompt が両方のテキストエンコーダーで使用されます。

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

eta (float、任意、デフォルト値は 0.0) : DDIM論文のパラメータ eta (η) に対応します。DDIMSchedulerでのみ適用され、他のスケジューラーでは無視されます。

generator (torch.Generator または list[torch.Generator]、任意) : 生成を決定論的にするための torch.Generator。

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

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

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

pooled_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたプールのテキスト埋め込み。テキスト入力（プロンプトの重み付け）を簡単に調整するために使用できます。指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。

negative_pooled_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたネガティブプールのテキスト埋め込み。テキスト入力（プロンプトの重み付け）を簡単に調整するために使用できます。指定されない場合、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) の形状を持つテンソルである必要があります。do_classifier_free_guidance が True に設定されている場合、負の画像埋め込みを含む必要があります。指定されない場合、ip_adapter_image 入力引数から埋め込みが計算されます。

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

return_dict (bool、任意、デフォルトはTrue) : プレーンなタプルではなく、StableDiffusionPipelineOutputを返すかどうか。

cross_attention_kwargs (dict, 任意) : 指定された場合、self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

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

guess_mode (bool、任意、デフォルトはFalse) : ControlNet エンコーダーは、すべてのプロンプトを削除した場合でも、入力画像の内容を認識しようとします。guidance_scale の値は 3.0 から 5.0 の範囲が推奨されます。

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

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

control_mode (int or list[int] or list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image.

original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : original_size が target_size と異なる場合、画像はダウンサンプリングまたはアップサンプリングされたように見えます。original_size は、指定されていない場合、デフォルトで (height, width) になります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。

crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : crops_coords_top_left を使用すると、crops_coords_top_left の位置から下方向に「切り抜かれた」ように見える画像を生成できます。crops_coords_top_left を (0, 0) に設定することで、通常は良好で中央が整った画像が得られます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定する必要があります。指定されない場合、デフォルトで (height, width) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

negative_original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 特定の画像解像度に基づいて、生成プロセスをネガティブに条件付けます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : 特定のクロップ座標に基づいて、生成プロセスを負の条件として設定します。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 目標画像の解像度に基づいて、生成プロセスをネガティブに条件付けます。ほとんどの場合、target_size と同じである必要があります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

clip_skip (int, optional) : プロンプト埋め込みを計算する際に、CLIPからスキップするレイヤー数。値が1の場合、プロンプト埋め込みの計算に最終レイヤーの直前のレイヤーの出力が使用されます。

callback_on_step_end (Callable、PipelineCallback、MultiPipelineCallbacks、任意) : 推論中の各デノイジングステップの終了時に呼び出される関数、または PipelineCallback または MultiPipelineCallbacks のサブクラスです。以下の引数を持ちます: 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 属性に列挙された変数のみを、リストに含めることができます。

戻り値: StableDiffusionPipelineOutput または tuple

return_dict が True の場合、StableDiffusionPipelineOutput が返され、それ以外の場合は出力画像を含む tuple が返されます。

生成用の pipeline への呼び出し関数。

例:

>>> # !pip install controlnet_aux
>>> from controlnet_aux import LineartAnimeDetector
>>> from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel, AutoencoderKL
>>> from diffusers.utils import load_image
>>> import torch

>>> prompt = "A cat"
>>> # download an image
>>> image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
... ).resize((1024, 1024))
>>> # initialize the models and pipeline
>>> controlnet = ControlNetUnionModel.from_pretrained(
...     "xinsir/controlnet-union-sdxl-1.0", torch_dtype=torch.float16
... )
>>> vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
>>> pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0",
...     controlnet=controlnet,
...     vae=vae,
...     torch_dtype=torch.float16,
...     variant="fp16",
... )
>>> pipe.enable_model_cpu_offload()
>>> # prepare image
>>> processor = LineartAnimeDetector.from_pretrained("lllyasviel/Annotators")
>>> controlnet_img = processor(image, output_type="pil")
>>> # generate image
>>> image = pipe(prompt, control_image=[controlnet_img], control_mode=[3], height=1024, width=1024).images[0]

encode_prompt[[diffusers.StableDiffusionXLControlNetUnionPipeline.encode_prompt]]

encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)

ソース

パラメータ:

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

prompt_2 (str または list[str]、省略可能) : tokenizer_2 および text_encoder_2 に送信するプロンプトです。未定義の場合、両方のテキストエンコーダーで prompt が使用されます。

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

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

do_classifier_free_guidance (bool) : classifier free guidance を使用するかどうか

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

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

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

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

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

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

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

clip_skip (int, optional) : プロンプト埋め込みを計算する際に、CLIPからスキップするレイヤー数。値が1の場合、プロンプト埋め込みの計算に最終レイヤーの直前のレイヤーの出力が使用されます。

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。

get_guidance_scale_embedding[[diffusers.StableDiffusionXLControlNetUnionPipeline.get_guidance_scale_embedding]]

get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)

ソース

パラメータ:

w (torch.Tensor) : 指定されたガイダンススケールで埋め込みベクトルを生成し、タイムステップ埋め込みを後で強化します。

embedding_dim (int、任意、デフォルトは 512) : 生成する埋め込みの次元数。

dtype (torch.dtype、任意、デフォルトはtorch.float32) : 生成される埋め込みのデータ型。

戻り値: torch.Tensor

(len(w), embedding_dim) の形状を持つ埋め込みベクトル。

https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298 を参照してください。

StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)

ソース

パラメータ:

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

text_encoder (CLIPTextModel) : 凍結されたテキストエンコーダー。Stable Diffusion は CLIP のテキスト部分、具体的には clip-vit-large-patch14 バリアントを使用します。

text_encoder_2 ( CLIPTextModelWithProjection) : 2番目の凍結されたテキストエンコーダー。Stable Diffusion XL は CLIP のテキストおよびプール部分を使用しており、具体的には laion/CLIP-ViT-bigG-14-laion2B-39B-b160k バリアントを使用しています。

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

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

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

controlnet (ControlNetUnionModel) : デノイジング処理中に unet へ追加の条件付けを提供します。

scheduler (SchedulerMixin) : unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラ。DDIMScheduler、LMSDiscreteScheduler、または PNDMScheduler のいずれかです。

requires_aesthetics_score (bool、任意、デフォルトは"False") : 推論時にunetがaesthetic_score条件の受け渡しを必要とするかどうか。stabilityai/stable-diffusion-xl-refiner-1-0の設定も参照してください。

force_zeros_for_empty_prompt (bool、任意、デフォルトは"True") : 負のプロンプト埋め込みを常に0に設定するかどうか。stabilityai/stable-diffusion-xl-base-1-0の設定も参照してください。

add_watermarker (bool, 任意) : 出力画像にウォーターマークを付与するためにinvisible_watermark ライブラリを使用するかどうかを指定します。未定義の場合、パッケージがインストールされていればデフォルトで True となり、インストールされていなければウォーターマーカーは使用されません。

feature_extractor (CLIPImageProcessor) : 生成された画像から特徴量を抽出するためのCLIPImageProcessor。safety_checkerの入力として使用されます。

ControlNetによるガイダンスを用いたStable Diffusion XLの画像から画像への生成を行うPipelineです。

このモデルは DiffusionPipeline を継承しています。ライブラリがすべてのパイプラインに対して実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、以下の読み込みメソッドも継承します:

テキストインバージョンの埋め込みを読み込むためのload_textual_inversion()
LoRA重みの読み込みにload_lora_weights()
LoRA重みの保存にはsave_lora_weights()を使用します
IP Adapterの読み込みにload_ip_adapter()

call[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, strength: float = 0.8, num_inference_steps: int = 50, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, 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: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = 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, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 0.8, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)

ソース

パラメータ:

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

prompt_2 (str または list[str]、省略可能) : tokenizer_2 および text_encoder_2 に送信するプロンプトです。未定義の場合、両方のテキストエンコーダーで prompt が使用されます。

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]]): 初期画像は、画像生成プロセスの開始点として使用されます。image として画像の潜在変数（latents）を直接渡すことも可能で、その場合は再度エンコードされません。

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

height (int、optional、デフォルトは control_image のサイズ) : 生成される画像のピクセル単位の縦幅です。stabilityai/stable-diffusion-xl-base-1.0 や、低解像度に特化してファインチューニングされていないチェックポイントでは、512 ピクセル未満ではうまく動作しません。

width (int、optional、デフォルトは control_image のサイズ) : 生成される画像の幅（ピクセル単位）です。stabilityai/stable-diffusion-xl-base-1.0 や、低解像度に特化してファインチューニングされていないチェックポイントでは、512 ピクセル未満の値ではうまく動作しません。

strength (float、任意、デフォルト値は 0.8) : 参照となるimageの変換の程度を示します。0 から 1 の間の値である必要があります。imageは開始点として使用され、strengthが大きいほど多くのノイズが追加されます。デノイジングのステップ数は、最初に追加されるノイズの量に依存します。strengthが 1 の場合、追加されるノイズは最大となり、デノイジングプロセスはnum_inference_stepsで指定された全イテレーション数分実行されます。値が 1 である場合、imageは実質的に無視されます。

num_inference_steps (int、任意、デフォルト値は 50) : デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常はより高品質な画像が得られます。

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

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

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

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

eta (float、任意、デフォルト値は 0.0) : DDIM 論文におけるパラメータ eta (η) に相当します: https://huggingface.co/papers/2010.02502。[schedulers.DDIMScheduler](/docs/diffusers/main/ja/api/schedulers/ddim#diffusers.DDIMScheduler) にのみ適用され、それ以外のスケジューラーでは無視されます。

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

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

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

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

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

negative_pooled_prompt_embeds (torch.Tensor, 任意) : 事前に生成されたネガティブなプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、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) の形状を持つテンソルである必要があります。do_classifier_free_guidance が True に設定されている場合、負の画像埋め込みを含む必要があります。指定されない場合、ip_adapter_image 入力引数から埋め込みが計算されます。

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

return_dict (bool、任意、デフォルトはTrue) : プレーンなタプルではなく、StableDiffusionPipelineOutputを返すかどうか。

cross_attention_kwargs (dict, 任意) : 指定された場合、diffusers.models.attention_processor の self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

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

guess_mode (bool、任意、デフォルトはFalse) : このモードでは、プロンプトをすべて削除した場合でも、ControlNet エンコーダーは入力画像の内容を認識しようと最大限に努めます。guidance_scale は 3.0 から 5.0 の範囲が推奨されます。

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

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

control_mode (int or list[int] or list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image

original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : original_size が target_size と異なる場合、画像はダウンサンプリングまたはアップサンプリングされたように見えます。original_size は、指定されていない場合、デフォルトで (height, width) になります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。

crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : crops_coords_top_left を使用すると、crops_coords_top_left の位置から下方向に「切り抜かれた」ように見える画像を生成できます。crops_coords_top_left を (0, 0) に設定することで、通常は良好で中央が整った画像が得られます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定する必要があります。指定されない場合、デフォルトで (height, width) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

negative_original_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 特定の画像解像度に基づいて、生成プロセスをネガティブに条件付けます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_crops_coords_top_left (tuple[int]、optional、デフォルト値は (0, 0)) : 特定のクロップ座標に基づいて、生成プロセスを負の条件として設定します。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

negative_target_size (tuple[int]、optional、デフォルト値は (1024, 1024)) : 目標画像の解像度に基づいて、生成プロセスをネガティブに条件付けます。ほとんどの場合、target_size と同じである必要があります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。

aesthetic_score (float、任意、デフォルト値は 6.0) : 正のテキスト条件に影響を与えることで、生成された画像の審美スコアをシミュレートするために使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。

negative_aesthetic_score (float、optional、デフォルト値は 2.5) : https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL の micro-conditioning の一部です。ネガティブなテキスト条件に影響を与えることで、生成された画像の美観スコアをシミュレートするために使用できます。

clip_skip (int, optional) : プロンプト埋め込みを計算する際に、CLIPからスキップするレイヤー数。値が1の場合、プロンプト埋め込みの計算に最終レイヤーの直前のレイヤーの出力が使用されます。

callback_on_step_end (Callable、PipelineCallback、MultiPipelineCallbacks、任意) : 推論中の各デノイジングステップの終了時に呼び出される関数、または PipelineCallback または MultiPipelineCallbacks のサブクラスです。以下の引数を持ちます: 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 属性に列挙された変数のみを、リストに含めることができます。

戻り値: StableDiffusionPipelineOutput または tuple

return_dict が True の場合は StableDiffusionPipelineOutput、それ以外の場合は出力画像を含む tuple が返されます。

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

例:

# !pip install controlnet_aux
from diffusers import (
    StableDiffusionXLControlNetUnionImg2ImgPipeline,
    ControlNetUnionModel,
    AutoencoderKL,
)
from diffusers.utils import load_image
import torch
from PIL import Image
import numpy as np

prompt = "A cat"
# download an image
image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
)
# initialize the models and pipeline
controlnet = ControlNetUnionModel.from_pretrained(
    "brad-twinkl/controlnet-union-sdxl-1.0-promax", torch_dtype=torch.float16
)
vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
pipe = StableDiffusionXLControlNetUnionImg2ImgPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    controlnet=controlnet,
    vae=vae,
    torch_dtype=torch.float16,
    variant="fp16",
).to("cuda")
# `enable_model_cpu_offload` is not recommended due to multiple generations
height = image.height
width = image.width
ratio = np.sqrt(1024.0 * 1024.0 / (width * height))
# 3 * 3 upscale correspond to 16 * 3 multiply, 2 * 2 correspond to 16 * 2 multiply and so on.
scale_image_factor = 3
base_factor = 16
factor = scale_image_factor * base_factor
W, H = int(width * ratio) // factor * factor, int(height * ratio) // factor * factor
image = image.resize((W, H))
target_width = W // scale_image_factor
target_height = H // scale_image_factor
images = []
crops_coords_list = [
    (0, 0),
    (0, width // 2),
    (height // 2, 0),
    (width // 2, height // 2),
    0,
    0,
    0,
    0,
    0,
]
for i in range(scale_image_factor):
    for j in range(scale_image_factor):
        left = j * target_width
        top = i * target_height
        right = left + target_width
        bottom = top + target_height
        cropped_image = image.crop((left, top, right, bottom))
        cropped_image = cropped_image.resize((W, H))
        images.append(cropped_image)
# set ControlNetUnion input
result_images = []
for sub_img, crops_coords in zip(images, crops_coords_list):
    new_width, new_height = W, H
    out = pipe(
        prompt=[prompt] * 1,
        image=sub_img,
        control_image=[sub_img],
        control_mode=[6],
        width=new_width,
        height=new_height,
        num_inference_steps=30,
        crops_coords_top_left=(W, H),
        target_size=(W, H),
        original_size=(W * 2, H * 2),
    )
    result_images.append(out.images[0])
new_im = Image.new("RGB", (new_width * scale_image_factor, new_height * scale_image_factor))
new_im.paste(result_images[0], (0, 0))
new_im.paste(result_images[1], (new_width, 0))
new_im.paste(result_images[2], (new_width * 2, 0))
new_im.paste(result_images[3], (0, new_height))
new_im.paste(result_images[4], (new_width, new_height))
new_im.paste(result_images[5], (new_width * 2, new_height))
new_im.paste(result_images[6], (0, new_height * 2))
new_im.paste(result_images[7], (new_width, new_height * 2))
new_im.paste(result_images[8], (new_width * 2, new_height * 2))

encode_prompt[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.encode_prompt]]

encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)