# ControlNet

  

تم تقديم ControlNet في [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala.

باستخدام نموذج ControlNet، يمكنك تقديم صورة تحكم إضافية لتكييف عملية توليد Stable Diffusion والتحكم فيها. على سبيل المثال، إذا قدمت خريطة عمق، فإن نموذج ControlNet يولّد صورة تحافظ على المعلومات المكانية المستمدة من خريطة العمق. وهي طريقة أكثر مرونة ودقة للتحكم في عملية توليد الصور.

ملخص الورقة البحثية هو:

*نقدّم ControlNet، وهو معمارية شبكة عصبية لإضافة ضوابط شرطيّة مكانية إلى نماذج الانتشار النصّية-إلى-صورة الكبيرة المُدرَّبة مسبقًا. تقوم ControlNet بقفل نماذج الانتشار الكبيرة الجاهزة للإنتاج، وتعيد استخدام طبقات الترميز العميقة والقوية المُدرَّبة مسبقًا على مليارات الصور كهيكل أساسي قوي لتعلّم مجموعة متنوعة من الضوابط الشرطيّة. يتم ربط المعمارية العصبية بـ "التحويلات الصفرية" (طبقات تحويل مُهيّأة إلى الصفر) التي تُنمّي المعاملات تدريجيًا من الصفر وتضمن عدم تأثير أي ضوضاء ضارة على الضبط الدقيق. اختبرنا ضوابط شرطيّة متنوعة، مثل الحواف، والعمق، والتجزئة، ووضع الجسم البشري، وغيرها، باستخدام Stable Diffusion، باستخدام شرط واحد أو عدة شروط، مع وجود موجهات نصية أو بدونها. نُظهر أنّ تدريب نماذج ControlNet متين مع مجموعات البيانات الصغيرة (<50k) والكبيرة (>1m). تُظهر النتائج الواسعة أنّ ControlNet قد يسهّل تطبيقات أوسع للتحكم في نماذج انتشار الصور.*

تمت مساهمة خط المعالجة هذا من قِبل [ishan24](https://huggingface.co/ishan24). ❤️ يمكن العثور على قاعدة الكود الأصلية في [NVlabs/Sana](https://github.com/NVlabs/Sana)، كما يمكنك العثور على نقاط التفتيش الرسمية لـ ControlNet على ملف [Efficient-Large-Model's](https://huggingface.co/Efficient-Large-Model) الشخصي في Hub.

## SanaControlNetPipeline[[diffusers.SanaControlNetPipeline]]

#### diffusers.SanaControlNetPipeline[[diffusers.SanaControlNetPipeline]]

```python
diffusers.SanaControlNetPipeline(tokenizer: GemmaTokenizer, text_encoder: Gemma2PreTrainedModel, vae: AutoencoderDC, transformer: SanaTransformer2DModel, controlnet: SanaControlNetModel, scheduler: DPMSolverMultistepScheduler)
```

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

خط أنابيب لتوليد الصور من النص باستخدام [Sana](https://huggingface.co/papers/2410.10629).

#### __call__[[diffusers.SanaControlNetPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', num_inference_steps: int = 20, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 4.5, 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, num_images_per_prompt: int | None = 1, height: int = 1024, width: int = 1024, eta: float = 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_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, clean_caption: bool = False, use_resolution_binning: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 300, complex_human_instruction: list[str] = ["Given a user prompt, generate an 'Enhanced prompt' that provides detailed visual descriptions suitable for image generation. Evaluate the level of detail in the user prompt:", '- If the prompt is simple, focus on adding specifics about colors, shapes, sizes, textures, and spatial relationships to create vivid and concrete scenes.', '- If the prompt is already detailed, refine and enhance the existing details slightly without overcomplicating.', 'Here are examples of how to transform or refine prompts:', '- User Prompt: A cat sleeping -> Enhanced: A small, fluffy white cat curled up in a round shape, sleeping peacefully on a warm sunny windowsill, surrounded by pots of blooming red flowers.', '- User Prompt: A busy city street -> Enhanced: A bustling city street scene at dusk, featuring glowing street lamps, a diverse crowd of people in colorful clothing, and a double-decker bus passing by towering glass skyscrapers.', 'Please generate only the enhanced description for the prompt below and avoid including any additional commentary or evaluations:', 'User Prompt: '])
```

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

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

prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير `prompt_embeds` بدلاً من ذلك.

negative_prompt (`str` أو `list[str]`، *اختياري*) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير `negative_prompt_embeds` بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان `guidance_scale` أقل من `1`).

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 20) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال.

timesteps (`list[int]`، *اختياري*) : خطوات زمنية مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل `timesteps` في طريقة `set_timesteps` الخاصة بهم. إذا لم يُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير `num_inference_steps`. يجب أن تكون بترتيب تنازلي.

sigmas (`list[float]`، *اختياري*) : قيم `sigmas` مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل `sigmas` في طريقة `set_timesteps` الخاصة بهم. إذا لم تُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير `num_inference_steps`.

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 4.5) : مقياس التوجيه كما هو مُعرَّف في [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). يُعرَّف `guidance_scale` على أنه `w` من المعادلة 2. في [Imagen Paper](https://huggingface.co/papers/2205.11487). يتم تفعيل مقياس التوجيه عن طريق تعيين `guidance_scale > 1`. يشجع مقياس التوجيه الأعلى على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt`، وعادةً على حساب انخفاض جودة الصورة.

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`، يمكنك تعيين المقياس المقابل كقائمة.

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

height (`int`، *اختياري*، الافتراضي هو self.unet.config.sample_size) : ارتفاع الصورة المولّدة بالبكسل.

width (`int`، *اختياري*، الافتراضي هو self.unet.config.sample_size) : عرض الصورة المولدة بالبكسل.

eta (`float`، *اختياري*، القيمة الافتراضية 0.0) : يتوافق مع المعامل eta (η) في ورقة DDIM: https://huggingface.co/papers/2010.02502. ينطبق فقط على [schedulers.DDIMScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/ddim#diffusers.DDIMScheduler)، وسيتم تجاهله في الحالات الأخرى.

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

latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، سيتم توليد كامنات من خلال الاستخراج باستخدام `generator` العشوائي المُقدَّم.

prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال `prompt`.

prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع انتباه مُولّد مسبقًا لتضمينات النص.

negative_prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى PixArt-Sigma، يجب أن يكون هذا الموجه السلبي "". إذا لم يُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال `negative_prompt`.

negative_prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع انتباه مُولّد مسبقًا لتضمينات النصوص السلبية.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة الناتجة عن عملية التوليد. اختر بين [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` أو `np.array`.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~pipelines.stable_diffusion.IFPipelineOutput` بدلاً من tuple عادي.

attention_kwargs : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

clean_caption (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تنظيف الوصف قبل إنشاء التضمينات. يتطلب تثبيت `beautifulsoup4` و`ftfy`. إذا لم يتم تثبيت الاعتماديات، فسيتم إنشاء التضمينات من النص الخام.

use_resolution_binning (`bool` الافتراضي هو `True`) : إذا تم ضبطه على `True`، فإن الارتفاع والعرض المطلوبين يُخضعان أولاً للتحويل إلى أقرب دقة باستخدام `ASPECT_RATIO_1024_BIN`. بعد فك ترميز الكمّيات الناتجة إلى صور، يتم تغيير حجمها مرة أخرى إلى الدقة المطلوبة. مفيد لتوليد صور غير مربعة.

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`، *اختياري*) : قائمة مدخلات المصفوفات (tensors) لدالة `callback_on_step_end`. سيتم تمرير المصفوفات المحددة في القائمة كحجة `callback_kwargs`. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية `._callback_tensor_inputs` لفئة خط الأنابيب (pipeline) الخاص بك.

max_sequence_length (`int` الافتراضي هو `300`) : أقصى طول تسلسل يُستخدم مع `prompt`.

complex_human_instruction (`list[str]`، *اختياري*) : تعليمات للانتباه البشري المعقد: https://github.com/NVlabs/Sana/blob/main/configs/sana_app_config/Sana_1600M_app.yaml#L55.

**يعيد:** [SanaPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/sana_sprint#diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [SanaPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/sana_sprint#diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput)، وإلا يُعاد `tuple` يكون عنصره الأول قائمة بالصور المولّدة

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:
```py
>>> import torch
>>> from diffusers import SanaControlNetPipeline
>>> from diffusers.utils import load_image

>>> pipe = SanaControlNetPipeline.from_pretrained(
...     "ishan24/Sana_600M_1024px_ControlNetPlus_diffusers",
...     variant="fp16",
...     torch_dtype={"default": torch.bfloat16, "controlnet": torch.float16, "transformer": torch.float16},
...     device_map="balanced",
... )
>>> cond_image = load_image(
...     "https://huggingface.co/ishan24/Sana_600M_1024px_ControlNet_diffusers/resolve/main/hed_example.png"
... )
>>> prompt = 'a cat with a neon sign that says "Sana"'
>>> image = pipe(
...     prompt,
...     control_image=cond_image,
... ).images[0]
>>> image.save("output.png")
```

#### encode_prompt[[diffusers.SanaControlNetPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, device: typing.Optional[torch.device] = 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, clean_caption: bool = False, max_sequence_length: int = 300, complex_human_instruction: list[str] | None = None, lora_scale: float | None = None)
```

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

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

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

negative_prompt (`str` أو `list[str]`، *اختياري*) : الأمر النصي الذي لا يوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير `negative_prompt_embeds` بدلاً منه. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان `guidance_scale` أقل من `1`). بالنسبة إلى PixArt-Alpha، يجب أن يكون "".

do_classifier_free_guidance (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام classifier free guidance أم لا

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي يجب توليدها لكل موجه

device : (`torch.device`, *اختياري*): جهاز torch لوضع التضمينات الناتجة عليه

prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال `prompt`.

negative_prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. بالنسبة إلى Sana، يجب أن تكون تمثيلات نص "" (فارغ).

clean_caption (`bool`، القيمة الافتراضية `False`) : إذا كانت `True`، سيقوم الدالة بمعالجة الوصف المقدم وتنظيفه قبل الترميز.

max_sequence_length (`int`، القيمة الافتراضية 300) : أقصى طول تسلسل يُستخدم للموجّه.

complex_human_instruction (`list[str]`، الافتراضي `complex_human_instruction`) : إذا لم يكن `complex_human_instruction` فارغًا، فستستخدم الدالة تعليمات Human المعقدة للتلميح.

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

## SanaPipelineOutput[[diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput]]

#### diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput[[diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput]]

```python
diffusers.pipelines.sana.pipeline_output.SanaPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

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

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

images (`list[PIL.Image.Image]` أو `np.ndarray`) : قائمة من صور PIL منزوعة الضوضاء بطول `batch_size` أو مصفوفة numpy بأبعاد `(batch_size, height, width, num_channels)`. تمثل صور PIL أو مصفوفة numpy صورًا منزوعة الضوضاء من خط أنابيب الانتشار.

فئة الإخراج لخطوط أنابيب Sana.