Diffusers documentation
ControlNet مع Hunyuan-DiT
ControlNet مع Hunyuan-DiT
HunyuanDiTControlNetPipeline هو تطبيق لـ ControlNet مخصص لـ Hunyuan-DiT.
تم تقديم ControlNet في Adding Conditional Control to Text-to-Image Diffusion Models بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala.
باستخدام نموذج ControlNet، يمكنك تقديم صورة تحكم إضافية لتكييف وتوجيه عملية توليد Hunyuan-DiT. على سبيل المثال، إذا قدمت خريطة عمق، فإن نموذج ControlNet يولّد صورة تحافظ على المعلومات المكانية المستمدة من خريطة العمق. وهي طريقة أكثر مرونة ودقة للتحكم في عملية توليد الصور.
ملخص الورقة البحثية هو:
نقدّم ControlNet، وهو معمارية شبكة عصبية لإضافة ضوابط شرطيّة مكانية إلى نماذج الانتشار النصّية-إلى-صورة الكبيرة المُدرَّبة مسبقًا. تقوم ControlNet بقفل نماذج الانتشار الكبيرة الجاهزة للإنتاج، وتعيد استخدام طبقات الترميز العميقة والقوية المُدرَّبة مسبقًا على مليارات الصور كهيكل أساسي قوي لتعلّم مجموعة متنوعة من الضوابط الشرطيّة. يتم ربط المعمارية العصبية بـ«التحويلات الصفرية» (طبقات تحويل مُهيّأة إلى الصفر) التي تُنمّي المعاملات تدريجيًا من الصفر وتضمن عدم تأثير أي ضوضاء ضارة على الضبط الدقيق. اختبرنا ضوابط شرطيّة متنوعة، مثل الحواف، والعمق، والتجزئة، ووضع الجسم البشري، وغيرها، باستخدام Stable Diffusion، باستخدام شرط واحد أو عدة شروط، مع وجود موجهات نصية أو بدونها. نُظهر أنّ تدريب نماذج ControlNet متين مع مجموعات البيانات الصغيرة (<50k) والكبيرة (>1m). تُظهر النتائج الواسعة أنّ ControlNet قد يسهّل تطبيقات أوسع للتحكم في نماذج انتشار الصور.
تم تنفيذ هذا الكود بواسطة فريق Tencent Hunyuan. يمكنك العثور على نقاط الفحص المسبقة التدريب لنماذج Hunyuan-DiT ControlNets على Tencent Hunyuan.
تأكد من الاطلاع على دليل المجدولين لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم إعادة استخدام المكونات عبر خطوط الأنابيب لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.
HunyuanDiTControlNetPipeline
فئة 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 )
المعاملات
- vae (AutoencoderKL) —
نموذج الترميز التبايني التلقائي (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها. نستخدم
sdxl-vae-fp16-fix. - text_encoder (
~transformers.BertModel,~transformers.CLIPTextModel| None) — مُشفِّر نص ثابت (clip-vit-large-patch14). يستخدم HunyuanDiT نسخة مُعدَّلة من [CLIP ثنائي اللغة]. - tokenizer (
~transformers.BertTokenizer,~transformers.CLIPTokenizer| None) —BertTokenizerأوCLIPTokenizerلتجزئة النص. - transformer (HunyuanDiT2DModel) — نموذج HunyuanDiT الذي صمّمته Tencent Hunyuan.
- text_encoder_2 (
T5EncoderModel) — مُضمِّن mT5. تحديداً، هو ‘t5-v1_1-xxl’. - tokenizer_2 (
T5Tokenizer) — مُقسِّم النصوص الخاص بمُضمِّن mT5. - scheduler (DDPMScheduler) — جدول زمني يُستخدم بالاقتران مع HunyuanDiT لإزالة الضوضاء من كامنات الصورة المُرمّزة.
- controlnet (HunyuanDiT2DControlNetModel أو
list[HunyuanDiT2DControlNetModel]أو HunyuanDiT2DControlNetModel) — توفر شروطًا إضافية لـunetأثناء عملية إزالة الضوضاء. إذا قمت بتعيين عدة ControlNets كقائمة، فإن المخرجات من كل ControlNet تُجمع معًا لإنشاء شرط إضافي واحد موحّد.
خط أنابيب لتوليد الصور من الإنجليزية/الصينية باستخدام HunyuanDiT.
يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع خطوط الأنابيب (مثل التنزيل أو الحفظ، أو التشغيل على جهاز معين، وما إلى ذلك).
يستخدم HunyuanDiT مشفّري نصّين: mT5 و[bilingual CLIP](تمّت معايرته من قِبلنا)
__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 = ['latents']guidance_rescale: float = 0.0original_size: tuple[int, int] | None = (1024, 1024)target_size: tuple[int, int] | None = Nonecrops_coords_top_left: tuple = (0, 0)use_resolution_binning: bool = True ) → StableDiffusionPipelineOutput or tuple
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب عليك تمريرprompt_embeds. - height (
int) — ارتفاع الصورة المولّدة بالبكسل. - width (
int) — عرض الصورة المولّدة بالبكسل. - num_inference_steps (
int، اختياري، القيمة الافتراضية 50) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال. يتم تعديل هذا المعامل بواسطةstrength. - guidance_scale (
float, اختياري، القيمة الافتراضية 7.5) — تشجع قيمة أعلى لمقياس التوجيه النموذج على توليد صور مرتبطة ارتباطًا وثيقًا بنصpromptعلى حساب انخفاض جودة الصورة. يتم تفعيل مقياس التوجيه عندما يكونguidance_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]]أوlist[list[PIL.Image.Image]]): شرط الإدخال الخاص بـ ControlNet لتوفير التوجيه إلىunetأثناء التوليد. إذا تم تحديد النوع على أنهtorch.Tensor، فإنه يُمرَّر إلى ControlNet كما هو. يمكن أيضًا قبولPIL.Image.Imageكصورة. الأبعاد الافتراضية للصورة الناتجة هي أبعادimage. إذا تم تمرير الارتفاع و/أو العرض، يتم تغيير حجمimageوفقًا لذلك. إذا تم تحديد عدة وحدات ControlNet فيinit، يجب تمرير الصور كقائمة بحيث يمكن تجميع كل عنصر من عناصر القائمة بشكل صحيح للإدخال إلى وحدة ControlNet واحدة. - controlnet_conditioning_scale (
floatأوlist[float]، اختياري، القيمة الافتراضية 1.0) — تُضرب مخرجات ControlNet فيcontrolnet_conditioning_scaleقبل إضافتها إلى الباقي فيunetالأصلية. إذا تم تحديد عدة ControlNets فيinit، يمكنك ضبط المقياس المقابل كقائمة. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي توجّه ما يجب عدم تضمينه في توليد الصورة. إذا لم يُعرَّف، يجب عليك تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (guidance_scale < 1). - num_images_per_prompt (
int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - eta (
float، اختياري، القيمة الافتراضية 0.0) — يتوافق مع المعامل eta (η) من ورقة DDIM. ينطبق فقط على DDIMScheduler، ويُتجاهل في المجدولين الآخرين. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) —torch.Generatorلجعل التوليد حتميًا. - latents (
torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كائن latents عن طريق الاستخراج باستخدامgeneratorالعشوائي المُقدَّم. - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة (مثل وزن الموجهات). إذا لم تُقدَّم، يتم توليد التضمينات النصية من معامل الإدخالprompt. - prompt_embeds_2 (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة (وزن الموجه). إذا لم تُقدَّم، يتم توليد التضمينات النصية من معامل الإدخالprompt. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة (وزن الموجه). إذا لم تُقدَّم، يتم توليدnegative_prompt_embedsمن معامل الإدخالnegative_prompt. - negative_prompt_embeds_2 (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة (وزن الموجه). إذا لم تُقدَّم، يتم توليدnegative_prompt_embedsمن معامل الإدخالnegative_prompt. - prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه للموجّه. مطلوب عند تمريرprompt_embedsمباشرةً. - prompt_attention_mask_2 (
torch.Tensor، اختياري) — قناع الانتباه للموجّه. مطلوب عند تمريرprompt_embeds_2مباشرةً. - negative_prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه (Attention mask) الخاص بالموجّه السلبي. مطلوب عند تمريرnegative_prompt_embedsمباشرةً. - negative_prompt_attention_mask_2 (
torch.Tensor، اختياري) — قناع الانتباه (Attention mask) للموجّه السلبي. مطلوب عند تمريرnegative_prompt_embeds_2مباشرةً. - output_type (
str، اختياري، الافتراضي"pil") — صيغة مخرجات الصورة المولّدة. اختر بينPIL.Imageأوnp.array. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع StableDiffusionPipelineOutput بدلاً من tuple عادي. - callback_on_step_end (
Callable[[int, int], None]،PipelineCallback،MultiPipelineCallbacks، اختياري) — دالة استجابة أو قائمة من دوال الاستجابة التي تُستدعى في نهاية كل خطوة إزالة ضوضاء. - callback_on_step_end_tensor_inputs (
list[str]، اختياري) — قائمة من مدخلات المصفوفات التي يجب تمريرها إلى دالة الاستدعاء. إذا لم تُعرَّف، فسيتم تمرير جميع مدخلات المصفوفات. - guidance_rescale (
float, optional, defaults to 0.0) — Rescale the noise_cfg according toguidance_rescale. Based on findings of Common Diffusion Noise Schedules and Sample Steps are Flawed. See Section 3.4 - original_size (
tuple[int, int]، اختياري، القيمة الافتراضية(1024, 1024)) — الحجم الأصلي للصورة. يُستخدم لحساب معرّفات الوقت. - target_size (
tuple[int, int], اختياري) — الحجم المستهدف للصورة. يُستخدم لحساب معرّفات الوقت. - crops_coords_top_left (
tuple[int, int]، اختياري، القيمة الافتراضية(0, 0)) — إحداثيات الزاوية العلوية اليسرى للمقتطف. تُستخدم لحساب معرّفات الوقت. - use_resolution_binning (
bool, اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم استخدام تجميع الدقة أم لا. إذا كانت القيمةTrue، فسيتم تعيين دقة الإدخال إلى أقرب دقة قياسية. الدقات المدعومة هي 1024x1024، 1280x1280، 1024x768، 1152x864، 1280x960، 768x1024، 864x1152، 960x1280، 1280x768، و 768x1280. يُوصى بإعداد هذه القيمة إلىTrue.
يعيد
StableDiffusionPipelineOutput أو tuple
إذا كان return_dict هو True، يُعاد StableDiffusionPipelineOutput،
وإلا يُعاد tuple حيث يكون العنصر الأول قائمة بالصور المولّدة والعنصر الثاني قائمة من قيم bool تشير إلى ما إذا كانت الصورة المولّدة المقابلة تحتوي على محتوى
“غير آمن للعمل” (nsfw).
دالة الاستدعاء call لخط الأنابيب pipeline للتوليد باستخدام HunyuanDiT.
أمثلة:
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 )
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه الذي سيتم ترميزه - device — (
torch.device): جهاز torch - dtype (
torch.dtype) — نوع بيانات torch - num_images_per_prompt (
int) — عدد الصور التي يجب توليدها لكل موجه - do_classifier_free_guidance (
bool) — ما إذا كان سيتم استخدام classifier free guidance أم لا - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي استخدامها لتوجيه توليد الصورة. إذا لم يُعرَّف، يجب تمريرnegative_prompt_embedsبدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كانguidance_scaleأقل من1). - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سلبية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخالnegative_prompt. - prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه للموجّه. مطلوب عند تمريرprompt_embedsمباشرةً. - negative_prompt_attention_mask (
torch.Tensor، اختياري) — قناع الانتباه (Attention mask) الخاص بالموجّه السلبي. مطلوب عند تمريرnegative_prompt_embedsمباشرةً. - max_sequence_length (
int، اختياري) — أقصى طول تسلسل يُستخدم للموجّه. - text_encoder_index (
int, اختياري) — مؤشر مُشفِّر النص المراد استخدامه.0لـ clip و1لـ T5.
يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.