Hugging Face's logo

Diffusers documentation

Stable Diffusion 3 と ControlNet

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

and get access to the augmented documentation experience

to get started

Stable Diffusion 3 と ControlNet

LoRA

StableDiffusion3ControlNetPipeline は、Stable Diffusion 3 向けの 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 mainly implemented by The InstantX Team. The inpainting-related code was developed by The Alimama Creative Team. You can find pre-trained checkpoints for SD3-ControlNet in the table below:

ControlNetのタイプ開発者リンク
CannyInstantX チームリンク
深さInstantX チームリンク
ポーズInstantX チームリンク
タイルInstantX チームリンク
インペインティングAlimamaCreative チームリンク

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

StableDiffusion3ControlNetPipeline

class diffusers.StableDiffusion3ControlNetPipeline

< >

( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizercontrolnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModelimage_encoder: transformers.models.siglip.modeling_siglip.SiglipVisionModel | None = Nonefeature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None )

パラメータ

  • transformer (SD3Transformer2DModel) — エンコードされた画像潜在変数からノイズを除去するための、条件付き Transformer (MMDiT) アーキテクチャ。
  • scheduler (FlowMatchEulerDiscreteScheduler) — transformer と組み合わせて、エンコードされた画像の潜在変数からノイズを除去するために使用するスケジューラ。
  • vae (AutoencoderKL) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。
  • text_encoder (CLIPTextModelWithProjection) — CLIP、 具体的には clip-vit-large-patch14 バリアントで、 hidden_size を次元とする対角行列で初期化された追加の投影層を備えています。
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP、 具体的には laion/CLIP-ViT-bigG-14-laion2B-39B-b160k バリアントです。
  • text_encoder_3 (T5EncoderModel) — 凍結されたテキストエンコーダーです。Stable Diffusion 3 は T5、具体的には t5-v1_1-xxl バリアントを使用しています。
  • tokenizer (CLIPTokenizer) — CLIPTokenizer クラスのトークナイザー。
  • tokenizer_2 (CLIPTokenizer) — クラス CLIPTokenizer の2番目の Tokenizer。
  • tokenizer_3 (T5TokenizerFast) — クラス T5Tokenizer のトークナイザー。
  • controlnet (SD3ControlNetModel または list[SD3ControlNetModel] または SD3MultiControlNetModel) — デノイジング処理中に unet に追加の条件付けを提供します。リストとして複数の ControlNet を設定した場合、各 ControlNet の出力が加算され、1 つの統合された追加条件付けが作成されます。
  • image_encoder (SiglipVisionModel、任意) — IP Adapter用の事前学習済みビジョンモデル。
  • feature_extractor (SiglipImageProcessor、任意) — IP Adapter用の画像プロセッサ。

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneprompt_3: str | list[str] | None = Noneheight: 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]] = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = Nonenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Nonenum_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] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_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: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

パラメータ

  • prompt (str または list[str]、省略可) — 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。
  • prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信するプロンプトです。未定義の場合、代わりに prompt が使用されます。
  • prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信するプロンプトです。未定義の場合、代わりに prompt が使用されます。
  • 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、任意、デフォルト値は 5.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 が指定されている場合、対応するスケールをリストとして設定できます。
  • controlnet_pooled_projections (torch.FloatTensor、shape (batch_size, projection_dim)) — controlnet の入力条件の embeddings から投影された embeddings。
  • negative_prompt (str または list[str]、省略可) — 画像生成をガイドしないプロンプトです。未定義の場合、代わりに negative_prompt_embeds を渡す必要があります。ガイダンスを使用していない場合は無視されます（guidance_scale が 1 未満の場合は無視されます）。
  • negative_prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信する、画像生成を誘導しないためのプロンプトです。未定義の場合、代わりに negative_prompt が使用されます。
  • negative_prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信する、画像生成を導かないためのプロンプトです。未定義の場合、代わりに negative_prompt が使用されます。
  • num_images_per_prompt (int、任意、デフォルトは 1) — プロンプトごとに生成する画像の数。
  • generator (torch.Generator または list[torch.Generator]、省略可) — 生成を決定論的にするためのtorch ジェネレーター1つまたはリスト。
  • latents (torch.FloatTensor, 任意) — 画像生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジーな潜在変数です。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。
  • prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • negative_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に使用できます。 指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプーリング済み negative_prompt_embeds が生成されます。
  • ip_adapter_image (PipelineImageInput、任意) — IP Adapter と組み合わせて使用する任意の画像入力です。
  • ip_adapter_image_embeds (torch.Tensor, 任意) — 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) — ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput を返すかどうか。プレーンなタプルを返すこともできます。
  • joint_attention_kwargs (dict、省略可) — 指定された場合、diffusers.models.attention_processor で定義されている self.processor 配下の AttentionProcessor に渡される kwargs の辞書です。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。
  • 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、デフォルトは 256) — prompt に使用する最大シーケンス長。

