# SparseControlNetModel

SparseControlNetModel هو تطبيق لـ ControlNet مخصص لـ [AnimateDiff](https://huggingface.co/papers/2307.04725).

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

طُرِح إصدار SparseCtrl من ControlNet في [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) لتحقيق التوليد المُتحكَّم به في نماذج الانتشار من النص إلى الفيديو، وذلك من قِبل Yuwei Guo وCeyuan Yang وAnyi Rao وManeesh Agrawala وDahua Lin وBo Dai.

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

*شهد تطوير النماذج التحويلية من النص إلى الفيديو (T2V)، أي توليد مقاطع فيديو بناءً على موجه نصي معيّن، تقدّمًا كبيرًا في السنوات الأخيرة. ومع ذلك، فإن الاعتماد حصريًا على الموجهات النصية غالبًا ما يؤدي إلى تكوين غامض للإطارات بسبب عدم اليقين المكاني. لذا، يستفيد مجتمع البحث من إشارات البنية الكثيفة، مثل تسلسلات العمق/الحواف لكل إطار، لتعزيز قابلية التحكم، مما يزيد بدوره من عبء الاستدلال. في هذا العمل، نقدّم SparseCtrl لتمكين التحكم المرن في البنية باستخدام إشارات متفرقة زمنيًا، حيث يتطلب الأمر إدخالًا واحدًا أو بضعة إدخالات فقط، كما هو موضح في الشكل 1. يتضمن هذا النموذج مشفّرًا إضافيًا للشروط لمعالجة هذه الإشارات المتفرقة مع إبقاء نموذج T2V المُدرَّب مسبقًا دون أي تعديل. يتوافق النهج المقترح مع أوضاع متعددة، بما في ذلك الرسومات التوضيحية، وخرائط العمق، والصور RGB، مما يوفر تحكمًا أكثر عملية في توليد الفيديو ويدفع تطبيقات مثل تخطيط اللوحات، وعرض العمق، وتحريك الإطارات المفتاحية، والاستيفاء. تُظهر التجارب الواسعة تعميم SparseCtrl على مولّدات T2V الأصلية والمخصصة على حد سواء. ستكون الأكواد والنماذج متاحة علنًا في [هذا الرابط](https://guoyww.github.io/projects/SparseCtrl).*

## مثال على تحميل SparseControlNetModel

```python
import torch
from diffusers import SparseControlNetModel

# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)

# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)

# For loading fp16 variant, pass `variant="fp16"` as an additional parameter
```

## SparseControlNetModel[[diffusers.SparseControlNetModel]]

#### diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

```python
diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), 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 = 768, transformer_layers_per_block: int | tuple[int, ...] = 1, transformer_layers_per_mid_block: int | tuple[int] | None = None, temporal_transformer_layers_per_block: int | tuple[int, ...] = 1, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)
```

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

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

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

conditioning_channels (`int`، القيمة الافتراضية 4) : عدد قنوات الإدخال في وحدة تضمين الشرط الخاصة بـ ControlNet. إذا كانت `concat_condition_embedding` تساوي True، فإن القيمة المُدخلة هنا تزداد بمقدار 1.

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`.

transformer_layers_per_mid_block (`int` أو `tuple[int]`، *اختياري*، القيمة الافتراضية 1) : عدد طبقات التحويل (transformer) المستخدمة في كل طبقة داخل الكتلة الوسطى.

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

num_attention_heads (`int` أو `tuple[int]`، *اختياري*) : عدد الرؤوس المستخدمة في الانتباه متعدد الرؤوس.

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

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

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

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

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

controlnet_conditioning_channel_order (`str`، الافتراضي هو `rgb`) --

motion_max_seq_length (`int`، القيمة الافتراضية `32`) : الحد الأقصى لطول التسلسل المستخدم في وحدة الحركة.

motion_num_attention_heads (`int` أو `tuple[int]`، الافتراضي `8`) : عدد الرؤوس المستخدمة في كل طبقة انتباه من طبقات وحدة الحركة.

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

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

نموذج SparseControlNet كما هو موصوف في [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933).

#### forward[[diffusers.SparseControlNetModel.forward]]

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

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

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

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.

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

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

conditioning_mask (`torch.Tensor`، *اختياري*، القيمة الافتراضية `None`) : قناع اختياري يحدد أي الإطارات في `controlnet_cond` هي إطارات تكييف صالحة.

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

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 العينة.

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

#### from_unet[[diffusers.SparseControlNetModel.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/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

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

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

أنشئ نموذج [SparseControlNetModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) من [UNet2DConditionModel](/docs/diffusers/v0.43.0/ar/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.SparseControlNetModel.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_sparsectrl.py#L469)

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

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

```python
set_default_attn_processor()
```

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

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

## SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

#### diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

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

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

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

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 الأصلية.

المخرجات الخاصة بـ [SparseControlNetModel](/docs/diffusers/v0.43.0/ar/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).