diffusers/main/ar/api/models/controlnet.md

ControlNetModel

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

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

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

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

بشكل افتراضي، يجب تحميل ControlNetModel باستخدام from_pretrained()، لكن يمكن أيضًا تحميله من التنسيق الأصلي باستخدام FromOriginalModelMixin.from_single_file على النحو التالي:

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 من خلال إضافة الضبط الدقيق الفعال المعتمد على المعلمات منخفضة الرتبة إلى ControlNet. توفر هذه الطريقة نهجًا أكثر كفاءة ومضغوطًا لجلب التحكم في النموذج إلى مجموعة أوسع من وحدات معالجة الرسومات الموجهة للمستهلكين.

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

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)

المصدر

المعاملات:

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

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)

المصدر

المعاملات:

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 بدلاً من tuple عادي.

يعيد: ControlNetOutput أو tuple

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

طريقة ControlNetModel الأمامية.

from_unet[[diffusers.ControlNetModel.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 التي سيتم نسخها إلى ControlNetModel. كما يتم نسخ جميع خيارات التهيئة حيثما كان ذلك ممكنًا.

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

set_attention_slice[[diffusers.ControlNetModel.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.ControlNetModel.set_default_attn_processor]]

set_default_attn_processor()

المصدر

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

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

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

diffusers.models.controlnets.ControlNetOutput(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 الأصلية.

مخرجات ControlNetModel.