戻り値

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers import StableDiffusion3ControlNetPipeline
>>> from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
>>> from diffusers.utils import load_image

>>> controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny", torch_dtype=torch.float16)

>>> pipe = StableDiffusion3ControlNetPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> control_image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png"
... )
>>> prompt = "A bird in space"
>>> image = pipe(
...     prompt, control_image=control_image, height=1024, width=768, controlnet_conditioning_scale=0.7
... ).images[0]
>>> image.save("sd3.png")

encode_image

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]device: device ) → torch.Tensor

パラメータ

  • image (PipelineImageInput) — エンコード対象の入力画像。
  • device — (torch.device): Torch のデバイス。

戻り値

torch.Tensor

エンコードされた画像の特徴表現。

事前学習済みの画像エンコーダーを使用して、指定された画像を特徴表現にエンコードします。

encode_prompt

< >

( prompt: str | list[str]prompt_2: str | list[str]prompt_3: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneclip_skip: int | None = Nonemax_sequence_length: int = 256lora_scale: float | None = None )

パラメータ

  • prompt (str または list[str]、省略可能) — エンコードするプロンプト
  • prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信するプロンプトです。定義されていない場合、すべての text-encoder で prompt が使用されます。
  • prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信するプロンプトです。定義されていない場合、すべてのテキストエンコーダーで 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 が使用されます。
  • negative_prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に渡す、画像生成を誘導しないためのプロンプトです。定義されていない場合、すべての text-encoder で negative_prompt が使用されます。
  • prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • negative_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に使用できます。 指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプーリング済み negative_prompt_embeds が生成されます。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。
  • lora_scale (float, 省略可) — LoRA レイヤーが読み込まれている場合、テキストエンコーダーのすべての LoRA レイヤーに適用される LoRA スケールです。

prepare_ip_adapter_image_embeds

< >

( ip_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: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = True )

パラメータ

  • ip_adapter_image (PipelineImageInput、任意) — IP-Adapter 用の特徴量抽出に使用する入力画像です。
  • ip_adapter_image_embeds (torch.Tensor, 任意) — 事前計算された画像埋め込み。
  • device — (torch.device、省略可): Torch のデバイス。
  • num_images_per_prompt (int、デフォルト値は 1) — プロンプトごとに生成する画像の数。
  • do_classifier_free_guidance (bool、デフォルトは True) — classifier free guidance を使用するかどうかを指定します。

IP-Adapterで使用する画像エンベディングを準備します。

ip_adapter_image または ip_adapter_image_embeds のいずれかを渡す必要があります。

StableDiffusion3ControlNetInpaintingPipeline

class diffusers.StableDiffusion3ControlNetInpaintingPipeline

< >

( transformer: SD3Transformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLtext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizertext_encoder_2: CLIPTextModelWithProjectiontokenizer_2: CLIPTokenizertext_encoder_3: T5EncoderModeltokenizer_3: T5Tokenizercontrolnet: diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel | list[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel] | diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModelimage_encoder: SiglipModel = Nonefeature_extractor: transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil | None = None )

パラメータ

  • transformer (SD3Transformer2DModel) — エンコードされた画像潜在変数からノイズを除去するための、条件付き Transformer (MMDiT) アーキテクチャ。
  • scheduler (FlowMatchEulerDiscreteScheduler) — transformer と組み合わせて、エンコードされた画像の潜在変数からノイズを除去するために使用するスケジューラ。
  • vae (AutoencoderKL) — 画像を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ (VAE) モデル。
  • text_encoder (CLIPTextModelWithProjection) — CLIP、 具体的には clip-vit-large-patch14 バリアントで、 hidden_size を次元とする対角行列で初期化された追加の投影層を備えています。
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP、 具体的には laion/CLIP-ViT-bigG-14-laion2B-39B-b160k バリアントです。
  • text_encoder_3 (T5EncoderModel) — 凍結されたテキストエンコーダーです。Stable Diffusion 3 は T5、具体的には t5-v1_1-xxl バリアントを使用しています。
  • tokenizer (CLIPTokenizer) — CLIPTokenizer クラスのトークナイザー。
  • tokenizer_2 (CLIPTokenizer) — クラス CLIPTokenizer の2番目の Tokenizer。
  • tokenizer_3 (T5TokenizerFast) — クラス T5Tokenizer のトークナイザー。
  • controlnet (SD3ControlNetModel または list[SD3ControlNetModel] または SD3MultiControlNetModel) — デノイジング処理中に transformer に追加の条件付けを提供します。リストとして複数の ControlNet を設定した場合、各 ControlNet の出力が加算され、1 つの統合された追加条件付けが作成されます。
  • image_encoder (PreTrainedModel、任意) — IP Adapter用の事前学習済みビジョンモデル。
  • feature_extractor (BaseImageProcessor、任意) — IP Adapter 用の画像プロセッサ。

