# ControlNet مع Hunyuan-DiT

HunyuanDiTControlNetPipeline هو تطبيق لـ ControlNet مخصص لـ [Hunyuan-DiT](https://huggingface.co/papers/2405.08748).

تم تقديم ControlNet في [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) بواسطة 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](https://huggingface.co/Tencent-Hunyuan).

> [!TIP]
> تأكد من الاطلاع على [دليل المجدولين](../../using-diffusers/schedulers) لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

## HunyuanDiTControlNetPipeline[[diffusers.HunyuanDiTControlNetPipeline]]

#### diffusers.HunyuanDiTControlNetPipeline[[diffusers.HunyuanDiTControlNetPipeline]]

```python
diffusers.HunyuanDiTControlNetPipeline(vae: AutoencoderKL, text_encoder: BertModel, tokenizer: BertTokenizer, transformer: HunyuanDiT2DModel, scheduler: DDPMScheduler, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, controlnet: 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.HunyuanDiT2DMultiControlNetModel, text_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = None, tokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None, requires_safety_checker: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L165)

**المعاملات:**

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ar/api/models/autoencoderkl#diffusers.AutoencoderKL)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها. نستخدم `sdxl-vae-fp16-fix`.

text_encoder (`~transformers.BertModel`، `~transformers.CLIPTextModel` | None) : مُشفِّر نص ثابت ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). يستخدم HunyuanDiT [CLIP ثنائي اللغة] مُعدّلًا.

tokenizer (`~transformers.BertTokenizer`، `~transformers.CLIPTokenizer` | None) : `BertTokenizer` أو `CLIPTokenizer` لتجزئة النص.

transformer ([HunyuanDiT2DModel](/docs/diffusers/v0.43.0/ar/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : نموذج HunyuanDiT الذي صمّمه Tencent Hunyuan.

text_encoder_2 (`T5EncoderModel`) : مُضمّن mT5. تحديداً، هو 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : مُجزِّئ النصوص الخاص بمُضمِّن mT5.

scheduler ([DDPMScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/ddpm#diffusers.DDPMScheduler)) : مُجدوِل يُستخدم بالاقتران مع HunyuanDiT لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

controlnet ([HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel) أو `list[HunyuanDiT2DControlNetModel]` أو [HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel)) : يوفر شروطًا إضافية لـ `unet` أثناء عملية إزالة الضوضاء. إذا قمت بتعيين عدة ControlNets كقائمة، فإن المخرجات من كل ControlNet تُجمع معًا لإنشاء شرط إضافي واحد موحّد.

خط أنابيب لتوليد الصور من الإنجليزية/الصينية باستخدام HunyuanDiT.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/v0.43.0/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع خطوط الأنابيب (مثل التنزيل أو الحفظ، أو التشغيل على جهاز معين، وما إلى ذلك).

يستخدم HunyuanDiT مشفّري نصّين: [mT5](https://huggingface.co/google/mt5-base) و[bilingual CLIP](fine-tuned by ourselves)

#### __call__[[diffusers.HunyuanDiTControlNetPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int | None = 50, guidance_scale: float | None = 5.0, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, controlnet_conditioning_scale: float | list[float] = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float | None = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_2: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_2: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], guidance_rescale: float = 0.0, original_size: tuple[int, int] | None = (1024, 1024), target_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), use_resolution_binning: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L632)

**المعاملات:**

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](https://huggingface.co/papers/2010.02502). ينطبق فقط على [DDIMScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/ddim#diffusers.DDIMScheduler)، ويُتجاهل في جدولة أخرى.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كامنات من خلال الاستخراج باستخدام `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](/docs/diffusers/v0.43.0/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) بدلاً من tuple عادي.

callback_on_step_end (`Callable[[int, int], None]`، `PipelineCallback`، `MultiPipelineCallbacks`، *اختياري*) : دالة استجابة أو قائمة من دوال الاستجابة التي تُستدعى في نهاية كل خطوة إزالة ضوضاء.

callback_on_step_end_tensor_inputs (`list[str]`، *اختياري*) : قائمة من مدخلات المصفوفات (tensors) التي يجب تمريرها إلى دالة الاستدعاء (callback). إذا لم تُعرَّف، فسيتم تمرير جميع مدخلات المصفوفات.

guidance_rescale (`float`, *optional*, defaults to 0.0) : Rescale the noise_cfg according to `guidance_rescale`. Based on findings of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). 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](/docs/diffusers/v0.43.0/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)، وإلا يُعاد `tuple` حيث يكون العنصر الأول قائمة بالصور المولّدة والعنصر الثاني قائمة من قيم `bool` تشير إلى ما إذا كانت الصورة المولّدة المقابلة تحتوي على محتوى "غير آمن للعمل" (nsfw).

دالة الاستدعاء call لخط الأنابيب pipeline للتوليد باستخدام HunyuanDiT.

أمثلة:
```py
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[[diffusers.HunyuanDiTControlNetPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, device: device = None, dtype: dtype = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, text_encoder_index: int = 0)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L276)

**المعاملات:**

prompt (`str` أو `list[str]`، *اختياري*) : النص الذي سيتم ترميزه

device : (`torch.device`): جهاز torch

dtype (`torch.dtype`) : نوع torch

num_images_per_prompt (`int`) : عدد الصور التي يجب توليدها لكل موجه

do_classifier_free_guidance (`bool`) : ما إذا كان سيتم استخدام التوجيه الحر للتصنيف أم لا

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.

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.