Hugging Face's logo

Diffusers documentation

ControlNetUnion

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNetUnion

LoRA

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

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

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

StableDiffusionXLControlNetUnionPipeline

class diffusers.StableDiffusionXLControlNetUnionPipeline

< >

( vae: AutoencoderKLtext_encoder: CLIPTextModeltext_encoder_2: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertokenizer_2: CLIPTokenizerunet: UNet2DConditionModelcontrolnet: 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.MultiControlNetUnionModelscheduler: KarrasDiffusionSchedulersforce_zeros_for_empty_prompt: bool = Trueadd_watermarker: bool | None = Nonefeature_extractor: CLIPImageProcessorPil = Noneimage_encoder: CLIPVisionModelWithProjection = None )

パラメータ

  • vae (AutoencoderKL) — 画像を潜在表現にエンコードし、潜在表現からデコードするための Variational Auto-Encoder (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、省略可) — 出力画像にウォーターマークを付与するために invisible_watermark ライブラリを使用するかどうかを指定します。未定義の場合、パッケージがインストールされている場合は True がデフォルトとなり、それ以外の場合はウォーターマークは使用されません。

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

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

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

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Nonecontrol_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]]]] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50timesteps: list = Nonesigmas: list = Nonedenoising_end: float | None = Noneguidance_scale: float = 5.0negative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = 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 = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecross_attention_kwargs: dict[str, typing.Any] | None = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0guess_mode: bool = Falsecontrol_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_mode: int | list[int] | list[list[int]] | None = Noneoriginal_size: tuple = Nonecrops_coords_top_left: tuple = (0, 0)target_size: tuple = Nonenegative_original_size: tuple[int, int] | None = Nonenegative_crops_coords_top_left: tuple = (0, 0)negative_target_size: tuple[int, int] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list = ['latents'] ) → StableDiffusionPipelineOutput or tuple

パラメータ

  • 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 の寸法になります。height および/または width が渡された場合、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], 任意) — timesteps 引数をサポートするスケジューラーの set_timesteps メソッドで、デノイジングプロセスに使用するカスタムタイムステップ。未定義の場合、num_inference_steps が渡された際のデフォルトの動作が使用されます。降順で指定する必要があります。
  • sigmas (list[float]、任意) — set_timesteps メソッドで sigmas 引数を受け付けるスケジューラーにおいて、デノイジングプロセスに使用するカスタムのシグマです。定義されていない場合、num_inference_steps が渡された際のデフォルトの動作が使用されます。
  • denoising_end (float, 省略可) — 指定した場合、デノイジング全体のどの割合（0.0 から 1.0 の間）で処理を意図的に早期終了させるかを決定します。その結果、スケジューラによって選択された離散タイムステップによって決定されるように、返されるサンプルには依然としてかなりの量のノイズが残ります。denoising_end パラメータは、画像出力の洗練 に詳述されている「Mixture of Denoisers」マルチパイプライン構成の一部としてこのパイプラインが使用される場合に、理想的には利用されるべきです。
  • guidance_scale (float、任意、デフォルト値は 5.0) — この値を大きくすると、画像の品質が低下する代わりに、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, 任意) — ガウス分布からサンプリングされた事前生成されたノイズ付き latents。画像生成のインプットとして使用します。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム generator を用いてサンプリングを行い、latents テンソルが生成されます。
  • 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]、任意、デフォルト値は (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]、任意、デフォルト値は (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]、任意、デフォルトは (1024, 1024)) — ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定すべきです。指定されない場合、デフォルトで (height, width) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL の micro-conditioning の一部です。
  • negative_original_size (tuple[int]、任意、デフォルト値は (1024, 1024)) — 特定の画像解像度に基づいて、生成プロセスをネガティブに条件付けするために使用します。これは、https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL の micro-conditioning の一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。
  • negative_crops_coords_top_left (tuple[int]、任意、デフォルト値は (0, 0)) — 特定のクロップ座標に基づいて、生成プロセスをネガティブに条件付けするために使用します。これは、https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。
  • negative_target_size (tuple[int]、任意、デフォルト値は (1024, 1024)) — ターゲット画像の解像度に基づいて、生成プロセスをネガティブに条件付けするために使用します。ほとんどの場合、target_size と同じ値である必要があります。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、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

< >

( prompt: strprompt_2: str | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | None = Nonenegative_prompt_2: str | None = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonelora_scale: float | None = Noneclip_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) — 1つのプロンプトに対して生成する画像の数
  • 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, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。

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

get_guidance_scale_embedding

< >

( w: Tensorembedding_dim: int = 512dtype: dtype = torch.float32 ) → torch.Tensor

パラメータ

  • 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

class diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline

< >

( vae: AutoencoderKLtext_encoder: CLIPTextModeltext_encoder_2: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertokenizer_2: CLIPTokenizerunet: UNet2DConditionModelcontrolnet: 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.MultiControlNetUnionModelscheduler: KarrasDiffusionSchedulersrequires_aesthetics_score: bool = Falseforce_zeros_for_empty_prompt: bool = Trueadd_watermarker: bool | None = Nonefeature_extractor: CLIPImageProcessorPil = Noneimage_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_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 を継承しています。すべてのパイプラインに対してライブラリが実装している汎用的なメソッド（ダウンロードや保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

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

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_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]]]] = Noneheight: int | None = Nonewidth: int | None = Nonestrength: float = 0.8num_inference_steps: int = 50guidance_scale: float = 5.0negative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = 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 = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecross_attention_kwargs: dict[str, typing.Any] | None = Nonecontrolnet_conditioning_scale: float | list[float] = 0.8guess_mode: bool = Falsecontrol_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_mode: int | list[int] | list[list[int]] | None = Noneoriginal_size: tuple = Nonecrops_coords_top_left: tuple = (0, 0)target_size: tuple = Nonenegative_original_size: tuple[int, int] | None = Nonenegative_crops_coords_top_left: tuple = (0, 0)negative_target_size: tuple[int, int] | None = Noneaesthetic_score: float = 6.0negative_aesthetic_score: float = 2.5clip_skip: int | None = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']**kwargs ) → StableDiffusionPipelineOutput or tuple

パラメータ

  • 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 の寸法になります。height および/または width が渡された場合、image はそれに応じてリサイズされます。init で複数の ControlNet が指定されている場合、各要素が単一の ControlNet への入力として正しくバッチ処理できるよう、画像をリストとして渡す必要があります。
  • height (int、任意、デフォルトは control_image のサイズ)— 生成される画像のピクセル高さです。512 ピクセル未満の値は、stabilityai/stable-diffusion-xl-base-1.0 や、低解像度に特化してファインチューニングされていないチェックポイントでは適切に動作しません。
  • width (int、任意、デフォルトは 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 にのみ適用され、それ以外の場合は無視されます。
  • 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]、任意、デフォルト値は (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]、任意、デフォルト値は (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]、任意、デフォルトは (1024, 1024)) — ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定すべきです。指定されない場合、デフォルトで (height, width) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL の micro-conditioning の一部です。
  • negative_original_size (tuple[int]、任意、デフォルト値は (1024, 1024)) — 特定の画像解像度に基づいて、生成プロセスをネガティブに条件付けするために使用します。これは、https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL の micro-conditioning の一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。
  • negative_crops_coords_top_left (tuple[int]、任意、デフォルト値は (0, 0)) — 特定のクロップ座標に基づいて、生成プロセスをネガティブに条件付けするために使用します。これは、https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。詳細については、この issue スレッドを参照してください: https://github.com/huggingface/diffusers/issues/4208。
  • negative_target_size (tuple[int]、任意、デフォルト値は (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、任意、デフォルト値: 2.5) — https://huggingface.co/papers/2307.01952のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。ネガティブなテキスト条件に影響を与えることで、生成された画像の美観スコアをシミュレートするために使用できます。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、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

< >

( prompt: strprompt_2: str | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | None = Nonenegative_prompt_2: str | None = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonelora_scale: float | None = Noneclip_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) — 1つのプロンプトに対して生成する画像の数
  • 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, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。

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

StableDiffusionXLControlNetUnionInpaintPipeline

class diffusers.StableDiffusionXLControlNetUnionInpaintPipeline

< >

( vae: AutoencoderKLtext_encoder: CLIPTextModeltext_encoder_2: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertokenizer_2: CLIPTokenizerunet: UNet2DConditionModelcontrolnet: 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.MultiControlNetUnionModelscheduler: KarrasDiffusionSchedulersrequires_aesthetics_score: bool = Falseforce_zeros_for_empty_prompt: bool = Trueadd_watermarker: bool | None = Nonefeature_extractor: transformers.models.clip.image_processing_pil_clip.CLIPImageProcessorPil | None = Noneimage_encoder: transformers.models.clip.modeling_clip.CLIPVisionModelWithProjection | None = None )

パラメータ

  • vae (AutoencoderKL) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。
  • text_encoder (CLIPTextModel) — 凍結されたテキストエンコーダー。Stable Diffusion XL は 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_2 (CLIPTokenizer) — クラス CLIPTokenizer の2番目の Tokenizer。
  • unet (UNet2DConditionModel) — エンコードされた画像の潜在変数をノイズ除去するための条件付き U-Net アーキテクチャ。
  • scheduler (SchedulerMixin) — unet と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラー。DDIMScheduler、LMSDiscreteScheduler、または PNDMScheduler のいずれかです。

Stable Diffusion XL を使用したテキストから画像への生成を行う Pipeline。

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

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

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonemask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrol_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]]]] = Noneheight: int | None = Nonewidth: int | None = Nonepadding_mask_crop: int | None = Nonestrength: float = 0.9999num_inference_steps: int = 50denoising_start: float | None = Nonedenoising_end: float | None = Noneguidance_scale: float = 5.0negative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = 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 = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecross_attention_kwargs: dict[str, typing.Any] | None = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0guess_mode: bool = Falsecontrol_guidance_start: float | list[float] = 0.0control_guidance_end: float | list[float] = 1.0control_mode: int | list[int] | list[list[int]] | None = Noneguidance_rescale: float = 0.0original_size: tuple = Nonecrops_coords_top_left: tuple = (0, 0)target_size: tuple = Noneaesthetic_score: float = 6.0negative_aesthetic_score: float = 2.5clip_skip: int | None = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']**kwargs ) → ~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput or tuple

