# ControlNetUnionModel

ControlNetUnionModel هو تطبيق لـ ControlNet مخصص لنموذج Stable Diffusion XL.

تم تقديم نموذج ControlNet في [ControlNetPlus](https://github.com/xinsir6/ControlNetPlus) بواسطة xinsir6. يدعم مدخلات شرطية متعددة دون زيادة في الحسابات.

*صممنا معمارية جديدة قادرة على دعم أكثر من 10 أنواع من التحكم في توليد الصور من النص إلى الصورة، وقادرة على توليد صور عالية الدقة قابلة للمقارنة بصريًا مع midjourney. يعتمد الشبكة على معمارية ControlNet الأصلية، ونقترح وحدتين جديدتين من أجل: 1 توسيع ControlNet الأصلية لدعم ظروف صور مختلفة باستخدام نفس معاملات الشبكة. 2 دعم إدخال ظروف متعددة دون زيادة إزاحة الحساب، وهو أمر مهم بشكل خاص للمصممين الذين يرغبون في تحرير الصورة بالتفصيل، حيث تستخدم الظروف المختلفة نفس مشفر الظروف، دون إضافة حسابات أو معاملات إضافية.*

## جارٍ التحميل

بشكل افتراضي، يجب تحميل [ControlNetUnionModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_union#diffusers.ControlNetUnionModel) باستخدام [from_pretrained()](/docs/diffusers/v0.43.0/ar/api/models/overview#diffusers.ModelMixin.from_pretrained).

```py
from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel

controlnet = ControlNetUnionModel.from_pretrained("xinsir/controlnet-union-sdxl-1.0")
pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet)
```

## ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

#### diffusers.ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

```python
diffusers.ControlNetUnionModel(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'), 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 = (48, 96, 192, 384), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64, num_control_type: int = 6, num_trans_channel: int = 320, num_trans_head: int = 8, num_trans_layer: int = 1, num_proj_channel: int = 320)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_union.py#L85)

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

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]`، *اختياري*، القيمة الافتراضية `(48, 96, 192, 384)`) : مجموعة قنوات الإخراج لكل كتلة في طبقة `conditioning_embedding`.

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

نموذج ControlNetUnion.

#### forward[[diffusers.ControlNetUnionModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: list[torch.Tensor], control_type: Tensor, control_type_idx: list[int], conditioning_scale: float | list[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, from_multi: bool = False, guess_mode: bool = False, return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_union.py#L541)

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

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

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

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

controlnet_cond (`list[torch.Tensor]`) : تينسورات الإدخال الشرطي.

control_type (`torch.Tensor`) : متجه (Tensor) على شكل `(batch, num_control_type)` بقيم `0` أو `1` اعتمادًا على ما إذا كان نوع التحكم مستخدمًا أم لا.

control_type_idx (`list[int]`) : فهارس `control_type`.

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` إذا تم تحديده.

from_multi (`bool`، القيمة الافتراضية `False`) : استخدام التقييس القياسي عند الاستدعاء من `MultiControlNetUnionModel`.

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

return_dict (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~models.controlnet.ControlNetOutput` بدلاً من tuple عادي.

**يعيد:** `~models.controlnet.ControlNetOutput` **أو** `tuple`

إذا كان `return_dict` هو `True`، يُعاد `~models.controlnet.ControlNetOutput`، وإلا يُعاد tuple حيث يكون العنصر الأول هو tensor العينة.

طريقة [ControlNetUnionModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_union#diffusers.ControlNetUnionModel) الأمامية.

#### from_unet[[diffusers.ControlNetUnionModel.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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_union.py#L389)

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

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

أنشئ كائنًا من [ControlNetUnionModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_union#diffusers.ControlNetUnionModel) انطلاقًا من [UNet2DConditionModel](/docs/diffusers/v0.43.0/ar/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.ControlNetUnionModel.set_attention_slice]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_union.py#L476)

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

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.ControlNetUnionModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_union.py#L460)

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