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

ControlNetUnionModel

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

تم تقديم نموذج ControlNet في ControlNetPlus بواسطة xinsir6. يدعم مدخلات شرطية متعددة دون زيادة في الحسابات.

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

جارٍ التحميل

بشكل افتراضي، يجب تحميل ControlNetUnionModel باستخدام from_pretrained().

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

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)

المصدر

المعاملات:

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

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)

المصدر

المعاملات:

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

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

المصدر

المعاملات:

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

أنشئ كائنًا من ControlNetUnionModel انطلاقًا من UNet2DConditionModel.

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

set_default_attn_processor()

المصدر

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