パラメータ

  • prompt (str または list[str]、省略可) — 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。
  • prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信するプロンプトです。定義されていない場合、両方のテキストエンコーダーに prompt が使用されます。
  • image (PIL.Image.Image) — インペイント対象のImage、または画像バッチを表すテンソル。つまり、画像の一部がmask_imageでマスクされ、promptに従って再描画されます。
  • mask_image (PIL.Image.Image) — Image、または画像バッチを表すテンソルで、image をマスクするために使用します。マスク内の白いピクセルは再描画され、黒いピクセルは保持されます。mask_image が PIL 画像の場合、使用前に単一チャネル（輝度）に変換されます。テンソルの場合は、3 チャネルではなく 1 つの色チャネル（L）を含む必要があるため、期待される形状は (B, H, W, 1) になります。
  • control_image (PipelineImageInput または list[PipelineImageInput]、任意) — 生成時に unet へのガイダンスを提供するための ControlNet の入力条件です。型が torch.Tensor として指定されている場合、そのまま ControlNet に渡されます。画像として PIL.Image.Image も受け付けられます。出力画像の寸法は、デフォルトで image の寸法になります。height および/または width が渡された場合、image はそれに応じてリサイズされます。init で複数の ControlNet が指定されている場合、各要素が単一の ControlNet への入力として正しくバッチ処理できるよう、画像をリストとして渡す必要があります。
  • height (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) — 生成される画像の高さ（ピクセル単位）。
  • width (int、任意、デフォルトは self.unet.config.sample_size * self.vae_scale_factor) — 生成される画像の幅（ピクセル単位）。
  • padding_mask_crop (int、任意、デフォルトは None) — 画像とマスクに適用されるクロップの余白サイズです。None の場合、画像および mask_image にはクロップが適用されません。padding_mask_crop が None でない場合、まず画像と同じアスペクト比を持ち、すべてのマスク領域を含む長方形領域を特定し、その後 padding_mask_crop に基づいてその領域を拡大します。その後、インペインティングのために元の画像サイズにリサイズする前に、拡大された領域に基づいて画像と mask_image がクロップされます。これは、マスク領域が小さく、画像が大きく、インペインティングに関連しない情報（背景など）を含む場合に有用です。
  • strength (float、任意、デフォルト値は 0.9999) — 概念的には、参照imageのマスクされた部分をどの程度変換するかを示します。0 から 1 の間の値である必要があります。imageが起点として使用され、strengthが大きいほど、それにより多くのノイズが加えられます。デノイジングのステップ数は、最初に追加されるノイズの量に依存します。strengthが 1 の場合、加えられるノイズは最大となり、デノイジングプロセスはnum_inference_stepsで指定された全イテレーション数分実行されます。したがって、値が 1 である場合、参照imageのマスクされた部分は実質的に無視されます。denoising_startが整数として宣言されている場合、strengthの値は無視されることに注意してください。
  • num_inference_steps (int、任意、デフォルト値は 50)— デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常はより高品質な画像が得られます。
  • denoising_start (float, 任意) — 指定した場合、デノイジング全体のどの割合（0.0 から 1.0 の間）をスキップしてから開始するかを示します。これにより、デノイジングプロセスの初期部分がスキップされ、渡された image が部分的にデノイズされた画像であるとみなされます。なお、このパラメータが指定されると、strength は無視されます。denoising_start パラメータは、画像出力の洗練 に詳述されている「Mixture of Denoisers」マルチパイプライン構成にこのパイプラインを統合する場合に特に有用です。
  • denoising_end (float, 任意) — 指定された場合、デノイジング全体のどの割合（0.0 から 1.0 の間）まで完了した時点で、意図的に処理を早期終了させるかを決定します。その結果、返されるサンプルには依然としてかなりの量のノイズ（最終的なタイムステップの約 20% 分）が残っており、denoising_start が 0.8 に設定された後続のパイプラインによってデノイズされるべきです。これにより、スケジューラの最終 20% の部分のみがデノイズされます。denoising_end パラメータは、画像出力の洗練 に詳述されている「Mixture of Denoisers」マルチパイプライン構成の一部としてこのパイプラインが機能する場合に、理想的には利用されるべきです。
  • 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 が使用されます。
  • prompt_embeds (torch.Tensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • negative_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 入力引数から埋め込みが計算されます。
  • pooled_prompt_embeds (torch.Tensor, 任意) — 事前に生成されたプールのテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に利用できます。 指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。
  • negative_pooled_prompt_embeds (torch.Tensor, 任意) — 事前に生成されたネガティブなプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプーリング済み negative_prompt_embeds が生成されます。
  • num_images_per_prompt (int、任意、デフォルトは 1) — プロンプトごとに生成する画像の数。
  • eta (float、省略可、デフォルト値は 0.0) — DDIM 論文におけるパラメータ eta (η) に相当します: https://huggingface.co/papers/2010.02502。 schedulers.DDIMScheduler にのみ適用され、それ以外の場合は無視されます。
  • generator (torch.Generator、省略可) — 生成を決定論的にするためのtorch ジェネレーター1つまたはリスト。
  • latents (torch.Tensor, 任意) — 画像生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイズ付き潜在変数。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。
  • 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.
  • guidance_rescale (float, optional, defaults to 0.0) — Guidance rescale factor from Common Diffusion Noise Schedules and Sample Steps are Flawed.
  • original_size (tuple[int]、任意、デフォルト値は (1024, 1024)) — original_size が target_size と異なる場合、画像はダウンサンプリングまたはアップサンプリングされたように見えます。 original_size は、指定されない場合、デフォルトで (width, height) になります。これは https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。
  • crops_coords_top_left (tuple[int]、任意、デフォルト値は (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]、任意、デフォルト値は (1024, 1024)) — ほとんどの場合、target_size は生成される画像の希望する高さおよび幅に設定すべきです。指定されない場合、デフォルトで (width, height) が使用されます。https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。
  • aesthetic_score (float、任意、デフォルト値は 6.0) — 正のテキスト条件に影響を与えることで、生成された画像の美観スコアをシミュレートするために使用されます。 https://huggingface.co/papers/2307.01952 のセクション 2.2 で説明されている SDXL のマイクロ条件付けの一部です。
  • negative_aesthetic_score (float、任意、デフォルト値: 2.5) — https://huggingface.co/papers/2307.01952のセクション 2.2 で説明されている SDXL のマイクロコンディショニングの一部です。ネガティブなテキスト条件に影響を与えることで、生成された画像の美観スコアをシミュレートするために使用できます。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、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 属性にリストされている変数のみを、このリストに含めることができます。

戻り値

~pipelines.stable_diffusion.StableDiffusionXLPipelineOutput または tuple

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

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

例:

from diffusers import StableDiffusionXLControlNetUnionInpaintPipeline, ControlNetUnionModel, AutoencoderKL
from diffusers.utils import load_image
import torch
import numpy as np
from PIL import Image

prompt = "A cat"
# download an image
image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/in_paint/overture-creations-5sI6fQgYIuo.png"
).resize((1024, 1024))
mask = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/in_paint/overture-creations-5sI6fQgYIuo_mask.png"
).resize((1024, 1024))
# 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 = StableDiffusionXLControlNetUnionInpaintPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    controlnet=controlnet,
    vae=vae,
    torch_dtype=torch.float16,
    variant="fp16",
)
pipe.enable_model_cpu_offload()
controlnet_img = image.copy()
controlnet_img_np = np.array(controlnet_img)
mask_np = np.array(mask)
controlnet_img_np[mask_np > 0] = 0
controlnet_img = Image.fromarray(controlnet_img_np)
# generate image
image = pipe(prompt, image=image, mask_image=mask, control_image=[controlnet_img], control_mode=[7]).images[0]
image.save("inpaint.png")

encode_prompt

< >

( prompt: strprompt_2: str | None = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | None = Nonenegative_prompt_2: str | None = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonelora_scale: float | None = Noneclip_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) — 1つのプロンプトに対して生成する画像の数
  • 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, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。

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

Update on GitHub

←ControlNet-Sana DDIM→