diffusers/v0.43.0/ar/api/models/controlnet_sparsectrl.md

SparseControlNetModel

SparseControlNetModel هو تطبيق لـ ControlNet مخصص لـ AnimateDiff.

تم تقديم ControlNet في Adding Conditional Control to Text-to-Image Diffusion Models بواسطة Lvmin Zhang وAnyi Rao وManeesh Agrawala.

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

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

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

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

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]]

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)

المصدر

المعاملات:

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.

forward[[diffusers.SparseControlNetModel.forward]]

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)

المصدر

المعاملات:

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

from_unet[[diffusers.SparseControlNetModel.from_unet]]

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)

المصدر

المعاملات:

unet (UNet2DConditionModel) : أوزان نموذج UNet التي سيتم نسخها إلى SparseControlNetModel. كما يتم نسخ جميع خيارات الإعداد حيثما كان ذلك ممكنًا.

أنشئ نموذج SparseControlNetModel من UNet2DConditionModel.

set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

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

المصدر

المعاملات:

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]]

set_default_attn_processor()

المصدر

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

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

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

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

المصدر

المعاملات:

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.