Hugging Face's logo

Diffusers documentation

ControlNet dengan Stable Diffusion 3

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNet dengan Stable Diffusion 3

LoRA

StableDiffusion3ControlNetPipeline adalah implementasi ControlNet untuk Stable Diffusion 3.

ControlNet diperkenalkan dalam Menambahkan Kontrol Kondisional ke Model Difusi Teks-ke-Gambar oleh Lvmin Zhang, Anyi Rao, dan Maneesh Agrawala.

Dengan model ControlNet, Anda dapat menyediakan gambar kontrol tambahan untuk mengondisikan dan mengendalikan generasi Stable Diffusion. Misalnya, jika Anda menyediakan peta kedalaman, model ControlNet akan menghasilkan gambar yang mempertahankan informasi spasial dari peta kedalaman tersebut. Ini adalah cara yang lebih fleksibel dan akurat untuk mengendalikan proses generasi gambar.

Abstrak dari makalah tersebut adalah:

Kami memperkenalkan ControlNet, sebuah arsitektur jaringan saraf untuk menambahkan kontrol kondisional spasial ke model difusi teks-ke-gambar besar yang telah dilatih sebelumnya. ControlNet mengunci model difusi besar yang siap produksi, dan memanfaatkan ulang lapisan enkoding yang dalam dan robust yang telah dilatih sebelumnya dengan miliaran gambar sebagai tulang punggung yang kuat untuk mempelajari berbagai set kontrol kondisional. Arsitektur saraf ini terhubung dengan “zero convolutions” (lapisan konvolusi yang diinisialisasi nol) yang secara bertahap mengembangkan parameter dari nol dan memastikan bahwa tidak ada noise berbahaya yang dapat memengaruhi finetuning. Kami menguji berbagai kontrol kondisional, misalnya, tepi, kedalaman, segmentasi, pose manusia, dll., dengan Stable Diffusion, menggunakan satu atau beberapa kondisi, dengan atau tanpa prompt. Kami menunjukkan bahwa pelatihan ControlNet bersifat robust dengan dataset kecil (<50k) dan besar (>1m). Hasil ekstensif menunjukkan bahwa ControlNet dapat memfasilitasi aplikasi yang lebih luas untuk mengontrol model difusi gambar.

Kode controlnet ini terutama diimplementasikan oleh The InstantX Team. Kode yang terkait dengan inpainting dikembangkan oleh The Alimama Creative Team. Anda dapat menemukan checkpoint terlatih sebelumnya untuk SD3-ControlNet pada tabel di bawah ini:

Jenis ControlNetPengembangTautan
CannyTim InstantXTautan
KedalamanTim InstantXTautan
PoseTim InstantXTautan
UbinTim InstantXTautan
InpaintingTim AlimamaCreativetautan

Pastikan untuk melihat panduan Schedulers untuk mempelajari cara mengeksplorasi tradeoff antara kecepatan dan kualitas scheduler, serta lihat bagian reuse components across pipelines untuk mempelajari cara memuat komponen yang sama secara efisien ke dalam beberapa pipeline.

StableDiffusion3ControlNetPipeline

kelas 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 )

Parameter

  • transformer (SD3Transformer2DModel) — Arsitektur Conditional Transformer (MMDiT) untuk mendenoise latens gambar yang telah dikodekan.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.
  • vae (AutoencoderKL) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
  • text_encoder (CLIPTextModelWithProjection) — CLIP, khususnya varian clip-vit-large-patch14, dengan lapisan proyeksi tambahan yang diinisialisasi dengan matriks diagonal berdimensi hidden_size.
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP, khususnya varian laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.
  • text_encoder_3 (T5EncoderModel) — Text-encoder yang dibekukan. Stable Diffusion 3 menggunakan T5, khususnya varian t5-v1_1-xxl.
  • tokenizer (CLIPTokenizer) — Tokenizer dari kelas CLIPTokenizer.
  • tokenizer_2 (CLIPTokenizer) — Tokenizer kedua dari kelas CLIPTokenizer.
  • tokenizer_3 (T5TokenizerFast) — Tokenizer dari kelas T5Tokenizer.
  • controlnet (SD3ControlNetModel atau list[SD3ControlNetModel] atau SD3MultiControlNetModel) — Menyediakan kondisioning tambahan untuk unet selama proses denoising. Jika Anda mengatur beberapa ControlNet sebagai list, output dari masing-masing ControlNet akan dijumlahkan untuk membuat satu kondisioning tambahan yang digabungkan.
  • image_encoder (SiglipVisionModel, opsional) — Model Visi yang telah dilatih sebelumnya untuk IP Adapter.
  • feature_extractor (SiglipImageProcessor, opsional) — Pemroses gambar untuk 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

