Diffusers documentation
ControlNet dengan Hunyuan-DiT
ControlNet dengan Hunyuan-DiT
HunyuanDiTControlNetPipeline adalah implementasi ControlNet untuk Hunyuan-DiT.
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 Hunyuan-DiT. 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 ini diimplementasikan oleh Tencent Hunyuan Team. Anda dapat menemukan checkpoint pre-trained untuk Hunyuan-DiT ControlNets di Tencent Hunyuan.
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.
HunyuanDiTControlNetPipeline
kelas diffusers.HunyuanDiTControlNetPipeline
< source >( vae: AutoencoderKLtext_encoder: BertModeltokenizer: BertTokenizertransformer: HunyuanDiT2DModelscheduler: DDPMSchedulersafety_checker: StableDiffusionSafetyCheckerfeature_extractor: CLIPImageProcessorPilcontrolnet: diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel | list[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel] | tuple[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel] | diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DMultiControlNetModeltext_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = Nonetokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = Nonerequires_safety_checker: bool = True )
Parameter
- vae (AutoencoderKL) —
Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten. Kami menggunakan
sdxl-vae-fp16-fix. - text_encoder (
~transformers.BertModel,~transformers.CLIPTextModel| None) — Text-encoder yang dibekukan (clip-vit-large-patch14). HunyuanDiT menggunakan [bilingual CLIP] yang telah dihaluskan. - tokenizer (
~transformers.BertTokenizer,~transformers.CLIPTokenizer| None) —BertTokenizeratauCLIPTokenizeruntuk melakukan tokenisasi teks. - transformer (HunyuanDiT2DModel) — Model HunyuanDiT yang dirancang oleh Tencent Hunyuan.
- text_encoder_2 (
T5EncoderModel) — Embedder mT5. Secara spesifik, ini adalah ‘t5-v1_1-xxl’. - tokenizer_2 (
T5Tokenizer) — Tokenizer untuk embedder mT5. - scheduler (DDPMScheduler) — Scheduler yang digunakan bersama HunyuanDiT untuk menghilangkan noise pada latens gambar yang telah dikodekan.
- controlnet (HunyuanDiT2DControlNetModel atau
list[HunyuanDiT2DControlNetModel]atau HunyuanDiT2DControlNetModel) — Menyediakan kondisioning tambahan untukunetselama proses denoising. Jika Anda mengatur beberapa ControlNet sebagai list, output dari masing-masing ControlNet akan dijumlahkan untuk membuat satu kondisioning tambahan yang digabungkan.
Pipeline untuk generasi gambar dari bahasa Inggris/Tionghoa menggunakan HunyuanDiT.
Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua pipeline (seperti mengunduh atau menyimpan, menjalankan pada perangkat tertentu, dll.)
HunyuanDiT menggunakan dua pengkode teks: mT5 dan [CLIP dwibahasa](fine-tuned by ourselves)
__call__
< source >( prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int | None = 50guidance_scale: float | None = 5.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.0negative_prompt: str | list[str] | None = Nonenum_images_per_prompt: int | None = 1eta: float | None = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Noneprompt_attention_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']guidance_rescale: float = 0.0original_size: tuple[int, int] | None = (1024, 1024)target_size: tuple[int, int] | None = Nonecrops_coords_top_left: tuple[int, int] = (0, 0)use_resolution_binning: bool = True ) → StableDiffusionPipelineOutput or tuple
Parameter
- prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt untuk memandu generasi gambar. Jika tidak didefinisikan, Anda perlu meneruskanprompt_embeds. - height (
int) — Tinggi gambar yang dihasilkan dalam piksel. - width (
int) — Lebar gambar yang dihasilkan dalam piksel. - 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. Parameter ini dimodulasi olehstrength. - guidance_scale (
float, opsional, default 7.5) — Nilai guidance scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang sangat terkait denganpromptteks, dengan mengorbankan kualitas gambar yang lebih rendah. Guidance scale diaktifkan ketikaguidance_scale > 1. - 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]]ataulist[list[PIL.Image.Image]]): Kondisi input ControlNet untuk memberikan panduan kepadaunetdalam proses generasi. Jika tipe dispesifikasikan sebagaitorch.Tensor, nilai tersebut diteruskan ke ControlNet apa adanya.PIL.Image.Imagejuga dapat diterima sebagai gambar. Dimensi gambar output secara default mengikuti dimensiimage. Jika tinggi dan/atau lebar diteruskan,imageakan di-resize sesuai dengan nilai tersebut. Jika beberapa ControlNet dispesifikasikan dalaminit, gambar harus diteruskan sebagai list sehingga setiap elemen list dapat di-batch dengan benar untuk input ke satu ControlNet. - controlnet_conditioning_scale (
floatataulist[float], opsional, default 1.0) — Output dari ControlNet dikalikan dengancontrolnet_conditioning_scalesebelum ditambahkan ke residual padaunetasli. Jika beberapa ControlNet ditentukan dalaminit, Anda dapat menetapkan skala yang sesuai sebagai list. - negative_prompt (
strataulist[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan apa yang tidak boleh disertakan dalam generasi gambar. Jika tidak didefinisikan, Anda perlu mengirimkannegative_prompt_embedssebagai gantinya. Diabaikan saat tidak menggunakan panduan (guidance_scale < 1). - num_images_per_prompt (
int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt. - eta (
float, opsional, default 0.0) — Bersesuaian dengan parameter eta (η) dari paper DDIM. Hanya berlaku untuk DDIMScheduler, dan diabaikan pada scheduler lainnya. - generator (
torch.Generatorataulist[torch.Generator], opsional) —torch.Generatoruntuk membuat generasi menjadi deterministik. - latents (
torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya dan 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 menggunakangeneratoracak yang diberikan. - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - prompt_embeds_2 (
torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - negative_prompt_embeds (
torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan,negative_prompt_embedsakan dibuat dari argumen inputnegative_prompt. - negative_prompt_embeds_2 (
torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan,negative_prompt_embedsakan dibuat dari argumen inputnegative_prompt. - prompt_attention_mask (
torch.Tensor, opsional) — Attention mask untuk prompt. Wajib diisi ketikaprompt_embedsdilewatkan secara langsung. - prompt_attention_mask_2 (
torch.Tensor, opsional) — Attention mask untuk prompt. Wajib diisi ketikaprompt_embeds_2dilewatkan secara langsung. - negative_prompt_attention_mask (
torch.Tensor, opsional) — Attention mask untuk negative prompt. Wajib diisi ketikanegative_prompt_embedsdilewatkan secara langsung. - negative_prompt_attention_mask_2 (
torch.Tensor, opsional) — Attention mask untuk negative prompt. Wajib diisi ketikanegative_prompt_embeds_2dilewatkan secara langsung. - output_type (
str, opsional, default"pil") — Format output dari gambar yang dihasilkan. Pilih antaraPIL.Imageataunp.array. - return_dict (
bool, opsional, defaultTrue) — Apakah akan mengembalikan StableDiffusionPipelineOutput alih-alih tuple biasa. - callback_on_step_end (
Callable[[int, int], None],PipelineCallback,MultiPipelineCallbacks, opsional) — Fungsi callback atau daftar fungsi callback yang akan dipanggil di akhir setiap langkah denoising. - callback_on_step_end_tensor_inputs (
list[str], opsional) — Daftar input tensor yang harus diteruskan ke fungsi callback. Jika tidak didefinisikan, semua input tensor akan diteruskan. - guidance_rescale (
float, opsional, default 0.0) — Skala ulang noise_cfg sesuai denganguidance_rescale. Berdasarkan temuan dari Common Diffusion Noise Schedules and Sample Steps are Flawed. Lihat Bagian 3.4 - original_size (
tuple[int, int], opsional, default(1024, 1024)) — Ukuran asli gambar. Digunakan untuk menghitung time ids. - target_size (
tuple[int, int], opsional) — Ukuran target dari gambar. Digunakan untuk menghitung time ids. - crops_coords_top_left (
tuple[int, int], opsional, default(0, 0)) — Koordinat kiri atas dari crop. Digunakan untuk menghitung time ids. - use_resolution_binning (
bool, opsional, defaultTrue) — Apakah akan menggunakan resolusi binning atau tidak. JikaTrue, resolusi input akan dipetakan ke resolusi standar terdekat. Resolusi yang didukung adalah 1024x1024, 1280x1280, 1024x768, 1152x864, 1280x960, 768x1024, 864x1152, 960x1280, 1280x768, dan 768x1280. Disarankan untuk mengatur ini keTrue.
Mengembalikan
StableDiffusionPipelineOutput atau tuple
Jika return_dict adalah True, StableDiffusionPipelineOutput dikembalikan,
sebaliknya sebuah tuple dikembalikan di mana elemen pertama adalah daftar berisi gambar yang dihasilkan dan elemen
kedua adalah daftar bool yang menunjukkan apakah gambar yang dihasilkan yang sesuai mengandung
konten “not-safe-for-work” (nsfw).
Fungsi panggilan untuk pipeline generasi dengan HunyuanDiT.
Contoh:
from diffusers import HunyuanDiT2DControlNetModel, HunyuanDiTControlNetPipeline
import torch
controlnet = HunyuanDiT2DControlNetModel.from_pretrained(
"Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny", torch_dtype=torch.float16
)
pipe = HunyuanDiTControlNetPipeline.from_pretrained(
"Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers", controlnet=controlnet, torch_dtype=torch.float16
)
pipe.to("cuda")
from diffusers.utils import load_image
cond_image = load_image(
"https://huggingface.co/Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny/resolve/main/canny.jpg?download=true"
)
## You may also use English prompt as HunyuanDiT supports both English and Chinese
prompt = "在夜晚的酒店门前，一座古老的中国风格的狮子雕像矗立着，它的眼睛闪烁着光芒，仿佛在守护着这座建筑。背景是夜晚的酒店前，构图方式是特写，平视，居中构图。这张照片呈现了真实摄影风格，蕴含了中国雕塑文化，同时展现了神秘氛围"
# prompt="At night, an ancient Chinese-style lion statue stands in front of the hotel, its eyes gleaming as if guarding the building. The background is the hotel entrance at night, with a close-up, eye-level, and centered composition. This photo presents a realistic photographic style, embodies Chinese sculpture culture, and reveals a mysterious atmosphere."
image = pipe(
prompt,
height=1024,
width=1024,
control_image=cond_image,
num_inference_steps=50,
).images[0]encode_prompt
< source >( prompt: strdevice: device = Nonedtype: dtype = Nonenum_images_per_prompt: int = 1do_classifier_free_guidance: bool = Truenegative_prompt: str | None = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int | None = Nonetext_encoder_index: int = 0 )
Parameter
- prompt (
strataulist[str], opsional) — prompt yang akan dienkod - device — (
torch.device): perangkat torch - dtype (
torch.dtype) — dtype 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 (
strataulist[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskannegative_prompt_embedssebagai gantinya. Diabaikan jika tidak menggunakan guidance (yaitu, diabaikan jikaguidance_scalekurang dari1). - prompt_embeds (
torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen inputprompt. - negative_prompt_embeds (
torch.Tensor, 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 inputnegative_prompt. - prompt_attention_mask (
torch.Tensor, opsional) — Attention mask untuk prompt. Wajib diisi ketikaprompt_embedsdilewatkan secara langsung. - negative_prompt_attention_mask (
torch.Tensor, opsional) — Attention mask untuk negative prompt. Wajib diisi ketikanegative_prompt_embedsdilewatkan secara langsung. - max_sequence_length (
int, opsional) — panjang maksimum urutan yang digunakan untuk prompt. - text_encoder_index (
int, opsional) — Indeks text encoder yang akan digunakan.0untuk clip dan1untuk T5.
Mengkodekan prompt menjadi hidden states dari text encoder.