# ControlNetModel

تم تقديم نموذج ControlNet في [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala. يوفر هذا النموذج درجة أكبر من التحكم في توليد الصور من النص من خلال اشتراط النموذج على مدخلات إضافية مثل خرائط الحواف، وخرائط العمق، وخرائط التقسيم، ونقاط المفاتيح لكشف الوضعية.

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

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

## التحميل من التنسيق الأصلي

بشكل افتراضي، يجب تحميل [ControlNetModel](/docs/diffusers/main/ar/api/models/controlnet#diffusers.ControlNetModel) باستخدام [from_pretrained()](/docs/diffusers/main/ar/api/models/overview#diffusers.ModelMixin.from_pretrained)، لكن يمكن أيضًا تحميله من التنسيق الأصلي باستخدام `FromOriginalModelMixin.from_single_file` على النحو التالي:

```py
from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth"  # can also be a local path
controlnet = ControlNetModel.from_single_file(url)

url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors"  # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)
```

## التحميل من Control LoRA

تم تقديم Control-LoRA من قبل Stability AI في [stabilityai/control-lora](https://huggingface.co/stabilityai/control-lora) من خلال إضافة الضبط الدقيق الفعال المعتمد على المعلمات منخفضة الرتبة إلى ControlNet. توفر هذه الطريقة نهجًا أكثر كفاءة ومضغوطًا لجلب التحكم في النموذج إلى مجموعة أوسع من وحدات معالجة الرسومات الموجهة للمستهلكين.

```py
from diffusers import ControlNetModel, UNet2DConditionModel

lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)
```

## ControlNetModel[[diffusers.ControlNetModel]]

#### diffusers.ControlNetModel[[diffusers.ControlNetModel]]

```python
diffusers.ControlNetModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 1280, transformer_layers_per_block: int | tuple[int, ...] = 1, encoder_hid_dim: int | None = None, encoder_hid_dim_type: str | None = None, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, class_embed_type: str | None = None, addition_embed_type: str | None = None, addition_time_embed_dim: int | None = None, num_class_embeds: int | None = None, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', projection_class_embeddings_input_dim: int | None = None, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L111)

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

in_channels (`int`، القيمة الافتراضية 4) : عدد القنوات في العينة المدخلة.

flip_sin_to_cos (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب عكس sin إلى cos في تضمين الوقت.

freq_shift (`int`، القيمة الافتراضية 0) : إزاحة التردد التي تُطبَّق على تضمين الوقت.

down_block_types (`tuple[str]`، القيمة الافتراضية هي `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : مجموعة أنابيب تقليل الحجم (downsample blocks) المستخدمة.

only_cross_attention (`bool | tuple[bool]`، القيمة الافتراضية `False`) --

block_out_channels (`tuple[int]`، القيمة الافتراضية هي `(320, 640, 1280, 1280)`) : مجموعة من القيم تمثل عدد قنوات الإخراج لكل كتلة.

layers_per_block (`int`، القيمة الافتراضية 2) : عدد الطبقات في كل كتلة.

downsample_padding (`int`، القيمة الافتراضية 1) : الحشو المستخدم لتحويل الاستخلاص (downsampling convolution).

mid_block_scale_factor (`float`، القيمة الافتراضية 1) : معامل المقياس المستخدم للكتلة الوسطى.

act_fn (`str`، القيمة الافتراضية هي "silu") : دالة التنشيط المستخدمة.

norm_num_groups (`int`، *اختياري*، القيمة الافتراضية 32) : عدد المجموعات المستخدمة للتطبيع. إذا كانت القيمة None، يتم تجاوز طبقات التطبيع والتفعيل في المعالجة اللاحقة.

norm_eps (`float`، القيمة الافتراضية 1e-5) : قيمة الإيبسلون المستخدمة في عملية التطبيع.

cross_attention_dim (`int`، القيمة الافتراضية 1280) : بُعد ميزات الانتباه المتقاطع.

transformer_layers_per_block (`int` أو `tuple[int]`، *اختياري*، القيمة الافتراضية 1) : عدد كتل التحويل من النوع `BasicTransformerBlock`. لا ينطبق إلا على `~models.unet_2d_blocks.CrossAttnDownBlock2D`، `~models.unet_2d_blocks.CrossAttnUpBlock2D`، `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

encoder_hid_dim (`int`، *اختياري*، القيمة الافتراضية هي None) : إذا تم تعريف `encoder_hid_dim_type`، فسيتم إسقاط `encoder_hidden_states` من بُعد `encoder_hid_dim` إلى `cross_attention_dim`.

encoder_hid_dim_type (`str`، *اختياري*، القيمة الافتراضية `None`) : إذا تم تقديمه، يتم إسقاط `encoder_hidden_states` والتضمينات الأخرى المحتملة إلى تضمينات نصية بأبعاد `cross_attention` وفقاً لـ `encoder_hid_dim_type`.

attention_head_dim (`int | tuple[int]`، الافتراضي 8) : بُعد رؤوس الانتباه.

use_linear_projection (`bool`، القيمة الافتراضية `False`) --

class_embed_type (`str`، *اختياري*، القيمة الافتراضية `None`) : نوع تضمين الفئة (class embedding) الذي سيتم استخدامه، والذي يُجمع في النهاية مع تضمينات الوقت. اختر من بين None، `"timestep"`، `"identity"`، `"projection"`، أو `"simple_projection"`.

addition_embed_type (`str`، *اختياري*، القيمة الافتراضية `None`) : يحدد تضمينًا اختياريًا سيُجمع مع تضمينات الوقت. اختر من بين `None` أو "text". سيستخدم "text" طبقة `TextTimeEmbedding`.

num_class_embeds (`int`، *اختياري*، القيمة الافتراضية 0) : بُعد المدخلات لمصفوفة التضمين القابلة للتعلم التي سيتم إسقاطها إلى `time_embed_dim`، عند تنفيذ التكييف حسب الفئة مع أن `class_embed_type` يساوي `None`.

upcast_attention (`bool`، القيمة الافتراضية `False`) --

resnet_time_scale_shift (`str`، القيمة الافتراضية `"default"`) : إعدادات إزاحة مقياس الوقت لكتل ResNet (انظر `ResnetBlock2D`). اختر من بين `default` أو `scale_shift`.

projection_class_embeddings_input_dim (`int`، *اختياري*، القيمة الافتراضية `None`) : بُعد مدخل `class_labels` عندما يكون `class_embed_type="projection"`. مطلوب عندما يكون `class_embed_type="projection"`.

controlnet_conditioning_channel_order (`str`، الافتراضي `"rgb"`) : ترتيب القنوات للصورة الشرطية. سيتم التحويل إلى `rgb` إذا كان `bgr`.

conditioning_embedding_out_channels (`tuple[int]`، *اختياري*، القيمة الافتراضية هي `(16, 32, 96, 256)`) : مجموعة القيم (tuple) لقنوات الإخراج لكل كتلة في طبقة `conditioning_embedding`.

global_pool_conditions (`bool`، القيمة الافتراضية `False`) : TODO(Patrick) - معامل غير مستخدم.

addition_embed_type_num_heads (`int`، القيمة الافتراضية 64) : عدد الرؤوس المستخدمة في طبقة `TextTimeEmbedding`.

نموذج ControlNet.

#### forward[[diffusers.ControlNetModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, guess_mode: bool = False, return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L602)

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

sample (`torch.Tensor`) : متجه الإدخال الضوضائي.

timestep (`torch.Tensor | float | int`) : عدد خطوات إزالة الضوضاء من المدخلات.

encoder_hidden_states (`torch.Tensor`) : حالات المُشفِّر المخفية.

controlnet_cond (`torch.Tensor`) : متجه الإدخال الشرطي ذو الشكل `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`، القيمة الافتراضية `1.0`) : معامل المقياس لمخرجات ControlNet.

class_labels (`torch.Tensor`، *اختياري*، القيمة الافتراضية `None`) : تسميات فئات اختيارية للتكييف. سيتم جمع تمثيلاتها مع تمثيلات خطوة الزمن.

timestep_cond (`torch.Tensor`، *اختياري*، القيمة الافتراضية `None`) : تضمينات شرطية إضافية لخطوة الزمن. إذا تم توفيرها، سيتم جمع التضمينات مع التضمين الزمني المُمرَّر عبر طبقة `self.time_embedding` للحصول على التضمينات النهائية لخطوة الزمن.

attention_mask (`torch.Tensor`، *اختياري*، القيمة الافتراضية `None`) : يُطبَّق قناع انتباه (attention mask) على شكل `(batch, key_tokens)` على `encoder_hidden_states`. إذا كانت القيمة `1` يُحافظ على القناع، وإلا إذا كانت `0` يُستبعد. يُحوَّل القناع إلى انحياز (bias) يضيف قيمًا سالبة كبيرة إلى درجات الانتباه المقابلة لرموز "الاستبعاد".

added_cond_kwargs (`dict`) : شروط إضافية لشبكة UNet في Stable Diffusion XL.

cross_attention_kwargs (`dict[str]`، *اختياري*، القيمة الافتراضية `None`) : قاموس kwargs يُمرَّر إلى `AttnProcessor` إذا تم تحديده.

guess_mode (`bool`، القيمة الافتراضية `False`) : في هذا الوضع، يحاول مُشفِّر ControlNet بأقصى جهد التعرف على محتوى الإدخال حتى إذا قمت بإزالة جميع الأوامر النصية. يُوصى باستخدام قيمة `guidance_scale` بين 3.0 و5.0.

return_dict (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [ControlNetOutput](/docs/diffusers/main/ar/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) بدلاً من tuple عادي.

**يعيد:** [ControlNetOutput](/docs/diffusers/main/ar/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **أو** `tuple`

إذا كان `return_dict` هو `True`، يُعاد [ControlNetOutput](/docs/diffusers/main/ar/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)، وإلا يُعاد tuple حيث العنصر الأول هو tensor العينة.

طريقة [ControlNetModel](/docs/diffusers/main/ar/api/models/controlnet#diffusers.ControlNetModel) الأمامية.

#### from_unet[[diffusers.ControlNetModel.from_unet]]

```python
from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True, conditioning_channels: int = 3)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L444)

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

unet (`UNet2DConditionModel`) : أوزان نموذج UNet التي سيتم نسخها إلى [ControlNetModel](/docs/diffusers/main/ar/api/models/controlnet#diffusers.ControlNetModel). كما يتم نسخ جميع خيارات التهيئة حيثما كان ذلك ممكنًا.

أنشئ نموذج [ControlNetModel](/docs/diffusers/main/ar/api/models/controlnet#diffusers.ControlNetModel) من [UNet2DConditionModel](/docs/diffusers/main/ar/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

```python
set_attention_slice(slice_size: str | int | list[int])
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L537)

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

slice_size (`str` أو `int` أو `list(int)`، *اختياري*، القيمة الافتراضية `"auto"`) : عند تعيين `"auto"`، يُنصَّف مدخل رؤوس الانتباه، فيُحسب الانتباه على خطوتين. أما عند تعيين `"max"`، فيُوفَّر الحد الأقصى من الذاكرة عبر تشغيل شريحة واحدة في كل مرة. وإذا تم تقديم رقم، فسيتم استخدام عدد من الشرائح يساوي `attention_head_dim // slice_size`. في هذه الحالة، يجب أن يكون `attention_head_dim` مضاعفًا لـ `slice_size`.

تفعيل حساب الانتباه المقطّع.

عند تمكين هذا الخيار، يقسم وحدة الانتباه (attention module) المصفوفة المدخلة إلى شرائح لحساب الانتباه على عدة خطوات. وهذا مفيد لتوفير بعض الذاكرة مقابل انخفاض طفيف في السرعة.

#### set_default_attn_processor[[diffusers.ControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L521)

يعطّل معالجات الانتباه المخصصة ويضبط تطبيق الانتباه الافتراضي.

## ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

#### diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

```python
diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L47)

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

down_block_res_samples (`tuple[torch.Tensor]`) : مجموعة (tuple) من تنشيطات التقليل (downsample) عند دقات مختلفة لكل كتلة تقليل. يجب أن يكون شكل كل متجه `(batch_size, channel * resolution, height //resolution, width // resolution)`. يمكن استخدام المخرجات لتكييف تنشيطات التقليل الأصلية في UNet.

mid_down_block_re_sample (`torch.Tensor`) : تفعيل الكتلة الوسطى (أدنى دقة للعينة). يجب أن يكون شكل كل متجه `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. يمكن استخدام المخرجات لتكييف تفعيل الكتلة الوسطى في UNet الأصلية.

مخرجات [ControlNetModel](/docs/diffusers/main/ar/api/models/controlnet#diffusers.ControlNetModel).