__call__

< >

( prompt: str | list[str] = Noneprompt_2: str | list[str] | None = Noneprompt_3: str | list[str] | None = Noneheight: 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_mask: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Nonecontrolnet_conditioning_scale: float | list[float] = 1.0controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = Nonenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Nonenum_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] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_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: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truejoint_attention_kwargs: dict[str, typing.Any] | None = Noneclip_skip: int | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput or tuple

パラメータ

  • prompt (str または list[str]、省略可) — 画像生成をガイドするためのプロンプトです。未定義の場合、代わりに prompt_embeds を渡す必要があります。
  • prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信するプロンプトです。未定義の場合、代わりに prompt が使用されます。
  • prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信するプロンプトです。未定義の場合、代わりに prompt が使用されます。
  • 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、任意、デフォルト値は 5.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]) — インペイント（画像の一部を塗り替える処理）の対象となる画像バッチを表す Image、NumPy 配列、またはテンソルです。画像のどの部分を control_mask でマスクし、prompt に従って再描画するかを指定します。NumPy 配列および PyTorch テンソルの場合、想定される値の範囲は [0, 1] です。テンソルまたはテンソルのリストの場合、想定される形状は (B, C, H, W) です。NumPy 配列または配列のリストの場合、想定される形状は (B, H, W, C) または (H, W, C) です。
  • control_mask (torch.Tensor、PIL.Image.Image、np.ndarray、list[torch.Tensor]、list[PIL.Image.Image]、list[np.ndarray]) — image をマスクするための画像バッチを表す Image、NumPy 配列、またはテンソルです。マスク内の白いピクセルは再描画され、黒いピクセルは保持されます。mask_image が PIL 画像の場合、使用前に単一チャネル（輝度）に変換されます。NumPy 配列または PyTorch テンソルの場合は、3 チャネルではなく 1 つの色チャネル（L）を含む必要があります。したがって、PyTorch テンソルの想定される形状は (B, 1, H, W) となり、NumPy 配列の場合は (B, H, W, 1)、(B, H, W)、(H, W, 1)、または (H, W) となります。
  • controlnet_conditioning_scale (float または list[float]、任意、デフォルト値は 1.0) — ControlNet の出力は、元の unet の残差に加算される前に controlnet_conditioning_scale 倍されます。init で複数の ControlNet が指定されている場合、対応するスケールをリストとして設定できます。
  • controlnet_pooled_projections (torch.FloatTensor、shape (batch_size, projection_dim)) — controlnet の入力条件の embeddings から投影された embeddings。
  • negative_prompt (str または list[str]、省略可) — 画像生成をガイドしないプロンプトです。未定義の場合、代わりに negative_prompt_embeds を渡す必要があります。ガイダンスを使用していない場合は無視されます（guidance_scale が 1 未満の場合は無視されます）。
  • negative_prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信する、画像生成を誘導しないためのプロンプトです。未定義の場合、代わりに negative_prompt が使用されます。
  • negative_prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信する、画像生成を導かないためのプロンプトです。未定義の場合、代わりに negative_prompt が使用されます。
  • num_images_per_prompt (int、任意、デフォルトは 1) — プロンプトごとに生成する画像の数。
  • generator (torch.Generator または list[torch.Generator]、省略可) — 生成を決定論的にするためのtorch ジェネレーター1つまたはリスト。
  • latents (torch.FloatTensor, 任意) — 画像生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジーな潜在変数です。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜在変数テンソルが生成されます。
  • prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • negative_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に使用できます。 指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプーリング済み negative_prompt_embeds が生成されます。
  • ip_adapter_image (PipelineImageInput、任意) — IP Adapter と組み合わせて使用する任意の画像入力です。
  • ip_adapter_image_embeds (torch.Tensor, 任意) — 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) — ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput を返すかどうか。プレーンなタプルを返すこともできます。
  • joint_attention_kwargs (dict、省略可) — 指定された場合、diffusers.models.attention_processor で定義されている self.processor 配下の AttentionProcessor に渡される kwargs の辞書です。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。
  • 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、デフォルトは 256) — prompt に使用する最大シーケンス長。

戻り値

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput または tuple

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

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

例:

>>> import torch
>>> from diffusers.utils import load_image, check_min_version
>>> from diffusers.pipelines import StableDiffusion3ControlNetInpaintingPipeline
>>> from diffusers.models.controlnet_sd3 import SD3ControlNetModel