Parameter

  • prompt (str atau list[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds sebagai gantinya.
  • prompt_2 (str atau list[str], opsional) — Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt akan digunakan sebagai gantinya
  • prompt_3 (str atau list[str], opsional) — Prompt atau prompt yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, prompt akan digunakan sebagai gantinya
  • height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 1024 untuk hasil terbaik.
  • width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • sigmas (list[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas dalam metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.
  • guidance_scale (float, opsional, default 5.0) — Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. dari Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.
  • control_guidance_start (float atau list[float], opsional, default 0.0) — Persentase dari total langkah di mana ControlNet mulai diterapkan.
  • control_guidance_end (float atau list[float], opsional, default 1.0) — Persentase total langkah di mana ControlNet berhenti diterapkan.
  • 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]] atau list[list[PIL.Image.Image]]): Kondisi input ControlNet untuk memberikan panduan kepada unet dalam proses generasi. Jika tipe dispesifikasikan sebagai torch.Tensor, nilai tersebut diteruskan ke ControlNet apa adanya. PIL.Image.Image juga dapat diterima sebagai gambar. Dimensi gambar output secara default mengikuti dimensi image. Jika tinggi dan/atau lebar diteruskan, image akan di-resize sesuai dengan nilai tersebut. Jika beberapa ControlNet dispesifikasikan dalam init, gambar harus diteruskan sebagai list sehingga setiap elemen list dapat di-batch dengan benar untuk input ke satu ControlNet.
  • controlnet_conditioning_scale (float atau list[float], opsional, default 1.0) — Output dari ControlNet dikalikan dengan controlnet_conditioning_scale sebelum ditambahkan ke residual pada unet asli. Jika beberapa ControlNet ditentukan dalam init, Anda dapat menetapkan skala yang sesuai sebagai list.
  • controlnet_pooled_projections (torch.FloatTensor dengan bentuk (batch_size, projection_dim)) — Embeddings yang diproyeksikan dari embeddings kondisi input controlnet.
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • negative_prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan sebagai gantinya
  • negative_prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk memandu generasi gambar yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, negative_prompt digunakan sebagai gantinya
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.
  • latents (torch.FloatTensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • prompt_embeds (torch.FloatTensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pemberatan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, mis. pembobotan prompt. Jika tidak disediakan, embedding teks pooled akan dibuat dari argumen input prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang sudah digenerate sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan digenerate dari argumen input negative_prompt.
  • ip_adapter_image (PipelineImageInput, opsional) — Input gambar opsional untuk bekerja dengan IP Adapters.
  • ip_adapter_image_embeds (torch.Tensor, opsional) — Embedding gambar yang telah dibuat sebelumnya untuk IP-Adapter. Harus berupa tensor dengan bentuk (batch_size, num_images, emb_dim). Harus berisi embedding gambar negatif jika do_classifier_free_guidance diatur ke True. Jika tidak disediakan, embedding dihitung dari argumen input ip_adapter_image.
  • output_type (str, opsional, defaultnya "pil") — Format output dari generate image. Pilih antara PIL: PIL.Image.Image atau np.array.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput alih-alih tuple biasa.
  • joint_attention_kwargs (dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.
  • clip_skip (int, opsional) — Jumlah lapisan yang akan dilewati dari CLIP saat menghitung embedding prompt. Nilai 1 berarti output dari lapisan pra-akhir akan digunakan untuk menghitung embedding prompt.
  • callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.
  • max_sequence_length (int defaultnya 256) — Panjang maksimum urutan yang digunakan dengan prompt.

Mengembalikan

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput atau tuple

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput jika return_dict bernilai True, selain itu berupa tuple. Saat mengembalikan tuple, elemen pertama adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> 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

Parameter

  • image (PipelineImageInput) — Gambar input yang akan dikodekan.
  • device — (torch.device): Perangkat Torch.

Mengembalikan

torch.Tensor

Representasi fitur gambar yang telah dikodekan.

Mengkodekan gambar yang diberikan menjadi representasi fitur menggunakan pengkode gambar yang telah dilatih sebelumnya.

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 )

Parameter

  • prompt (str atau list[str], opsional) — prompt yang akan dienkod
  • prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt digunakan di semua text-encoder
  • prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, prompt digunakan di semua text-encoder
  • device — (torch.device): perangkat torch
  • num_images_per_prompt (int) — jumlah gambar yang harus dihasilkan per prompt
  • do_classifier_free_guidance (bool) — apakah akan menggunakan classifier free guidance atau tidak
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • negative_prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar, yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di semua text-encoder.
  • negative_prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar, yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, negative_prompt digunakan di semua text-encoder.
  • prompt_embeds (torch.FloatTensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pemberatan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, mis. pembobotan prompt. Jika tidak disediakan, embedding teks pooled akan dibuat dari argumen input prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang sudah digenerate sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan digenerate dari argumen input negative_prompt.
  • clip_skip (int, opsional) — Jumlah lapisan yang akan dilewati dari CLIP saat menghitung embedding prompt. Nilai 1 berarti output dari lapisan pra-akhir akan digunakan untuk menghitung embedding prompt.
  • lora_scale (float, opsional) — Skala LoRA yang akan diterapkan ke semua lapisan LoRA dari text encoder jika lapisan LoRA dimuat.

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 )

Parameter

  • ip_adapter_image (PipelineImageInput, opsional) — Gambar input untuk mengekstrak fitur untuk IP-Adapter.
  • ip_adapter_image_embeds (torch.Tensor, opsional) — Embedding gambar yang telah dihitung sebelumnya.
  • device — (torch.device, opsional): Perangkat Torch.
  • num_images_per_prompt (int, defaultnya 1) — Jumlah gambar yang harus dihasilkan per prompt.
  • do_classifier_free_guidance (bool, defaultnya True) — Apakah akan menggunakan classifier free guidance atau tidak.

Menyiapkan embedding gambar untuk digunakan dalam IP-Adapter.

ip_adapter_image atau ip_adapter_image_embeds harus diteruskan.

StableDiffusion3ControlNetInpaintingPipeline

kelas 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 )

Parameter

  • transformer (SD3Transformer2DModel) — Arsitektur Conditional Transformer (MMDiT) untuk mendenoise latens gambar yang telah dikodekan.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler yang digunakan bersama transformer untuk menghilangkan noise pada latens gambar yang telah dikodekan.
  • vae (AutoencoderKL) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.
  • text_encoder (CLIPTextModelWithProjection) — CLIP, khususnya varian clip-vit-large-patch14, dengan lapisan proyeksi tambahan yang diinisialisasi dengan matriks diagonal berdimensi hidden_size.
  • text_encoder_2 (CLIPTextModelWithProjection) — CLIP, khususnya varian laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.
  • text_encoder_3 (T5EncoderModel) — Text-encoder yang dibekukan. Stable Diffusion 3 menggunakan T5, khususnya varian t5-v1_1-xxl.
  • tokenizer (CLIPTokenizer) — Tokenizer dari kelas CLIPTokenizer.
  • tokenizer_2 (CLIPTokenizer) — Tokenizer kedua dari kelas CLIPTokenizer.
  • tokenizer_3 (T5TokenizerFast) — Tokenizer dari kelas T5Tokenizer.
  • controlnet (SD3ControlNetModel atau list[SD3ControlNetModel] atau SD3MultiControlNetModel) — Menyediakan kondisioning tambahan untuk transformer selama proses denoising. Jika Anda mengatur beberapa ControlNet sebagai list, output dari masing-masing ControlNet akan dijumlahkan untuk membuat satu kondisioning tambahan yang digabungkan.
  • image_encoder (PreTrainedModel, opsional) — Model Visi Pra-terlatih untuk IP Adapter.
  • feature_extractor (BaseImageProcessor, opsional) — Pemroses gambar untuk 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

Parameter

  • prompt (str atau list[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds sebagai gantinya.
  • prompt_2 (str atau list[str], opsional) — Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt akan digunakan sebagai gantinya
  • prompt_3 (str atau list[str], opsional) — Prompt atau prompt yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, prompt akan digunakan sebagai gantinya
  • height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Tinggi gambar yang dihasilkan dalam piksel. Nilai ini secara default diatur ke 1024 untuk hasil terbaik.
  • width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) — Lebar gambar yang dihasilkan dalam piksel. Ini diatur ke 1024 secara default untuk hasil terbaik.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • sigmas (list[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas dalam metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.
  • guidance_scale (float, opsional, default 5.0) — Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. dari Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.
  • control_guidance_start (float atau list[float], opsional, default 0.0) — Persentase dari total langkah di mana ControlNet mulai diterapkan.
  • control_guidance_end (float atau list[float], opsional, default 1.0) — Persentase total langkah di mana ControlNet berhenti diterapkan.
  • control_image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], list[np.ndarray]) — Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk di-inpaint (bagian mana dari gambar yang akan diberi mask dengan control_mask dan diwarnai ulang sesuai dengan prompt). Baik untuk array numpy maupun tensor pytorch, rentang nilai yang diharapkan adalah antara [0, 1]. Jika berupa tensor atau daftar tensor, bentuk yang diharapkan adalah (B, C, H, W). Jika berupa array numpy atau daftar array, bentuk yang diharapkan adalah (B, H, W, C) atau (H, W, C).
  • control_mask (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], list[np.ndarray]) — Image, array numpy, atau tensor yang merepresentasikan batch gambar untuk memasker image. Piksel putih pada mask akan diwarnai ulang, sedangkan piksel hitam dipertahankan. Jika mask_image adalah gambar PIL, gambar tersebut dikonversi menjadi satu channel (luminance) sebelum digunakan. Jika berupa array numpy atau tensor pytorch, array tersebut harus berisi satu channel warna (L) alih-alih 3, sehingga bentuk yang diharapkan untuk tensor pytorch adalah (B, 1, H, W). Dan untuk array numpy, bentuknya dapat berupa (B, H, W, 1), (B, H, W), (H, W, 1), atau (H, W).
  • controlnet_conditioning_scale (float atau list[float], opsional, default 1.0) — Output dari ControlNet dikalikan dengan controlnet_conditioning_scale sebelum ditambahkan ke residual pada unet asli. Jika beberapa ControlNet ditentukan dalam init, Anda dapat menetapkan skala yang sesuai sebagai list.
  • controlnet_pooled_projections (torch.FloatTensor dengan bentuk (batch_size, projection_dim)) — Embeddings yang diproyeksikan dari embeddings kondisi input controlnet.
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • negative_prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan sebagai gantinya
  • negative_prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk memandu generasi gambar yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, negative_prompt digunakan sebagai gantinya
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.
  • latents (torch.FloatTensor, opsional) — Latents berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • prompt_embeds (torch.FloatTensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pemberatan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, mis. pembobotan prompt. Jika tidak disediakan, embedding teks pooled akan dibuat dari argumen input prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang sudah digenerate sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan digenerate dari argumen input negative_prompt.
  • ip_adapter_image (PipelineImageInput, opsional) — Input gambar opsional untuk bekerja dengan IP Adapters.
  • ip_adapter_image_embeds (torch.Tensor, opsional) — Embedding gambar yang telah dibuat sebelumnya untuk IP-Adapter. Harus berupa tensor dengan bentuk (batch_size, num_images, emb_dim). Harus berisi embedding gambar negatif jika do_classifier_free_guidance diatur ke True. Jika tidak disediakan, embedding dihitung dari argumen input ip_adapter_image.
  • output_type (str, opsional, defaultnya "pil") — Format output dari generate image. Pilih antara PIL: PIL.Image.Image atau np.array.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput alih-alih tuple biasa.
  • joint_attention_kwargs (dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.
  • clip_skip (int, opsional) — Jumlah lapisan yang akan dilewati dari CLIP saat menghitung embedding prompt. Nilai 1 berarti output dari lapisan pra-akhir akan digunakan untuk menghitung embedding prompt.
  • callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.
  • max_sequence_length (int defaultnya 256) — Panjang maksimum urutan yang digunakan dengan prompt.

Mengembalikan

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput atau tuple

~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput jika return_dict bernilai True, selain itu berupa tuple. Saat mengembalikan tuple, elemen pertama adalah daftar berisi gambar yang dihasilkan.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

>>> 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

Parameter

  • image (PipelineImageInput) — Gambar input yang akan dikodekan.
  • device — (torch.device): Perangkat Torch.

Mengembalikan

torch.Tensor

Representasi fitur gambar yang telah dikodekan.

Mengkodekan gambar yang diberikan menjadi representasi fitur menggunakan pengkode gambar yang telah dilatih sebelumnya.

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 )

Parameter

  • prompt (str atau list[str], opsional) — prompt yang akan dienkod
  • prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt digunakan di semua text-encoder
  • prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, prompt digunakan di semua text-encoder
  • device — (torch.device): perangkat torch
  • num_images_per_prompt (int) — jumlah gambar yang harus dihasilkan per prompt
  • do_classifier_free_guidance (bool) — apakah akan menggunakan classifier free guidance atau tidak
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • negative_prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar, yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di semua text-encoder.
  • negative_prompt_3 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar, yang akan dikirim ke tokenizer_3 dan text_encoder_3. Jika tidak didefinisikan, negative_prompt digunakan di semua text-encoder.
  • prompt_embeds (torch.FloatTensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pemberatan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, mis. pembobotan prompt. Jika tidak disediakan, embedding teks pooled akan dibuat dari argumen input prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang sudah digenerate sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan digenerate dari argumen input negative_prompt.
  • clip_skip (int, opsional) — Jumlah lapisan yang akan dilewati dari CLIP saat menghitung embedding prompt. Nilai 1 berarti output dari lapisan pra-akhir akan digunakan untuk menghitung embedding prompt.
  • lora_scale (float, opsional) — Skala LoRA yang akan diterapkan ke semua lapisan LoRA dari text encoder jika lapisan LoRA dimuat.

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 )

Parameter

  • ip_adapter_image (PipelineImageInput, opsional) — Gambar input untuk mengekstrak fitur untuk IP-Adapter.
  • ip_adapter_image_embeds (torch.Tensor, opsional) — Embedding gambar yang telah dihitung sebelumnya.
  • device — (torch.device, opsional): Perangkat Torch.
  • num_images_per_prompt (int, defaultnya 1) — Jumlah gambar yang harus dihasilkan per prompt.
  • do_classifier_free_guidance (bool, defaultnya True) — Apakah akan menggunakan classifier free guidance atau tidak.

Menyiapkan embedding gambar untuk digunakan dalam IP-Adapter.

ip_adapter_image atau ip_adapter_image_embeds harus diteruskan.

StableDiffusion3PipelineOutput

kelas diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

< >

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

Parameter

  • images (list[PIL.Image.Image] atau np.ndarray) — daftar gambar PIL yang telah didenoise dengan panjang batch_size atau array numpy dengan bentuk (batch_size, height, width, num_channels). Gambar PIL atau array numpy menyajikan gambar-gambar yang telah didenoise dari pipeline difusi.

Kelas output untuk pipeline Stable Diffusion.

Update on GitHub

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