Hugging Face's logo

Diffusers documentation

SparseControlNetModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

< >

( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 768transformer_layers_per_block: int | tuple[int, ...] = 1transformer_layers_per_mid_block: int | tuple[int] | None = Nonetemporal_transformer_layers_per_block: int | tuple[int, ...] = 1attention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falsecontrolnet_conditioning_channel_order: str = 'rgb'motion_max_seq_length: int = 32motion_num_attention_heads: int = 8concat_conditioning_mask: bool = Trueuse_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")) — المجموعة المرتبة (tuple) من كتل التقليل (downsample) المستخدمة.
  • 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, اختياري، القيمة الافتراضية 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) — عدد طبقات الترانسفورمر المستخدمة في كل طبقة داخل الكتلة الوسطى.
  • 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) — إعدادات إزاحة مقياس الوقت لكتل ResNet (انظر ResnetBlock2D). القيمة الافتراضية "default". اختر من بين default أو scale_shift.
  • conditioning_embedding_out_channels (tuple[int]، القيمة الافتراضية (16, 32, 96, 256)) — مجموعة قنوات الإخراج لكل كتلة في طبقة 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

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0timestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneconditioning_mask: typing.Optional[torch.Tensor] = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.ControlNetOutput or tuple

المعاملات

  • sample (torch.Tensor) — مصفوفة الإدخال الضجيج.
  • timestep (torch.Tensor | float | int) — عدد خطوات الزمن (timesteps) لإزالة الضوضاء من مدخل.
  • 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) — تضمينات شرطية إضافية لخطوة الزمن. إذا تم توفيرها، سيتم جمع التضمينات مع timestep_embedding المُمررة عبر طبقة 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

< >

( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )

المعاملات

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

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

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

< >

( )

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

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.

Update on GitHub

←SD3ControlNetModel AceStepTransformer1DModel→