>>> controlnet = SD3ControlNetModel.from_pretrained(
...     "alimama-creative/SD3-Controlnet-Inpainting", use_safetensors=True, extra_conditioning_channels=1
... )
>>> pipe = StableDiffusion3ControlNetInpaintingPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers",
...     controlnet=controlnet,
...     torch_dtype=torch.float16,
... )
>>> pipe.text_encoder.to(torch.float16)
>>> pipe.controlnet.to(torch.float16)
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog.png"
... )
>>> mask = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog_mask.png"
... )
>>> width = 1024
>>> height = 1024
>>> prompt = "A cat is sitting next to a puppy."
>>> generator = torch.Generator(device="cuda").manual_seed(24)
>>> res_image = pipe(
...     negative_prompt="deformed, distorted, disfigured, poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, mutated hands and fingers, disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation, NSFW",
...     prompt=prompt,
...     height=height,
...     width=width,
...     control_image=image,
...     control_mask=mask,
...     num_inference_steps=28,
...     generator=generator,
...     controlnet_conditioning_scale=0.95,
...     guidance_scale=7,
... ).images[0]
>>> res_image.save(f"sd3.png")

encode_image

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]device: device ) → torch.Tensor

パラメータ

  • image (PipelineImageInput) — エンコード対象の入力画像。
  • device — (torch.device): Torch のデバイス。

戻り値

torch.Tensor

エンコードされた画像の特徴表現。

事前学習済みの画像エンコーダーを使用して、指定された画像を特徴表現にエンコードします。

encode_prompt

< >

( prompt: str | list[str]prompt_2: str | list[str]prompt_3: str | list[str]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | list[str] | None = Nonenegative_prompt_2: str | list[str] | None = Nonenegative_prompt_3: str | list[str] | None = Noneprompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonepooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = Noneclip_skip: int | None = Nonemax_sequence_length: int = 256lora_scale: float | None = None )

パラメータ

  • prompt (str または list[str]、省略可能) — エンコードするプロンプト
  • prompt_2 (str または list[str]、省略可) — tokenizer_2 および text_encoder_2 に送信するプロンプトです。定義されていない場合、すべての text-encoder で prompt が使用されます。
  • prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に送信するプロンプトです。定義されていない場合、すべてのテキストエンコーダーで 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 が使用されます。
  • negative_prompt_3 (str または list[str]、省略可) — tokenizer_3 および text_encoder_3 に渡す、画像生成を誘導しないためのプロンプトです。定義されていない場合、すべての text-encoder で negative_prompt が使用されます。
  • prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが生成されます。
  • negative_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が生成されます。
  • pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたプールのテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどに簡単に使用できます。 指定されない場合、prompt 入力引数からプールのテキスト埋め込みが生成されます。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 任意) — 事前に生成されたネガティブなプーリング済みテキスト埋め込み。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、negative_prompt 入力引数からプーリング済み negative_prompt_embeds が生成されます。
  • clip_skip (int, 任意) — プロンプト埋め込みを計算する際に、CLIP からスキップするレイヤー数です。値が 1 の場合、最終レイヤーの直前のレイヤーの出力がプロンプト埋め込みの計算に使用されます。
  • lora_scale (float, 省略可) — LoRA レイヤーが読み込まれている場合、テキストエンコーダーのすべての LoRA レイヤーに適用される LoRA スケールです。

prepare_ip_adapter_image_embeds

< >

( ip_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: typing.Optional[torch.Tensor] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = True )

パラメータ

  • ip_adapter_image (PipelineImageInput、任意) — IP-Adapter 用の特徴量抽出に使用する入力画像です。
  • ip_adapter_image_embeds (torch.Tensor, 任意) — 事前計算された画像埋め込み。
  • device — (torch.device、省略可): Torch のデバイス。
  • num_images_per_prompt (int、デフォルト値は 1) — プロンプトごとに生成する画像の数。
  • do_classifier_free_guidance (bool、デフォルトは True) — classifier free guidance を使用するかどうかを指定します。

IP-Adapterで使用する画像エンベディングを準備します。

ip_adapter_image または ip_adapter_image_embeds のいずれかを渡す必要があります。

StableDiffusion3PipelineOutput

class diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

パラメータ

  • images (list[PIL.Image.Image] または np.ndarray) — batch_size 長さのデノイズ済み PIL イメージのリスト、または (batch_size, height, width, num_channels) の形状を持つ numpy 配列。PIL イメージまたは numpy 配列は、拡散パイプラインのデノイズ済みイメージを表します。

Stable Diffusion パイプライン用の出力クラスです。

Update on GitHub

←Hunyuan-DiT と ControlNet Stable Diffusion XL と ControlNet→